免开发寄件组件对接文档

一、接口介绍

本文档面向快递100API开放平台的客户，指导其通过对接寄件H5组件，快速在其应用或网页中集成寄件功能。

对接流程概览：

1. 获取授权：调用授权接口，获取业务接口的访问凭证（Authorization）。
2. 导入订单：调用订单导入接口，预填寄件信息，生成任务ID（id）。
3. 嵌入组件：拼接URL，通过iframe将寄件H5组件嵌入您的页面。
4. 接收回调：监听回调接口，获取用户下单结果。
5. 管理订单：根据业务需要，调用取消订单等接口。

二、授权接口

后续所有业务接口（订单导入、取消订单等）均需在请求头中携带授权凭证（Authorization）。此凭证通过本接口获取，有效期为30分钟，过期后需刷新。

2.1 获取授权凭证

接口地址：POST https://api.kuaidi100.com/apisentback/auth/token Content-Type：application/json

请求参数：

请求示例：

{
  "key": "your_authorized_key",
  "timestamp": 1646819137650,
  "sign": "223C4078B7D664A86D1722FE5E9F5430"
}

响应参数：

data字段详情：

响应示例：

{
  "result": true,
  "returnCode": 200,
  "message": "SUCCESS",
  "data": {
    "authorization": "gmtCe4eee9xuBdxKjWdBo_kLA4jGjvBWfBTtcvjMblAcZ_654564543mUSk",
    "expireTime": 1800000
  }
}

凭证使用方法： 将data.authorization的值放入后续请求的Header中：

Authorization: gmtCe4eee9xuBdxKjWdBo_kLA4jGjvBWfBTtcvjMblAcZ_dYYvmGjNXyEmUSk

2.2 刷新授权凭证

授权凭证（authorization）默认有效期为30分钟。在有效期内，您可以通过本接口刷新凭证，获取新的authorization和expireTime。

接口地址：https://api.kuaidi100.com/apisentback/auth/refresh

请求方式：POST 或 GET

Content-Type：application/json

请求头：

请求示例（无请求体，仅携带Header）：

Authorization: gmtCe4eee9xuBdxKjWdBo_kLA4jGjvBWfBTtcvjMblAcZ_dYYvmGjNXyEmUSk

响应参数：

data字段内容：

响应示例：

{
  "result": true,
  "returnCode": 200,
  "message": "SUCCESS",
  "data": {
    "authorization": "gmtCe4eee9xuBdxKjWdBo_kLA4jGjvBWfBTtcvjMblAcZ_dYYvmGjNXyEmUSk",
    "expireTime": 1800000
  }
}

三、业务接口

3.1 寄件信息预导入接口

在用户进入H5组件前，通过此接口预填寄件人、收件人、物品等信息，简化用户操作。

接口地址：POST https://api.kuaidi100.com/apisentback/border/importOrderInfo Content-Type：application/json

请求参数：

param数据结构：

请求示例：

{
  "key": "your_key",
  "t": "1750317297077",
  "sign": "28E47AC27E283D09CDD6BC623CD23E3F",
  "param": "{\"thirdOrderId\":\"123456\",\"kuaidiCom\":\"yuantong\",\"recName\":\"张三\",\"recMobile\":\"13800138000\",\"recPrintAddr\":\"上海市浦东新区xx路1号\",\"sendPrintAddr\":\"广东省深圳市南山区xx路2号\",\"sendName\":\"李四\",\"sendMobile\":\"13900139000\",\"cargo\":\"文件\",\"weight\":\"0.5\",\"payer\":1,\"callbackUrl\":\"https://your.domain.com/callback\"}"
}

响应参数：

响应示例：

{
  "result": true,
  "returnCode": "200",
  "message": "成功",
  "data": "111111"
}

3.2 取消订单接口

通过此接口取消用户已下单但快递员尚未取件的订单。

接口地址：POST https://api.kuaidi100.com/apisentback/ent/cancelOrder Content-Type：application/x-www-form-urlencoded

请求参数：

param数据结构：

请求示例：

key=your_key
sign=4BBDE07660E5EFF90873642CFAE9A8DD
t=1647258957705
param={"orderId":"694509391680","cancelMsg":"用户取消"}

响应参数：

响应示例：

{
  "result": true,
  "returnCode": "200",
  "message": "SUCCESS",
  "data": "成功"
}

四、回调接口

4.1 订单状态回调

用户通过H5组件下单后，订单状态发生变更（下单成功、快递员接单、取消、签收等）时，快递100服务器会向您在导入订单接口传入的回调地址（callbackUrl）推送订单状态。

推送方式：POST Content-Type：application/x-www-form-urlencoded

回调参数：

param数据结构：

data数据结构：

回调请求示例：

