일괄 발송(consolidation)

이 문서는 Zonos GraphQL API를 통해 Japan Post 후납 발송 batch를 생성하는 3단계 flow를 설명합니다. consolidation을 열고, n개의 배송을 연결한 뒤, 마감하여 Japan Post 발송표(manifest 문서)를 받습니다.

이 flow를 사용하는 경우 

Japan Post 후납 프로그램(後納)을 사용하면 판매자는 소포를 접수할 때마다 건별로 결제하는 대신, 하루 종료 시점에 일일 배송비를 한 번에 정산할 수 있습니다. 판매자는 당일의 모든 소포와 함께 최대 250건의 배송을 포함하는 발송표(差出票) 하나를 우체국에 제출합니다. 우편료는 사전 등록된 Later Pay Number로 청구됩니다.

개별 Japan Post 라벨을 발송하고 창구에서 소포별로 결제하는 경우에는 이 flow가 필요하지 않습니다. consolidation 없이 단일 배송 체인을 직접 호출하세요.

개요 

1. shipmentConsolidationCreate            → open the batch (returns consolidation ID)
2. Attach shipments × n                   → create each shipment + label, attached to the batch
3. shipmentConsolidationUpdate(CLOSED)    → close the batch (returns the dispatch slip)

batch에 배송을 연결하는 방법은 두 가지입니다. 연동 방식에 맞는 방법을 사용하거나(또는 혼합) 진행하세요.

• 라벨 생성 시 연결 — 1단계에서 받은 consolidation ID를 각 shipmentCreateWorkflow 호출의 shipmentConsolidationId 필드로 전달합니다.
• ID로 기존 배송 연결 — shipmentConsolidationCreate(batch 초기 구성) 또는 shipmentConsolidationUpdate(열린 batch에 추가)에서 shipmentIds를 전달합니다. 각 배송에는 이미 Japan Post 라벨이 있어야 합니다.

어떤 방법을 사용하든 각 라벨에는 Later Pay Number가 포함되어 생성되므로, 3단계에서 batch를 마감할 때 Japan Post가 발송표에 해당 라벨을 수락합니다.

왜 하나의 mutation이 아니라 별도 호출인가요? 2.1, 2.2, ..., 2.n 단계는 판매자의 하루 동안 분산됩니다. 주문이 들어올 때마다 라벨을 인쇄하고 소포를 봉인합니다. 단일 배송 체인과 달리 batch는 단일 round-trip으로 처리할 수 없습니다. consolidation을 연 뒤 마감하기까지 수 시간의 간격이 있습니다.

사전 요건 

특정 Verified Account에서 이 flow가 동작하려면 다음이 필요합니다.

• 계정에 Japan Post 후납 Later Pay Number(後納お客様番号)가 저장되어 있어야 합니다. 1111111111-222222-3333333333-444444와 같이 하이픈으로 구분된 형식입니다. 1단계에서 shipmentConsolidationCreate의 accountNumber로 전달하세요.
• API key에 SHIPMENT_WRITE와 배송별 workflow에 필요한 표준 scope가 있어야 합니다.

엔드포인트 및 인증 

아래 세 단계는 모두 동일한 엔드포인트로 전송하는 GraphQL 작업입니다. 헤더에 전달할 값은 설정에 따라 다릅니다. 해당 탭을 선택하세요.

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

예제 요청 

consolidation을 여는 복사·수정용 예제입니다. mutation, variables, response를 포함합니다. flow를 시작하는 batch 전용 호출이며, 배송 연결(2단계)은 단일 배송 예제를 재사용하고, batch 마감(3단계)은 manifest 문서를 반환합니다. 각 필드는 아래 단계에서 설명합니다.

1단계: shipmentConsolidationCreate 

consolidation을 엽니다. carrier code는 batch를 Japan Post에 고정하며, 모든 구성 배송은 Japan Post service level을 사용해야 합니다. 라벨이 준비된 배송이 이미 있으면 shipmentIds로 batch에 초기 구성하고, 그렇지 않으면 빈 batch를 연 뒤 2단계에서 배송을 연결하세요.

Mutation:

mutation {
  shipmentConsolidationCreate(
    input: {
      carrierCode: JAPAN_POST
      accountNumber: "1111111111-222222-3333333333-444444"
      name: "Tokyo dispatch — 2026-05-01"
      externalId: "merchant-batch-20260501-001"
      shipmentIds: ["shipment_01hxa...", "shipment_01hxb..."]
    }
  ) {
    id
    status
    accountNumber
    carrierCode
    shipments {
      id
    }
  }
}

Response:

