创建单个发货单

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 链接到日本邮政返回的跟踪号的地方。

关键字段：

对于 contentsType，Verified Account 流量中最常见的两个取值是 ECOMMERCE_GOODS（卖给消费者，BtoC）和 COMMERCIAL_GOODS（企业间交易，BtoB）。它们决定了 Zonos 在调用日本邮政标签 API 时发送的 pkgType，因此这一选择会改变海关申报单上打印的内容 — 它不仅仅是一个标签字段。

nonDelivery 子输入

告诉日本邮政在包裹无法送达时该如何处理 — 被收货人拒收、在边境被拒绝入境，或按地址无法送达。

option 只接受以下四个值。没有 RETURN 这个值 — 使用 RETURN_AFTER_RETENTION 或 RETURN_IMMEDIATELY 来选择包裹返回的时机。

API 将两种退件方式分别开放；Dashboard 的 Return 选项则同时覆盖这两者。

transportMethod 接受 AIR 或 MOST_ECONOMICAL，用于设置退回包裹的运输方式。它仅适用于两个 RETURN_* 选项 — 只有在选择了 Return 时，Dashboard 才会显示对应的 Return method 字段。

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

Dashboard Create label 对话框中的 If undeliverable 选择器写入的正是这同一个字段，因此在 Dashboard 中创建的标签和通过 API 创建的标签行为完全一致。

references 子输入

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

响应

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

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

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

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

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

日本邮政服务等级 

在 shipmentRatingCreateWorkflow 中，将以下代码之一作为 serviceLevelCode 传入。

服务等级代码使用点号，不是下划线。你可能会在错误消息和内部引用中看到下划线形式（japan_post_air_parcel），但它不是有效的输入。

航空服务

水陆服务

在相似服务之间选择

小包与国际航空小包。 两者上限都是 2 公斤。japan_post.air.packet 是日本邮政可跟踪的小包服务。japan_post.air.small_packet 是不可跟踪的等效服务。如果轻量包裹需要跟踪，请使用 japan_post.air.packet。

挂号变体。 对于信函和印刷品，跟踪功能由该服务的挂号（書留）版本提供。japan_post.air.printed_matter 和 japan_post.air.letter 本身不包含跟踪功能。

已弃用的代码

japan_post.air.epacket_light 曾是国际 e-Packet Light。日本邮政已于2026 年 6 月 1 日将该服务重命名为国际航空小包，并将其扩展到所有国家和地区。服务本身没有变化。

旧代码仍然有效，因此现有集成可以继续正常工作，但新工作请使用 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 不为空。

要随时获取当前列表：

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

此查询接受承运人的 ID。传入承运人代码 japan_post 会返回一个空列表，且不会报错。

错误处理 

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

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）。Verified Account 上的标准商家角色授予所有这些。

后续步骤 

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