sign=58686F006D7860706188314BF3BCEC02
taskId=58686F006D7860706188314BF3BCEC08
param={
    "data": {
        "courierName": "向力军",
        "defPrice": null,
        "mktId": null,
        "orderId": "288222524",
        "courierMobile": "1772***105",
        "price": null,
        "freight": null,
        "weight": null,
        "pollToken": "0DnLJY3be0zNp71yJ7XWWK0mhNys4teXATSL1+3Fn7Y=",
        "status": 9
    },
    "kuaidicom": "shentong",
    "kuaidinum": "772042264852909",
    "message": "成功",
    "status": "200"
}

您需返回的响应： 接收到回调后，请返回如下JSON，告知快递100服务器已成功接收。

{
  "result": true,
  "returnCode": "200",
  "message": "SUCCESS"
}

五、前端嵌入说明

5.1 H5链接拼接规则

通过iframe嵌入寄件H5组件，URL拼接规则如下：

https://m.kuaidi100.com/h5activities/apiReverseShipping/?key=<授权凭证>&id=<任务ID>&hideTitleBar=1

Query参数说明：

5.2 示例代码

<iframe 
  src="https://m.kuaidi100.com/h5activities/apiReverseShipping/?key=gmtCe4eee9xuBdxKjWdBo_kLA4jGjvBWfBTtcvjMblAcZ_654564543mUSk&id=111111&hideTitleBar=1" 
  width="100%" 
  height="800px" 
  frameborder="0">
</iframe>

效果示意图：

六、发票接口

针对寄件订单寄件人直接支付运费场景，平台提供线上开票功能，支持单笔或多笔订单合并申请发票。请注意，寄件金支付订单无法使用此接口开票，请联系快递100商务处理。

6.1 开票申请接口

提交开票申请，最多支持 10笔订单 合并开票。开票成功后，系统会主动回调您传入的 callbackUrl。

接口地址：POST https://api.kuaidi100.com/apisentback/invoice/apply

Content-Type：application/x-www-form-urlencoded

请求参数

param 参数结构

请求示例

POST /invoice/apply
Content-Type: application/x-www-form-urlencoded

key=your_key&sign=sign_value&t=1747200000&param={"importOrderId":["ORDER001","ORDER002"],"invoiceType":1,"titleType":1,"title":"测试企业","taxNo":"91110000MA00XXXXXX","remark":"测试开票","callbackUrl":"https://your-domain.com/callback"}

响应参数

data 结构

响应示例

{
    "result": true,
    "code": 200,
    "message": "成功",
    "data": {
        "taskId": "123456789",
        "pdfUrl": "https://example.com/invoice/123.pdf",
        "ofdUrl": "https://example.com/invoice/123.ofd",
        "xmlUrl": "https://example.com/invoice/123.xml"
    }
}

6.2 发票详情接口

根据开票申请返回的 taskId 查询发票最新状态及下载链接。

接口地址：POST https://api.kuaidi100.com/apisentback/invoice/detail

Content-Type：application/x-www-form-urlencoded

请求参数

param 参数结构

请求示例

POST /invoice/detail
Content-Type: application/x-www-form-urlencoded

key=your_key&sign=sign_value&t=1747200000&param={"taskId":"123456789"}

响应参数

data 结构

响应示例

{
    "result": true,
    "code": 200,
    "message": "成功",
    "data": {
        "taskId": "123456789",
        "pdfUrl": "https://example.com/invoice/123.pdf",
        "ofdUrl": "https://example.com/invoice/123.ofd",
        "xmlUrl": "https://example.com/invoice/123.xml",
        "status": 1,
        "invoiceAmount": "100.00",
        "title": "测试企业",
        "titleType": 1,
        "taxNo": "91110000MA00XXXXXX",
        "remark": "测试开票",
        "invoiceType": 1
    }
}

6.3 发票状态回调

当您提交开票申请时指定了 callbackUrl，平台将在开票状态变更（开票成功、开票失败）时，以 HTTP POST 方式主动向该地址推送通知。

推送方式：POST

Content-Type：application/x-www-form-urlencoded

回调参数

param 参数结构

回调请求示例

POST https://your-domain.com/callback
Content-Type: application/x-www-form-urlencoded

param={"taskId":"123456789","status":1,"pdfUrl":"https://example.com/invoice/123.pdf","ofdUrl":"https://example.com/invoice/123.ofd","xmlUrl":"https://example.com/invoice/123.xml"}&sign=md5_hash_value&taskId=123456789

您需返回的响应
接收到回调后，请返回以下 JSON，告知平台已成功接收。

{
    "result": true,
    "code": 200,
    "message": "成功"
}

重试机制：若您返回的 result 不为 true 或 HTTP 状态码非 200，系统会在 5分钟 后重试，最多重试 3次。

七、 附录

7.1 全局状态码说明

7.2 快递公司编码（常用示例）

更多编码见快递100官网：https://api.kuaidi100.com/manager/v2/express-company