API / 派送用 API

ParcelBee 派送 API

第一版开放接口聚焦一票一件派送流程：先询价，再创建订单，然后获取面单、 取消订单或查询轨迹。后续文档中心会继续加入操作说明、账单说明和更多集成文档。

Overview

Base URL

https://api.parcelbee.ca

认证方式

Public API 建议使用 API Key。正式字段名会在接口开发时确定。

Authorization: Bearer <api_key>
第一版范围

Quote 只支持一票一件。Create Order 会在服务端重新验价，客户传入的价格只作为参考， 最终扣费以服务端报价和 ParcelBee 价格规则为准。

Endpoint 1

询价接口

根据发货邮编、收件邮编和单件包裹尺寸重量，返回所有允许参与 API Quote 的可用渠道报价。 返回价格需要包含运费、燃油费、附加费、税和最终总价。 

POST /api/v1/public/quotes
字段 要求 说明
sender.postalCode 必填 发货邮编，用于渠道报价。
recipient.postalCode 必填 收件邮编，用于尾程可用性、DAS 和附加费判断。
package.lengthCm / widthCm / heightCm 必填 单件包裹尺寸，单位 cm。
package.weightKg 必填 单件包裹重量，单位 kg。

Endpoint 2

创建订单接口

创建一票一件订单。此接口需要完整发货人、收件人、包裹和渠道信息，并会执行地址、 电话、渠道启用状态、重复订单号、钱包余额和服务端重新验价检查。 

POST /api/v1/public/orders
字段 要求 说明
externalReference 必填 客户系统订单号，也用于幂等和防重复。
quoteId 或 channelCode 必填 推荐使用 quoteId，服务端仍会重新验证最终价格。
sender / recipient 必填 需要完整联系人、电话、地址、城市、省份、国家和邮编。
package 必填 第一版只接受单件包裹。

Endpoint 3

获取面单接口

根据 ParcelBee 订单号获取 provider label 或 last-mile label。第一版建议只支持单票查询。

GET /api/v1/public/orders/{orderNo}/label

Endpoint 4

取消订单接口

根据订单状态尝试取消订单。已经入网或尾程不支持取消的订单，需要返回明确失败原因。

POST /api/v1/public/orders/{orderNo}/cancel

Endpoint 5

获取轨迹接口

返回订单最新状态和轨迹事件列表。可按 ParcelBee 订单号查询，后续可扩展 tracking number 查询。

GET /api/v1/public/orders/{orderNo}/tracking