배송 API 시작하기

글로벌쉽 배송 API의 호출 순서와 각 단계에서 주고받는 식별자, 배송 상태값을 안내합니다.

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. 식별자 흐름

식별자	어디서 받나	어디에 쓰나
orderId	주문 등록 응답	배송 신청 요청
shipmentId	배송 신청 응답	배송건 식별 (조회·대조용)
masterNumber	배송 신청 응답	라벨 발행(다건·단건) · 배송 정보 조회 요청

masterNumber 는 DK 입고 송장번호입니다. 라벨 바코드에 인쇄되는 번호와 같은 값이며, 배송 신청 이후의 모든 배송 API는 이 번호를 키로 사용합니다.

주문만 등록한 상태에서는 라벨도 배송 상태도 존재하지 않습니다. 배송 신청을 해야 배송건이 생성되고 masterNumber 가 부여됩니다.

---

3. 배송 상태값

배송 정보 조회 응답의 shipmentStatus 는 아래 9종입니다. 딜리버드 트래킹 페이지가 보여주는 값과 같습니다.

값	의미
CONFIRM_ORDER	신청완료
RECEIVING_COMPLETE	입고완료
RECEIVING_ON_HOLD	입고보류
PREPARE_SHIP	출고대기
SHIPPED_OUT	출고완료
IN_DELIVERY	배송중
DELIVERED	배송완료
SHIPBACK	반송완료
CANCEL	취소

표시 문구는 파트너사에서 직접 정할 수 있도록 코드값만 반환합니다.

3-1. 트래킹 이벤트

trackingEvents 는 라스트 마일 송장이 발행된 이후부터 쌓입니다.

• 아직 발행되지 않았거나 트래킹 조회에 실패하면 빈 배열([]) 이 반환됩니다. 필드가 생략되지는 않습니다.
• 트래킹 조회에 실패해도 응답은 200 이며 배송 상태는 정상 반환됩니다.
• 이벤트 발생 시각 occurredAt 은 UTC 기준 하나만 제공합니다.

배송 상태 변경에 대한 웹훅은 제공하지 않습니다. 폴링 방식으로 주기적으로 조회해 주세요.

---

4. 인증과 환경

배송 API의 인증·환경·공통 응답 규약은 기존 오픈 API와 동일합니다.

• API 키 — 키 발급과 Authorization 헤더 사용법
• 환경 — 운영·테스트 환경 URL과 식별자(global-ship)
• 요청 및 응답 — 요청 본문 형식과 공통 응답 규약

---

5. 오류 응답

배송 API의 오류 응답에는 실패 유형을 구분하는 errorCode 가 담깁니다.

{
  "httpStatus": 404,
  "message": "존재하지 않는 DK 입고 송장번호가 포함되어 있습니다.",
  "errorCode": "SHIPMENT_NOT_FOUND",
  "masterNumbers": ["D04510082600099"]
}

HTTP	errorCode	설명
400	INVALID_REQUEST	요청 형식 오류 · 필드 누락 · 유효성 검증 실패
400	MASTER_NUMBERS_EMPTY	라벨 발행(다건) 요청의 송장번호 목록이 비어 있음
400	MASTER_NUMBERS_LIMIT_EXCEEDED	라벨 발행(다건) 요청이 상한 100건을 초과
401	AUTHENTICATION_FAILED	인증 정보 없음 · 위변조 · 만료
403	SHIPMENT_ACCESS_DENIED	다른 고객사의 주문 또는 배송 건 포함
404	SHIPMENT_NOT_FOUND	배송 신청은 존재하지 않는 주문 ID가, 라벨·배송 조회는 존재하지 않는 DK 입고 송장번호가 포함된 경우입니다. 송장번호로 인한 404일 때만 응답 masterNumbers 에 해당 번호가 실립니다
500	DK_LABEL_CREATION_FAILED	라벨 발행 실패
500	INTERNAL_SERVER_ERROR	그 외 서버 오류

배송 신청과 라벨 발행(다건)은 전체 실패 방식입니다. 요청한 건 중 하나라도 조건을 만족하지 못하면 전체가 거부되고, 배송건 생성이나 라벨 발행이 일어나지 않습니다.

라벨 발행 중 서버 오류가 발생한 경우, 그 전에 이미 발행된 라벨은 저장되어 재호출 시 다시 발행되지 않습니다.