Skip to main content
홈블로그가이드API를 통해 운송장 번호를 등록하는 방법: 요청 필드, 운송업체 코드 및 응답

API를 통해 운송장 번호를 등록하는 방법: 요청 필드, 운송업체 코드 및 응답

17TRACK

API를 통해 운송장 번호를 등록하려면 인증된 등록 요청을 보내야 하며, 이 요청에는 배송의 운송장 번호와 필요한 경우 운송업체 식별자가 포함되어야 합니다. 그런 다음 HTTP 상태 코드만 확인하지 말고 제출한 각 배송 건의 응답을 검토하여 등록이 성공했는지, 실패했는지 또는 결과가 불확실한지 저장해야 합니다. 등록은 배송 추적 워크플로를 시작하는 것이며, 운송업체가 소포를 스캔했거나 추적 이벤트를 이미 이용할 수 있다는 의미는 아닙니다.

API 요청 필드를 통한 운송장 번호 등록 방법

이 가이드는 주문 관리 시스템, 창고 애플리케이션 또는 전자상거래 플랫폼을 추적 API에 연결하는 개발자를 위한 것입니다. 구체적인 통합 예시로 17TRACK을 사용하며, 선택한 API 버전에 대해 어떤 세부 정보를 문서와 대조하여 확인해야 하는지 설명합니다.

등록으로 할 수 있는 일과 할 수 없는 일

등록 요청은 추적 서비스에 어떤 배송을 추적할지 알려줍니다. 이는 배송 라벨을 구매하거나, 픽업을 예약하거나, 운송업체에 배송 생성을 요청하는 것과는 다릅니다. 일반적인 통합에서는 배송 워크플로가 먼저 운송장 번호를 생성하고, 애플리케이션이 그 후 해당 번호를 등록합니다.

애플리케이션에서 다음 세 가지 이벤트를 구분하여 관리하세요.

  • 배송 생성: 배송 시스템이 운송장 번호를 할당했습니다.
  • 등록 수락: 추적 서비스가 추적 대상 배송을 수락했습니다.
  • 추적 정보 수신: 추적 서비스를 통해 운송업체 이벤트를 이용할 수 있게 되었습니다.

등록이 성공했다는 이유만으로 주문을 “배송 중”으로 업데이트하지 마세요. 새로 생성된 라벨에는 아직 물리적인 인수 스캔 기록이 없을 수 있습니다. 고객에게 표시되는 배송 상태는 등록 응답이 아니라 상태 매핑 규칙을 통해 해석된 추적 이벤트를 기반으로 해야 합니다.

17TRACK 통합의 경우 Tracking API 개요에서 시작하고, 엔드포인트, 필드 정의, 인증 및 응답 코드에 대한 기준으로 공식 API 문서를 사용하세요. 아래 예시는 결과 조회 또는 업데이트 수신과 같은 별도의 작업이 아니라 등록에 초점을 둡니다.

API 호출을 작성하기 전에 요청 필드 준비하기

가장 유용한 준비 작업은 배송 시스템과 추적 통합 사이에 간단한 필드 계약을 마련하는 것입니다. 각 값의 출처, 누락 가능 여부 및 검증 방법을 결정하세요.

필드 또는 값용도구현 규칙
운송장 번호추적할 배송을 식별합니다.문자열로 저장하고 전송하며 앞의 0을 유지합니다.
운송업체 식별자추적 제공업체 시스템에서 운송업체를 식별합니다.내부 창고 코드가 아니라 제공업체가 문서에 명시한 식별자를 사용합니다.
내부 참조등록을 배송 기록에 연결합니다.사용 가능한 경우 지원되는 참조 필드를 사용하되, 자체 데이터베이스 매핑도 반드시 유지합니다.
추가 식별 데이터운송업체가 운송장 번호 외의 정보를 요구하는 경우 배송 식별에 도움이 될 수 있습니다.해당 통합 및 운송업체에 대해 문서화된 필드만 제출합니다.
API 자격 증명호출 계정을 인증합니다.서버에 보관하고 애플리케이션 로그에서 제외합니다.

운송장 번호를 식별자로 취급하기

