채널사 주문 연동을 준비하면서 문서와 문답을 훑었다. GET /orders 하나면 전부 가져올 것으로 보고 시작했다.
Table of contents
Open Table of contents
배경 — 이름이 비슷한 두 서비스
문서에 이름이 한 글자만 다른 서비스가 둘 있었다. 하나는 판매자가 채널사 창고에 미리 입고시키고 채널사가 직접 발송하는 방식이다.
다른 하나는 판매자가 자체 창고에서 채널사 창고로 보내면 채널사가 환적해 배송하는 방식이다. 이름은 비슷한데 흐름이 다르므로 처리도 달라야 한다.
원인 — API가 반환하지 않는 유형
문답에서 결정적인 것을 찾았다. GET /orders 가 자체배송과 환적 유형만 반환하고 입고 유형은 반환하지 않는다는 내용이었다.
협력 창고가 전담 처리해서 API 에 집계되지 않고 별도 플랫폼에서 확인해야 한다. 이것을 모르고 연동하면 그 유형 주문이 없다고 판단하게 되는데 오류도 없이 [] 가 오기 때문이다.
조치 — 유형 구분과 전용 경로
반환되는 것 중에서 유형을 가르는 방법도 확인했다. shipmentType 값으로 구분하는데 값 하나가 'DIRECT ' 처럼 뒤에 공백이 들어 있어서 trim() 없이 비교하면 안 걸린다.
환적 유형은 barcode 발급과 조회 API 가 따로 있고 분할 배송을 지원하지 않았다. 결국 일반 주문과 환적 유형과 API 밖의 유형으로 세 갈래가 되고 각각 처리가 다르다.
검증 — 원문이 안 맞았다
문서를 대조하다 하나가 안 맞았다. 두 용어가 정확히 같은 개념인지를 원문마다 다르게 쓰고 있었다.
한 문서에서는 같은 것처럼 쓰고 다른 데서는 구분하는 것처럼 읽혀서 확정하지 못했다. 그래서 두 개념이 동일한지는 원문 불일치로 확정되지 않았다고 INTEGRATION.md 에 적었다. 대조했는데 안 맞으면 안 맞는다고 적고 한쪽을 골라 확정하지 않는다.
주의 — 연동 전에 알아야 하는 것
이 내용들이 어디 있었는지도 남길 만하다. 규격 문서 PDF 에서 관련 키워드를 검색하니 0건이었고 전부 문답과 부속 문서에만 있었다.
읽는 방법은 두 가지가 있었다. 채널사가 준 요약본만 보는 것과 문답 원문 파일까지 대조하는 것이다. 뒤쪽을 골랐다. 이유는 요약본은 요약한 사람의 해석이 이미 들어가 있어서다. 대신 문답 수백 건 중 몇 건을 골라 원문 파일을 대조하는 데 하루가 더 드는 것을 감수했고 일부는 다른 언어로 돼 있었다. 요약본만 봤으면 매끄럽게 정리됐을 것이고 앞의 불일치도 못 봤을 것이다. 세 가지가 다 구조에 영향을 주므로 연동을 만든 뒤에 알면 다시 짜야 한다.
정리
- 조회 API에 안 나오는 유형이 있을 수 있다
- 안 나온다가 없다가 아니고 오류도 없이 빈 목록이 온다
- 이름이 비슷한 서비스가 흐름이 다를 수 있다
- 유형 구분은 특정 필드 값으로 하고 값에 공백이 있을 수 있다
- 유형마다 전용 API와 제약이 있을 수 있다
- 원문 대조에서 안 맞으면 안 맞는다고 적는다
- 이런 내용은 규격 문서가 아니라 문답에 있다
- 요약을 요약하지 않고 원문까지 본다