하나의 API 요청으로 여러 추적 번호를 보내는 방법(배치 제한 및 부분 실패)
하나의 API 요청으로 여러 추적 번호를 전송하려면 배치를 명시적으로 허용하는 Tracking API 엔드포인트를 사용하고, 각 배송 건을 해당 요청 스키마에 맞게 구성한 다음, 문서에 명시된 제한 내에서 많은 목록을 여러 배치로 나누세요. 그런 다음 HTTP 응답과 각 배송 건의 결과를 모두 확인하세요. HTTP 요청이 성공했다고 해서 모든 추적 번호가 반드시 승인된 것은 아닙니다. 재시도 가능한 실패만 재시도하고, 전체 배치를 다시 제출하기 전에 결과가 불확실한 건을 대조하고 확인하세요.

이 가이드는 배송 추적을 주문 관리 시스템, 창고 플랫폼, 전자상거래 애플리케이션 또는 내부 대시보드에 연결하는 개발자를 위한 것입니다. 목표는 단순히 요청 수를 줄이는 것이 아닙니다. 중복 작업을 만들거나 실패한 기록을 잃지 않고 모든 배송 건을 관리하는 것입니다.
먼저 배치 엔드포인트가 실제로 수행하는 작업을 확인하세요
추적 통합에는 여러 가지 서로 다른 작업이 포함될 수 있습니다. 배송 건을 등록하고, 최신 추적 정보를 조회하며, 이후 업데이트를 수신하는 작업은 서로 대체할 수 없습니다.
- 등록: 서비스가 해당 배송 건의 추적을 시작하거나 유지할 수 있도록 배송 건을 제출합니다.
- 조회: 엔드포인트의 조회 규칙에 따라 배송 건의 추적 정보를 요청합니다.
- 배송 업데이트: 웹훅과 같은 지원되는 메커니즘을 통해 이후 변경 사항을 수신하거나 예약된 요청으로 가져옵니다.
필요한 정확한 작업은 문서에서 확인하세요. 여러 레코드를 허용하는 등록 엔드포인트라고 해서 조회 엔드포인트도 동일한 수량을 허용하거나, 동일한 스키마를 사용하거나, 동일한 속도 제한을 공유한다고 볼 수는 없습니다.
17TRACK 통합의 경우 Tracking API 제품 페이지에서 시작하고, 공식 API 문서를 사용하여 작업, 인증 방식, 요청 형식 및 응답 필드를 확인하세요. 아래 예시는 해당 API 계약을 대체하는 것이 아니라 구현 패턴으로 활용해야 합니다.
배치 제한은 배송 건의 최대 수보다 더 많은 것을 의미합니다
Tracking API에 보편적으로 적용되는 배치 제한은 없습니다. 제한은 제공업체, 엔드포인트, API 버전 및 계정 설정에 따라 달라질 수 있습니다. 배치를 구현하기 전에 다음 제약 조건을 별도로 기록하세요.
| 제약 조건 | 확인할 사항 | 구현상 영향 |
|---|---|---|
| 요청당 항목 수 | 특정 작업에 허용되는 최대 레코드 수 | 전송 전에 입력 목록을 분할 |
| 요청 본문 크기 | 문서에 명시된 바이트 제한 | 선택적 필드와 직렬화 크기를 고려 |
| 요청 속도 | 정해진 시간 동안 허용되는 요청 수 | 공유 제한기를 통해 요청 속도를 조절 |
| 동시성 | 동시 요청 제한 | 활성 작업자 수를 제한 |
| 사용량 산정 | 사용량이 요청, 배송 건 또는 다른 단위로 계산되는지 여부 | 요청량과 별도로 사용량을 추정 |
예를 들어 가상의 엔드포인트가 요청당 25개 레코드를 허용한다면, 63개 레코드는 25개, 25개, 13개로 구성된 세 번의 요청이 필요합니다. 이 수치는 청킹을 설명하기 위한 것일 뿐이며 17TRACK의 제한을 나타내지 않습니다.
배치를 사용한다고 해서 과금 대상 사용량이 줄어든다고 가정하지 마세요. HTTP 요청 오버헤드는 줄일 수 있지만 요금에 미치는 영향은 제공업체의 실제 산정 규칙에 따라 달라집니다. 마찬가지로 유효한 배치 크기가 무제한 병렬 요청을 허용하는 것은 아닙니다.
요청을 구성하기 전에 레코드를 준비하세요
대부분의 방지 가능한 배치 실패는 입력 준비에서 시작됩니다. 각 배송 건을 배치에 추가하기 전에 검증하되, 서로 다른 운송업체의 정상적인 추적 번호를 실수로 거부하는 규칙은 피하세요.
- 추적 번호를 문자열로 유지하세요. 숫자로 변환하면 앞의 0이 제거되거나 긴 식별자가 변경될 수 있습니다.
- 실수로 포함된 앞뒤 공백을 제거하세요. 관련 사양에서 정규화를 허용하지 않는 한 내부 문자를 제거하거나 대소문자를 변경하지 마세요.
- 필수 필드를 검증하세요. 일부 워크플로에서는 운송업체 식별자나 추가 배송 정보가 필요할 수 있습니다. 문서에 명시된 필드 이름과 값만 사용하세요.
- 중복 제거 범위를 명시적으로 선택하세요. 동일한 추적 번호가 모든 운송업체, 판매자 또는 과거 배송 건에서 자동으로 중복인 것은 아닙니다.
- 로컬 배송 식별자를 유지하세요. API가 사용자 지정 참조 필드를 허용하지 않더라도 전송 항목과 주문 또는 배송 레코드 간의 관계를 저장하세요.
여러 네트워크에 걸친 Carrier Tracking에서는 특정 워크플로에서 해당 추론이 신뢰할 수 있는 경우가 아니라면 추적 번호의 길이나 접두사만으로 운송업체를 추정하지 마세요. API가 운송업체 식별을 지원하는 경우 문서에 명시된 모호성 처리 동작을 따르세요.
예시 요청 구조
다음 JSON은 배치 페이로드의 개념을 보여줍니다. 래퍼, 속성 이름 및 식별자는 예시일 뿐이며 17TRACK 요청 스키마가 아닙니다. 일부 API는 배열을 포함하는 객체 대신 최상위 배열을 요구합니다.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}문자열을 이어 붙이는 대신 JSON 직렬화기를 사용하여 페이로드를 구성하세요. 문서에 명시된 방식으로 인증 정보를 전송하고, 인증 정보가 소스 관리 시스템, 브라우저로 전달되는 코드 및 일반 로그에 포함되지 않도록 하세요.
응답을 두 가지 수준에서 처리하세요
배치 요청에는 전송 수준의 결과와 애플리케이션 수준의 결과가 있습니다. 통합 시스템은 두 결과를 모두 평가해야 합니다.
수준 1: 요청이 사용할 수 있는 응답을 받았나요?
먼저 HTTP 상태, 응답 헤더 및 응답 본문을 확인하세요. 인증 오류, 잘못된 요청, 속도 제한 및 서버 오류로 인해 정상적인 항목 처리가 불가능할 수 있습니다. 네트워크 타임아웃은 다릅니다. 클라이언트는 서버가 요청을 수신했거나 처리했는지 알지 못할 수 있습니다.
HTTP 의미 체계는 RFC 9110에 정의되어 있습니다. 그러나 애플리케이션 수준 결과 필드가 실제 배송 결과에 어떻게 매핑되는지는 제공업체의 문서가 결정합니다.
수준 2: 각 배송 건에 어떤 일이 발생했나요?
응답이 항목 수준 결과를 지원한다면 제출된 모든 레코드를 분류하세요. HTTP 200이 모든 레코드의 성공을 의미한다고 가정하거나, 계약에서 명시적으로 보장하지 않는 한 결과 목록이 요청 순서를 유지한다고 가정하지 마세요.
- 승인됨: 엔드포인트의 문서화된 정의에 따라 작업이 성공했습니다.
- 영구적인 입력 실패: 다시 시도하기 전에 레코드를 수정하거나 조사해야 합니다.
- 재시도 가능한 실패: 제공업체의 재시도 지침에 따라 다시 시도하도록 예약합니다.
- 알 수 없는 결과: 응답이 없거나 불완전하거나 제출된 레코드와 안전하게 일치시킬 수 없습니다.
“이미 등록됨” 또는 이와 유사한 중복 관련 응답은 문서화된 의미를 이해할 때까지 별도로 처리하세요. 이러한 응답은 원하는 상태가 이미 존재함을 나타낼 수 있지만, 성공적인 소유권, 구성 또는 구독 확인으로 자동 처리해서는 안 됩니다.
응답을 처리한 후 모든 입력 레코드에는 정확히 하나의 로컬 결과가 있어야 합니다. 유용한 조정 검사는 제출된 레코드 수가 승인된 레코드, 영구 실패, 재시도 가능한 실패 및 알 수 없는 결과의 합과 같은지 확인하는 것입니다. 이는 로컬 회계 규칙이며 필수 API 응답 형식이 아닙니다.
성공한 레코드를 다시 실행하지 않고 부분 실패를 처리하세요
예시 배치에 배송 건 10개가 있고, 7개는 승인되었으며, 2개에는 잘못된 필수 필드가 있고, 1개에는 문서화된 일시적 오류가 발생했다고 가정해 보겠습니다. 성공한 7개의 결과를 저장하고, 잘못된 2개는 수정을 위해 전달하며, 일시적 오류가 발생한 1개만 재시도하세요.
10개 전체를 다시 실행하면 불필요한 트래픽이 발생하고 중복 처리가 복잡해질 수 있습니다. 또한 최초 거부와 이후 중복 관련 응답을 구분하기가 더 어려워집니다.
| 결과 | 권장 조치 |
|---|---|
| 잘못된 필드 또는 지원되지 않는 값 | 입력을 수정하고 변경하지 않은 상태로 재시도하지 않음 |
| 인증 또는 권한 오류 | 영향받는 작업을 일시 중지하고 인증 정보 또는 액세스를 수정 |
| 속도 제한 응답 | 문서 지침 및 해당 응답 헤더에 따라 지연 |
| 일시적인 항목 수준 오류 | 제한된 횟수와 백오프를 적용하여 해당 항목을 재시도 |
| 제출 후 타임아웃 | 불확실한 상태로 표시하고, 조정하거나 문서화된 재시도 안전성 보장을 사용 |
| 인식할 수 없거나 불완전한 결과 | 성공으로 가정하지 말고 증거를 보존한 후 조사 |
HTTP 429는 요청이 너무 많음을 의미하며, 응답에는 RFC 6585에 설명된 Retry-After 헤더가 포함될 수 있습니다. 해당 헤더가 항상 존재한다고 가정하지 마세요. 명시적인 재시도 지연이 제공되지 않는 경우 API 문서에 부합하는 제한된 백오프 정책을 사용하세요.
여러 작업자의 재시도를 분산하기 위해 지터를 추가하고, 최대 시도 횟수 또는 재시도 가능 기간을 설정하며, 소진된 레코드는 검토 큐로 보내세요. 무기한 재시도는 지속적인 구성 문제를 숨길 수 있습니다.
타임아웃에 특별한 처리가 필요한 이유
타임아웃이 거부를 증명하는 것은 아닙니다. 연결이 끊어지기 전에 서버가 배치를 수락했을 수 있습니다. 따라서 상태를 변경하는 요청을 자동으로 다시 실행하면 작업이 반복될 수 있습니다.
엔드포인트가 문서화된 멱등성 키를 지원한다면 키의 범위와 보존 기간을 포함한 해당 규칙을 따르세요. 멱등성 헤더를 임의로 만들고 서버가 이를 준수한다고 가정하지 마세요. 그렇지 않다면 재제출하기 전에 지원되는 조회 또는 조정 워크플로를 사용하여 원하는 상태가 존재하는지 확인하세요. 로컬 중복 제거는 자체 작업자 조정에 도움이 되지만 서버 측 멱등성을 보장하지는 않습니다.
실용적인 배치 처리 워크플로
제공업체별 세부 사항은 어댑터에 보관하여 큐, 재시도 스케줄러 및 모니터링 로직이 원시 응답 필드 이름에 의존하지 않도록 하세요.
validate records and retain local shipment IDs
resolve duplicates within the intended business scope
split records using documented item and payload limits
for each batch through a bounded worker pool:
persist an attempt record before sending
wait for the shared rate limiter
send using the provider-specific adapter
if the outcome is uncertain:
enqueue reconciliation
continue
classify request-level and item-level outcomes
persist one outcome for every submitted record
schedule only eligible failures for retry
route invalid or exhausted records for review
결과 저장 및 재시도 예약이 복구 가능하도록 만드세요. 예를 들어 영구 작업 레코드 또는 트랜잭션 큐잉 패턴을 사용하면 프로세스 충돌로 재시도 결정이 손실되는 것을 방지할 수 있습니다. 작업자가 다시 시작되면 전송되지 않은 작업과 원격 결과가 아직 불확실한 작업을 구분할 수 있어야 합니다.
배치 크기는 코드베이스 곳곳에 흩어진 상수가 아니라 관련 엔드포인트에 연결된 구성 가능한 설정으로 사용하세요. 문제를 해결하거나 문제가 있는 레코드를 격리할 때는 더 작은 배치가 유용할 수 있습니다. 허용되는 최대 배치가 자동으로 가장 적합한 운영 크기인 것은 아닙니다.
HTTP 가동 시간뿐 아니라 배송 결과를 모니터링하세요
API 모니터링은 배송 건이 의도한 상태에 도달하고 있는지 보여줘야 합니다. HTTP 성공률만 표시하는 대시보드는 정상적으로 성공한 응답 내부의 부분 실패를 놓칠 수 있습니다.
- 항목 승인율: 재시도 처리 방식을 명확히 정의한 상태에서 제출된 레코드 대비 승인된 레코드의 비율
- 실패 분포: 엔드포인트, 문서화된 오류 코드 및 관련 운송업체 컨텍스트별 횟수
- 알 수 없는 결과: 조정되지 않은 레코드와 해결되지 않은 상태로 남아 있는 기간
- 재시도 대기열: 대기 중인 재시도, 가장 오래된 재시도의 경과 시간 및 소진된 시도
- 요청 상태: 지연 시간, 타임아웃, 속도 제한 및 서버 오류
- 추적 최신성: 승인된 배송 건이 이후 사용할 수 있는 추적 정보를 수신하는지 여부
등록 승인은 새로운 운송업체 스캔의 증거가 아닙니다. API 처리 상태를 배송 이동 및 데이터 최신성과 별도로 관리하여 통합 장애를 배송 지연과 혼동하지 않도록 하세요.
로컬 배치 ID, 배송 참조, 시도 횟수, 문서화된 오류 코드 및 가능한 경우 제공업체 요청 ID를 기록하세요. 인증 정보와 불필요한 개인정보는 삭제하거나 가리세요. 운영상 필요한 경우에만 추적 식별자를 사용하고, 원시 배송 식별자를 카디널리티가 높은 메트릭 레이블에 넣지 마세요.
프로덕션 전에 다음 사례를 테스트하세요
가능한 경우 문서화된 샌드박스 또는 통제된 테스트 환경을 사용하세요. 임의로 만든 추적 번호가 프로덕션에서 예측 가능한 응답을 생성한다고 가정하지 마세요.
- 문서에 명시된 항목 제한으로 유효한 배치를 제출한 다음, 클라이언트가 크기 초과 배치를 방지하는 방식을 테스트하세요.
- 앞에 0이 있는 추적 번호가 직렬화 및 저장 과정에서 유지되는지 확인하세요.
- 승인된 항목과 거부된 항목이 섞인 경우를 테스트하되 성공한 레코드는 재시도하지 마세요.
- 속도 제한을 시뮬레이션하고 여러 작업자가 동일한 제한을 준수하는지 확인하세요.
- 제출 후 타임아웃을 시뮬레이션하고 조정 경로를 확인하세요.
- 응답 수신과 로컬 저장 사이에 작업자를 다시 시작하세요.
- 누락되었거나 익숙하지 않거나 일치시킬 수 없는 항목 결과를 테스트하세요.
- 잘못된 레코드가 무한히 재시도되지 않고 확인 가능한 수정 큐에 도달하는지 확인하세요.
프로덕션 준비가 된 통합은 결과가 일시적으로 불확실한 배송 건을 포함하여 제출된 모든 배송 건의 상태를 설명할 수 있어야 합니다. 요청 수를 줄이는 것도 유용하지만 이러한 책임성을 유지하는 것이 더 중요한 설계 목표입니다.
FAQ
한 번의 요청으로 몇 개의 추적 번호를 보낼 수 있나요?
정확한 엔드포인트와 API 버전에 대해 문서화된 제한을 사용하세요. 또한 요청 크기, 속도 제한 및 계정별 제약 조건을 확인하세요. 추적 API 전반 또는 하나의 API 내 서로 다른 작업에 적용할 수 있는 안전한 보편적 수량은 없습니다.
추적 번호 하나가 잘못되면 전체 배치가 실패할 수 있나요?
예. 엔드포인트의 검증 규칙에 따라 달라집니다. 일부 API는 개별 거부를 반환하지만, 다른 API는 항목 처리 전에 요청을 거부할 수 있습니다. 요청 수준 오류와 항목 수준 결과를 모두 확인하세요. 모든 배치 엔드포인트가 부분 승인을 지원한다고 가정하지 마세요.
HTTP 응답이 성공적이면 배치를 재시도해야 하나요?
자동으로 재시도해서는 안 됩니다. 먼저 문서화된 애플리케이션 수준 상태와 항목 결과를 분석하세요. 성공한 레코드를 저장하고 재시도 가능한 실패만 재시도하세요. 결과를 안전하게 해석할 수 없다면 불확실한 상태로 분류하고 조사하세요.
같은 배치에 여러 운송업체를 섞을 수 있나요?
엔드포인트가 해당 요청 구조를 지원하는 경우에만 가능합니다. 운송업체 정보가 배송 건별로 제공되는지, 자동 식별이 지원되는지, 식별이 모호할 때 어떤 일이 발생하는지 확인하세요. 멀티 운송업체 서비스라는 사실만으로 모든 엔드포인트의 배치 규칙이 정해지는 것은 아닙니다.
배치를 사용하면 추적 업데이트가 더 빨리 도착하나요?
배치를 사용하면 애플리케이션이 전송하는 요청 수를 줄일 수 있지만, 그 자체로 운송업체 이벤트가 더 빨리 표시되는 것은 아닙니다. 등록, 데이터 조회, 운송업체 스캔 가용성 및 업데이트 전달은 워크플로의 서로 다른 부분입니다.
출처
- 17TRACK Tracking API — 추적 통합을 평가하는 개발자를 위한 공식 제품 진입점
- 17TRACK API documentation — 제공업체별 엔드포인트 계약, 제한, 인증 및 응답 처리에 대한 참고 자료
- RFC 9110: HTTP Semantics — HTTP 상태 의미, 멱등성, 자동 재시도 및 Retry-After
- RFC 6585: Additional HTTP Status Codes — HTTP 429 Too Many Requests 및 선택적 Retry-After 헤더의 정의


