Skip to main content

​
1. 호출 순서

배송은 아래 순서로 진행됩니다. 각 단계의 응답이 다음 단계의 입력값이 됩니다.
1

주문 등록

POST /open-api/v1/orders 로 주문을 등록하고 orderId 를 받습니다.
2

배송 신청

POST /open-api/v1/shipments 에 orderId 목록을 전달해 배송건을 생성하고, shipmentId 와 masterNumber(DK 입고 송장번호)를 받습니다.
3

라벨 발행

POST /open-api/v1/shipments/labels 에 masterNumber 목록을 전달해 DK 입고 송장 라벨 PDF를 받습니다(다건). 한 건만 필요하면 GET /open-api/v1/shipments/{masterNumber}/label 을 쓰며, 동작은 같고 건수만 다릅니다.
4

배송 조회

GET /open-api/v1/shipments/{masterNumber}/tracking 으로 배송 상태와 트래킹 정보를 조회합니다.

​
라벨 API는 다건(POST /open-api/v1/shipments/labels)과 단건(GET /open-api/v1/shipments/{masterNumber}/label) 두 가지이며 동작이 같습니다 — 라벨이 없으면 발행하고, 있으면 저장된 라벨을 그대로 반환합니다. 다건은 상한 100건에 전체 실패 방식이고, 단건은 재출력이나 다건 중 일부 실패 건을 복구할 때 씁니다.

​
2. 식별자 흐름

masterNumber 는 DK 입고 송장번호입니다. 라벨 바코드에 인쇄되는 번호와 같은 값이며, 배송 신청 이후의 모든 배송 API는 이 번호를 키로 사용합니다.
주문만 등록한 상태에서는 라벨도 배송 상태도 존재하지 않습니다. 배송 신청을 해야 배송건이 생성되고 masterNumber 가 부여됩니다.

​
3. 배송 상태값

배송 정보 조회 응답의 shipmentStatus 는 아래 9종입니다. 딜리버드 트래킹 페이지가 보여주는 값과 같습니다. 표시 문구는 파트너사에서 직접 정할 수 있도록 코드값만 반환합니다.

​
3-1. 트래킹 이벤트

trackingEvents 는 라스트 마일 송장이 발행된 이후부터 쌓입니다.
  • 아직 발행되지 않았거나 트래킹 조회에 실패하면 빈 배열([]) 이 반환됩니다. 필드가 생략되지는 않습니다.
  • 트래킹 조회에 실패해도 응답은 200 이며 배송 상태는 정상 반환됩니다.
  • 이벤트 발생 시각 occurredAt 은 UTC 기준 하나만 제공합니다.
배송 상태 변경에 대한 웹훅은 제공하지 않습니다. 폴링 방식으로 주기적으로 조회해 주세요.

​
4. 인증과 환경

배송 API의 인증·환경·공통 응답 규약은 기존 오픈 API와 동일합니다.
  • API 키 — 키 발급과 Authorization 헤더 사용법
  • 환경 — 운영·테스트 환경 URL과 식별자(global-ship)
  • 요청 및 응답 — 요청 본문 형식과 공통 응답 규약

​
5. 오류 응답

배송 API의 오류 응답에는 실패 유형을 구분하는 errorCode 가 담깁니다.
배송 신청과 라벨 발행(다건)은 전체 실패 방식입니다. 요청한 건 중 하나라도 조건을 만족하지 못하면 전체가 거부되고, 배송건 생성이나 라벨 발행이 일어나지 않습니다.
라벨 발행 중 서버 오류가 발생한 경우, 그 전에 이미 발행된 라벨은 저장되어 재호출 시 다시 발행되지 않습니다.