快速开始

苍鸾系统对接文档

本文档面向接入苍鸾系统的客户开发人员。协议格式全平台统一，每个客户只使用自己账号中生成的接口地址和凭据。

租户隔离文档不按签约公司复制。公司、客户和下单权限由接口凭据自动绑定，调用方不得传入或猜测内部公司代码、客户代码。

获取接入信息

客户管理员登录客户服务端，进入“接口接入”。
新增接口账号并选择接口规范。
保存系统一次性展示的账号、密钥或密码；长期页面只显示必要的调用标识。
为兼容协议维护外部产品编号与已授权下单产品的映射。

接口账号与页面登录账号归属同一客户，接口下单与页面下单执行相同的产品、地址、报价、财务和幂等校验。

苍鸾标准接口

POSThttps://api.cluan.cn/api/v1/orders

使用 AccessKey 与 SecretKey 对请求签名。签名密钥只允许当前客户管理员查看，轮换后旧密钥立即失效。

Content-Type: application/json
X-Access-Key: <客户接口账号中的 AccessKey>
X-Timestamp: <毫秒时间戳>
X-Nonce: <随机字符串>
X-Signature: <HMAC-SHA256 签名>
Idempotency-Key: <客户侧唯一请求号>

完整字段、响应结构和查询接口见 OpenAPI YAML。

华磊兼容接口

适用于客户原系统已经支持华磊协议、不希望重新开发报文的场景。客户专属下单地址和面单地址由系统自动生成。

POST客户接口接入页显示的下单地址

GET客户接口接入页显示的面单地址

调用时使用系统生成的接口账号、接口密码、客户编号、客户用户编号和华磊产品编号。产品编号只映射到当前客户已授权且启用的下单产品。

统一业务校验

身份鉴权→客户准入→产品授权与路由→报价与附加费→财务校验→服务商下单

页面下单、苍鸾标准接口和华磊兼容接口共用订单核心。失败请求返回明确阶段和原因；相同幂等键不会重复创建订单或重复扣费。

轨迹与面单

订单取得运单号后，Worker 自动建立轨迹同步任务。默认每 15 秒扫描待处理任务，未妥投订单每 30 分钟向服务商拉取一次，失败后 10 分钟重试；妥投后停止常规轮询。仅服务商支持 POD 时才创建 POD 拉取任务。

客户可在订单详情查看订单时间线，也可使用签约公司提供的公开查件网址查询。公开查件只展示当前签约公司订单，不会触发一次新的服务商调用。

错误与重试

错误类型	处理方式
鉴权失败	核对账号、密钥、时间戳和签名；不要自动无限重试。
参数或地址错误	修改数据后使用新的幂等键重新提交。
余额、授权或报价不足	由客户管理员或运营人员完成配置后重试。
服务商临时失败	保留原请求号，按响应中的可重试标识执行退避重试。