WMS/OMS 운송사 추적 API 연동: 피해야 할 6가지 함정

결론부터 말하자면: WMS나 OMS에 운송사 추적 API를 연동할 때, 쿼리가 성공하는 것 자체는 전체 작업의 약 30%에 불과합니다. 저는 WMS go-live를 30회 이상 해왔는데, 추적 연동이 "쿼리가 안 됐다"는 이유로 실패한 적은 없습니다. 실패하는 이유는 상태가 잘못 번역되었거나, 업데이트가 조용히 멈췄거나, 운송사가 쿼리를 제한했기 때문입니다. 아래 6가지 함정은 제가 한 번 이상 목격한 것들이고, 마지막에는 go-live 당일 밤 체크리스트가 있습니다. 출력해서 하나씩 체크하세요.

먼저, 추적 API가 해결하는 진짜 문제를 정의하라

WMS나 OMS는 고객을 위해 세 가지 질문에 답해야 합니다: 출고됐는가, 어디에 있는가, 받았는가. 운송사의 API는 다른 언어를 씁니다: 수십 개의 상태 코드, 늦게 도착하는 업데이트, 가끔의 장애. 당신의 일은 번역과 백업입니다. 이 함정을 저는 세 번 목격했습니다—한 팀이 "API가 200을 반환했다"를 "연동 완료"로 여겼고, go-live 2주 뒤에 지원 티켓이 들어오기 시작했습니다: "배송 완료라고 나오는데 받은 게 없습니다." 아무도 상태 매핑 테이블을 만들지 않았던 것입니다.

2023년의 사례: 캘리포니아 온타리오의 3PL 창고로, 하루 약 6,000건의 주문을 출고했습니다. 구성은 15분마다 운송 중인 모든 추적 번호를 싹 훑고 각 운송사의 추적 API를 하나씩 쿼리하는 스케줄 작업이었습니다. 잘 돌아갔습니다—피크 시즌에 물량이 하루 9,000건을 넘기 전까지는. 쿼리량이 덩달아 두 배가 되어 운송사의 요청 제한에 부딪혔고, 계정이 스로틀됐습니다. 추적 업데이트가 이틀 내내 멈췄습니다. 고객 서비스 전화는 불이 났고, 오퍼레이션은 운송사 웹사이트에서 추적 번호를 수작업으로 확인했습니다. 저희가 들어가서 고칠 때 처음 한 일은 전체 폴링을 없애는 것이었습니다: 상태 푸시용 webhook 콜백으로 전환하고, 폴링은 24시간 이상 업데이트가 없는 배송 건에 대한 안전망으로만 남겼습니다. 2주 뒤에는 추적이 다시 건강해졌고, 쿼리량은 이전의 10분의 1 이하로 떨어졌습니다.

추적 API 연동: 폴링 vs webhook — 이것부터 정하라

이것이 함정 1번이며, 가장 비싼 것입니다. 어느 패턴도 만능은 아니지만, 잘못 고르면 영원히 패치만 하게 됩니다.

	폴링	Webhook
신선도	간격에 따라 다름, 보통 15–60분 지연	거의 실시간, 업데이트 시 푸시
API 부하	무거움 — 전체 스윕은 금방 요청 제한에 부딪힘	가벼움 — 변경된 배송 건만
신뢰성	안정적, 리듬을 내가 통제	운송사의 푸시에 의존; 놓친 콜백은 내가 직접 잡아야 함
적합한 용도	안전망, 백필, 정산(리컨실리에이션)	주 파이프라인

직관에 반하는 부분은 여기입니다: webhook은 폴링의 "업그레이드"가 아닙니다. 파트너입니다. 올바른 아키텍처는 webhook을 주 파이프라인으로, 스케줄된 폴백 폴링을 보험으로 두는 것입니다. 이 함정을 저는 세 번 목격했습니다—한 팀이 webhook에 올인했는데 운송사의 푸시 서비스가 반나절 다운됐고, "다 정상으로 보였기" 때문에 아무도 눈치채지 못했습니다.

단계별:

연동하는 각 운송사가 실제로 webhook을 지원하는지 확인하라. 정책은 회사마다 다르므로 운송사의 최신 공개 문서를 기준으로 하라.
지원하면: 콜백 수신기를 세 가지 필수 요소—서명 검증, 멱등성, 원시 페이로드 저장—와 함께 구축하라. 검증은 위조 푸시를 차단하고, 멱등성은 중복 푸시를 처리하며(운송사는 상시 재푸시한다), 원시 저장은 나중에 정산할 수 있게 한다.
지원하지 않으면: 폴링하되, 운송 중이고 N시간 이상 업데이트가 없는 배송 건으로 제한하라. 전체를 훑는 것은 절대 금지.
어느 쪽이든 폴백 작업을 돌려라: 24시간 이상 업데이트가 없는 운송 중 배송 건 전체를 하루에 한 번 훑어, 놓친 webhook 푸시를 잡아낸다.