운송장 번호를 정수로 변환하지 마세요. 숫자로 변환하면 앞의 0이 제거될 수 있으며, 일부 프로그래밍 환경에서는 큰 값의 정밀도가 손실될 수 있습니다. 실수로 포함된 앞뒤 공백은 제거하되, 관련 문서나 운송업체 형식에서 정규화를 지원하지 않는 한 구두점을 제거하거나 대소문자를 변경하지 마세요.

API를 호출하기 전에 빈 문자열, 예상하지 못한 줄바꿈, 운송장 번호 필드에 복사된 주문 번호 등 명백한 입력 오류를 검증하세요. 모든 운송업체에 하나의 길이 또는 문자 규칙을 적용하지 마세요. 한 운송업체에 맞는 검증 규칙이 다른 운송업체의 유효한 번호를 거부할 수 있습니다.

주문 참조와 배송 식별자를 분리하기

하나의 주문에 여러 소포가 포함될 수 있고, 교체 배송으로 인해 다른 운송장 번호가 추가될 수 있습니다. 주문마다 운송장 번호가 하나라고 가정하지 말고 배송 또는 소포 수준에서 등록을 모델링하세요.

제공업체가 지원하는 태그 또는 참조 필드를 사용하는 경우 고객의 이메일 주소나 도로명 주소보다는 의미를 노출하지 않는 배송 참조를 사용하는 것이 좋습니다. 주문, 배송, 운송장 번호 및 운송업체 매핑 간의 기준 연결 정보는 자체 데이터베이스에 유지해야 합니다.

올바른 운송업체 코드 선택하기

운송업체 코드는 반드시 업계 공통 식별자인 것은 아닙니다. 추적 플랫폼이 인식하는 값은 배송 소프트웨어에 저장된 운송업체 이름과 다를 수 있습니다. 숫자 코드를 사용하는 두 시스템조차 같은 운송업체에 서로 다른 번호를 할당할 수 있습니다.

배송 서비스와 추적 제공업체의 운송업체 식별자 사이에 명시적인 매핑을 유지하세요. 필요한 경우 운송업체의 지역별 운영 또는 서비스를 더 넓은 브랜드와 구분하세요. 표시 이름만을 기반으로 한 매핑은 배송 시스템이 별칭을 사용할 때 모호해질 수 있습니다.

  • 운송업체를 알고 있는 경우: 지원된다면 문서화된 운송업체 식별자를 사용하세요. 특히 운송장 번호 형식이 겹치는 경우에 중요합니다.
  • 운송업체를 모르는 경우: 문서화된 방법을 통해서만 자동 감지를 사용하세요. 생략, 빈 문자열, 0 및 null이 같은 의미라고 가정하지 마세요.
  • 결과가 잘못된 것처럼 보이는 경우: 같은 번호를 반복 등록하기 전에 원본 라벨, 배송 서비스 및 매핑을 확인하세요.

자동 감지는 유용하지만 특정 운송업체가 실제로 배송물을 보유하고 있다는 증거는 아닙니다. 마찬가지로 유효한 운송업체 코드가 제공된 운송장 번호가 해당 운송업체의 것임을 보장하지도 않습니다.

운송업체 매핑을 애플리케이션 코드 곳곳에 분산하지 말고 구성 가능하게 유지하세요. 매핑을 마지막으로 확인한 시점을 기록하고, 매핑을 변경할 때마다 알려진 배송 건을 회귀 테스트에 포함하세요.

예시: 17TRACK 등록 요청 제출하기

다음 예시는 17TRACK v2.2 등록 엔드포인트, 17token 인증 헤더 및 운송장 번호 객체 하나를 포함하는 배열을 보여줍니다. 배포 전에 이 버전과 요청 요구 사항이 계정 및 공식 문서와 일치하는지 확인하세요. 운송장 번호는 자리 표시자이므로 실제 배송 식별자로 교체해야 합니다.

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

이 최소 예시는 운송업체 선택이나 운송업체별 추가 필드를 보여주지 않습니다. 운송업체 필드를 생략했을 때 운송업체 감지가 어떻게 작동하는지, 배송에 추가 정보가 필요한지 확인하려면 등록 문서를 검토하세요. 운송업체를 제공하는 경우 문서화된 carrier 필드와 해당 API 버전이 요구하는 식별자를 사용하세요.

이 요청은 서버 측 환경에서 실행하세요. 토큰을 공개 스토어, 브라우저 스크립트 또는 고객에게 배포되는 모바일 애플리케이션에 삽입하지 마세요. 환경 변수는 로컬 예시에 편리하지만, 운영 배포에서는 조직의 비밀 관리 제어 기능을 사용해야 합니다.

