> ## 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.

# 배송 신청

> <Warning>주문 등록 API로 등록한 주문만 신청할 수 있습니다.</Warning>주문 ID 목록을 받아 배송건을 생성하고, 생성된 배송 ID와 DK 입고 송장번호(`masterNumber`)를 반환합니다. 반환된 `masterNumber`는 라벨 발행·배송 정보 조회 API의 입력값입니다.

요청한 주문 중 하나라도 신청할 수 없는 건이 있으면 **전체가 실패하며 배송건은 생성되지 않습니다.** 다른 고객사의 주문이 섞이거나, 존재하지 않는 주문 ID가 있거나, 이미 배송 신청된 주문이 포함된 경우가 이에 해당합니다.

자세한 호출 순서와 식별자 흐름은 [배송 API 시작하기](/reference/global-ship/shipping-guide)를 참고하세요. 인증은 [API 키](/reference/using-api/api-keys) · [환경](/reference/using-api/environment) 문서를 따릅니다.



## OpenAPI

````yaml api-reference/global-ship-api.json POST /open-api/v1/shipments
openapi: 3.0.1
info:
  title: Global Ship Open API
  description: '-'
  version: 1.0.0
servers:
  - url: https://gw-staging.delivered.co.kr/global-ship
    description: 테스트 환경
  - url: https://gw.delivered.co.kr/global-ship
    description: 운영 환경
security:
  - accessToken: []
  - Authorization: []
tags:
  - name: 주문
    description: 주문
paths:
  /open-api/v1/shipments:
    post:
      tags:
        - 배송
      summary: 배송 신청
      description: >-
        <Warning>주문 등록 API로 등록한 주문만 신청할 수 있습니다.</Warning>주문 ID 목록을 받아 배송건을 생성하고,
        생성된 배송 ID와 DK 입고 송장번호(`masterNumber`)를 반환합니다. 반환된 `masterNumber`는 라벨
        발행·배송 정보 조회 API의 입력값입니다.


        요청한 주문 중 하나라도 신청할 수 없는 건이 있으면 **전체가 실패하며 배송건은 생성되지 않습니다.** 다른 고객사의 주문이
        섞이거나, 존재하지 않는 주문 ID가 있거나, 이미 배송 신청된 주문이 포함된 경우가 이에 해당합니다.


        자세한 호출 순서와 식별자 흐름은 [배송 API 시작하기](/reference/global-ship/shipping-guide)를
        참고하세요. 인증은 [API 키](/reference/using-api/api-keys) ·
        [환경](/reference/using-api/environment) 문서를 따릅니다.
      operationId: createShipment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenApiCreateShipmentRequest'
        required: true
      responses:
        '201':
          description: Created — 배송건이 생성되었습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiCreateShipmentResponse'
        '400':
          description: >-
            요청 항목 검증에 실패했습니다. 주문 ID 목록이 비어 있거나, 형식이 올바르지 않거나, 이미 배송 신청된 주문이 포함된
            경우입니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiErrorResponse'
              example:
                httpStatus: 400
                message: >-
                  요청 항목 검증에 실패했습니다. 주문 ID 목록이 비어 있거나, 형식이 올바르지 않거나, 이미 배송 신청된
                  주문이 포함된 경우입니다.
                errorCode: INVALID_REQUEST
        '401':
          description: 인증에 실패했습니다. 인증 정보가 없거나 위변조·만료되었습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiErrorResponse'
              example:
                httpStatus: 401
                message: 인증에 실패했습니다. 인증 정보가 없거나 위변조·만료되었습니다.
                errorCode: AUTHENTICATION_FAILED
        '403':
          description: 다른 고객사의 주문이 포함되어 있습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiErrorResponse'
              example:
                httpStatus: 403
                message: 다른 고객사의 주문이 포함되어 있습니다.
                errorCode: SHIPMENT_ACCESS_DENIED
        '404':
          description: 존재하지 않는 주문 ID가 포함되어 있습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiErrorResponse'
              example:
                httpStatus: 404
                message: 존재하지 않는 주문 ID가 포함되어 있습니다.
                errorCode: SHIPMENT_NOT_FOUND
        '500':
          description: 서버 오류가 발생했습니다. 배송건은 생성되지 않았습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiErrorResponse'
              example:
                httpStatus: 500
                message: 서버 오류가 발생했습니다. 배송건은 생성되지 않았습니다.
                errorCode: INTERNAL_SERVER_ERROR
components:
  schemas:
    OpenApiCreateShipmentRequest:
      required:
        - orderIds
      type: object
      properties:
        orderIds:
          type: array
          description: 배송 신청 대상 주문 ID 목록. 주문 등록 API 응답의 `orderId` 값입니다.
          example:
            - 1
            - 2
            - 3
          items:
            type: integer
            format: int64
    OpenApiCreateShipmentResponse:
      required:
        - shipments
      type: object
      properties:
        shipments:
          type: array
          description: 생성된 배송 신청 목록
          items:
            $ref: '#/components/schemas/CreatedShipment'
    OpenApiErrorResponse:
      type: object
      description: 오픈 API 오류 응답
      required:
        - httpStatus
        - message
      properties:
        httpStatus:
          type: integer
          description: HTTP 상태 코드
          example: 404
        message:
          type: string
          description: 오류 메시지
        errorCode:
          type: string
          description: >-
            실패 유형을 구분하는 코드. `AUTHENTICATION_FAILED` · `SHIPMENT_ACCESS_DENIED` ·
            `SHIPMENT_NOT_FOUND` · `MASTER_NUMBERS_EMPTY` ·
            `MASTER_NUMBERS_LIMIT_EXCEEDED` · `INVALID_REQUEST` ·
            `DK_LABEL_CREATION_FAILED` · `INTERNAL_SERVER_ERROR`
          example: SHIPMENT_NOT_FOUND
        masterNumbers:
          type: array
          description: '`SHIPMENT_NOT_FOUND`일 때만 실립니다. 존재하지 않는 DK 입고 송장번호 목록입니다.'
          items:
            type: string
          example:
            - D04510082600099
    CreatedShipment:
      required:
        - mallOrderNumber
        - masterNumber
        - orderId
        - shipmentId
      type: object
      description: 생성된 배송 신청
      properties:
        orderId:
          type: integer
          format: int64
          description: 요청한 주문 ID
          example: 1
        mallOrderNumber:
          type: string
          description: 주문 등록 시 전달한 쇼핑몰 주문 번호
          example: ORD202501010001
        shipmentId:
          type: integer
          format: int64
          description: 생성된 배송 ID
          example: 74536
        masterNumber:
          type: string
          description: DK 입고 송장번호. 라벨 발행·배송 정보 조회 API의 입력값이며, 라벨 바코드에 인쇄되는 번호와 같습니다.
          example: D04510082600064
  securitySchemes:
    accessToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
    Authorization:
      type: apiKey
      description: 발급받은 시크릿 키
      name: Authorization
      in: header

````