홈블로그해상 화물 추적 API: 컨테이너 이벤트, ETA 데이터 및 선택 기준

해상 화물 추적 API: 컨테이너 이벤트, ETA 데이터 및 선택 기준

17TRACK

해상 화물 추적 API는 컨테이너 이동, 운송 마일스톤, ETA 업데이트를 팀이 관리하는 배송 건과 연결해야 합니다. 화물 운송업체, 수입업체, 통합 팀에게 선택 기준은 올바른 컨테이너 운송 여정을 안정적으로 식별하고, 실제 이벤트와 예측을 구분하며, 운영 의사결정을 지원할 수 있을 만큼 충분한 맥락을 제공하는지 여부입니다. 일반적인 배송 상태나 설명이 없는 도착일만으로는 해상 화물을 관리하기에 충분하지 않습니다.

해상 화물 추적 API 컨테이너 이벤트 ETA 데이터 및 선택

이 가이드에서는 요청해야 할 데이터, 컨테이너 이벤트와 도착 예상 시간을 해석하는 방법, 운영 트래픽이나 조달 예산을 투입하기 전에 통합을 평가하는 방법을 설명합니다.

추적 화면이 아니라 배송 모델부터 시작하기

해상 화물 추적에는 여러 관련 객체가 포함됩니다. 상업적 배송 건, 운송 서류, 하나 이상의 컨테이너, 그리고 이를 운송하는 운송 구간입니다. 이러한 관계가 중요한 이유는 하나의 예약에 여러 컨테이너가 포함될 수 있고, 하나의 컨테이너가 여러 선박, 터미널 및 내륙 운송 구간을 거칠 수 있기 때문입니다.

유용한 통합은 이러한 관계를 하나의 상태로 단순화하지 않고 그대로 유지해야 합니다. 동일한 배송 건에 속한 두 컨테이너가 서로 다르게 이동한다면, 시스템은 완전해 보이는 배송 수준의 마일스톤을 제시하는 대신 운영자가 그 차이를 확인할 수 있도록 해야 합니다.

API를 평가하기 전에 비즈니스에서 실제로 수신하는 참조 정보를 파악하십시오.

  • 컨테이너 번호: 장비를 식별하지만 컨테이너는 재사용되므로 관련 배송 건 또는 운송 여정과 연결되어야 합니다.
  • 운송업체 예약 참조 번호: 원본 시스템의 조회 요건에 따라 추적 요청을 예약 건과 연결할 수 있습니다.
  • 운송 서류 참조 번호: 해상 운송업체 수준에서 배송 건을 식별할 수 있습니다. API가 팀이 보유한 서류 참조 정보를 허용하는지 확인하십시오.
  • 내부 배송 ID: 외부 추적 기록을 운송 관리 시스템, ERP 또는 운송 주선 소프트웨어와 연결합니다.

운송 주선업체가 발행한 하우스 선하증권 참조 번호를 해상 운송업체의 서류 참조 번호가 필요한 모든 곳에서 사용할 수 있다고 가정하지 마십시오. 예약 및 서류 업무 흐름에서 사용할 수 있는 정확한 식별자를 테스트하십시오.

API는 어떤 컨테이너 이벤트를 제공해야 하는가?

Digital Container Shipping Association의 Track & Trace 표준은 해상 배송 데이터를 논의할 때 유용한 참고 자료입니다. DCSA는 배송 이벤트, 운송 이벤트, 장비 이벤트를 구분합니다. 이러한 범주는 행정적 진행 상황, 운송 수단의 이동, 실제 컨테이너의 취급을 분리하는 데 도움이 됩니다.

공급업체가 선호하는 필드 이름을 사용하지 않아도 유용할 수 있지만, 이벤트 모델이 필요한 운영 마일스톤에 어떻게 매핑되는지는 설명해야 합니다.

장비 이벤트: 컨테이너에 어떤 일이 발생했는가

관련 장비 마일스톤에는 반입, 선적, 양하, 반출 및 공 컨테이너 이동이 포함될 수 있습니다. 제공 여부는 운송 여정, 데이터 출처 및 제품에 따라 달라집니다. 모든 터미널에서 모든 이벤트를 이용할 수 있다고 가정하지 말고 샘플 기록을 요구하십시오.

이러한 구분은 실무적으로 중요합니다. 선박 도착은 특정 컨테이너가 양하되었다는 증거가 아닙니다. 양하는 컨테이너가 반출 가능하거나 수거 준비가 되었다는 의미가 아닙니다. 반출 기록에도 위치와 맥락이 필요합니다. 환적 시설에서의 반출은 최종 수입 터미널에서의 수거와 동일한 비즈니스 결과가 아닙니다.

운송 이벤트: 선박 또는 운송 구간의 현재 위치

