시스템 연동 프로젝트에서 겪은 시행착오와 해결 과정

오늘은 작년에 제가 참여했던 금융 결제 시스템 연동 프로젝트의 기획과 실행 과정을 되돌아보며, 웹서비스 기획자들이 API 연동을 준비할 때 참고할 만한 실전 사례를 공유하고자 합니다. 이 프로젝트는 무국의 중개 거래 플랫폼인 갑페이와 은머스의 재고관리시스템을 연동하는 작업이었습니다.

프로젝트 배경: 왜 시스템 연동이 필요했나

무국 내 거래 건의 80%를 처리하던 갑페이와의 기존 프로세스는 매우 비효율적이었습니다. 거래 승인 전 갑페이 포털에 거래정보를 수동으로 업로드한 뒤, 물리적으로 은머스 센터에서 입금 확인 후 거래승인서를 출력해서 다시 시스템에 등록하는 방식이었습니다. 이 과정에 정산 담당자는 최소 1분 30초가 소요되었고, 거래량 확대 시 심각한 병목이 예상되었습니다.

 

기획 단계에서 우리는 단순히 연동 API를 호출한다고 해결될 줄 알았습니다. 하지만 현실은 그렇지 않았습니다.

이슈 1: 연동 환경 구분과 인증 정보의 중요성

프로젝트 초반 가장 큰 혼란은 테스트 환경과 실제 환경의 구분이었습니다. 갑페이의 경실무자가 처음 제공한 정보는:

• 연동 문서 종점: https://sandbox.갑페이.asia/API/docs/v2
• 인증 정보: Client ID LTU3Mzg3NDUx, Password MTU123487
• 거래 ID Prefix: 59206 (16자리 숫자)

하지만 실제 연동 시도하자 실제 환경 접속이 불가능했습니다. 확인 결과, 제공받은 것은 테스트 전용 인증 정보였고, 실제 환경은 전혀 다른 계정이 필요했습니다. 더 큰 문제는 이후 테스트 계정이 다른 고객사에 재할당되어 우리가 사용할 수 없게 되었다는 점이었습니다.

기획자에게 주는 교훈:

• 연동 기획 시 테스트/스테이징/프로덕션 환경을 명확히 문서화하라
• 인증 정보의 유효 기간과 재사용 가능 여부를 반드시 확인하라
• 테스트 계정과 프로덕션 계정의 승인 프로세스를 미리 파악하고 일정에 반영하라

이슈 2: 거래 ID 규칙의 함정

갑페이는 거래 ID 생성 시 필수 Prefix를 요구했습니다. 처음에는 MYECO를 붙이라고 했으나, 갑페이 내부 시스템에서는 접두사를 로그인 계정 기준으로 관리하는 것으로 확인되었습니다. 이후 우리가 원하는 은머스 고유 번호(NGM153604205 형식)를 사용하려고 하자, 다른 고객사와 번호 충돌 가능성을 이유로 거절당했습니다.

결국 협상 끝에 은머스 전용 Prefix를 등록하여 해결했지만, 이 과정에서 2주가 추가로 소요되었습니다.

기획자에게 주는 교훈:

• ID 생성 규칙을 연동 문서만 보고 판단하지 말고, 실제 담당자와 직접 확인하라
• 고유 식별자 충돌 방지 정책을 사전에 파악하고, 예외 처리 방안을 마련하라
• 파트너사의 내부 시스템 제약 조건을 문서만으로는 파악하기 어렵다

이슈 3: 필수 파라미터와 선택적 파라미터의 모호함

연동 가이드에서는 상품설명, 총중량 등을 선택적 파라미터로 명시했습니다. 하지만 실제 테스트에서는 중량단위 값을 "G"가 아닌 G로 보내어 오류가 발생했고, 상품설명은 null 문자열이 아닌 "null"로 전달해야 했습니다. 또한 실시간정산 값을 null로 보내도 영수증에는 정산: 0 MYC로 표시되는 등 문서와 실제 동작의 불일치가 빈번했습니다.

특히 주소 필드는 가이드상 최대 길이가 50자로 명시되어 있었으나, 실제로는 더 긴 주소를 처리할 수 없어 주소를 주소1/주소2로 분할해야 했습니다.

기획자에게 주는 교훈:

• 연동 문서의 Optional/Required 표기는 믿되, 반드시 샘플 데이터로 검증하라
• 실패 케이스에 대한 에러 코드와 메시지를 상세히 문서화하라
• 파트너사 기술지원팀에 실패 로그를 제공할 수 있는 체계를 미리 마련하라

