배송 추적 API를 사용하여 사전 배송 알림을 보내는 방법
배송 추적 API로 선제적인 배송 알림을 보내려면 각 패키지를 주문에 연결하고, 추적 업데이트를 수집하며, 해당 업데이트를 고객과 관련된 이벤트로 변환한 다음 이메일, SMS 또는 앱 알림 서비스를 통해 메시지를 트리거하세요. 수신되는 추적 데이터와 발신 메시지 사이에 내구성 있는 큐와 중복 확인을 배치하여 반복되거나 지연된 업데이트로 인해 혼란스러운 알림이 발생하지 않도록 하세요.
이 가이드는 이러한 워크플로를 구축하는 개발자와 이커머스 운영팀을 위한 것입니다. 목표는 모든 운송업체 스캔을 전달하는 것이 아닙니다. 중요한 변화가 발생했을 때 고객에게 알리고, 그 변화가 무엇을 의미하는지 설명하며, 고객이 조치를 취해야 하는지 알려주는 것입니다.
API를 연결하기 전에 알림 워크플로를 설계하세요
배송 추적 API는 추적 정보를 제공하지만, 이를 어떻게 사용할지는 애플리케이션이 결정합니다. 선택한 서비스가 두 기능을 모두 제공하더라도 배송 가시성과 고객 커뮤니케이션을 별도의 책임으로 다루세요.
실용적인 아키텍처는 다음 6단계로 구성됩니다.
- 주문 연결: 필요한 경우 추적 번호와 운송업체 식별자를 내부 배송 기록에 연결합니다.
- 추적 등록: 제공업체의 통합 요구사항에 따라 배송을 제출하거나 등록합니다.
- 업데이트 수집: 웹훅 콜백을 수신하거나 API 요청을 통해 업데이트를 가져오거나 두 가지 방식을 결합합니다.
- 이벤트 처리: 수신 이벤트를 검증하고, 정규화하고, 중복을 제거하고, 평가합니다.
- 알림 결정: 알림을 보낼지, 누구에게 연락할지, 어떤 채널과 템플릿을 사용할지 선택합니다.
- 메시지 전달: 알림을 보내고 메시징 서비스의 응답을 기록합니다.
통합에 실제로 필요한 경우가 아니라면 고객 연락처 정보는 자체 주문 시스템 또는 메시징 시스템에 보관하세요. 일반적으로 추적 서비스는 애플리케이션이 추적 이벤트를 주문과 연결하기 위해 고객의 이메일 주소를 필요로 하지 않습니다.
1. 통합 계약을 확인하세요
수신기를 작성하기 전에 제공업체의 문서에서 인증, 배송 등록, 운송업체 식별, 지원되는 업데이트 방식, 응답 형식, 요청 제한, 오류 처리를 확인하세요. 웹훅 통합의 경우 콜백 인증 방식, 수신을 확인하는 응답, 실패한 전달의 처리 방식도 확인하세요.
17TRACK 구현의 경우 17TRACK Tracking API 페이지와 공식 API 문서에서 시작하세요. 이 가이드의 예시 필드 이름을 17TRACK 요청 또는 응답 필드로 간주하지 말고 문서화된 계약을 통합에 사용하세요. 구현 전에 콜백 설정, 보안 요구사항 및 계정별 제한을 확인하세요.
통합 계약에 따라 업데이트 방식을 선택하세요.
- 웹훅: 인프라에서 지원되고 적합한 경우 콜백을 사용하세요. 제공업체가 업데이트를 보낼 때 애플리케이션이 이를 처리할 수 있으므로 동일한 배송을 반복해서 요청할 필요가 없습니다.
- 폴링: 콜백을 사용할 수 없거나 적합하지 않을 때 일정에 따라 추적 정보를 가져오세요. 일정이 문서화된 요청 제한을 넘지 않도록 하세요.
- 결합 방식: 일반적인 처리는 콜백으로 수행하고, 제공업체가 해당 워크플로를 지원한다면 업데이트가 오래된 것으로 보이는 배송을 조정하기 위해 선택적으로 API를 조회하세요.
웹훅을 사용한다는 이유만으로 고객에게 즉시 알림을 약속하지 마세요. 상위 추적 데이터에서 운송업체 이벤트를 제공하기 전에는 애플리케이션이 이를 보고할 수 없습니다.
2. 실제 주문을 견딜 수 있는 배송 기록을 구축하세요
기본 참조로 추적 번호만 사용하지 말고 내부 배송 ID를 사용하세요. 하나의 주문에 여러 패키지가 포함될 수 있으며 추적 번호가 영구적으로 전 세계에서 고유하다고 가정해서는 안 됩니다.
유용한 내부 기록에는 다음이 포함됩니다.
- 내부 주문 ID와 배송 ID
- 알려진 경우 추적 번호와 운송업체 식별자
- 제공된 경우 제공업체의 배송 참조 번호
- 현재 정규화된 상태와 최신 의미 있는 이벤트
- 가능한 경우 시간대 또는 오프셋을 포함한 운송업체 이벤트 시간
- 시스템이 업데이트를 수신한 시간
- 고객의 커뮤니케이션 환경설정에 대한 참조
- 알림 기록과 활성화된 예외 워크플로
이벤트 시간과 수신 시간을 별도로 저장하세요. 이전에 발생한 스캔이 더 최신 스캔 이후에 도착할 수 있습니다. 애플리케이션이 도착 순서로만 정렬하면 배송 완료 상태를 배송 중으로 잘못 되돌릴 수 있습니다.
분할 주문의 경우 알림을 영향을 받는 패키지에 연결하세요. 다른 패키지가 아직 이동 중이라면 “주문의 패키지 하나가 도착했습니다”가 “주문이 도착했습니다”보다 정확합니다.
3. 추적 이벤트를 고객의 의사결정에 매핑하세요
운송업체 설명은 운영 데이터이지 바로 사용할 수 있는 고객 메시지가 아닙니다. 원본 이벤트를 보존하면서 알림 규칙이 이해할 수 있는 내부 카테고리를 부여하는 정규화 계층을 구축하세요.
다음 카테고리는 권장되는 애플리케이션 개념이며, 보편적인 API 상태 용어가 아닙니다.
| 내부 카테고리 | 알림 결정 | 메시지 경계 |
|---|---|---|
| 배송 정보 수신 | 유용한 경우에만 준비 업데이트를 보냅니다. | 라벨 생성만으로 운송업체가 실제로 배송물을 보유하고 있다고 암시하지 마세요. |
| 배송 중 | 처음으로 의미 있는 이동이 발생했을 때 알림을 고려합니다. | 고객의 다음 단계가 바뀌지 않는 정기적인 시설 스캔은 억제합니다. |
| 배송 출발 | 지원되는 이벤트가 이 상태를 나타낼 때 알립니다. | 상태를 보장된 도착 시간으로 바꾸지 마세요. |
| 배송 시도 또는 픽업 필요 | 실행 가능한 알림을 보냅니다. | 확인된 경우에만 기한 또는 수령 지침을 포함합니다. |
| 배송 예외 | 원인과 고객이 조치를 취해야 하는지 평가합니다. | 모든 예외를 분실된 소포로 설명하지 마세요. |
| 배송 완료 | 패키지 단위의 확인을 보냅니다. | 수령인, 배송 위치 또는 배송 증명을 지어내지 마세요. |
불확실성을 유지하세요. 인식할 수 없는 이벤트는 가장 가까운 익숙한 카테고리에 억지로 넣지 말고 검토 또는 대체 경로로 보내야 합니다. 문제 해결을 위해 지원 직원이 원본 설명을 확인할 수 있도록 하세요.
4. 작업을 잃거나 중복하지 않고 업데이트를 수신하세요
웹훅 엔드포인트는 요청을 검증하고, 승인된 업데이트를 내구성 있게 저장한 다음, 제공업체가 요구하는 승인을 반환해야 합니다. 콜백 요청 중 이메일 또는 SMS 서비스가 응답할 때까지 기다리지 말고 메시지 생성을 비동기식으로 수행하세요.
제공업체가 문서화한 콜백 검증 방식을 구현하세요. 서명 헤더를 임의로 만들거나 모든 제공업체가 동일한 인증 방식을 사용한다고 가정하지 마세요. 또한 HTTPS, 요청 크기 제한, 페이로드 검증 및 적절한 접근 제어를 적용하세요.
간소화된 처리 흐름은 다음과 같습니다. 이는 애플리케이션 수준의 작업이며 작동하는 SDK 예제가 아닙니다.
receive callback
verify request using documented provider mechanism
validate payload
persist accepted payload and enqueue processing atomically
return documented acknowledgment
process queued update
find internal shipment
normalize relevant events
ignore already-processed events
evaluate chronology and state transition
create notification job if policy permits
commit state and job together
send notification job
check recipient preferences and suppression rules
submit message to messaging service
record result and retry only when appropriate
원자적 단계가 중요합니다. 애플리케이션이 상태 변경을 저장한 후 알림 작업을 생성하기 전에 중단되면 고객은 알림을 받지 못할 수 있습니다. 트랜잭션 아웃박스는 하나의 설계 옵션입니다. 동일한 데이터베이스 트랜잭션에서 상태 변경과 대기 중인 작업을 저장한 다음 워커가 작업을 전달하도록 합니다.
알 수 없는 배송 참조를 명시적으로 처리하세요. 어떤 고객에게 알림을 보내야 하는지 추측하지 말고 조사를 위해 격리하거나 조정 대상으로 보내세요.
5. 중복 방지와 시간 순서 확인을 추가하세요
반복되는 콜백과 워커 재시도를 허용하도록 수신기를 설계하세요. 문서화된 안정적인 제공업체 이벤트 식별자가 있다면 이를 우선 사용하세요. 그렇지 않다면 내부 배송 ID, 이벤트 코드, 이벤트 시간 및 위치와 같은 적절한 필드에서 결정론적 이벤트 지문을 생성하세요. 이 지문에 의존하기 전에 실제 페이로드로 테스트하세요.
이벤트 중복 제거와 알림 억제는 서로 다른 문제를 해결합니다. 중복 제거는 동일한 이벤트가 두 번 처리되는 것을 막습니다. 억제는 서로 다른 여러 스캔이 사실상 동일한 고객 메시지를 생성하는 것을 방지합니다.
비즈니스 이벤트를 중심으로 알림 식별자를 정의하세요. 배송 확인에는 배송 ID와 배송 완료 마일스톤을 사용할 수 있습니다. 배송 시도에는 시도별 식별자가 필요할 수 있습니다. 이후의 시도가 실제로 새로운 이벤트일 수 있기 때문입니다.
순서가 뒤바뀐 업데이트의 경우 이벤트 타임스탬프를 비교하고 허용된 상태 전환을 평가하세요. 콜백에 새로운 스캔만 포함된다고 가정하지 말고, 문서화된 구조가 개별 이벤트, 스냅샷 또는 기록을 나타내는지 확인하세요. 모순되는 업데이트는 모든 수정 사항을 조용히 폐기하지 말고 조정 절차로 보내세요.
6. 다음에 일어날 일을 설명하는 메시지를 작성하세요
각 알림에는 관련 패키지, 확인된 변경 사항 및 고객의 다음 단계가 명시되어야 합니다. 안전한 추적 링크와 쉽게 알아볼 수 있는 주문 참조를 포함하세요. SMS 메시지와 잠금 화면 미리보기에는 전체 주소나 불필요한 개인정보가 노출되지 않도록 하세요.
예:
- 배송 출발: “주문 {order_reference}의 패키지가 배송을 시작했습니다. 여기에서 진행 상황을 확인하세요: {tracking_link}.”
- 배송 시도: “운송업체가 패키지 배송을 시도했다고 보고했습니다. 이용 가능한 다음 단계는 추적 페이지에서 확인하세요: {tracking_link}.”
- 배송 완료: “운송업체가 주문 {order_reference}의 패키지를 배송 완료로 표시했습니다. 이용 가능한 배송 세부 정보를 확인하세요: {tracking_link}.”
검증된 데이터에서만 플레이스홀더를 렌더링하세요. 배송 예정 시간이 있고 표시하기에 적절하다면 예상 시간임을 표시하세요. 정보가 없으면 날짜를 지어내지 말고 생략하세요.
예외 상황에서는 배송 문제와 고객 작업을 구분하세요. 장애는 설명만 필요할 수 있지만, 확인된 주소 문제는 조치가 필요할 수 있습니다. 신뢰할 수 없는 자유 형식 추적 콘텐츠만을 근거로 고객을 결제 또는 문서 업로드 페이지로 보내지 마세요.
고객 환경설정, 채널 권한, 긴급성 및 적용 규칙을 기준으로 채널을 선택하세요. 사용하는 관할권과 메시징 채널의 동의, 수신 거부 및 방해 금지 시간 요구사항을 검토하세요. 동일한 권한이 두 가지 모두에 적용된다고 가정하지 말고 배송 서비스 알림을 프로모션 캠페인과 분리하세요.
7. 추적이 중단되었을 때의 상황을 정의하세요
선제적인 커뮤니케이션은 새로운 이벤트뿐 아니라 진행이 없는 경우도 다뤄야 하지만, 침묵만으로 배송이 지연되었거나 분실되었다고 입증할 수는 없습니다.
서비스 수준, 경로, 마지막 의미 있는 이벤트 및 지원되는 배송 예정 시간을 사용하여 추적 지연 규칙을 만드세요. 모든 배송에 하나의 보편적인 대기 기간을 적용하지 말고 운영 데이터와 지원 프로세스를 기준으로 임계값을 설정하세요.
해당 규칙이 작동하면 누락된 처리가 있는지 확인하고, 지원되는 경우 추적 소스와 조정한 후, 내부 지원 작업을 열지 결정하세요. 고객에게 알릴 경우 알고 있는 사실을 반영하는 표현을 사용하세요. “새로운 추적 업데이트를 받지 못했습니다”는 “패키지가 분실되었습니다”와 다릅니다.
해결되지 않은 예외에 담당자를 지정하세요. 해결 경로를 만들지 않고 문제를 반복해서 알리는 알림 시스템은 고객의 불만을 키울 수 있습니다.
8. 자동 발송을 활성화하기 전에 전체 경로를 테스트하세요
먼저 섀도 모드로 워크플로를 실행하세요. 실제 또는 승인된 테스트 이벤트를 수집하고, 제안된 알림을 생성한 다음 고객에게 연락하지 않고 결과를 검사합니다.
- 동일한 콜백을 재생하고 또 다른 메시지가 생성되지 않는지 확인하세요.
- 배송 완료 이벤트 이후 더 오래된 배송 중 이벤트를 처리하고 결과 상태를 검사하세요.
- 타임스탬프 누락, 알 수 없는 상태 및 잘못된 페이로드를 테스트하세요.
- 승인 전 데이터베이스 장애와 저장 후 워커 장애를 시뮬레이션하세요.
- 서비스가 이미 메시지를 수락했을 수 있는 불확실한 응답을 포함하여 메시징 시간 초과를 테스트하세요.
- 분할 배송에서 패키지별 문구가 생성되는지 확인하세요.
- 수신 거부한 수신자, 잘못된 연락처 정보 및 방해 금지 시간 처리를 확인하세요.
- 추적 링크가 다른 고객의 주문 정보를 노출하지 않는지 검증하세요.
승인된 콜백, 처리 실패, 큐 대기 시간, 알림 작업, 중복 억제 및 메시징 결과를 모니터링하세요. 시스템의 수신 시간부터 처리 지연 시간을 운송업체 이벤트의 경과 시간과 별도로 측정하세요. 이러한 구분은 느린 알림이 상위 데이터 가용성에서 발생했는지 자체 파이프라인에서 발생했는지 파악하는 데 도움이 됩니다.
잘 이해된 마일스톤 몇 가지로 시작하세요. 지원팀과 운영팀이 메시지가 정확하고 실행 가능하며 수신할 가치가 있다고 동의한 후에만 규칙을 확장하세요.
FAQ
배송 추적 API가 이메일이나 SMS 메시지를 자동으로 보내나요?
반드시 그렇지는 않습니다. 추적 데이터 액세스와 고객 메시징은 별도의 기능입니다. 서비스의 문서화된 범위를 확인하세요. 맞춤형 통합에서는 애플리케이션이 추적 업데이트를 처리하고 별도의 메시징 서비스를 통해 알림을 보낼 수 있습니다.
모든 추적 스캔을 고객에게 알려야 하나요?
대개 그렇지 않습니다. 의미 있는 마일스톤과 조치가 필요한 이벤트를 우선하세요. 여러 시설 스캔은 고객이 알아야 할 내용을 바꾸지 않는 정상적인 배송을 나타낼 수 있습니다. 자세한 기록은 추적 페이지에 유지하세요.
실시간 배송 알림을 보장할 수 있나요?
시스템이 업데이트를 수신한 후 처리 목표를 설정하고 모니터링할 수는 있습니다. 운송업체가 스캔을 기록하거나 게시하는 시점은 보장할 수 없습니다. 이러한 의존성을 반영하는 방식으로 서비스를 설명하세요.
중복 배송 메시지를 방지하려면 어떻게 해야 하나요?
영구적인 이벤트 중복 제거, 각 비즈니스 마일스톤에 대한 별도의 알림 식별자 및 트랜잭션 작업 생성을 사용하세요. 메시징 서비스가 멱등성을 지원한다면 추가적인 보호 장치로 사용하세요. 메모리 내 중복 확인만으로는 재시작이나 여러 워커를 견딜 수 없습니다.
운송업체가 배송 완료 상태를 수정하면 어떻게 해야 하나요?
두 이벤트를 모두 보존하고 배송 상태를 조정하세요. 수정 사항이 고객에게 중대한 영향을 미치면 명확한 수정 알림을 보내거나 정책에 따라 지원팀으로 전달하세요. 코드를 단순화하기 위해 배송 완료 상태를 영구적으로 되돌릴 수 없게 만들지 마세요.
출처
다음 공식 리소스는 위에서 설명한 17TRACK 통합의 구현 참고 자료입니다. 이 가이드의 내부 스키마, 알림 규칙 및 처리 흐름은 인용된 API 계약이 아니라 아키텍처 권장사항입니다.
- 17TRACK Tracking API — API 통합을 평가하기 위한 공식 시작점입니다.
- 17TRACK API documentation — 제공업체별 요청 형식, 인증, 추적 작업 및 통합 요구사항에 대한 참고 자료입니다.


