Создание одной отправки

CreateDeclarationShipment объединяет шесть мутаций *Workflow в один запрос GraphQL. Каждый этап построен на основе данных, предоставленных предыдущими этапами, и все они отправляются вместе, чтобы полная отправка могла быть создана за один раунд обмена данными:

partyCreateWorkflow            → описать стороны отправления + доставки
itemCreateWorkflow             → описать позиции строк
cartonsCreateWorkflow          → описать физическую упаковку
shipmentRatingCreateWorkflow   → записать расценку перевозчика
landedCostCalculateWorkflow    → рассчитать пошлины / налоги / сборы
shipmentCreateWorkflow         → создать отправку + ярлык

Мутации Workflow разработаны для цепочечной обработки: вам не нужно передавать идентификаторы из одного этапа в следующий, и вам не нужно отправлять отдельный запрос для каждого этапа. Отправьте весь документ и получите финальный Shipment.

Когда serviceLevel на финальном этапе — это уровень обслуживания Japan Post (japan_post.*), Zonos вызывает Japan Post Label API (код 52) от вашего имени, используя номера Later Pay вашей проверенной учетной записи, генерирует ярлык и номер отслеживания, создает Declaration ID и связывает их — все внутри финального этапа shipmentCreateWorkflow.

Почему одна мутация? Каждый этап зависит от предыдущего (расчет приземленной стоимости требует позиций + сторон; ярлык требует всего). Объединение их в один документ GraphQL обеспечивает согласованность данных и избегает пяти дополнительных раундов обмена данными.

Конечная точка и аутентификация 

Все запросы в этой цепочке используют одну и ту же конечную точку. Что вы передаете в заголовках, зависит от вашей установки — выберите вашу вкладку.

URL:

https://api.zonos.com/graphql

Заголовки:

credentialToken: {{YOUR_API_TOKEN}}

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

Полный запрос CreateDeclarationShipment, который вы можете скопировать и адаптировать — мутация, ее переменные и ответ — для одной посылки Japan Post, отправленной DDP в США. Каждый ввод разбирается в пошаговом разделе ниже.

Пошаговое выполнение 

Столбец Статус в каждой таблице ниже использует следующие термины:

• Требуется — запрос не выполнится без этого.
• Требуется для ярлыка — не обязательно в схеме GraphQL, но необходимо для создания действительного ярлыка Japan Post для США.
• Условное — требуется в зависимости от другого поля (указано в строке).
• Рекомендуется — необязательно, но обеспечивает точные пошлины и налоги.
• Необязательно — не требуется.

1. partyCreateWorkflow

Создает стороны, участвующие в отправке — как минимум ORIGIN (откуда отправляется посылка) и DESTINATION (покупатель / получатель).

Пример полезной нагрузки:

[
  { "type": "DESTINATION", "location": { "countryCode": "US" }, "person": {} },
  { "type": "ORIGIN", "location": { "countryCode": "JP" }, "person": {} }
]

Ответ возвращает созданные идентификаторы Party и разрешенные поля адреса.

2. itemCreateWorkflow

Создает позиции строк, которые составляют отправку. Это артикулы (SKU), которые будут отображаться в коммерческом счете-фактуре и управлять расчетом приземленной стоимости.

Код HS, страна происхождения и сумма — это три поля, которые в наибольшей степени влияют на результат пошлины / налога на этапе 5.

3. cartonsCreateWorkflow

Создает физические упаковки — коробки, полиэтиленовые пакеты или письма, которые будут содержать товары.

Каждая коробка становится одной посылкой на ярлыке перевозчика на этапе 6. Несколько коробок → многокомпонентная отправка с одним номером отслеживания на коробку.

4. shipmentRatingCreateWorkflow

Записывает расценку, которую торговец взимает с покупателя за доставку.

Это тариф, предложенный покупателю при оформлении покупки. Он входит в расчет приземленной стоимости как подитог «доставка», чтобы пошлины и налоги рассчитывались для правильного значения CIF.

5. landedCostCalculateWorkflow

Запускает расчет пошлин, налогов и сборов для страны назначения. Использует товары, стороны и стоимость доставки из предыдущих этапов.

Ответ включает amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — это числа, которые вы отображаете покупателю при оформлении и которые печатаются в коммерческом счете-фактуре.

6. shipmentCreateWorkflow

Завершающий этап — создает сущность Shipment, генерирует ярлык перевозчика и (опционально) коммерческий счет-фактуру / лист упаковки.

Для проверенных учетных записей Japan Post это также место, где Zonos вызывает Japan Post Label API (код 52) от вашего имени, внедряет ваши номера Later Pay, создает Declaration ID и связывает Declaration ID с номером отслеживания, возвращенным Japan Post.

Ключевые поля:

Для contentsType два наиболее распространенных значения для трафика проверенных учетных записей — это ECOMMERCE_GOODS (продано потребителю, BtoC) и COMMERCIAL_GOODS (продано между компаниями, BtoB). Они задают pkgType, который Zonos отправляет в вызове Japan Post Label API, поэтому этот выбор меняет то, что печатается в таможенной декларации, — это не просто ярлык.

Вспомогательный ввод nonDelivery

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

option принимает ровно эти четыре значения. Значения RETURN не существует — используйте RETURN_AFTER_RETENTION или RETURN_IMMEDIATELY, чтобы выбрать, когда посылка возвращается.

API предоставляет оба варианта возврата отдельно; опция Возврат в Dashboard объединяет оба.

