快速开始

这份文档面向要把自己的系统接入 Alpha Cargo TMS 的开发者。读完你应该能独立完成一条完整链路：建单 → 排车 → 跟踪 → 接收事件通知。

如果你只想按资源查接口字段，请直接看各章的字段表；如果你是第一次接入，请从本页往下顺序读。

两种集成模式

接入之前先确认你属于哪一种 —— 这决定了你调哪组接口、用哪种鉴权。

	A 自己承运	B 报价卖运力
场景	货已经是你的，推进 TMS 后自己排车	给终端客户报价、收款，再安排履约
入口	POST /api/waybills	POST /api/quotes
鉴权	组织签名	组织签名 + X-Sender-Account-Id
排车	你调装载规划接口	客户付款后系统自动创建
跟踪	GET /api/waybills/{waybillNo}/events	GET /api/orders/{id}/tracking

两条路最终会汇合：B 模式下客户付款后，系统会自动创建运单和配送，之后的状态流转与 A 模式完全一致。

两种模式可以同时使用。

整体流程

5 分钟连通性自检

拿到 api_key / api_secret 后，先确认凭证可用再写业务代码。下面这个接口不受套餐限制，是最干净的自检入口：

GET https://staging.alphacargo.io/api/organizations

它需要签名。完整的可运行示例（Node.js / Python）在组织鉴权一章，你也可以直接导入 Postman Collection —— 里面已经内置了自动签名脚本，填上 key/secret 就能点。

返回你的组织信息即表示凭证正常。若返回 401，看鉴权排查表。

接下来

1. 组织鉴权 —— 签名怎么算，X-Sender-Account-Id 怎么用
2. 运单 CRUD —— 建单、查单、改单、取消、面单
3. 地址解析 —— 把自由文本变成结构化地址和经纬度
4. 配送规划与跟踪 —— 两条 FTL 路径
5. 配送事件 Webhook —— 接收轨迹变更通知
6. Postman Collection —— 导入即可测试

约定

• 所有示例的基地址都是 https://staging.alphacargo.io（测试环境）。请先在测试环境跑通，正式接入时再换成你拿到的生产域名。
• 示例中的 ak_example... / as_example... 是占位值，请替换成你自己的凭证。
• 时间除特别说明外都是 ISO 8601 UTC。
• 请求和响应都是 application/json，除非接口明确返回 PDF 或接收 multipart/form-data。