도착 및 출발 이벤트는 운송 활동을 설명합니다. 이를 해석하려면 시스템에 관련 위치, 운송 수단 및 운송 구간 정보가 필요합니다. 이용 가능한 경우 선박 및 항차 식별자는 동일한 항구를 운항하는 다른 이동과 의도한 운항을 구분하는 데 도움이 됩니다.

환적 화물의 경우 중간 기항지를 유지하십시오. 운송 일정을 출발지와 목적지만으로 축소하면 연결편 누락이나 경로 변경을 숨길 수 있습니다. 운영 타임라인에서는 어떤 구간이 완료되었고 어떤 구간이 아직 예상 상태인지 확인할 수 있어야 합니다.

배송 이벤트: 행정적 진행은 실제 이동이 아니다

서류 및 배송 처리 이벤트는 운송 주선 업무에 유용할 수 있지만 컨테이너 이동과 구분되어야 합니다. 서류 마일스톤은 화물이 실제로 이동했다는 사실을 입증하지 않으며, 이동 이벤트는 모든 상업적 또는 규제 요건이 충족되었다는 사실을 입증하지 않습니다.

각 이벤트에 대해 이벤트 유형, 관련 객체, 위치, 이벤트 타임스탬프, 시간대 정보, 출처, 그리고 해당 이벤트가 계획된 것인지 예상된 것인지 실제 발생한 것인지에 대한 표시를 요청하십시오. 반복 업데이트가 중복 마일스톤을 생성하지 않도록 안정적인 이벤트 식별자와 수정 처리 방식도 요청하십시오.

ETA 데이터에는 목적지, 의미 및 이력이 필요하다

ETA는 지정된 지점에 도착할 것으로 예상되는 시간입니다. 이는 화물을 수거할 수 있다는 약속이 아닙니다. 해상 화물 추적 API는 eta라고만 표시된 모호한 필드를 반환하는 대신 도착 마일스톤의 목적지를 명확히 해야 합니다.

예를 들어 도착 예상 시간은 항구 기항, 터미널, 내륙 시설 또는 기타 정의된 목적지를 의미할 수 있습니다. 트럭 배차나 재고 가용성 약속에 사용하기 전에 해당 타임스탬프가 정확히 무엇을 나타내는지 확인하십시오.

예상 시간의 출처와 상태를 구분하기

운송업체가 제공하는 예상 시간과 공급업체가 생성한 예측은 서로 다른 데이터 제품입니다. 어느 것도 실제 도착으로 표시해서는 안 됩니다. 응답에 예상 시간의 출처, 계산 또는 게시 시간, 그리고 예측 대상 위치나 이벤트가 표시되는지 확인하십시오.

공급업체가 예측 ETA를 제공한다면 그 방법론과 검증 방식을 요청하십시오. 어떤 마일스톤을 예측하는지, 도착 전 얼마의 기간을 기준으로 성능을 측정하는지, 사용하는 운송 경로에 따라 결과가 달라지는지 등을 확인해야 합니다. 목표 이벤트와 측정 기간이 명시되지 않은 포괄적인 정확도 주장은 적용하기 어렵습니다.

ETA 수정 이력을 덮어쓰지 말고 유지하기

최신 ETA는 오늘의 계획을 지원하고, 수정 이력은 무엇이 변경되었는지 설명합니다. 이전 예상 시간, 새 예상 시간, 관련 마일스톤, 출처 및 시스템이 변경 사항을 수신한 시간을 저장하십시오.

이 이력을 통해 운영 팀은 중대한 지연과 서식 수정 또는 관련 없는 항구 기항 변경을 구분할 수 있습니다. 또한 여정 초기에 최종 예상 시간을 알고 있었던 것처럼 가장하지 않고 사후 평가를 수행할 수 있습니다.

시간대는 명시적으로 테스트해야 합니다. 제공되는 경우 원본 타임스탬프와 오프셋을 유지하고, 계산을 위해 타임스탬프를 표준화하며, 적절한 경우 현지 운영 시간을 표시하십시오. 출처가 날짜만 제공한다면 이를 정확한 자정 도착 약속으로 조용히 변환하지 마십시오.

이벤트 수준에서 제공 범위를 평가하기

운송업체가 제공 범위 목록에 있다는 사실만으로 모든 컨테이너 마일스톤을 이용할 수 있다고 볼 수는 없습니다. 제공 범위는 비즈니스에 중요한 운송업체, 운송 경로, 배송 참조 정보 및 운영 이벤트를 기준으로 테스트해야 합니다.