{
  "data": {
    "shipmentConsolidationCreate": {
      "id": "shco_01hjk...",
      "status": "OPEN",
      "accountNumber": "1111111111-222222-3333333333-444444",
      "carrierCode": "JAPAN_POST",
      "shipments": [
        { "id": "shipment_01hxa..." },
        { "id": "shipment_01hxb..." }
      ]
    }
  }
}

id(예: shco_01HJK...)를 보관하세요. 이후 모든 단계에서 사용합니다. 3단계 전까지 status는 OPEN입니다.

2단계: 배송 연결 

오늘 발송할 각 소포마다 연결된 단일 배송 workflow 전체를 실행하여 배송과 라벨을 생성합니다. 그다음 아래 방법 중 하나로 batch에 연결하세요.

옵션 A: 라벨 생성 시 연결

체인의 마지막 shipmentCreateWorkflow 단계에서 consolidation ID를 전달합니다. 체인의 이전 mutation은 단일 배송 workflow와 동일합니다.

shipmentCreateWorkflow의 관련 필드:

shipmentCreateWorkflow(
  input: {
    serviceLevel: "japan_post.air.ems_merchandise"
    shipmentConsolidationId: "shco_01hjk..."
    generateLabel: true
  }
) {
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      labelImage
    }
  }
}

옵션 B: ID로 기존 배송 연결

배송이 이미 생성·라벨링되어 있으면 shipmentConsolidationUpdate의 shipmentIds로 열린 batch에 추가하세요.

mutation {
  shipmentConsolidationUpdate(
    input: {
      id: "shco_01hjk..."
      shipmentIds: ["shipment_01hxd...", "shipment_01hxe..."]
    }
  ) {
    id
    status
    shipments {
      id
    }
  }
}

아직 배송을 추가하는 중이면 input에서 status를 생략하세요. batch는 OPEN 상태를 유지합니다. 3단계에서 batch를 마감하기 전에 각 배송은 Japan Post service level을 사용하고 라벨(추적 번호)이 있어야 합니다.

연결이 라벨에 미치는 영향

어떤 옵션을 사용하든 Japan Post 배송이 consolidation에 포함되면 다음과 같습니다.

• 배송에는 평소와 같이 추적 번호가 있습니다.
• 배송 라벨 PDF에는 고객/우체국 영수증 사본이 포함되지 않습니다. 해당 영수증은 3단계로 연기되며, batch 전체의 발송표 문서에 묶입니다.
• 배송은 consolidation과 연결됩니다. shipmentConsolidation(id: ...)로 재조회하여 구성원을 확인할 수 있습니다.

당일 batch의 모든 소포에 대해 이 단계를 반복하세요. consolidation당 최대 250건까지 가능하며, 더 큰 batch를 마감하려 하면 Japan Post 호출 전에 명확한 유효성 검사 오류로 실패합니다.

마감 전 batch 내용을 확인할 수도 있습니다.

query {
  shipmentConsolidation(id: "shco_01hjk...") {
    status
    shipments {
      id
      trackingDetails {
        number
      }
    }
  }
}

모든 배송에 추적 번호가 표시되어야 합니다. 없으면 라벨이 생성되지 않은 것입니다. 마감 전에 해결하세요. 3단계에서 consolidation을 마감하기 전까지 status는 OPEN입니다.

3단계: shipmentConsolidationUpdate(status: CLOSED) 

batch를 마감합니다. 이 호출은 Japan Post에 모든 구성원의 추적 번호를 포함하는 후납 발송표 생성을 요청하고, 결과 PDF를 consolidation에 첨부합니다.

GraphQL 작업 이름은 batch 마감 의도를 나타내기 위해 CloseConsolidation입니다. status: CLOSED로 shipmentConsolidationUpdate mutation을 실행합니다.

Mutation:

mutation CloseConsolidation {
  shipmentConsolidationUpdate(input: { id: "shco_01hjk...", status: CLOSED }) {
    id
    status
    statusTransitions {
      status
      changedAt
      note
    }
    customsDocuments {
      documentType
      fileUrl
    }
  }
}

CLOSED 요청 시:

1. consolidation이 검증됩니다. 배송 ≤250건이며 모든 구성원에 추적 번호가 있어야 합니다. 추적 번호가 없으면(라벨이 생성되지 않음) 호출이 거부됩니다.
2. Japan Post에 모든 구성원의 추적 번호를 포함하는 후납 발송표 생성을 요청합니다.
3. 발송표 PDF를 가져오는 동안 status가 잠시 MANIFEST_CREATED로 바뀌었다가, 문서가 첨부되면 CLOSED가 됩니다.
4. 발송표 PDF(발송표와 모든 구성원의 고객/우체국 영수증이 하나의 파일)가 documentType: MANIFEST_DOCUMENT인 CustomsDocument로 consolidation에 첨부됩니다.

