快递100寄件测试平台使用说明
平台简介
快递100寄件测试平台（地址：http://testapi.kuaidilab.com/）为开发者提供了一套独立的测试环境，可用于模拟寄件下单、获取快递单号、推送快递状态回调等全流程调试，无需产生真实快递订单。
1. 注册账户
测试平台采用邀请开通制，请直接联系与您对接的商务人员，提供必要信息（如公司名称、联系人、用途），由商务为您开通测试账户。
开通后，您将收到登录所需的账号和密码。
2. 登录并获取认证凭证
-
访问测试平台登录页：http://testapi.kuaidilab.com
-
使用商务为您开通的账户信息登录。
-
登录成功后，进入测试账号信息页面，您将看到调用接口所需的：
-
key（身份标识）
-
secret（签名密钥）
-
-
请妥善保管 secret，切勿泄露或提交至代码仓库。所有接口请求均需使用这对凭证按文档规则生成签名。
3. 准备回调地址
模拟回调会向您的服务端推送快递状态变更通知，因此您需要准备一个可接收 POST 请求的公网地址（例如 https://your-domain.com/callback）。 此地址可以通过以下两种方式提供给测试平台：
- 方式一（推荐）：在调用寄件下单接口时，直接将回调地址填入参数
callbackurl（参数名以实际文档为准）。平台会记录该笔订单的回调地址，后续模拟回调将默认推送到该地址。 - 方式二：在模拟回调页面（见第5步）手动输入回调地址。
4. 调用寄件接口
请严格参照 快递100寄件API文档:https://api.kuaidi100.com/document/5f0ff095bc8da837cbd8aef6 编写调用代码。测试环境中需特别注意：
-
请求地址：将所有接口的根域名替换为测试环境专用地址
- 上门取件API（线上支付）测试环境地址：http://e-test.kuaidilab.com/api/order/borderapi.do
- 上门取件API（线下支付）测试环境地址：http://e-test.kuaidilab.com/api/order/corderapi.do
-
认证方式：使用第2步获取的 key 和 secret 按文档规则生成签名。
- 必填参数：下单时务必按文档传入正确的寄件人、收件人信息以及回调地址（callbackurl），否则无法接收模拟回调。
- 返回结果：测试环境会返回与正式环境结构一致的响应，包含运单号等信息，请记录运单号用于后续回调模拟。
如果您调用成功，可以在测试平台-寄件订单看到创建的订单信息：
5. 模拟快递状态回调
-
访问模拟回调页面：http://testapi.kuaidilab.com/callback
-
在页面中进行模拟测试：
- 轨迹回调地址：不为空时，会按快递信息推送接口的规范https://api.kuaidi100.com/document/5f0ffa8f2977d50a94e1023c，推送物流轨迹信息。
- 模拟状态：选择您需要模拟的快递节点，例如：已揽收、运输中、派送中、已签收、异常等。点击**“应用到报文”**，系统会模拟更新单号的物流状态。
-
点击**“提交”**，系统将立即向指定的回调地址推送一条模拟状态变更通知。
-
检查您的服务端日志，确认是否成功接收到推送，并验证报文格式、签名及业务处理逻辑是否正确。
推送的内容结构和正式环境完全一致，您可以使用此功能测试各种状态的业务处理、异常重试机制。
6. 常见问题
Q：登录后看不到 key 和 secret？
A：确认账户已由商务正常开通，若仍有问题请核对是否登录了正确的地址 http://testapi.kuaidilab.com/sandbox-account。
Q：接口请求报签名错误？
A：请检查 secret 是否复制完整（无多余空格），签名生成方式是否与文档一致，并确认请求参数排序、编码等细节。
Q：模拟回调已发送，但我的服务未收到？
A：请依次排查：
- 回调地址是否可从公网正常访问（未被防火墙拦截）；
- 下单时是否传入了正确的回调地址；
- 是否接收的是 POST 请求，且 Content-Type 匹配；
- 模拟页面是否显示推送成功。
Q：为什么请求到正式环境了？
A：请注意测试环境和正式环境接口请求地址不同，您需要将正式文档中接口路径保持不变，仅替换域名部分即可。如仍有疑问，请联系您的商务获取测试环境完整接口清单。
如您在接入过程中遇到任何问题，欢迎随时联系对接商务人员，或查阅快递100开放平台正式文档获取参数详细说明。祝调试顺利！