처리량을 늘리기 전에 알려진 배송 하나를 테스트하고 전체 응답을 확인하세요. 그런 다음 잘못된 입력과 유효한 항목 및 잘못된 항목이 함께 있는 배치를 테스트하세요. 이러한 검사를 통해 HTTP 성공 응답을 인식하는 데 그치지 않고 항목 수준의 결과를 실제로 처리하는지 확인할 수 있습니다.

세 가지 수준에서 응답 읽기

신뢰할 수 있는 응답 처리기는 세 가지 별도 질문에 답해야 합니다. 요청이 서비스에 도달했는가, 서비스가 작업을 수락했는가, 각 배송에는 어떤 결과가 발생했는가?

1. HTTP 및 전송 결과

연결 시간 초과, TLS 오류 또는 중단된 응답만으로는 서버가 요청을 처리했는지 알 수 없습니다. 조정할 수 있을 때까지 해당 결과를 불확실한 것으로 표시하세요. HTTP 성공 상태는 HTTP 교환이 성공했음을 확인할 뿐이며, 애플리케이션 응답도 반드시 확인해야 합니다.

2. 요청 수준 결과

API에 문서화된 최상위 결과 및 오류 필드를 확인하세요. 인증 오류, 잘못된 JSON 및 계정 제한은 서로 다른 조치가 필요합니다. 모든 실패를 “추적 불가”로 축약하지 말고 제공업체의 원래 오류 코드와 메시지를 저장하세요.

숫자로 된 애플리케이션 코드가 HTTP 상태 코드와 같은 의미라고 가정하지 마세요. 두 코드는 서로 다른 계층에서 나오므로 별도로 해석해야 합니다.

3. 배송 수준 결과

일괄 등록의 경우 제출한 모든 항목을 처리하세요. 응답은 수락된 배송과 거부된 배송을 구분할 수 있으며, 파서는 선택한 버전에 대해 문서화된 정확한 스키마를 따라야 합니다. 한 항목이 성공했다는 이유만으로 전체 배치를 등록된 것으로 표시하지 마세요.

제공업체 응답을 자체적으로 안정적인 애플리케이션 상태로 정규화하세요. 예를 들어 데이터베이스에서 accepted, rejected 및 uncertain을 사용할 수 있습니다. 이는 권장되는 내부 상태이며 실제 17TRACK 응답 값이라는 뜻은 아닙니다. 개발자가 불일치를 조사할 수 있도록 적절한 보존 및 접근 정책에 따라 원래 제공업체 응답을 보관하세요.

유용한 등록 기록에는 내부 배송 ID, 제출된 번호, 운송업체 선택, 시도 시간, API 버전, 결과 및 제공업체 오류 세부 정보가 포함됩니다. 등록 상태와 배송 상태는 분리하여 관리하세요.

무한 루프를 만들지 않고 재시도 처리하기

재시도 정책은 예외가 발생했는지가 아니라 실패 원인에 따라 결정해야 합니다.

  • 잘못된 입력: 재시도하기 전에 필드를 수정하세요. 변경하지 않은 잘못된 요청을 반복해도 도움이 되지 않을 가능성이 높습니다.
  • 인증 실패: 자격 증명과 계정 구성을 확인하세요. 계속 실패하는 동일한 배치를 반복 제출하지 마세요.
  • 요청 제한: 문서화된 제한과 해당되는 재시도 지침을 따르세요. 즉시 병렬 재시도하지 말고 제한된 백오프를 사용하세요.
  • 일시적인 서비스 장애: 정의된 시도 횟수 및 시간 예산 내에서 재시도하세요.
  • 제출 후 시간 초과: 첫 번째 시도가 실패했다고 가정하기 전에 문서화된 API 동작을 사용하여 배송 등록 상태를 조정하세요.
  • 중복 관련 응답: 배송이 이미 등록되어 있는지, 애플리케이션 기록과 올바르게 연결되어 있는지 확인하세요.

문서에서 해당 동작을 정의하지 않았다면 등록이 멱등적이라고 가정하지 마세요. 애플리케이션 측 중복 제거는 실수로 인한 반복 제출을 줄여주지만, 제공업체의 중복 처리 정책을 확립하지는 않습니다.

