배송 추적 데이터를 Oms에 연결하는 방법: 주문 매핑 및 동기화 규칙
배송 추적 데이터를 주문 관리 시스템(OMS)에 연결하려면 추적되는 각 패키지를 내부 배송 기록에 매핑한 다음, 해당 배송을 주문 및 주문 처리 라인에 연결합니다. 공급자가 지원하는 인터페이스를 통해 추적 업데이트를 수신하고, 원본 이벤트를 보존하며, 중복, 지연 업데이트, 배송 상태 및 주문 완료에 대한 명시적인 규칙을 적용합니다. 추적 번호만 주문 식별자로 사용하거나 단일 배송 이벤트로 여러 패키지로 구성된 주문을 자동으로 종료하지 마십시오.
이 가이드는 이러한 연결을 구현하는 통합 엔지니어와 이커머스 운영팀을 위한 것입니다. 권장 설계는 운송업체의 관찰 결과와 비즈니스 의사결정을 분리합니다. 추적 데이터는 패키지의 이동 경로를 설명하고, OMS는 해당 이동 경로가 주문 처리, 고객 커뮤니케이션 및 주문 종료에 어떤 의미를 갖는지 결정합니다.
각 기록을 소유하는 시스템을 정의합니다
API 연결을 구축하기 전에 OMS 관리자, 주문 처리팀 및 고객 서비스팀과 소유권에 합의하십시오. 그렇지 않으면 기술적으로 성공한 통합이라도 유효한 비즈니스 데이터를 덮어쓸 수 있습니다.
- OMS: 주문, 주문 라인, 필요 수량, 취소 및 주문 완료 규칙을 소유합니다.
- 주문 처리 시스템: 패킹 할당 및 라벨 할당을 포함하여 생성하는 배송 또는 패키지 기록을 소유합니다. 이는 OMS 자체일 수도 있고 별도의 창고 시스템일 수도 있습니다.
- 추적 제공업체: 추적 관찰 결과와 제공업체가 정의한 상태 분류를 제공합니다.
- 통합 계층: 식별자 상호 참조, 이벤트 처리, 정규화, 재시도 처리 및 동기화 감사 기록을 소유합니다.
이러한 구분을 소프트웨어에 대한 가정이 아닌 권장 경계로 취급하십시오. 예외를 문서화하십시오. 예를 들어 창고에서 배송 라벨을 교체할 수 있다면, 통합 시스템은 새로 관찰된 번호가 이전 번호를 대체한다고 추측하지 말고 해당 시스템으로부터 명시적인 업데이트를 받아야 합니다.
상태를 동기화하기 전에 주문과 패키지의 매핑을 구축합니다
실용적인 관계는 주문 → 주문 처리 → 패키지 → 추적 할당입니다. OMS에서 다른 이름을 사용하거나 일부 기록을 결합할 수도 있습니다. 데이터베이스 구조가 다르더라도 관계는 보존하십시오.
주문에는 여러 주문 처리가 포함될 수 있고, 하나의 주문 처리에는 여러 패키지가 포함될 수 있습니다. 패키지에는 교체 추적 할당이나 연결된 라스트마일 식별자가 추가될 수도 있습니다. 이러한 식별자는 주문 수량을 추가로 생성해서는 안 됩니다.
| 기록 | 권장 필드 | 목적 |
|---|---|---|
| 주문 | 테넌트 또는 스토어 ID, 변경 불가능한 OMS 주문 ID | 판매자를 구분하고 화면에 표시되는 주문 번호에 대한 의존을 방지합니다. |
| 주문 처리 | 주문 처리 ID, 주문 ID, 할당된 라인 ID 및 수량 | 구매한 항목 중 어떤 항목이 처리되는지 식별합니다. |
| 패키지 | 내부 패키지 ID, 주문 처리 ID, 가능한 경우 패키지 할당 | 추적 라벨과 무관한 안정적인 식별자를 제공합니다. |
| 추적 할당 | 할당 ID, 패키지 ID, 제공업체 계정, 운송업체 식별자, 추적 번호, 활성 기간 | 수신되는 추적 관찰 결과를 올바른 패키지 및 할당 수명 주기에 연결합니다. |
저장된 상호 참조를 통해 업데이트를 매칭합니다
배송이 생성되면 추적 등록 전에 내부 ID를 저장합니다. 문서화된 등록 프로세스에서 반환되는 제공업체 발급 추적 기록 ID도 저장합니다. 제공업체가 판매자 참조를 지원하는 경우 불투명한 내부 참조를 사용하고 매핑을 로컬에 보관합니다.
수신 업데이트의 경우 먼저 올바른 제공업체 계정과 테넌트 내에서 저장된 제공업체 기록 ID를 확인합니다. 해당 식별자를 사용할 수 없다면 문서화된 추적 번호, 운송업체 식별 정보, 계정 컨텍스트 및 할당 이력의 조합을 사용합니다. 이를 조회 전략으로 취급해야 하며, 해당 조합이 전역적으로 고유하다는 보장으로 간주해서는 안 됩니다.
고객 이름, 이메일 주소 또는 범위가 지정되지 않은 화면 표시 주문 번호로 매칭하지 마십시오. 앞부분의 0이 유지되도록 추적 번호를 문자열로 보존합니다. 관련 운송업체 또는 제공업체 계약에서 정규화를 허용하지 않는 한 문자를 제거하거나 대소문자를 변경하지 마십시오.
조회 결과가 일치 항목을 찾지 못하거나 여러 후보가 반환되면 조사를 위해 해당 업데이트를 격리합니다. 해결되지 않은 이벤트가 잘못된 고객의 주문을 확신에 차서 업데이트하는 것보다 안전합니다.
패키지 할당을 임의로 생성하지 않고 분할 주문을 처리합니다
세 개 단위로 구성된 예시 주문을 생각해 보십시오. 패키지 A에는 두 단위가 들어 있고 패키지 B에는 한 단위가 들어 있습니다. 패키지 A가 배송되었다는 것은 두 단위에 배송 증거가 있다는 의미이지, 주문 전체가 배송되었다는 의미는 아닙니다.
주문 처리 시스템에 두 패키지가 동일한 주문 처리에 속한다는 사실만 기록되어 있다면 단위 수준의 할당을 임의로 만들지 마십시오. 필요한 모든 패키지가 배송되었는지는 계산할 수 있지만, 할당 데이터가 존재할 때까지 항목 수준의 배송 보고는 제공하지 않거나 명시적으로 불확실한 상태로 유지해야 합니다.
내구성 있는 수집 계층을 통해 추적 API를 연결합니다
제공업체와의 통신을 OMS 쓰기 작업과 분리하는 파이프라인을 사용하십시오.
배송 생성 → 추적 등록 → 수신 업데이트 또는 예약 조회 → 내구성 있는 이벤트 저장 → 매핑 및 정규화 → OMS 업데이트 → 조정
17TRACK 구현의 경우 Tracking API 제품 페이지와 공식 API 문서가 관련 시작점입니다. 어댑터를 구현하기 전에 적용 가능한 등록 인터페이스, 운송업체 식별자, 업데이트 전달 옵션, 인증 요구 사항, 상태 정의 및 계정 제한을 확인하십시오. 이 가이드의 데이터 모델은 통합 권장 사항이며, 17TRACK이 이러한 필드 이름을 사용하거나 OMS용 네이티브 커넥터를 제공한다는 주장이 아닙니다.
선택한 제공업체가 웹훅을 지원한다면 문서화된 메커니즘을 사용하여 수신 요청을 인증하고, 승인된 메시지를 확인 응답하기 전에 내구성 있게 저장하십시오. 느린 OMS 작업은 요청 처리 경로 밖에서 수행하십시오. 특정 응답 본문이나 타임아웃을 가정하지 말고 제공업체의 실제 확인 및 재시도 계약을 따르십시오.
폴링이 필요한 경우 API가 지원하는 범위에서 조회 진행 상태를 저장하고 동시성을 제어하며 문서화된 속도 제한을 따르십시오. 웹훅 수신이나 성공적인 폴링 요청만으로 OMS가 업데이트되었다는 사실이 증명되지는 않으므로 해당 결과를 별도로 기록하십시오.
재시도와 지연 이벤트에도 견디는 동기화 규칙을 정의합니다
1. 처리를 멱등적으로 만듭니다
동일한 관찰 결과를 두 번 처리해도 배송이 중복 생성되거나 수량이 두 번 진행되거나 동일한 고객 알림이 다시 전송되어서는 안 됩니다. HTTP는 임의의 POST 작업을 멱등적으로 만들지 않으므로 통합 시스템이 중복 방지를 구현해야 합니다. RFC 9110은 HTTP 메서드 멱등성을 설명합니다.
문서화되어 있고 사용 가능한 경우 안정적인 제공업체 이벤트 ID를 사용하십시오. 그렇지 않다면 할당 ID와 이벤트 타임스탬프, 원본 상태 및 위치와 같은 관련 이벤트 필드로 지문을 정의하십시오. 충돌이나 변경된 이벤트 설명의 가능성을 문서화하십시오. 원본 관찰 결과가 추가 OMS 작업을 발생시키지 않더라도 이를 보관하십시오.
각 부수 효과를 별도로 보호하십시오. 예를 들어 OMS 상태 쓰기와 이메일 알림에는 각각 자체 중복 제거 제어가 필요합니다. 트랜잭션 아웃박스 또는 이에 상응하는 내구성 있는 작업 기록을 사용하여 프로세스 충돌로 인해 승인된 이벤트가 예약된 업데이트 없이 남지 않도록 하십시오.
2. 이벤트 시간과 수신 시간을 별도로 저장합니다
이벤트가 발생한 시간과 통합 시스템이 이를 수신한 시간은 서로 다른 질문에 답합니다. 원래 타임스탬프 표현과 제공된 시간대 오프셋을 함께 두 값을 모두 저장하십시오. 시간대를 알 수 없는 이벤트에 창고 시간대를 조용히 할당하지 마십시오.
늦게 도착한 운송 중 스캔은 일반적으로 최신 배송 완료 상태를 대체하지 않고 이력을 보강해야 합니다. 그러나 제공업체가 정정을 발행할 수 있고 이벤트의 시간 정보가 불완전할 수 있으므로 타임스탬프만으로는 충분하지 않습니다. 가능한 경우 문서화된 시퀀스 또는 수정 필드와 명시적인 정정 정책을 함께 사용하십시오.
3. 원본 세부 정보를 삭제하지 않고 상태를 정규화합니다
OMS가 이해할 수 있는 소규모 내부 용어를 만드십시오. 예를 들어 운송업체 인수 대기, 운송 중, 배송 출발, 배송 완료, 예외 및 반송 중 등이 있습니다. 제공업체의 문서화된 상태를 이에 매핑하십시오. 이는 제안된 내부 분류이며 모든 운송업체에 보편적으로 적용되는 정의가 아닙니다.
원본 상태 코드, 설명, 이벤트 위치, 제공업체 기록 참조 및 매핑 규칙 버전을 저장하십시오. 매핑되지 않은 값은 배송 완료 또는 실패로 기본 설정하지 말고 검토 가능한 조건을 생성해야 합니다. 출처 이벤트가 해당 해석을 명시적으로 지원하지 않는 한 라벨 생성은 실제 운송업체 인수의 증거로 취급해서는 안 됩니다.
4. 단순한 숫자 순위가 아니라 전환 규칙을 사용합니다
배송 상태가 항상 직선적인 순서를 이루는 것은 아닙니다. 예외 뒤에 정상적인 운송이 이어질 수 있고, 배송 시도는 배송 완료가 아닙니다. 이전에 배송 완료 이벤트가 발생한 후 반송 이동이 시작될 수도 있습니다.
- 이후 증거가 운송 재개를 뒷받침하면 예외 상태가 해제되도록 합니다.
- 일반적인 과거 스캔이 배송 완료 상태를 조용히 대체하지 못하도록 합니다.
- 문서화된 정정은 통제된 수정 경로를 통해 허용합니다.
- OMS가 지원하는 경우 반송 이동을 출고 완료와 별도로 추적합니다.
- 모호하거나 모순되는 증거는 운영 큐로 보냅니다.
이러한 규칙에 버전을 부여하십시오. 매핑이 변경될 때 새 이벤트에만 적용할지, 과거 기록에 통제된 재계산이 필요한지 결정하십시오.
필요한 주문 처리 의무를 기준으로 주문 상태를 계산합니다
패키지 상태와 주문 상태는 별도의 필드여야 합니다. 배송 완료로 표시된 패키지는 해당 패키지에 대한 증거를 제공하지만, 주문 완료 여부는 남아 있는 필요 수량과 비즈니스 정책에 따라 결정됩니다.
유용한 기본 규칙은 배송이 필요한 모든 수량에 유효한 패키지 수준의 배송 완료 증거가 있고 해결되지 않은 필수 할당이 남아 있지 않을 때만 주문을 완전히 배송된 것으로 표시하는 것입니다. OMS의 취소 규칙에 따라 취소된 수량을 제외하십시오. 디지털 상품, 픽업 주문 및 기타 비배송 의무는 자체 완료 조건으로 처리하십시오.
교체 배송에는 명시적인 관계가 필요합니다. 분실 패키지를 교체하는 경우 교체품이 원래 배송 의무를 대체하는지 결정하십시오. 그렇지 않으면 원래 패키지가 완료를 무기한 차단하거나 두 패키지가 모두 주문 처리에 포함될 수 있습니다. 추적 상태만으로 도출하지 말고 결정을 기록하십시오.
배송 완료를 재무 종료, 환불 자격 및 분쟁 해결과 분리하십시오. 운송업체의 배송 이벤트가 자동으로 환불을 승인하거나 고객 청구를 종결해서는 안 됩니다.
감사 추적을 잃지 않고 장애에서 복구합니다
제한된 백오프와 문서화된 재시도 지침을 사용하여 일시적인 장애를 재시도하십시오. 일시적인 연결 실패를 잘못된 식별자, 만료된 자격 증명, 권한 오류 및 스키마 비호환성과 구분하십시오. 후자의 경우에는 무한 재시도가 아니라 수정 조치가 필요합니다.
영향받은 테넌트, 패키지, 이벤트 참조, 시도한 작업, 오류 분류 및 다음 조치를 포함하는 실패 작업 큐를 유지하십시오. 불필요한 고객 데이터나 자격 증명을 로그에 복사하지 않고 조사에 충분한 컨텍스트를 기록하십시오.
정상 업데이트 경로와 함께 조정을 실행하십시오. 오래된 추적 정보가 있는 활성 배송, OMS 쓰기에 실패한 승인 이벤트, 매칭되지 않은 관찰 결과, 통합 시스템의 계산 상태와 OMS 간 차이를 검토하십시오. 검토 빈도는 임의의 보편적 일정이 아니라 배송 약속, API 제한 및 운영 위험에 따라 정하십시오.
소유권을 할당하십시오. 엔지니어링은 수집 및 쓰기 실패를 처리하고, 주문 처리 운영팀은 누락된 패키지 관계를 해결하며, 고객 서비스팀은 고객 커뮤니케이션이 필요한 예외를 검토합니다. 책임자가 없는 큐는 단순한 저장 위치일 뿐입니다.
출시 전에 매핑과 비즈니스 규칙을 테스트합니다
통제된 테스트 데이터와 제한된 프로덕션 롤아웃을 사용하십시오. 이벤트 이력과 그 결과 생성된 OMS 기록을 모두 대상으로 다음 사례를 테스트하십시오.
- 단일 패키지 주문이 정상적으로 배송까지 진행됩니다.
- 분할 주문에서 한 패키지는 배송 완료되고 다른 패키지는 아직 이동 중입니다.
- 동일한 이벤트가 반복 수신되어도 부수 효과가 중복되지 않습니다.
- 배송 완료 후 더 오래된 운송 중 스캔이 도착합니다.
- 알 수 없는 운송업체 또는 상태가 검토 큐에 들어갑니다.
- 추가 주문 처리 의무를 생성하지 않고 라벨이 교체됩니다.
- 승인된 규칙에 따라 교체 배송이 원래 패키지를 대체합니다.
- 이벤트가 승인된 후 OMS를 사용할 수 없게 됩니다.
- OMS 쓰기와 확인 응답 사이에 프로세스가 재시작됩니다.
- 테넌트 간 매칭 없이 두 스토어에 동일한 화면 표시 주문 번호가 존재합니다.
모든 승인된 이벤트에 추적 가능한 처리 결과가 있고, 모호한 매칭이 주문을 자동으로 업데이트할 수 없으며, 운영자가 실패 작업을 안전하게 재생할 수 있을 때 출시하십시오. 이는 API 요청이 성공한다는 사실만 입증하는 것보다 유용한 승인 기준입니다.
FAQ
추적 번호를 주문에 직접 연결할 수 있나요?
엄격하게 단일 패키지로 처리되는 업무 흐름에서는 처음에 직접 관계를 사용하는 것으로 충분할 수 있습니다. 그래도 주문과 추적 할당 사이에 내부 배송 식별자를 사용하십시오. 이를 통해 주문 기록의 의미를 변경하지 않고 분할 배송, 라벨 변경 및 교체를 위한 마이그레이션 경로를 확보할 수 있습니다.
통합에 웹훅과 폴링 중 어떤 방식을 사용해야 하나요?
제공업체가 지원하고 인프라와 호환되는 전달 방식을 사용하십시오. 웹훅은 반복 조회를 줄일 수 있고, 폴링은 가능한 경우 조회 기반 업무 흐름과 조정을 지원할 수 있습니다. 어느 방식도 내구성 있는 저장, 중복 처리 및 복구의 필요성을 없애지는 않습니다.
추적 이벤트에 일치하는 주문이 없으면 어떻게 해야 하나요?
이를 매칭되지 않은 이벤트 큐에 저장하고 등록 기록, 테넌트 컨텍스트, 운송업체 식별 정보 및 배송 생성 시점을 조사하십시오. 자동으로 주문을 생성하거나 그럴듯한 고객에게 이벤트를 연결하지 마십시오. 매핑이 수정된 후 재생하십시오.
배송 알림은 OMS에서 보내야 하나요, 아니면 추적 시스템에서 보내야 하나요?
각 알림 유형과 트리거에 대해 한 시스템을 소유자로 선택하십시오. 두 시스템이 동일한 메시지를 보낼 수 있다면 한 경로를 비활성화하거나 내구성 있는 알림 원장을 공유하십시오. 특히 분할 주문 처리에서는 메시지가 하나의 패키지를 가리키는지 전체 주문을 가리키는지도 결정하십시오.
예외 상태는 주문이 실패했다는 의미인가요?
아닙니다. 예외는 반드시 영구적인 결과를 의미하는 것이 아니라 해석이 필요한 관찰 결과입니다. 사유를 보존하고 후속 이벤트를 모니터링하며, 운영팀이 개입해야 하는 시점을 에스컬레이션 정책으로 결정하십시오.
출처
- 17TRACK Tracking API — API 통합 시작점에 대한 공식 제품 참조입니다.
- 17TRACK API documentation — 제공업체별 계약을 구현하기 위한 참조 자료입니다. 배포 전에 적용 가능한 인터페이스와 계정 요구 사항을 확인하십시오.
- RFC 9110, Section 9.2.2: Idempotent Methods — 메서드 멱등성과 애플리케이션 수준의 중복 방지를 구분하는 HTTP 의미 체계를 설명합니다.


