连接自定义承运商 API

Last updated

ChannelDock 提供大量预构建的承运商集成，卖家和履约中心可开箱即用。但我们无法与每个承运商平台都建立连接，因此还提供了 Custom Carrier API。通过它，您作为承运商（或发货平台），可以为卖家或履约中心的 ChannelDock 账户添加自己的发货方式，并自行创建发货面单。

工作原理

您注册自己的发货方式：通过 ChannelDock REST API，在卖家或履约中心的 ChannelDock 账户中注册。
用户选择您的发货方式：在 ChannelDock 中创建发货面单时选择。
ChannelDock 调用您的 API，并传入订单数据和所选的发货方式。
您的 API 返回面单（PDF 格式）以及物流单号。
ChannelDock 打印面单，并将物流单号发送到销售渠道（例如 bol 或 Amazon），使订单被标记为已发货。

您需要开发两个部分：一个用于注册发货方式的脚本（步骤 1），以及您这边用于创建面单的接口（步骤 3 和 4）。

步骤 1：获取 API 凭据

发货方式创建在将使用它们的卖家或履约中心的账户中。该账户生成 API 凭据并提供给您：

卖家：设置 → API 与 Webhooks
履约中心：设置 → API 与 Webhooks

如果 API 密钥的接口权限受到限制，请确保该密钥有权访问 shipment methods 接口。有关 API 密钥的更多信息，请参阅 ChannelDock REST API 文档。

步骤 2：注册您的发货方式

将您的发货方式发送到与账户类型对应的接口：

账户	方法	接口
卖家	POST	`https://channeldock.com/portal/api/v2/seller/shipmentmethods`
履约中心	POST	`https://channeldock.com/portal/api/v2/center/shipmentmethods`

使用 api-key 和 api-secret 请求头进行身份验证。

在 API 文档中找到此接口

打开 docs.channeldock.com，进入 ChannelDock Seller（或 ChannelDock Fulfillment Center）→ Shipment methods → Create / Update custom shipment method。您也可以搜索 “custom shipment method”。我们不提供该章节的直接链接，因为每次重新发布 API 文档时这些链接都会变化。

请求示例

{
  "name": "MyCarrier - Package large express",
  "remote_carrier_id": "my_carrier_large_express",
  "carrier_code": "mycarrier",
  "logo_url": "https://example.com/logo-700x300.png",
  "min_weight": 0,
  "max_weight": 23,
  "max_x": 150,
  "max_y": 150,
  "max_z": 150,
  "mailbox_size": 0,
  "callback_request": {
    "method": "POST",
    "url": "https://yourdomain.com/api/channeldock/labels",
    "headers": {
      "Accept": "application/json",
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_CARRIER_API_TOKEN"
    }
  },
  "shipment_method_countries": [
    { "country_code_from": "NL", "country_code_to": "NL", "price": 3.20 },
    { "country_code_from": "NL", "country_code_to": "BE", "price": 4.80 },
    { "country_code_from": "NL", "country_code_to": "DE", "price": 5.60 }
  ]
}

字段	必填	说明
name	是	发货方式的名称，会显示给用户。也用于识别已有的发货方式（见下文）。
remote_carrier_id	是	您为该发货方式设定的自有 ID。我们会在每次面单请求中原样传回。
carrier_code	是	您的平台或承运商的小写代码，例如 `mycarrier` 或 `dhl`。
logo_url	是	700 x 300 像素 PNG 徽标的公开 URL。
min_weight, max_weight	是	重量限制，单位 kg。
max_x, max_y, max_z	是	最大尺寸，单位 cm。
mailbox_size	是	如果该方式适用于信箱包裹则为 `1`，否则为 `0`。为 `1` 时，仅当包裹能放入信箱才会显示该方式。
callback_request	是	ChannelDock 如何调用您的面单接口：`url`、`method`（建议使用 `POST`）和 `headers`（一个对象，例如包含您自己的认证令牌）。
shipment_method_countries	是	至少一条线路，包含 `country_code_from`、`country_code_to`（2 位 ISO 代码）和 `price`。该发货方式仅在这些线路上提供。

须知

