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

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

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

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

Когда serviceLevel на финальном этапе — это уровень обслуживания Japan Post (japan_post.*), Zonos вызывает Japan Post Label API (код 52) от вашего имени, используя номера Later Pay вашей проверенной учетной записи, генерирует ярлык и номер отслеживания, создает 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, создает ID объявления и связывает ID объявления с номером отслеживания, возвращенным Japan Post.

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

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

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

Ответ

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

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

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

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

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

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

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

Разрешения 

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

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

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