번역되지 않은 운송사 상태 코드는 지뢰밭이다

함정 2번. 모든 택배·화물 회사는 각자의 상태 코드 체계를 가지고 있다. "Delivered"는 한 운송사에서는 배송 증명을 의미하고, 다른 곳에서는 "대리점 픽업 지점으로의 인도"를 의미한다. 원시 코드를 그대로 고객에게 전달하는 것은 번역 작업을 지원 팀에게 떠넘기는 것이다.

2024년, 선전의 국경 간 이커머스 셀러가 하루 약 4,000건을 출고하면서 세 운송사의 추적 API를 연동했다. 매핑 로직은 단순했다: "deliver"가 포함된 것은 모두 "Delivered". 미국행 배송 건 일부가 대리점 픽업 지점에 인도됐고("delivered to agent"), 시스템은 그것들을 모두 배송 완료로 찍었다. 200명 이상의 구매자가 "아무것도 받지 못했다"고 주장했고, 분쟁과 환불이 함께 폭발했다. 매핑 테이블을 다시 만들 때, "대리점에 대한 인도"는 독립 상태—"수령 대기"—가 됐고, 지원팀이 구매자들에게 선제적으로 연락했다. 일주일 만에 분쟁량이 줄었다.

단계별:

상태 매핑 테이블을 만들라: 운송사 원시 상태 코드 → 하나의 내부 표준 상태(픽업 / 운송 중 / 배송 중 / 대리점 인도 / 배송 완료 / 예외 / 반품).
뭉뚱그리지 말고 세밀하게 매핑하라. "대리점 인도", "배송 실패", "주소 오류"는 독립 카테고리—절대 "배송 완료"나 "운송 중"에 합치지 않는다.
새로운 운송사마다 2주간 섀도 모드로 돌려라: 매핑 결과를 기록만 하고 누구에게도 보여주지 말고, 100건의 배송을 수작업으로 스팟 체크한 뒤 릴리스하라.
매핑 테이블을 버전 관리해서, 운송사가 코드를 바꿀 때 역추적할 수 있게 하라.

소포 배송 라벨을 스캔하는 작업자의 클로즈업

요청 제한, 캐싱, 알림: 이 셋은 항상 같이 터진다

함정 3번과 4번은 항상 같이 터지므로 한 세트다. 운송사 추적 피드에는 거의 전부 요청 제한이 있다—구체적인 숫자는 회사마다 다르니 최신 공개 정책을 확인하라—제한을 넘기면 스로틀되거나 차단된다. 쿼리량을 줄이는 방법은 정확히 하나다: 캐싱이다.

단계별:

추적 결과는 추적 번호별로 캐시하라. 배송 완료된 건은 7일간 캐시하라—상태가 다시 바뀔 일은 없으므로 조회 한 번이면 충분하다.
운송 중인 건은 15–30분 캐시하라. 프론트엔드와 지원팀은 캐시에서 읽고, 운송사 API를 직접 두드리지 않는다.
동시 쿼리를 중복 제거하라: 5분 이내에 같은 번호에 대한 반복 조회는 실제 요청을 정확히 1회만 발생시킨다.
세 단계의 알림을 설정하라: (1) 24시간 이상 추적 업데이트가 없는 배송 건 1개 → 오퍼레이션이 후속 조치; (2) 상태 후퇴—예: "배송 중"에서 "운송 중"으로 되돌아가기 → 즉시 알림, 분실·반품의 첫 징후인 경우가 많다; (3) 10분 이상 연속되는 API 실패 → 엔지니어링 알림, 스로틀되거나 운송사 서비스가 다운됐을 가능성이 높다.

두 번째로 직관에 반하는 판단: 고객은 30분 늦은 추적은 견딜 수 있다. 잘못된 "배송 완료"는 견디지 못한다. 신선도는 있으면 좋은 정도; 정확도는 생사 문제다. 예산과 에너지는 먼저 매핑과 알림에 쓰고, 실시간 이야기는 나중에 하라.

함정 5번과 6번: "배송 완료"는 증명이 아니며, 장애 훈련이 필요하다

"배송 완료"는 운송사의 주장이지 고객의 주장이 아니다. 리컨실리에이션(정산)이 최후의 방어선이다:

매주 리컨실리에이션을 돌려라: 배송 완료로 표시된 건에 대해 배송 증명 기록이나 고객 확인을 스팟 체크하라.
고액 주문은 POD(배송 증명) 반환을 필수로 하고, 상태 코드만으로 끝내지 마라. 임계값은 직접 정하라—예: $500을 초과하는 배송.
"배송 완료" 상태에서 48시간 이내에 고객이 미수령을 보고하면 → 자동으로 예외로 플래그하고 지원 워크플로우를 가동하라. 고객이 찾아오기를 기다리지 마라.

go-live 당일 밤 체크리스트(출력해서 한 칸씩 체크):