이슈 4: 해외 거래 시 승인자료 처리의 복잡성

우리는 경국, 기국에서 무국으로 들어오는 해외 거래 건에 대해 승인자료를 무국 은머스 센터로 통일하고 싶었습니다. 갑페이의 기운영자는 인수방법을 2(센터승인)로 설정하고 승인자료를 무국 주소로 하면 된다고 답했습니다.

하지만 경실무자는 발송국가와 승인자료 국가가 다르면 에러가 발생하며, 해외 거래 시에는 인수방법을 1(직접인수)으로 변경하고 반송모드를 01로 처리해야 한다고 추가 지시했습니다. 이 정보는 초기 기획에 전혀 반영되지 않아 개발 후반부에 시스템 구조를 변경해야 했습니다.

기획자에게 주는 교훈:

• 국가 코드, 주소, 인수 방법의 조합에 따른 전처리 로직을 사전에 설계하라
• 해외/국내를 구분하는 기준을 비즈니스 룰 문서(BRD)에 명확히 정의하라
• 연동 담당자와의 커뮤니케이션 로그를 이메일이 아닌 공식 이슈 트래킹 시스템에 남기라

이슈 5: 영수증 포맷과 재출력 정책

우리 시스템은 HTML 모듈을 사용했기에 갑페이에 HTML 형식 영수증을 요청했습니다. 하지만 지원 포맷은 PDF, PNG, ZPL만 가능했고, HTML은 지원되지 않았습니다. 결국 PDF를 다시 HTML로 변환하는 별도 모듈을 개발해야 했습니다.

재출력 시나리오 또한 복잡했습니다. 거래ID로 재출력 API를 호출해야 하는데, 이 ID는 최초 생성 시 우리가 자유롭게 지정할 수 없고 갑페이 Prefix 규칙을 따라야 했습니다.

기획자에게 주는 교훈:

• 출력 포맷의 호환성을 가장 먼저 검증하라
• 재출력, 취소, 수정 등 수명주기 전반에 대한 연동 존재 여부를 확인하라
• ID 생성 주체(누가 생성하는가)에 따라 재처리 로직이 달라질 수 있다

이슈 6: 커뮤니케이션의 비효율성

전체 이메일 스레드를 보면 질문→답변→추가질문→추가답변의 패턴이 반복됩니다. 특히 경실무자가 "연동 테스트 페이로드 샘플을 2개 보내달라"고 했을 때, 무직원이 인증 토큰 URL만 보내어 개념 오해를 보이는 등 기술적 커뮤니케이션의 단절이 빈번했습니다. 이로 인해 협상 기간이 2개월 이상 지연되었습니다.

기획자에게 주는 교훈:

• 연동 프로젝트에는 기술 지식이 있는 중재자(API PM) 를 반드시 지정하라
• 질문하기 전에 "우리가 무엇을 모르는지"를 정리한 문서(요구사항 불명확 사항 리스트) 를 만들라
• 주간/격주 간격으로 정기 회의를 강제하여 비동기적 이메일 의존도를 낮춰라

마무리: 기획자에게 주는 핵심 체크리스트

이 프로젝트를 통해 얻은 교훈을 담아, 웹서비스 기획자가 API 연동을 준비할 때 반드시 확인해야 할 체크리스트를 만들었습니다.

API 기획 전 단계:

• [ ] 연동 문서 버전과 실제 운영 버전의 일치 여부 확인
• [ ] 테스트/스테이징/프로덕션 환경 계정 승인 프로세스 및 소요 기간 파악
• [ ] ID 생성 규칙, Prefix 정책, 중복 방지 방식 확인
• [ ] 지원 데이터 포맷(PDF, HTML, JSON 등) 및 인코딩 방식 검증

개발 단계:

• [ ] 샘플 데이터로 실제 연동 호출 테스트 (성공/실패 케이스 모두)
• [ ] 에러 코드별 대응 방안 문서화
• [ ] Rate Limit, Timeout, Retry 정책 수립
• [ ] 로그 수집 및 분석 체계 마련

운영 단계:

• [ ] 연동 담당자 긴급 연락처 및 에스컬레이션 경로 확보
• [ ] 장애 대응 매뉴얼 작성 (우리/파트너사 책임 구분)
• [ ] 정기 동기화 테스트 스케줄링

API 연동은 기술문제를 넘어 비즈니스 프로세스 통합 프로젝트입니다. 문서상의 "Optional"이 현실에서 "Required"가 될 수 있음을 기억하고, 검증 없는 기획은 실패를 낳는다는 점을 명심해야 합니다.

---