실제 요구사항을 포함한 평가 매트릭스를 작성하십시오. 대표 배송 건마다 API가 참조 정보를 확인하고, 올바른 운송 일정을 반환하며, 필요한 마일스톤을 제공하고, 팀이 관리하는 여정 구간 전체에서 업데이트를 유지할 수 있는지 확인하십시오.

  • 직접 해상 운송: 출발지 출항, 목적지 도착 및 관련 컨테이너 취급 이벤트를 식별할 수 있습니까?
  • 환적 운송: 중간 구간이 표시되며, 서로 다르게 이동하는 컨테이너를 구분할 수 있습니까?
  • 내륙 운송 구간: 서비스에 포함되는 경우 API가 관련 철도, 바지선 또는 트럭 마일스톤을 제공합니까, 아니면 항구에서 가시성이 끝납니까?
  • 예외: 누락 이벤트, 변경된 경로, 일치하지 않는 참조 정보 및 데이터 출처 중단이 어떻게 표시됩니까?
  • 완료된 배송: 고객 분쟁을 조사하거나 운영 기록을 대조할 수 있을 만큼 충분한 과거 데이터를 팀이 조회할 수 있습니까?

이용할 수 없는 데이터와 부정적 이벤트를 구분하십시오. 양하 기록이 없다고 해서 양하가 발생하지 않았다는 뜻은 아닙니다. 유용한 통합은 명시적인 운영 상태와 가시성 부족을 구분합니다.

이벤트 목록만큼 중요한 API 동작

이벤트 피드가 풍부하더라도 전달 동작이 불분명하면 운영이 어려워질 수 있습니다. 애플리케이션이 업데이트를 수신하는 방식, 수정 사항을 처리하는 방식, 장애 후 복구하는 방식을 평가하십시오.

폴링, 웹훅 및 복구

폴링을 사용하면 애플리케이션이 일정에 따라 업데이트를 요청할 수 있습니다. 웹훅을 사용하면 공급업체가 운영 중인 엔드포인트로 업데이트를 전송할 수 있습니다. 어느 방식도 그 자체로 최신성을 보장하지는 않습니다. 즉시 전달된 웹훅에도 늦게 수신된 원본 이벤트가 포함될 수 있습니다.

가능한 경우 원본 이벤트 시간, 공급업체 수신 시간 및 알림 시간을 별도로 정의해 달라고 요청하십시오. 웹훅의 경우 인증 또는 서명 확인, 재시도, 중복 전달 처리 및 실패한 알림의 재생 가능 여부를 확인하십시오. 폴링의 경우 페이지 매김, 요청 제한, 증분 조회 및 과거 수정 사항의 처리 방식을 확인하십시오.

증거를 잃지 않는 정규화

정규화된 상태는 운송업체 간 업무 흐름을 쉽게 만들지만 과도한 단순화는 유용한 맥락을 제거합니다. 가능한 경우 원본 출처 설명 또는 코드와 정규화된 이벤트를 함께 보존할 수 있는 모델을 선호하십시오.

대시보드 상태로 변환하는 비즈니스 규칙과 원시 수신 기록을 별도로 저장하십시오. 이렇게 하면 원본 증거를 잃지 않고 매핑을 수정할 수 있습니다. 또한 고객에게 표시되는 상태가 운영 팀의 해석과 다를 때 이를 더 쉽게 조사할 수 있습니다.

상업 및 거버넌스 확인

청구 단위에 대한 서면 설명을 요청하십시오. 구독, 추적 배송 건, 컨테이너, API 요청 및 알림은 서로 대체할 수 있는 측정 단위가 아닙니다. 특정 요금 모델을 가정하지 말고 재시도, 중복 등록, 과거 조회 및 재활성화된 배송 건이 요금에 어떤 영향을 미치는지 명확히 하십시오.

또한 데이터 보존, 접근 제어, 자격 증명 교체, 허용된 다운스트림 사용, 지원 에스컬레이션 및 서비스 약정을 검토하십시오. 계약상 보장은 제품 시연 및 마케팅 문구와 별도로 취급하십시오.

일반 추적 API가 해상 화물 요건을 충족한다고 가정하지 않기

추적 API는 카테고리 명칭이 아니라 검증된 데이터 모델을 기준으로 선택해야 합니다. 두 가지 모두 배송 추적이라고 설명되더라도 소포 배송 업데이트와 해상 컨테이너 가시성은 서로 다른 업무 흐름을 지원할 수 있습니다.

17TRACK이 이미 통합 후보 목록에 있다면 공식 Tracking API 페이지와 API 문서를 요구사항 검토의 출발점으로 사용하십시오. 일반적인 추적 통합을 해상 화물 솔루션으로 간주하기 전에 애플리케이션에 필요한 정확한 해상 참조 정보, 컨테이너 이벤트, 운송 구간 및 ETA 필드를 확인하십시오. 이 가이드는 17TRACK의 해상 특화 기능을 입증하지 않습니다.

