공급 조건과 연동 문서부터 확인하기
API 연동을 준비할 때는 먼저 제공 권한과 실제 제공 항목을 확인해야 합니다. 같은 공급사의 이름을 사용하더라도 계약 상품과 지원 조건에 따라 콘텐츠, 데이터 범위와 기술 지원이 달라질 수 있습니다.
문서에는 인증 방법, 요청과 응답 형식, 상태와 오류 코드, 콜백 제공 방식, 지원 버전과 변경 정책이 필요합니다. 설명 자료나 화면 이미지가 기술 문서를 대신하지는 않습니다. 준비된 자료와 추가로 받아야 할 자료를 분리해 정리하세요.
- 콘텐츠와 데이터의 사용 권한, 제공 범위와 지원 조건
- 요청·응답 형식, 인증, 오류 코드와 버전 정책
- 샌드박스, 테스트 계정과 기술 문의 담당자
식별자와 상태값의 의미 맞추기
회원, 콘텐츠, 요청과 거래를 서로 연결할 식별자가 필요합니다. 내부에서 사용하는 값과 공급사가 사용하는 값이 다를 수 있으므로 어떤 항목이 무엇을 의미하는지 문서로 정리해야 합니다.
특히 성공 응답이 곧 모든 업무의 완료를 뜻하는지 확인하세요. 요청 접수, 처리 진행과 최종 완료는 서로 다른 상태일 수 있습니다. 결과를 확인하지 못한 상황을 실패로 확정하면 중복 처리와 기록 불일치의 원인이 될 수 있습니다.
| 확인 대상 | 정리할 내용 |
|---|---|
| 회원·계정 | 내부 회원과 공급사 계정의 연결 기준 |
| 요청·거래 | 고유 식별자의 생성·보관과 중복 판단 기준 |
| 상태·오류 | 접수, 진행, 완료, 실패와 미확인 상태의 의미 |
| 시간 | 기록 시각의 기준과 시간대 변환 방식 |
지연·중복·재시도 상황 정리하기
실제 운영에서는 응답이 늦거나 같은 알림이 여러 번 도착할 수 있습니다. 정상 흐름만 테스트하면 이런 상황에서 어디까지 처리됐는지 확인하기 어렵습니다. 기다리는 시간, 결과 재조회와 재시도 가능 조건을 각각 구분해야 합니다.
재시도는 언제나 안전한 작업이 아닙니다. 공급사 문서의 중복 요청 규칙을 확인하고, 동일한 업무가 여러 번 처리되지 않도록 식별 기준을 정하세요. 담당자가 직접 조치하는 경우에도 확인 근거와 처리 전후 상태를 기록하는 것이 좋습니다.
- 응답 지연 시 상태와 대기 시간을 확인합니다.
- 결과를 재조회할 수 있는지, 어떤 식별자를 사용하는지 정합니다.
- 중복 응답과 알림을 재현해 처리 이력을 확인합니다.
- 수동 조치가 가능한 항목과 승인 절차를 정합니다.
테스트 결과와 변경 이력 남기기
검증 결과는 기능별로 남겨야 합니다. 정상 요청, 인증 실패, 응답 지연, 중복 알림과 데이터 누락 등 점검한 조건을 적고, 요청 식별자와 결과를 연결해 확인할 수 있도록 하세요. 문제가 수정됐다면 같은 조건으로 다시 확인한 결과도 기록합니다.
오픈 이후에는 문서 변경과 버전 업데이트가 영향을 줄 수 있습니다. 적용 버전, 변경 담당자, 테스트 항목과 되돌리기 조건을 정리하면 변경 시 필요한 점검을 다시 찾기 쉽습니다. API 연동은 최초 연결 이후에도 관리해야 하는 운영 항목입니다.