Пакетная отправка (консолидация)

Этот документ описывает трёхэтапный процесс создания партии Japan Post с отложенной оплатой через GraphQL API Zonos: откройте консолидацию, приложите n отправок к ней, затем закройте её, чтобы получить накладную Japan Post (документ манифеста).

Когда использовать этот процесс 

Программа отложенной оплаты Japan Post (後納) позволяет торговцу рассчитаться за все дневные доставки в одной транзакции в конце дня, вместо того чтобы платить за каждую посылку при передаче. Торговец приносит все посылки дня в почтовое отделение вместе с одной накладной (差出票) на 250 отправок. Почтовые расходы выставляются на номер отложенной оплаты, предварительно зарегистрированный у торговца.

Если вы отправляете отдельные этикетки Japan Post и платите поштучно в окне, вам не нужен этот процесс — вызовите одиночную отправку напрямую без консолидации.

Обзор 

1. shipmentConsolidationCreate            → открыть партию (возвращает ID консолидации)
2. Приложить отправки × n                 → создать каждую отправку + этикетку, приложить к партии
3. shipmentConsolidationUpdate(CLOSED)    → закрыть партию (возвращает накладную)

Существует два способа приложения отправок к партии — используйте то, что лучше всего подходит для вашей интеграции (или комбинируйте их):

• Приложить при создании этикетки — передайте ID консолидации из шага 1 в каждый вызов shipmentCreateWorkflow через поле shipmentConsolidationId.
• Приложить существующие отправки по ID — передайте shipmentIds в shipmentConsolidationCreate (чтобы подготовить партию) или в shipmentConsolidationUpdate (чтобы добавить к открытой партии). Каждая отправка должна уже иметь этикетку Japan Post.

В любом случае каждая этикетка создаётся с вашим номером отложенной оплаты, встроенным для того, чтобы Japan Post смогла принять её на накладную при закрытии партии на шаге 3.

Почему отдельные вызовы вместо одной мутации? Шаги 2.1, 2.2, ..., 2.n происходят в течение дня торговца — этикетки печатаются и посылки запечатываются по мере поступления заказов. Партия не может быть одним круглым путём, как одиночная цепочка отправки: между открытием консолидации и её закрытием есть промежуток в несколько часов.

Предварительные условия 

Прежде чем этот процесс будет работать для данного проверенного аккаунта:

• Ваш аккаунт должен иметь номер отложенной оплаты Japan Post (後納お客様番号), сохранённый на нём — значение в формате с дефисами, как 1111111111-222222-3333333333-444444. Передайте его в shipmentConsolidationCreate через accountNumber (Шаг 1).
• Ваш ключ API должен иметь SHIPMENT_WRITE плюс стандартные области действия, необходимые для рабочего процесса для каждой отправки.

Endpoint и аутентификация 

Все три шага ниже — это GraphQL операции, отправленные на один и тот же endpoint. То, что вы передаёте в заголовках, зависит от вашей настройки — выберите свой вариант.

URL:

https://api.zonos.com/graphql

Заголовки:

credentialToken: {{YOUR_API_TOKEN}}

Пример запроса 

Копируемый и адаптируемый пример открытия консолидации — мутация, её переменные и ответ. Это зависящий от партии вызов, который запускает процесс; приложение отправок (Шаг 2) повторно использует пример одиночной отправки, а закрытие партии (Шаг 3) возвращает документ манифеста. Каждое поле подробно описано в следующих шагах.

Шаг 1: shipmentConsolidationCreate 

Открывает консолидацию. Код перевозчика блокирует партию на Japan Post; все участвующие отправки должны использовать уровни обслуживания Japan Post. Если у вас уже есть помеченные отправки, подготовьте партию с их ID через shipmentIds — в противном случае создайте её пустой и приложите отправки на шаге 2.

Мутация:

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
    }
  }
}

Ответ:

{
  "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...) — вы будете использовать его везде ниже. status — это OPEN до шага 3.

Шаг 2: Приложить отправки 

Для каждой посылки, которую вам нужно отправить сегодня, запустите полный цепочечный процесс одиночной отправки, чтобы создать отправку и её этикетку. Затем приложите отправку к партии, используя один из методов ниже.

Вариант A: Приложить при создании этикетки

Передайте ID консолидации на финальном шаге shipmentCreateWorkflow цепочки. Все предшествующие мутации в цепочке идентичны рабочему процессу одиночной отправки.

Соответствующие поля в shipmentCreateWorkflow:

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

Вариант B: Приложить существующие отправки по ID

Если ваши отправки уже созданы и помечены, добавьте их к открытой партии с shipmentIds в shipmentConsolidationUpdate:

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

Оставьте status вне входа, пока вы ещё добавляете отправки — партия остаётся OPEN. Каждая отправка должна использовать уровень обслуживания Japan Post и иметь свою этикетку (номер отслеживания) перед закрытием партии на Шаге 3.

Что означает приложение для этикетки

Независимо от используемого варианта, когда отправка Japan Post является частью консолидации:

• Отправка имеет номер отслеживания, как обычно.
• PDF этикетки доставки не включает копии для клиента/почтового отделения. Эти квитанции отложены на Шаг 3, где они объединены в документ накладной для всей партии.
• Отправка связана с консолидацией; вы можете повторно запросить её через shipmentConsolidation(id: ...), чтобы увидеть её участников.

Повторите этот шаг для каждой посылки в дневной партии. До 250 отправок на консолидацию; попытка закрыть большую партию завершается неудачей с чётким сообщением об ошибке валидации перед любым вызовом Japan Post.

Вы также можете проверить содержимое партии перед закрытием:

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

Каждая отправка должна показать номер отслеживания здесь. Если нет, её этикетка никогда не была создана — разберитесь с этим перед закрытием. status — это OPEN до закрытия консолидации на Шаге 3.

Шаг 3: shipmentConsolidationUpdate(status: CLOSED) 

Закрывает партию. Это вызов, который просит Japan Post создать накладную отложенной оплаты, охватывающую номер отслеживания каждого участника, и присоединяет результирующий PDF к консолидации.

Операция GraphQL названа CloseConsolidation, чтобы описать её намерение — закрыть партию. Она запускает мутацию shipmentConsolidationUpdate с status: CLOSED.

Мутация:

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

На запрос CLOSED:

1. Консолидация проверяется: ≤250 отправок, и каждый участник должен иметь номер отслеживания. Если отправка не имеет номера отслеживания (её этикетка никогда не была создана), вызов отклоняется.
2. Japan Post просят создать накладную отложенной оплаты, охватывающую номер отслеживания каждого участника.
3. Статус ненадолго переходит в MANIFEST_CREATED, пока выполняется получение PDF-файла накладной, затем в CLOSED после присоединения документа.
4. PDF накладной (один файл, содержащий накладную плюс копии клиента/почтового отделения каждого участника) присоединяется к консолидации как CustomsDocument с documentType: MANIFEST_DOCUMENT.

Ответ:

{
  "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"
        }
      ]
    }
  }
}

Получение документов

Накладная присоединяется непосредственно к консолидации как CustomsDocument с documentType: MANIFEST_DOCUMENT — возьмите fileUrl из ответа на закрытие выше или запросите его в любое время позже:

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

Распечатайте PDF на fileUrl. Он содержит:

• Страница 1: Накладная отложенной оплаты — передайте её в почтовое отделение.
• Страницы 2+: Копии клиента/почтового отделения для каждой посылки — по одной скреплённой к каждой посылке, другая остаётся в почтовом отделении.

Ещё раз печать, принесите посылки + накладную + квитанции в почтовое отделение в одной поездке. Japan Post выставляет счёт вашему номеру отложенной оплаты в конце расчётного периода.

Собираем всё вместе 

Репрезентативный день для торговца, отправляющего 50 посылок Japan Post, выглядит так:

08:00 → shipmentConsolidationCreate(JAPAN_POST, accountNumber)  → shco_01HJK...
08:30 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    посылка 1
09:15 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    посылка 2
...
16:45 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    посылка 50
17:30 → shipmentConsolidationUpdate(id: "shco_01HJK...", status: CLOSED)
17:32 → Распечатать PDF

Предпочитаете пакетно закрывать в конце дня? Создайте этикетки дня без ID консолидации, затем откройте консолидацию один раз со всеми значениями shipmentIds (или добавьте их порциями через shipmentConsolidationUpdate) и закройте её в том же или последующем вызове.

Если вы доставляете через несколько бизнес-подразделений / расчётных счетов, запустите отдельную консолидацию на счет — передайте другой accountNumber на каждый shipmentConsolidationCreate и маршрутизируйте отправки соответственно. Отправляете более 250 посылок в день? Откройте вторую консолидацию.

Обработка ошибок 

Ошибки валидации (перехвачены перед любым вызовом Japan Post)

• Неверный формат accountNumber — отклонено на Шаге 1 (shipmentConsolidationCreate) перед сохранением консолидации. Сообщение об ошибке определяет проблемный сегмент.
• >250 отправок — отклонено на Шаге 3, перед вызовом Japan Post.
• Отправка участника без номера отслеживания — отклонено на Шаге 3. Означает, что создание этикетки молча завершилось неудачей ранее; исследуйте затронутую отправку через shipment(id: ...) { trackingDetails }.
• Нет номера отложенной оплаты на консолидации — отклонено на Шаге 3. Передайте accountNumber в shipmentConsolidationCreate или сохраните номер аккаунта отложенной оплаты по умолчанию на вашем аккаунте Japan Post.

Ошибки API Japan Post

Если Japan Post отклонит запрос на накладную, мутация на закрытие выводит код ошибки и сообщение перевозчика как ошибку GraphQL. Наиболее распространённые:

Повторные попытки

Если вызов на закрытие завершится неудачей после того, как Japan Post принимает запрос на накладную (т.е. во время получения PDF), повторное выполнение shipmentConsolidationUpdate(status: CLOSED) безопасно — платформа пропустит вызов перевозчика и просто повторит получение и присоединение документа.

Если закрытие завершится неудачей перед тем, как Japan Post принимает запрос (ошибка валидации, E0xx, тайм-аут сети), состояние не изменилось — исправьте основную причину и повторите попытку.