Response:

{
  "data": {
    "shipmentConsolidationUpdate": {
      "id": "shco_01hjk...",
      "status": "CLOSED",
      "statusTransitions": [
        {
          "status": "OPEN",
          "changedAt": "2026-05-01T08:00:00Z",
          "note": "Shipment batch created"
        },
        {
          "status": "MANIFEST_CREATED",
          "changedAt": "2026-05-01T17:30:12Z",
          "note": "Dispatch slip created with Japan Post"
        },
        {
          "status": "CLOSED",
          "changedAt": "2026-05-01T17:30:14Z",
          "note": "Dispatch slip downloaded and uploaded"
        }
      ],
      "customsDocuments": [
        {
          "documentType": "MANIFEST_DOCUMENT",
          "fileUrl": "https://customs-docs.zonos.com/.../japanpost-dispatch-slip.pdf"
        }
      ]
    }
  }
}

문서 조회

발송표는 documentType: MANIFEST_DOCUMENT인 CustomsDocument로 consolidation에 직접 첨부됩니다. 위 마감 응답의 fileUrl을 사용하거나, 이후 언제든지 조회할 수 있습니다.

query {
  shipmentConsolidation(id: "shco_01hjk...") {
    status
    customsDocuments {
      documentType
      fileUrl
    }
  }
}

fileUrl의 PDF를 인쇄하세요. 포함 내용:

• 1페이지: 후납 발송표 — 우체국에 제출합니다.
• 2페이지 이후: 각 소포의 고객/우체국 영수증 — 하나는 소포에 부착하고, 다른 하나는 우체국이 보관합니다.

인쇄 후 소포, 발송표, 영수증을 한 번에 우체국에 가져가세요. Japan Post는 청구 기간 종료 시 Later Pay Number로 청구합니다.

전체 흐름 정리 

Japan Post 소포 50건을 발송하는 판매자의 하루 예시는 다음과 같습니다.

08:00 → shipmentConsolidationCreate(JAPAN_POST, accountNumber)  → shco_01HJK...
08:30 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 1
09:15 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 2
...
16:45 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 50
17:30 → shipmentConsolidationUpdate(id: "shco_01HJK...", status: CLOSED)
17:32 → Print PDF

하루 말에 일괄 묶기를 선호하나요? consolidation ID 없이 당일 라벨을 생성한 뒤, 모든 shipmentIds로 consolidation을 한 번 열거나(shipmentConsolidationUpdate로 분할 추가) 같은 호출 또는 후속 호출에서 마감하세요.

여러 사업부/청구 계정으로 발송하는 경우 account별로 별도 consolidation을 실행하세요. 각 shipmentConsolidationCreate에 다른 accountNumber를 전달하고 배송을 해당 consolidation으로 라우팅하세요. 하루 250건을 초과하면 두 번째 consolidation을 여세요.

오류 처리 

유효성 검사 오류(Japan Post 호출 전에 차단)

• accountNumber 형식 오류 — 1단계(shipmentConsolidationCreate)에서 consolidation 저장 전에 거부됩니다. 오류 메시지에 문제 구간이 표시됩니다.
• 250건 초과 — 3단계에서 Japan Post 호출 전에 거부됩니다.
• 구성 배송에 추적 번호 없음 — 3단계에서 거부됩니다. 이전에 라벨 생성이 조용히 실패했음을 의미합니다. shipment(id: ...) { trackingDetails }로 해당 배송을 조사하세요.
• consolidation에 후납 번호 미설정 — 3단계에서 거부됩니다. shipmentConsolidationCreate에 accountNumber를 전달하거나 Japan Post carrier 계정에 기본 account number를 저장하세요.

Japan Post API 오류

Japan Post가 발송표 요청을 거부하면 마감 mutation이 carrier의 오류 코드와 메시지를 GraphQL 오류로 반환합니다. 흔한 경우:

재시도

Japan Post가 발송표 요청을 수락한 후 마감 호출이 실패하는 경우(PDF 조회 중) shipmentConsolidationUpdate(status: CLOSED) 재시도는 안전합니다. 플랫폼은 carrier 호출을 건너뛰고 문서 조회·첨부만 다시 시도합니다.

Japan Post가 요청을 수락하기 전 마감이 실패하면(유효성 검사 오류, E0xx, 네트워크 타임아웃) 상태는 변경되지 않습니다. 근본 원인을 수정한 뒤 재시도하세요.