> ## Documentation Index
> Fetch the complete documentation index at: https://developers-partners.delivered.co.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# 배송 API 시작하기

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

## 1. 호출 순서

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

<Steps>
  <Step title="주문 등록">
    `POST /open-api/v1/orders` 로 주문을 등록하고 `orderId` 를 받습니다.
  </Step>

  <Step title="배송 신청">
    `POST /open-api/v1/shipments` 에 `orderId` 목록을 전달해 배송건을 생성하고, `shipmentId` 와 `masterNumber`(DK 입고 송장번호)를 받습니다.
  </Step>

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

  <Step title="배송 조회">
    `GET /open-api/v1/shipments/{masterNumber}/tracking` 으로 배송 상태와 트래킹 정보를 조회합니다.
  </Step>
</Steps>

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

## 2. 식별자 흐름

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

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

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

***

## 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** 기준 하나만 제공합니다.

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

***

## 4. 인증과 환경

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

* [API 키](/reference/using-api/api-keys) — 키 발급과 `Authorization` 헤더 사용법
* [환경](/reference/using-api/environment) — 운영·테스트 환경 URL과 식별자(`global-ship`)
* [요청 및 응답](/reference/using-api/req-res) — 요청 본문 형식과 공통 응답 규약

***

## 5. 오류 응답

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

```json theme={null}
{
  "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`         | 그 외 서버 오류                                                                                                         |

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

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