배송 모델에 적합한 내부 고유성 규칙을 사용하세요. 운송장 번호만으로는 운송업체가 다르거나 장기간 보관하는 경우 영구 키로 충분하지 않을 수 있습니다. 운송업체 정보와 자체 배송 식별자를 보존하고, 교체 배송 및 수정된 번호를 어떻게 처리할지 문서화하세요.

등록 모니터링과 추적 업데이트를 분리하기

API 모니터링에서는 통합 실패와 단순히 새로운 운송업체 이벤트가 없는 배송을 구분해야 합니다. 두 조건은 서로 다른 담당자와 해결 방법이 필요합니다.

등록에 대해서는 수락 및 거부 건수, 오류 범주, 불확실한 결과, 재시도 대기열 및 응답 지연 시간을 모니터링하세요. 이후 추적에 대해서는 업데이트 수신 또는 조회 실패를 별도로 모니터링하세요. 정상적인 트래픽과 제공업체의 문서화된 운영 한도를 파악하기 전에는 수치 기반 경고 임계값을 설정하지 마세요.

운영 환경에서 다음 질문에 답할 수 있어야 합니다.

  1. 추적을 기다리는 모든 배송에 등록 기록이 있습니까?
  2. 수락된 모든 등록을 올바른 소포로 추적할 수 있습니까?
  3. 거부된 항목이 근본적인 데이터를 수정할 수 있는 담당자에게 전달됩니까?
  4. 불확실한 요청이 방치되거나 무기한 재시도되지 않고 조정됩니까?
  5. 고객에게 표시되는 상태가 등록 수락이 아니라 배송 이벤트에서 파생됩니까?
  6. 자격 증명과 불필요한 개인정보가 로그에서 제외됩니까?

전자상거래 운영에서는 API 호출만큼 운영 인계도 중요합니다. 개발자는 전송 및 파싱 실패를 담당해야 하며, 배송 또는 주문 처리 팀은 잘못된 라벨, 운송업체 매핑 및 누락된 배송 정보를 조사할 수 있어야 합니다.

FAQ

첫 번째 운송업체 스캔 전에 운송장 번호를 등록할 수 있나요?

등록과 운송업체 스캔은 별개의 이벤트입니다. 서비스는 자체 검증 규칙에 따라 추적 이벤트를 이용할 수 있게 되기 전에 번호를 수락할 수 있습니다. 수락을 운송업체가 소포를 수령했다는 증거로 해석하지 마세요.

항상 운송업체 코드를 제공해야 하나요?

이는 API에 문서화된 감지 동작과 해당 배송에 따라 다릅니다. 운송업체를 알고 있다면 명시적이고 올바르게 매핑된 식별자를 사용하여 모호성을 줄일 수 있습니다. 모르는 경우 운송업체 값을 임의로 만들어 내지 말고 문서화된 자동 감지 방법을 사용하세요.

배송이 실패했는데 API가 HTTP 성공을 반환한 이유는 무엇인가요?

HTTP 요청은 성공했지만 애플리케이션이 개별 항목을 거부할 수 있습니다. 최상위 애플리케이션 결과와 배송 수준 결과를 모두 읽으세요. 이러한 구분은 일괄 요청에서 특히 중요합니다.

등록 요청 시간이 초과되면 어떻게 해야 하나요?

결과를 불확실한 것으로 처리하세요. 연결이 실패하기 전에 서버가 요청을 처리했을 수 있습니다. 제공업체의 문서화된 중복 처리 방식과 사용 가능한 등록 또는 추적 조회 방법을 확인한 다음 제한된 정책에 따라 조정하거나 재시도하세요.

등록하면 추적 알림이 자동으로 구성되나요?

그렇다고 가정하지 마세요. 등록, 추적 조회 및 웹훅 구성은 별도의 통합 과제입니다. 관련 문서를 확인하고 고객 알림에 의존하기 전에 전체 업데이트 경로를 테스트하세요.

출처

  • 17TRACK API 문서 — 등록 엔드포인트, 인증, 요청 필드, 운송업체 식별자, 응답 스키마 및 오류 처리를 참조하기 위한 문서입니다. 구현 세부 사항을 배포하는 API 버전에 맞추세요.
  • 17TRACK Tracking API 개요 — 추적 API 제품 및 개발자 통합 리소스를 위한 공식 시작점입니다.