创建或更新： ChannelDock 会在账户中查找同名（name）的现有发货方式。如果存在，则更新（包括 remote_carrier_id 和 callback_request）；如果不存在，则新建。因此，修改 name 会产生第二个发货方式，旧的仍会保留。
线路只会新增或更新，不会删除： 您在请求中省略的线路仍然有效，并保持原价格。
一次注册多个方式： 发送发货方式对象的数组，而不是单个对象。响应中会显示每个方式的结果。
履约中心 可以通过 GET https://channeldock.com/portal/api/v2/center/shipmentmethods 获取其发货方式。

响应

{
  "response": "success",
  "message": "Shipment method MyCarrier - Package large express created successfully"
}

步骤 3：接收面单请求

ChannelDock 用户一旦使用您的某个发货方式创建发货面单，ChannelDock 就会使用您提供的 method 和 headers 调用 callback_request 中的 url。使用 POST（推荐）时，订单数据以 JSON 请求体发送；使用 GET 时，相同字段以查询参数发送。

来自 ChannelDock 的请求示例

{
  "order_id": 774,
  "remote_order_id": "ORD-2025-4055",
  "seller_id": 1223,
  "center_id": 0,
  "api_id": 456,
  "api_description": "Bol.com - Main shop",
  "channel_name": "Bol.com",
  "order_date": "2025-05-13 08:49:28",
  "ship_on_date": "2025-05-14",
  "remote_carrier_id": "my_carrier_large_express",
  "carrier_code": "mycarrier",
  "number_of_labels": 1,
  "sender_details": {
    "name": "John Doe",
    "company_name": "Doe Logistics BV",
    "street": "Keizersgracht",
    "house_number": "241",
    "address_line_2": "Suite 301",
    "zipcode": "1016 EA",
    "city": "Amsterdam",
    "state_province_code": "",
    "country": "NL",
    "phone_number": "+31 20 123 4567",
    "email": "[email protected]",
    "signature_full_name": "John Doe",
    "signature_initials": "JD",
    "vat_number": "NL123456789B01",
    "eori_number": "NL123456789000"
  },
  "shipping_first_name": "Emma",
  "shipping_middle_name": null,
  "shipping_last_name": "van Dijk",
  "shipping_company": "KiteGear BV",
  "shipping_street": "Keizersgracht",
  "shipping_house_number": "123",
  "shipping_house_number_ext": "B",
  "shipping_address1": "Keizersgracht 123",
  "shipping_address2": "2nd floor",
  "shipping_address_supplement": "Entrance via side door",
  "shipping_zip_code": "1015 CJ",
  "shipping_city": "Amsterdam",
  "shipping_region": "Noord-Holland",
  "shipping_country_code": "NL",
  "shipping_email": "[email protected]",
  "shipping_phone_number": "+31 6 12345678",
  "shipping_address_accurate": 1,
  "shipping_service": "",
  "billing_first_name": "Emma",
  "billing_middle_name": null,
  "billing_last_name": "van Dijk",
  "billing_company": "KiteGear BV",
  "billing_street": "Keizersgracht",
  "billing_house_number": "123",
  "billing_house_number_ext": "B",
  "billing_address1": "Keizersgracht 123",
  "billing_address2": "2nd floor",
  "billing_address_supplement": "Finance dept.",
  "billing_zip_code": "1015 CJ",
  "billing_city": "Amsterdam",
  "billing_region": "Noord-Holland",
  "billing_country_code": "NL",
  "billing_email": "[email protected]",
  "total_weight": 8.0,
  "total_length": 80,
  "total_width": 25,
  "total_height": 25,
  "total_order_price": 749.95,
  "total_order_currency": "EUR",
  "order_products": [
    {
      "order_product_id": 868,
      "remote_order_product_id": "NL-PROD-001",
      "ean": "8719326583655",
      "sku": null,
      "quantity": 1,
      "product_title": "North Orbit Kite 2025 - 12m",
      "order_product_price": 699.95,
      "order_product_price_currency": "EUR",
      "product_weight": "5.00",
      "product_length": 80,
      "product_width": 25,
      "product_height": 15,
      "product_hs_code": "95062900",
      "product_origin_country_code": "NL"
    },
    {
      "order_product_id": 869,
      "remote_order_product_id": "NL-PROD-002",
      "ean": "8719326583617",
      "sku": "PUMP-PRO",
      "quantity": 1,
      "product_title": "Mystic Kite Pump Pro",
      "order_product_price": 50.0,
      "order_product_price_currency": "EUR",
      "product_weight": "3.00",
      "product_length": 40,
      "product_width": 10,
      "product_height": 10,
      "product_hs_code": "84142080",
      "product_origin_country_code": "DE"
    }
  ]
}

