> ## 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. 호출 순서

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

**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는 이 번호를 키로 사용합니다.

> [!WARNING]
>
> 주문만 등록한 상태에서는 라벨도 배송 상태도 존재하지 않습니다. 배송 신청을 해야 배송건이 생성되고 `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** 기준 하나만 제공합니다.

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

***

## 4. 인증과 환경

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

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

***

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.