동일한 승인 기준을 모든 후보에 적용해야 합니다. 대표 배송 건으로 필요한 데이터를 시연하고 한계를 설명하도록 하십시오. 더 광범위한 운송업체 추적 업무 흐름은 공급망의 다른 영역에서 유용할 수 있지만, 전문 컨테이너 이벤트 피드를 대체하지는 않습니다.

운영 의사결정을 중심으로 개념 증명 실행하기

가장 강력한 개념 증명은 대시보드 시연이 아니라 팀이 내려야 하는 의사결정에서 시작합니다. 간단한 운항과 수작업을 유발하는 어려운 사례를 모두 포함하여 실제 운영에서 대표적인 배송 건을 선택하십시오.

  1. 승인 기준 정의. 테스트 전에 필요한 참조 정보, 이벤트, 위치, 타임스탬프 의미 및 누락 데이터의 허용 가능한 처리 방식을 명시하십시오.
  2. 식별 정보 검증. 모든 결과가 의도한 배송 건과 컨테이너 운송 여정에 속하는지 확인하십시오. 관련되는 경우 재사용 장비와 다중 컨테이너 예약을 포함하십시오.
  3. 원본 기록과 비교. 업데이트 시점의 차이를 고려하여 반환된 마일스톤을 확인 가능한 운송업체 또는 터미널 기록과 비교하십시오.
  4. 수정 및 장애 테스트. 중복 알림, 순서가 뒤바뀐 이벤트, 수정된 타임스탬프, 사용할 수 없는 데이터 출처 및 엔드포인트 장애를 테스트하십시오.
  5. 비즈니스 업무 흐름 재현. 지연된 연결편 검토나 입고 재고 예상치 업데이트 등 의도한 작업을 데이터가 지원하는지 확인하십시오.
  6. 해결되지 않은 격차 검토. 각 격차가 원본 데이터, 공급업체 처리 또는 통합에서 발생했는지 기록하십시오. 사용 범위를 확대하기 전에 해결 방안에 합의하십시오.

ETA 테스트에서는 각 예측이 도착할 때마다 보존하고 동일한 마일스톤의 최종 실제 이벤트와 비교하십시오. 항구 도착 예측을 창고 수령과 비교하거나, 리드 타임이 크게 다른 시점에 생성된 예측을 하나의 설명 없는 점수로 결합하지 마십시오.

선택 규칙은 간단합니다. 추적 가능한 이벤트, 이해할 수 있는 예상치 및 복구 가능한 전달 동작을 통해 필요한 의사결정을 실제로 지원하는 통합을 선택하십시오. 수거 계획에 터미널 가용성, 반출 상태 또는 예약도 필요한 경우 선박 도착에서 이를 추론하지 말고 해당 입력을 별도로 확인하십시오.

FAQ

컨테이너 번호만으로 해상 배송을 추적할 수 있습니까?

데이터 출처와 API에 따라 다릅니다. 일부 업무 흐름에서는 운송업체 식별자, 예약 참조 번호 또는 운송 서류 참조 번호가 추가로 필요할 수 있습니다. 장비는 재사용되므로 컨테이너 번호만으로 판단하지 말고 반환된 이벤트가 의도한 운송 여정에 속하는지 확인하십시오.

실제 선박 도착은 컨테이너가 수거 준비되었다는 뜻입니까?

아닙니다. 선박 도착, 컨테이너 양하, 화물 가용성 및 수거 허가는 서로 별개의 운영 사실입니다. 배송 건에 따라 수거를 위해 반출 정보와 터미널 예약이 추가로 필요할 수 있습니다. 관련 조건을 담당하는 당사자에게 확인하십시오.

AIS 선박 추적이 컨테이너 추적을 대체합니까?

아닙니다. AIS는 선박 식별 및 이동 정보에 관한 것이며 개별 컨테이너의 선적, 양하, 반출 또는 게이트 반출 상태를 자체적으로 입증하지 않습니다. 선박 이동은 맥락을 제공할 수 있지만 컨테이너와 항차의 연결은 여전히 확인해야 합니다.

해상 추적 API는 얼마나 자주 업데이트해야 합니까?

모든 업무 흐름에 유용한 단일 간격은 없습니다. 관련 원본 정보가 제공된 후 팀이 얼마나 신속하게 조치를 취해야 하는지를 기준으로 요구사항을 설정하십시오. 원본 지연 시간과 API 전달 지연 시간을 별도로 측정하고, 원본이 새 이벤트를 게시하지 않을 때 어떤 일이 발생하는지 확인하십시오.

추적 이벤트로 체화료 또는 지체료를 계산할 수 있습니까?

이벤트는 타임라인을 지원할 수 있지만 완전한 요금 계산을 확정하지는 않습니다. 적용되는 계약 조건, 무료 기간 규칙, 달력 처리 방식 및 권위 있는 시작·종료 조건도 필요합니다. 일반적인 마일스톤만으로 지불 금액을 산출하지 마십시오.

출처

Loading