transportMethod принимает AIR или MOST_ECONOMICAL и определяет, как возвращаемая посылка будет доставлена обратно. Это применяется только к двум опциям RETURN_* — Dashboard показывает соответствующее поле Способ возврата только тогда, когда выбрано Возврат.

{
  "nonDelivery": {
    "option": "RETURN_AFTER_RETENTION",
    "transportMethod": "MOST_ECONOMICAL"
  }
}

Переключатель Если доставка невозможна в диалоге Создать ярлык в Dashboard записывает то же самое поле, поэтому ярлык, созданный в Dashboard, и ярлык, созданный через API, ведут себя одинаково.

Вспомогательный ввод references

Эти поля печатаются на ярлыке перевозчика и / или счете-фактуре. Используйте их для отображения номеров закупок, номеров лицензий и свободного текста замечаний, которые нужно видеть получателю или таможенному органу.

Ответ

Интересующие поля на возвращенном Shipment:

{
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      url
      labelImage
    }
  }
}

trackingDetails.number — это номер отслеживания Japan Post.

Объект label может возвращать ярлык двумя способами — запросите то, что подходит вашему рабочему процессу (или оба):

Запросите только нужные вам поля. Запрос url уменьшает размер ответа; запрос labelImage возвращает полный ярлык встроенным, чтобы вам не понадобился второй раунд обмена данными для его загрузки. Пример выше запрашивает url.

Уровни обслуживания Japan Post 

Передайте один из этих кодов в качестве serviceLevelCode в shipmentRatingCreateWorkflow.

Коды уровней обслуживания используют точки, а не подчеркивания. Вы можете встретить форму с подчеркиванием (japan_post_air_parcel) в сообщениях об ошибках и внутренних ссылках, но она не является допустимым вводом.

Воздушные услуги

Наземные услуги

Выбор между похожими услугами

Мелкий пакет и International Air Packet. Обе услуги ограничены весом 2 кг. japan_post.air.packet — это отслеживаемая услуга Japan Post для мелких пакетов. japan_post.air.small_packet — её неотслеживаемый эквивалент. Если вам нужно отслеживание для легкой посылки, используйте japan_post.air.packet.

Заказные варианты. Для писем и печатных материалов отслеживание добавляется заказной (書留) версией услуги. japan_post.air.printed_matter и japan_post.air.letter сами по себе его не включают.

Устаревшие коды

japan_post.air.epacket_light — это бывший International e-Packet Light. Japan Post переименовала эту услугу в International Air Packet 1 июня 2026 года и расширила её на все страны и регионы. Сама услуга не изменилась.

Старый код по-прежнему распознаётся, поэтому существующие интеграции продолжают работать, но для новых разработок используйте japan_post.air.packet.

Коды транспортного режима

japan_post.air, japan_post.surface, japan_post.economy_air и japan_post.custom также распознаются, но они обозначают транспортный режим или запасной вариант, а не конкретный почтовый продукт. Используйте один из указанных выше кодов услуг для обычных отправок.

Проверка отправляемого кода

Нераспознанный serviceLevelCode не вызывает ошибку. Запрос возвращает HTTP 200 без массива errors, serviceLevel возвращается как null, а стоимость доставки выпадает из итоговой приземленной стоимости — поэтому ответ выглядит корректным, хотя суммы неверны.

Всегда проверяйте, что shipmentRatingCreateWorkflow.serviceLevel не равен null, прежде чем полагаться на итоговые суммы.

Чтобы получить актуальный список в любой момент:

{
  serviceLevels(carrier: "carrier_00004c9b-9431-4518-bfbc-b9f8476335b1") {
    code
    name
  }
}

Этот запрос принимает ID перевозчика. Передача кода перевозчика japan_post возвращает пустой список без ошибки.

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

• Ошибки валидации (отсутствующие обязательные поля, неверные коды стран и т. д.) возвращаются в стандартный массив GraphQL errors и прерывают остальную цепочку.
• Ошибки Japan Post (ошибка генерации ярлыка, неверный адрес и т. д.) отображаются как ошибки GraphQL на shipmentCreateWorkflow. Если требуется повторная попытка, свяжитесь с поддержкой — рекомендуемый путь — повторно отправить полную мутацию с исправленным вводом.

VALIDATION_INVALID_TYPE_VARIABLE

{
  "errors": [
    {
      "message": "invalid type for variable: 'shipmentInput'",
      "extensions": {
        "name": "shipmentInput",
        "code": "VALIDATION_INVALID_TYPE_VARIABLE"
      }
    }
  ]
}

Эта ошибка называет всю переменную целиком, а не то поле, которое на самом деле неверно. Почти всегда это означает, что одно из значений перечисления внутри этой переменной не входит в набор допустимых значений — чаще всего это nonDelivery.option, contentsType или serviceLevel.

Это не проблема типизации JSON. Добавление или удаление кавычек у булевых значений и чисел ничего не изменит, потому что до этой проверки полезная нагрузка не доходит — сначала отклоняется значение перечисления.

Чтобы найти проблемное поле, проверьте каждое поле с типом перечисления в переменной на соответствие допустимым значениям:

Полный список значений перечисления для любого ввода приведен на странице его типа в справочнике API.

Разрешения 

Каждый этап защищен отдельно. Ваш API ключ должен иметь область записи для каждой сущности в цепочке (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). Стандартная роль торговца на проверенной учетной записи предоставляет все это.

Следующие шаги 

• Пакетная отправка (консолидация) — объедините дневные посылки в один лист отсроченной оплаты Japan Post.