创建单个发货单

CreateDeclarationShipment 将六个 *Workflow 变更链接到一个 GraphQL 请求中。每个步骤都建立在前面步骤提供的数据之上，所有这些都一起提交，以便完整的发货单可以在一次往返中创建：

partyCreateWorkflow            → 描述原点和目的地参与方
itemCreateWorkflow             → 描述产品行项目
cartonsCreateWorkflow          → 描述物理包装
shipmentRatingCreateWorkflow   → 记录承运人报价
landedCostCalculateWorkflow    → 计算关税/税金/费用
shipmentCreateWorkflow         → 创建发货单 + 标签

Workflow 变更被设计为链式的：你不需要从一个步骤将 ID 映射到下一个步骤，也不需要为每个步骤发送单独的请求。提交整个文档，获得最终的 Shipment 返回。

当最后一个步骤的 serviceLevel 是日本邮政服务等级（japan_post.*）时，Zonos 代表你使用你的 Verified Account 的 Later Pay Numbers 调用日本邮政标签 API（代码 52），生成标签和跟踪号，创建申报 ID，并在最后的 shipmentCreateWorkflow 步骤中链接它们。

为什么是一个变更？ 每个步骤都取决于前一个步骤（落地成本需要产品和参与方；标签需要一切）。将它们捆绑到一个 GraphQL 文档中可以保持数据一致并避免五个额外的往返。

端点和认证 

此链中的请求都使用相同的端点。你在头中传递的内容取决于你的设置 — 选择你的选项卡。

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

示例请求 

一个完整的 CreateDeclarationShipment 请求，你可以复制和调整 — 变更、其变量和响应 — 用于发送给美国的单个日本邮政包裹 DDP。下面逐步部分中分解了每个输入。

逐步说明 

下面每个表格中的 Status 列使用这些术语：

• Required — 没有它请求会失败。
• Required for label — 在 GraphQL 架构中是可选的，但需要生成有效的日本邮政美国标签。
• Conditional — 根据另一个字段（注明内联）是否需要。
• Recommended — 可选，但提高关税和税金的准确性。
• Optional — 不需要。

1. partyCreateWorkflow

创建发货单中涉及的参与方 — 至少一个 ORIGIN（发货单发送的地方）和一个 DESTINATION（买家/收货人）。

示例负载：

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

响应返回创建的 Party ID 和解析的地址字段。

2. itemCreateWorkflow

创建组成发货单的产品行项目。这些是将出现在商业发票上并驱动落地成本计算的 SKU。

HS 代码、原产国和金额是影响第 5 步关税/税金结果最多的三个字段。

3. cartonsCreateWorkflow

创建物理包装 — 将容纳产品的纸箱、聚袋或信件。

每个纸箱成为第 6 步中运单上的一个包裹。多个纸箱 → 多件发货单，每个纸箱有一个跟踪号。

4. shipmentRatingCreateWorkflow

记录商家向买家收取的运费报价。

这是买家在结账时报价的费率。它作为"运费"小计进入落地成本计算，以便针对正确的 CIF 值计算关税和税金。

5. landedCostCalculateWorkflow

运行目的地国家的关税、税金和费用计算。使用前面步骤中的产品、参与方和运费成本。

响应包括 amountSubtotals（duties、taxes、fees、shipping、landedCostTotal） — 这些是你在结账时向买家显示的数字，并打印在商业发票上。

6. shipmentCreateWorkflow

最终步骤 — 创建**Shipment** 实体、生成运单标签和（可选）商业发票/装箱单。

对于日本邮政 Verified Account，这也是 Zonos 代表你调用日本邮政标签 API（代码 52）、注入你的 Later Pay Numbers、创建申报 ID 并将申报 ID 链接到日本邮政返回的跟踪号的地方。

关键字段：

references 子输入

这些字段打印在运单标签和/或商业发票上。使用它们来显示收货人或海关部门需要看到的 PO 号、许可号和自由文本注释。

响应

返回的 Shipment 上有趣的字段是：

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

trackingDetails.number 是日本邮政跟踪号。

label 对象可以通过两种方式返回标签 — 请求符合你的工作流的任何一个（或两个）：

仅选择你需要的字段。请求 url 会保持响应较小；请求 labelImage 会返回完整的标签内联，所以你不需要第二次往返来获取它。上面的示例请求 url。

错误处理 

• 验证错误（缺少必需字段、无效国家代码等）在标准 GraphQL errors 数组中返回并中止链的其余部分。
• 日本邮政错误（标签生成失败、地址无效等）在 shipmentCreateWorkflow 上作为 GraphQL 错误出现。如果需要重试，请联系支持 — 推荐的路径是使用更正的输入重新提交完整的变更。

权限 

每个步骤都独立保护。你的 API 密钥必须为链中的每个实体持有写入作用域（ITEM_WRITE、CARTON_WRITE、SHIPMENT_RATING_WRITE、LANDED_COST_WRITE、SHIPMENT_WRITE）。Verified Account 上的标准商家角色授予所有这些。

后续步骤 

• 批量调度（合并） — 将当天的包裹捆绑成一份日本邮政延期支付调度单。