字段	说明
order_id	ChannelDock 中的订单 ID。
remote_order_id	销售渠道中的订单号（例如 bol 或 Amazon 订单号）。
seller_id, center_id	订单所属的卖家。由履约中心创建面单时会填写 `center_id`，否则为 `0`。
api_id, api_description, channel_name	订单来源的销售渠道连接。
remote_carrier_id	所选发货方式的自有 ID，即您在步骤 2 中注册的值。可用它来决定预订哪项服务。
carrier_code	所选发货方式的 `carrier_code`。
number_of_labels	用户请求的面单（包裹）数量。
sender_details	发件人地址，如有则包含增值税号和 EORI 号。
shipping_*	收货地址。如果您的系统需要分开的字段，请使用 `shipping_street`、`shipping_house_number` 和 `shipping_house_number_ext`；`shipping_address1` 和 `shipping_address2` 包含完整的地址行。
billing_*	账单地址。
total_weight	包裹总重量，单位 kg。
total_length, total_width, total_height	包裹尺寸，单位 cm。
total_order_price, total_order_currency	订单商品的总价值，例如用于海关和保险。
order_products	订单中的商品，包括 EAN、SKU、数量、价格、重量（kg）、尺寸（cm）、HS 编码和原产国。

当 ChannelDock 中没有相应数据时，字段可能为 null 或空，因此请不要把每个字段都视为必填。对于欧盟以外的发货，只有每件商品都有重量时，ChannelDock 才会发送请求。

步骤 4：返回面单

在您的系统中创建面单，并以 HTTP 状态码 200 和以下 JSON 作为响应：

{
  "label_id": "99999",
  "carrier_code": "dhl",
  "tracking_number": "JVGL0123456789",
  "tracking_number_url": "https://www.dhl.com/nl-en/home/tracking.html?tracking-id=JVGL0123456789",
  "pdf_content_base64": "JVBERi0xLjQKJeLjzgo8PC9UeXBlL0NhdGFsb2cvUG..."
}

字段	必填	说明
label_id	是	您系统中的面单 ID。
carrier_code	是	实际派送包裹的承运商（例如 `dhl`、`postnl`、`ups`）。ChannelDock 会将其传递给销售渠道，因此必须与物流单号相匹配。
tracking_number	建议提供	来自同一承运商的物流单号。缺少时仍会创建面单，但销售渠道不会收到物流单号。
tracking_number_url	建议提供	在承运商网站上跟踪该货件的链接。
pdf_content_base64	是	面单，为 PDF 文件，经 Base64 编码，A6 尺寸。当 `number_of_labels` 大于 1 时，请将所有面单放在同一个 PDF 中返回。

如果缺少 label_id、carrier_code 或 pdf_content_base64，用户会看到错误 “Missing field in JSON response”，并且不会创建面单。

之后 ChannelDock 会保存面单、使其可供打印，并将物流单号发送到销售渠道。

错误处理

如果您无法创建面单（例如地址无效），请返回 400 范围内的 HTTP 状态码和一条消息：

{
  "error": {
    "message": "House number is missing in the delivery address"
  }
}

用户随后会在 ChannelDock 中看到以下错误：

Please contact the owner of this shipment method (integration) for support assistance. Shipping error 400 from mycarrier: House number is missing in the delivery address.

请将消息写得让用户知道需要修正什么。用户正在等待面单，因此请在几秒内响应。

测试与故障排除

在卖家或履约中心账户中创建一个测试订单，并使用您的发货方式创建面单。
ChannelDock 会在订单日志中记录发送到您 API 的请求以及您的响应（不含 PDF 内容）。在 ChannelDock 中打开该订单，即可准确查看发送和接收的内容。
创建面单时没有出现您的发货方式？请检查重量和尺寸限制、mailbox_size，以及订单的发件国和目的国之间是否存在对应线路。

Was this helpful?