추적 API는 어떤 데이터를 반환해야 할까요? 현재 상태 외에 필요한 12개 필드는 무엇일까요?
트래킹 API는 “배송 중”과 같은 라벨만 반환해서는 안 됩니다. 현재 상태를 넘어 배송 식별자, 운송사 정보, 자세한 상태 정보, 운송사의 원문 메시지, 이벤트 이력, 이벤트 타임스탬프, 위치, 배송 예정 정보, 예외 사항, 운송사 인계 정보, 배송 세부 정보, 데이터 최신성 메타데이터를 확인해야 합니다. 이 12개 데이터 그룹은 개발자가 신뢰할 수 있는 워크플로를 구축하고 운영팀이 조치를 취하는 데 필요한 충분한 맥락을 제공합니다.

이는 개발자, 기술 구매 담당자, 이커머스 운영팀을 위한 권장 응답 계약이며, 모든 운송사 또는 API가 모든 필드를 제공한다는 의미는 아닙니다. 일부 값은 정당한 이유로 제공되지 않을 수 있습니다. 더 나은 설계는 이러한 공백을 추정으로 채우기보다 명시적으로 나타냅니다.
트래킹 데이터를 유용하게 만드는 요소는 무엇인가?
현재 상태는 배송의 요약된 상태가 무엇인지라는 한 가지 좁은 질문에 답합니다. 하지만 반드시 어떤 일이 발생했는지, 언제 발생했는지, 정보가 최신인지, 다음에 무엇을 해야 하는지는 설명하지 않습니다.
예를 들어 두 배송 모두 “배송 중”으로 표시되지만 서로 다른 대응이 필요할 수 있습니다. 하나는 최근 시설 스캔이 있고 보고된 문제가 없을 수 있습니다. 다른 하나는 이벤트 이력에 해결되지 않은 주소 문제가 기록되어 있을 수 있습니다. 헤드라인 상태만 읽는 애플리케이션은 이러한 차이를 놓칠 수 있습니다.
응답을 세 가지 실무 작업에 따라 평가하세요. 배송을 올바른 주문과 연결하고, 배송 진행 상황을 정확하게 설명하며, 조치가 필요한지 판단하는 것입니다. 다음 필드가 이러한 작업을 지원합니다. 필드 이름은 예시일 뿐이며, 보편적인 표준이나 특정 제공업체의 스키마가 아닙니다.
현재 상태 외에 평가해야 할 12개 필드
1. 배송 및 트래킹 식별자
응답은 설명 대상인 배송을 식별해야 합니다. 유용한 값에는 제출된 트래킹 번호, API의 트래킹 기록 식별자, 시스템에서 주문 처리 또는 패키지 기록과 매핑할 수 있는 고객 참조가 포함됩니다.
하나의 주문이 하나의 배송과 같다고 가정하지 마세요. 주문은 여러 패키지로 분할될 수 있고, 교체품으로 인해 다른 배송이 생성될 수 있습니다. 트래킹 기록은 패키지 또는 주문 처리 단위로 저장한 다음 주문과 연결하세요. 형식과 앞자리 0이 손실되지 않도록 트래킹 번호를 문자열로 보존하세요.
2. 운송사 정보
읽기 쉬운 운송사 이름과 함께 안정적인 운송사 식별자를 확인하세요. 가능한 경우 응답은 애플리케이션이 명시적으로 제공한 운송사와 자동 감지를 통해 선택된 운송사를 구분해야 합니다.
트래킹 번호와 이벤트를 해석할 때 운송사 맥락이 중요합니다. 감지가 모호한 경우 통합 시스템에는 이를 해결할 방법이 있어야 하며, 불확실한 일치 결과를 확인된 것으로 조용히 표시해서는 안 됩니다. 서비스 수준 정보는 별도로 유지하세요. 운송사 이름만으로는 배송이 특급, 우편 또는 기타 서비스 중 무엇을 사용하는지 알 수 없습니다.
3. 정규화된 상태 세부 정보
주요 상태와 함께 문서화된 세부 코드 또는 하위 상태를 요청하세요. 광범위한 범주는 배송을 예외로 설명할 수 있지만, 세부 정보는 배송 시도, 주소 문제 또는 통관 관련 보류를 식별합니다.
비즈니스 로직에는 안정적인 코드를 사용하고 화면 표시에는 읽기 쉬운 라벨을 사용하세요. 알 수 없거나 매핑되지 않은 이벤트를 처리하는 방법을 포함해 제공업체가 운송사 이벤트를 해당 코드로 매핑하는 방식을 확인하세요. 정규화된 라벨은 서로 다른 운송사 피드를 더 쉽게 사용할 수 있게 하지만, 지원팀에 필요한 차이까지 지워서는 안 됩니다.
4. 운송사의 원본 메시지 및 코드
제공되는 경우 원본 이벤트 설명과 운송사 이벤트 코드를 보존하세요. 특히 운송사가 특정 운영 문구를 사용하는 경우, 이러한 값은 정규화된 상태에는 없는 맥락을 지원 담당자에게 제공합니다.
원본 텍스트를 번역되거나 다시 작성된 설명과 분리하세요. 그렇지 않으면 고객에게 제공되는 설명을 운송사의 정확한 문구로 오인할 수 있습니다. 운송사 텍스트를 표시할 때는 신뢰할 수 없는 입력으로 취급하세요. 적절히 이스케이프하고 실행 가능한 HTML로 렌더링하지 마세요.
5. 트래킹 이벤트 이력
유용한 응답은 최신 이벤트뿐 아니라 배송 타임라인을 노출해야 합니다. 각 이벤트에는 이상적으로 식별자, 상태 또는 코드, 설명, 타임스탬프, 가능한 위치 정보가 포함되어야 합니다.
API가 전체 이력, 제한된 기간 또는 페이지로 나뉜 결과를 반환하는지 확인하세요. 수정 사항과 중복 관찰 결과가 어떻게 표시되는지도 정립해야 합니다. 응답 계약에서 정렬 순서를 명시적으로 보장하지 않는 한 첫 번째 항목이 항상 최신 항목이라고 가정해서는 안 됩니다.
6. 이벤트 타임스탬프 및 시간대 정보
이벤트가 발생한 시간은 API가 이벤트를 수신하거나 반환한 시간과 다릅니다. 가능한 경우 두 시간을 모두 보존하세요. 이러한 구분은 새로 수신된 업데이트가 이전에 발생한 일을 설명할 수 있는 이유를 이해하는 데 도움이 됩니다.
명시적인 UTC 오프셋 또는 UTC 표기가 포함된 타임스탬프를 요청하세요. RFC 3339는 숫자 형식의 시간 오프셋을 포함해 인터넷 프로토콜에 적합한 타임스탬프 형식을 정의합니다. 출처가 알려진 오프셋 없이 현지 시간만 제공하는 경우 이를 조용히 UTC로 취급하지 말고 불확실성을 보존하세요. 기본 출처가 날짜만 제공하는 경우 초 단위 정밀도가 있다고 암시하지 마세요.
7. 이벤트 위치 및 배송 지리 정보
제공되는 경우 도시, 지역, 국가, 우편번호와 같은 구조화된 위치 구성 요소를 확인하세요. 구조화된 필드로 변환하면 의미가 손실될 수 있는 경우 원시 위치 문자열도 보존하세요.
스캔 위치가 반드시 패키지의 실시간 위치인 것은 아닙니다. 마찬가지로 마지막으로 보고된 시설이 소포가 여전히 그곳에 있다는 증거도 아닙니다. 고객에게 표시되는 페이지에서는 이를 가장 최근에 보고된 위치로 설명해야 합니다. 불완전한 스캔 텍스트에서 좌표나 정확한 배송 주소를 추론하지 마세요.
8. 배송 예정일 또는 기간
배송 예정 필드는 단일 날짜인지 기간인지, 누가 생성했는지, 마지막으로 언제 업데이트되었는지를 식별해야 합니다. 운송사가 제공한 예상치와 별도로 계산된 예측치는 서로 구분해야 합니다.
날짜만 있는 예상치를 정확한 도착 시간으로 변환하지 마세요. 통합 시스템은 수정되거나 철회된 예상치도 처리해야 하며, 트래킹 페이지에 오래된 약속을 계속 표시해서는 안 됩니다. 예상치가 없으면 근거 없는 가정으로 계산하지 말고 사용할 수 없다고 표시하세요.
9. 예외 사유 및 필요한 조치
예외 정보는 문제를 설명하고, 출처가 지원하는 경우 조치, 책임 주체 또는 기한을 식별해야 합니다. 일반적인 지연 알림은 수취인 정보 요청과 운영상 서로 다릅니다.
보고된 사실과 자체 워크플로 결정을 분리하세요. 예를 들어 비즈니스는 일정 기간 업데이트가 없으면 지원 작업을 생성할 수 있습니다. 이는 내부 에스컬레이션 규칙이지 운송사가 소포를 분실로 선언했다는 증거가 아닙니다. 모호한 트래킹 텍스트에서 결제 안내나 민감한 정보 요청을 생성하지 마세요.
10. 운송사 인계 및 관련 트래킹 번호
배송이 운송 사업자 간에 이동하는 경우 유용한 데이터에는 다음 운송사, 관련 트래킹 번호, 원래 기록과 후속 기록 간의 관계가 포함됩니다. 배송 구간에서 다른 식별자를 사용하는 경우에도 이러한 정보는 연속성을 유지하는 데 도움이 됩니다.
보고된 인계를 원래 운송사를 덮어쓰는 대신 관계로 취급하세요. 목적지나 트래킹 번호가 비슷해 보인다는 이유만으로 기록을 병합하지 마세요. 관계가 제공되지 않았거나 다른 방식으로 확인되지 않은 경우 연속적인 여정을 만들어 내지 말고 미해결 상태로 유지하세요.
11. 배송 결과 및 증빙 참조
배송이 보고되면 응답은 기록된 배송 시간과 안전한 장소 설명 또는 수취인 유형과 같은 이용 가능한 배송 세부 정보를 제공해야 합니다. 운송사와 서비스에서 제공하는 경우 배송 증빙 참조도 유용할 수 있습니다.
배송 완료 상태를 의도한 수취인이 직접 소포를 수령했다는 증거로 취급해서는 안 됩니다. 서명, 사진, 이름, 정확한 위치에는 개인정보가 포함될 수 있습니다. 접근을 제한하고 공개 트래킹 페이지에 이러한 세부 정보를 노출하지 않으며, 증빙 링크에 필요한 승인 또는 만료 요건을 확인하세요.
12. 최신성, 조회 상태 및 응답 메타데이터
최신 배송 이벤트와 가장 최근에 성공한 데이터 조회를 구분할 수 있을 만큼 충분한 메타데이터를 요청하세요. 유용한 값에는 마지막 성공 확인 시간, 마지막 실패 시도, 응답 생성 시간, 반환된 데이터가 캐시되었는지 또는 부분적인지가 포함됩니다.
API 요청이 성공했다고 해서 운송사가 새로운 스캔을 게시했다는 의미는 아닙니다. HTTP 응답 의미론은 요청 결과를 설명하며, 배송 진행 상황은 애플리케이션 데이터에 속합니다. 일시적인 연결 문제가 잘못된 배송 알림으로 변하지 않도록 조회 오류와 배송 예외를 별도로 보존하세요.
누락된 데이터에는 정의된 의미가 필요합니다
필드의 존재 여부는 계약의 일부일 뿐입니다. 팀은 값이 없는 것이 무엇을 의미하는지도 이해해야 합니다. 배송 예정 정보가 출처에서 제공되지 않았거나, 아직 조회되지 않았거나, 배송 후 적용되지 않을 수 있습니다. 이러한 상황에 동일한 고객 메시지를 자동으로 생성해서는 안 됩니다.
- 알 수 없음: 값이 아직 확인되지 않았습니다.
- 제공되지 않음: 출처가 조회된 데이터에 해당 값을 제공하지 않았습니다.
- 해당 없음: 해당 필드가 이 기록 또는 상태에 적용되지 않습니다.
- 조회 실패: 시스템이 관련 조회를 완료하지 못했습니다.
이는 권장되는 구분이며, 반드시 이러한 리터럴 값을 사용해야 한다는 의미는 아닙니다. 어떤 표현을 선택하든 문서화하세요. 자리 표시자 날짜, 유효한 기록처럼 보이는 빈 객체, 실제 위치로 오인될 수 있는 기본 좌표를 사용하지 마세요.
통합 전에 응답을 테스트하는 방법
비즈니스에서 사용하는 운송사, 서비스, 배송 경로의 실제 페이로드를 평가하세요. 스키마에 선택적 필드가 나열되어 있어도 모든 기본 출처가 해당 필드를 채운다는 보장은 없습니다. 17TRACK 통합의 경우 이 가이드의 개념적 필드 이름을 그대로 사용할 수 있는 매개변수로 취급하지 말고 공식 Tracking API 문서에서 응답 계약을 확인하세요.
- 대표 샘플을 구축하세요. 새로 등록된 배송, 진행 중인 배송, 배송 시도, 완료된 배송, 이용 가능한 인계 사례를 포함하세요.
- 필드를 이벤트까지 추적하세요. 표시된 상태, 최신 이벤트, 배송 세부 정보가 일관된 기록을 설명하는지 확인하세요. 불일치를 숨기지 말고 조사하세요.
- 지연 및 반복 업데이트를 테스트하세요. 동일한 페이로드를 다시 처리하고 최신 이벤트 이후 오래된 이벤트를 수신하세요. 두 경우 모두 중복 알림이 생성되거나 표시 상태가 잘못 되돌아가지 않는지 확인하세요.
- 누락되거나 잘못된 값을 테스트하세요. 예상치 누락, 알 수 없는 위치, 익숙하지 않은 상태 코드, 불완전한 타임스탬프를 포함하세요. 대체 값을 임의로 만들지 않고도 애플리케이션을 사용할 수 있어야 합니다.
- 전송 실패와 트래킹 결과를 분리하세요. 인증 실패, 시간 초과 또는 잘못된 응답은 배송 예외 워크플로가 아니라 통합 오류 경로로 처리해야 합니다.
- 고객 화면을 검증하세요. 내부 참조, 원시 진단 세부 정보, 개인정보가 공개 페이지나 알림에 유출되지 않는지 확인하세요.
웹훅 기반 업데이트의 경우 제공업체 문서에서 전달 식별자, 인증, 재시도 동작, 재생 처리도 확인하세요. 이는 배송 사실이 아니라 통합 요구 사항입니다. 수신기는 반복 전달을 안전하게 처리해야 하며 도착 순서가 이벤트 순서와 같다고 가정해서는 안 됩니다.
실용적인 승인 기준은 다음과 같아야 합니다. 애플리케이션이 근거 없는 주장을 하지 않고 배송을 설명할 수 있는가? 운영팀이 다음에 정당하게 취할 조치를 식별할 수 있는가? 설명되지 않은 선택적 값으로 가득 찬 큰 응답보다 작고 잘 정의된 페이로드가 더 유용할 수 있습니다.
FAQ
모든 배송에 12개 데이터 그룹이 모두 채워져야 하나요?
아니요. 배송 증빙, 후속 트래킹 번호, 배송 예정일은 제공되지 않거나 적용되지 않을 수 있습니다. 모든 필드를 채우도록 요구하기보다 명확한 필드 정의와 예측 가능한 누락 값 동작을 요구하세요. 실제 배송 구성에서 가장 중요한 필드를 확인하세요.
원시 응답을 저장해야 하나요, 아니면 정규화된 필드만 저장해야 하나요?
애플리케이션 로직에는 정규화된 필드를 저장하세요. 관련 원본 페이로드를 보존하면 디버깅과 매핑 변경에도 도움이 될 수 있지만, 개인정보 보호, 보안, 계약, 보존 요건을 따라야 합니다. 접근을 제한하고 응답에 포함되었다는 이유만으로 민감한 콘텐츠를 보존하지 마세요.
최신 이벤트를 결정할 때 어떤 타임스탬프를 사용해야 하나요?
시간대와 수정 사항을 고려하면서 문서화된 이벤트 시간 순서와 제공업체의 정렬 규칙을 사용하세요. 수신 시간은 시스템이 이벤트를 알게 된 시점을 나타내며, 반드시 이벤트가 발생한 시점은 아닙니다. 타임스탬프가 불완전하거나 서로 충돌하는 경우 정확한 순서를 주장하지 말고 모호성을 보존하세요.
트래킹 API가 패키지 분실을 확인할 수 있나요?
출처가 해당 해석을 명시적으로 지원하는 경우에만 분실을 운송사가 보고한 것으로 취급하세요. 장기간 스캔이 없으면 운영 규칙에 따라 조사를 시작할 수 있지만, 침묵만으로 분실이 확정되지는 않습니다. “오래된 트래킹”과 “분실 보고됨”을 별도의 개념으로 유지하세요.
배송 완료 상태만으로 고객 불만을 종결해도 되나요?
자동으로는 안 됩니다. 이는 보고된 트래킹 결과를 확정하지만 수취인의 이의를 해결하지 못할 수 있습니다. 이용 가능한 배송 세부 정보, 고객 계정, 지원 프로세스를 검토하세요. 상태 라벨을 상충하는 정보를 조사하는 대신 사용하지 마세요.
출처
- 17TRACK Tracking API documentation — 통합에 문서화된 필드와 동작을 확인하기 위한 제품별 참조 자료이며, 위의 12개 그룹은 편집상 권장 사항으로 해당 스키마를 재현한 것이 아닙니다.
- RFC 3339: Date and Time on the Internet: Timestamps — 타임스탬프 표현 및 시간 오프셋 규칙.
- RFC 9110: HTTP Semantics — 배송 수준의 비즈니스 상태와 구분되는 HTTP 응답 의미론.


