腾讯出行服务跑腿MCP开发文档
1. 简介
本文档用于描述腾讯出行服务基于跑腿业务MCP能力外输的对接说明。
当外输方接入腾讯跑腿MCP时,必要实现以下行为
本文档分为2个部分:
- 第一部分:API 能力描述
- 第二部分:MCP能力描述
2. API能力描述
2.1 基础说明
- 接口协议 除非特殊指定,默认请求方式均为 HTTPS/POST 方式。
- 返回数据格式 除非特殊指定,默认返回数据格式均为 JSON 格式。
- 字符编码 除非特殊指定,默认字符编码均为 UTF-8 编码格式。
- 请求格式 接口内如果没有特殊说明的,请求格式一律统一为 application/json 。
- 重试机制 调⽤出行服务接口时,返回码 Code 不成功,要有重试机制(具体见错误码表)。
- 通用参数
| 字段名 | 字段类型 | 最大长度 | 必填 | 说明 |
| api_key | string | 32 | 是 | 腾讯出行服务分配给服务商调用api_key |
| seq_id | string | 36 | 是 | 请求流水号,调用方自动生成一个随机ID,建议使用uuid |
| timestamp | int | 11 | 是 | 请求发送时的时间戳(unix时间戳) 秒 |
| nonce | string | 10 | 是 | 10位随机字符串 |
| sign | string | 32 | 是 | 验证签名参数 |
| 字段名 | 字段类型 | 最大长度 | 必填 | 说明 |
| code | int | 11 | 是 | 服务响应状态,参见错误码表 |
| message | string | 64 | 是 | 服务响应状态说明,参见错误码表 |
| data | object | - | 否 | 具体的接口对应不同的对象详见具体的接口 |
错误码表
| 错误码范围 | 分类 |
| 0 | 成功 |
| 500 | 服务器异常 |
| 5000 ~ 5999 | 通用错误 |
| 10001 ~ 10050 | 业务错误 |
| 20000 ~ 29999 | 转发相关错误 |
| 30000 ~ 39999 | 用户状态错误 |
2.2 需外输方提供API
- 接口域名路径由外输方提供
- 接口AKSK研发线下同步
2.2.1 登录态同步
- 接口说明 本接口用于出行服务在用户完成OAuth授予后,向外输方同步用户accessToken。
- 请求地址 /token/sync (外输方可自定义)
- 请求方式 POST
- 请求参数 通用参数 + 业务参数
业务参数
| 参数名称 | 类型 | 最大长度 | 必选 | 说明 |
| usercode | string | 64 | 是 | 来自外输方的用户标识码 |
| access_token | string | 256 | 是 | 访问令牌 |
| refresh_token | string | 256 | 是 | 刷新令牌 |
| expires_in | int | 11 | 是 | 过期时间(秒) |
| 参数名称 | 类型 | 最大长度 | 必选 | 说明 |
| code | int | 11 | 是 | 服务响应状态,参见错误码表 |
| message | string | 64 | 是 | 服务响应状态说明,参见错误码表 |
2.2.2 订单状态同步
- 接口说明 本接口用于出行服务向外输方提供外输订单的信息同步。
- 请求地址 /order/sync (外输方可自定义)
- 请求方式 POST
- 请求参数 通用参数 + 业务参数
业务参数
| 参数名称 | 类型 | 最大长度 | 必选 | 说明 |
| usercode | string | 64 | 是 | 来自外输方的用户标识码 |
| order_code | string | 64 | 是 | 订单ID |
| order_data | string | - | 是 | 订单数据,JSON字符串格式 |
| 参数名称 | 类型 | 最大长度 | 必选 | 说明 |
| code | int | 11 | 是 | 服务响应状态,参见错误码表 |
| message | string | 64 | 是 | 服务响应状态说明,参见错误码表 |
2.3 腾讯方API
腾讯方域名路径
腾讯方AKSK
- 在出行服务开放平台注册【第三方接入应用】后,可查看
2.3.1 refreshToken刷新
- 接口说明 本接口用于外输方通过后台刷新refreshToken
- 请求路径 /tms/auth/refreshToken
- 请求方式 POST
- 请求参数 通用参数 + 业务参数
业务参数
| 参数名称 | 类型 | 最大长度 | 必选 | 说明 |
| usercode | string | 64 | 是 | 来自外输方的用户标识码 |
| refresh_token | string | 256 | 是 | 刷新令牌 |
| 参数名称 | 类型 | 最大长度 | 必选 | 说明 |
| code | int | 11 | 是 | 服务响应状态,参见错误码表 |
| message | string | 64 | 是 | 服务响应状态说明,参见错误码表 |
| data | object | - | 是 | |
data结构定义
| 参数名称 | 类型 | 最大长度 | 必选 | 说明 |
| access_token | string | 256 | 是 | 访问令牌 |
| refresh_token | string | 256 | 是 | 刷新令牌 |
| expires_in | int | 11 | 是 | 过期时间(秒) |
2.3.2 订单查询接口
- 接口说明 : 用于查询跑腿订单的最新状态及费用明细。
- 接口路径 :/runerrand/api/mcp/order/detail
- 输入参数结构 :
| 序号 | 字段名 | 类型 | 必填 | 说明 | 示例 |
| 1 | usercode | String | 是 | 外输方用户标识 | your-usercode-value |
| 2 | order_code | String | 是 | 订单ID,不传时查询当前账号下未完成订单 | yb0IEI5Fc2SVp6 |
JSON 示例:
| 参数名 | 类型 | 长度 | 必选 | 说明 |
| code | int | 10 | 是 | 参考下方响应Code定义 |
| message | string | 64 | 否 | 错误描述信息 |
| data | object | | 否 | 响应数据对象,详见ResponseData结构定义 |
ResponseData结构定义
| 参数名称 | 类型 | 参数描述 |
| orderCode | string | 订单ID |
| orderStatusText | string | 订单状态文案,如:派单中、取件中、送件中、已完成等 |
| spName | string | 运力商名称,如:顺丰同城、达达、京东秒送等 |
| expressTypeName | string | 送件类型名称,如:特惠跑腿、极速跑腿 |
| riderName | string | 骑手姓名 |
| riderPhone | string | 骑手手机号 |
| deliveryTime | integer | 预计送达时间,Unix时间戳(秒) |
| totalFee | string | 总费用,单位元 |
| payFee | string | 实际费用(已扣除优惠后),单位元 |
| paidFee | string | 已支付费用,单位元 |
| couponFee | string | 优惠费用,单位元 |
| cancelFee | string | 取消费,单位元(有值时需告知用户) |
| refundFee | string | 退款费用,单位元 |
| waitRefundFee | string | 待退款费用,单位元 |
| customerInfo | List | 客服信息列表,详见CustomerInfo结构定义 |
| orderSuggestion | string | 大模型话术建议,可直接参考该字段组织回复话术 |
CustomerInfo结构定义
| 参数名称 | 类型 | 参数描述 |
| title | string | 客服标题,如:顺丰同城电话客服 |
| phones | List | 客服电话列表,示例:["4001881888"] |
| onlineTimeInfos | List | 客服在线时间列表,示例:["8:00-22:00"] |
JSON 示例:
3. MCP能力描述
3.1 接入方式
创建MCP KEY
登录腾讯出行服务开放平台控制台,申请MCP KEY。具体参考腾讯出行服务MCP接入指南 (opens new window)。
协议支持
支持 SSE 协议 和 Streamable HTTP 协议,所有请求均基于 JSON-RPC 2.0 进行通信。
接入地址
SSE协议接入地址:
Streamable HTTP协议接入地址:
接入方式
请求头鉴权接入,需要在请求头 Authorization 中填入申请的MCP KEY,在请求头 Access-Token 中填入用户访问令牌。
以Streamable HTTP协议示例:
3.2 响应状态编码(code)
公共响应码
所有MCP接口通用的响应码:
| 编码 | 说明 |
| 0 | 成功 |
| 10000 | 服务器开小差了,请稍后重试 |
| 10001 | 参数校验错误 |
| 10002 | 业务失败 |
| 10003 | 无数据 |
| 11001 | 用户未登录 |
业务个性响应码
todo
3.3 MCP能力
输出格式说明
所有 MCP 工具的输出均遵循 JSON-RPC 2.0 协议格式。实际返回结构如下:
其中 result.content[].text 字段的值是一个 JSON 字符串,其内容为各工具的业务响应(即下文各工具描述的输出参数结构 code/message/data)。
完整响应结构说明:
| 层级 | 字段名 | 类型 | 说明 |
| 外层(JSON-RPC) | jsonrpc | string | 固定值 "2.0" |
| 外层(JSON-RPC) | id | int | 请求ID,与请求中的 id 对应 |
| 外层(JSON-RPC) | result | object | MCP 结果对象 |
| result | content | array | 内容数组 |
| content[] | type | string | 内容类型,固定为 "text" |
| content[] | text | string | 业务响应 JSON 字符串(包含 code/message/data) |
JSON 示例(完整MCP协议响应):
text字段内容解析后:
MCP工具见下附录
4. 第三方应用拉起出行小程序能力描述
4.1 跳转流程

4.2 前置条件
| 序号 | 准备事项 | 说明 |
| 1 | 微信开放平台注册移动应用 | 在 微信开放平台 (opens new window) 创建移动应用并通过审核,获得移动应用 AppID |
| 2 | 关联出行服务小程序 | 在微信开放平台「管理中心 → 移动应用 → 详情 → 关联小程序信息」中关联出行小程序(已认证的开放平台账号可跳转任意合法小程序,无需关联) |
| 3 | 出行服务开放平台注册 | 在 出行服务开放平台 (opens new window) 注册商户,创建【第三方接入应用】和【MCP应用】 |
| 4 | 获取出行侧参数 | 从出行侧获取小程序原始ID、授权页路径等,详见 1.1.5 |
| 5 | iOS配置Universal Links | iOS应用需按微信要求配置Universal Links,详见官方iOS接入指南 |
4.3 参考资源与示例
Android 拉起授权页:
Android 接收回调(WXEntryActivity.onResp):
4.4 相关参数
| 参数名 | 说明 | 示例值 | 用途 |
userName | 出行服务小程序的原始ID | gh_ad64296dc8bd | WXLaunchMiniProgram.Req.userName,指定拉起的小程序 |
path | OAuth授权页面路径 | /launch/launch | WXLaunchMiniProgram.Req.path,指定拉起的页面 |
path 所需 Query 参数定义 | 授权页路径上需携带的参数列表及规则 | target=oauthAuth&from=xxx | 按规则拼接完整path,来源值双方约定 |
extMsg 回调数据格式 | 授权完成后小程序返回给APP的数据结构定义 | {"auth_status":"success"} | 第三方客户端解析授权结果 |
miniprogramType 推荐值 | 各阶段(联调/测试/上线)应使用的小程序版本类型 | 联调用1,上线用0 | 控制拉起的小程序版本 |
版本说明
| 版本 | 说明 | 日期 | 编辑者 |
| 1.0 | 文档初始化 | 2026-04-01 | zeuszzhou,ellerywang,yannigao |
| 1.1 | 补充小程序拉起方式,更新部分mcp描述 | 2026-04-13 | zeuszzhou,jankinxie |
| 1.2 | 订单详情新增接单车型品类标识,更新部分mcp描述 | 2026-04-27 | zeuszzhou |
| 1.3 | MCP输出结构补充JSON-RPC 2.0协议包裹说明,腾讯接口路径更正 | 2026-05-21 | pioneerchen,ellerywang |
| 1.4 | 调整排版 | 2026-05-26 | ellerywang |
| 1.5 | 更新MCP通用错误码 | 2026-05-27 | andynwang |
| 1.6 | 更新MCP业务错误码 | 2026-06-01 | zeusszhou |
5. 附录. 工具列表
5.1 概述
| 能力 | 标识 | 描述 |
| 跑腿询价 | runerrand_estimate_price | 根据寄件和收件地址信息,获取各运力商的跑腿配送预估价格列表。返回的 estimatePriceRecordId 与 skuId 用于后续创建订单 |
| 跑腿预取消订单 | runerrand_precancel_order | 在订单未完成前,根据订单ID查询是否可以取消跑腿订单,并返回取消费 |
| 查询跑腿订单详情 | runerrand_query_order_detail | 用户根据订单ID询问订单进度、费用明细、骑手信息或需要联系客服时调用 |
| 查询进行中的跑腿订单 | runerrand_query_going_order | 查询用户当前是否有进行中的跑腿订单 |
| 取消跑腿订单 | runerrand_cancel_order | 根据订单 orderCode 取消订单 |
| 创建跑腿订单 | runerrand_book_order | 根据询价结果和用户勾选的SKU下单,创建跑腿订单并返回支付信息 |
5.2 跑腿询价
输入参数结构
| 参数名称 | 类型 | 是否必填 | 参数描述 |
| fromAddrDetail | string | 是 | 寄件地址名称,示例:腾讯武汉研发中心 |
| fromLat | number | 是 | 寄件地址纬度 |
| fromLng | number | 是 | 寄件地址经度 |
| fromUserName | string | 是 | 寄件人姓名 |
| fromUserPhone | string | 是 | 寄件人手机号 |
| toAddrDetail | string | 是 | 收件地址名称 |
| toLat | number | 是 | 收件地址纬度 |
| toLng | number | 是 | 收件地址经度 |
| toUserName | string | 是 | 收件人姓名 |
| toUserPhone | string | 是 | 收件人手机号 |
| goodsType | integer | 否 | 物品类型枚举,1-文件证照;2-服饰;3-食品饮料;4-蛋糕;5-鲜花;6-数码;7-水果生鲜;8-药品;9-汽配;10-日用品;11-家居家纺;0-其他。不传或者不在以上枚举范围内时按默认(其他类型)处理 |
| goodsWeight | number | 否 | 物品重量,单位kg,不传默认0;如用户表述实际重量则传入实际重量 |
返回参数结构
| 参数名称 | 类型 | 参数描述 |
| code | integer | 响应状态码,0表示成功 |
| message | string | 响应消息 |
| data | object | 响应数据对象,详见ResponseData结构定义 |
ResponseData结构定义
| 参数名称 | 类型 | 参数描述 |
| estimatePriceRecordId | string | 预估缓存Key,后续创建订单时必填 |
| spEstimatePrices | List | 运力商预估列表,详见SpEstimatePrice结构定义 |
SpEstimatePrice结构定义
| 参数名称 | 类型 | 参数描述 |
| skuId | string | SKU标识,格式为:运力ID_车型编码,后续创建订单时使用,示例:60796_1 |
| spName | string | 运力商名称,如顺丰同城、美团跑腿、京东秒送 |
| expressTypeName | string | 送件类型名称,如特惠跑腿、极速跑腿 |
| defaultChecked | integer | 是否默认勾选,1-默勾,0-不默勾 |
| totalFee | string | 实际应支付金额(元,小数点后两位),已扣除优惠金额,示例:2.59 |
| couponFee | string | 优惠金额(元,小数点后两位),示例:2.59 |
| deliveryTime | string | 预计送达时间,格式:xx年xx月xx日 xx时xx分xx秒,示例:2026年01月05日 15时25分36秒 |
5.3 跑腿预取消订单
输入参数结构
| 参数名称 | 类型 | 是否必填 | 参数描述 |
| orderCode | string | 是 | 订单ID |
返回参数结构
| 参数名称 | 类型 | 参数描述 |
| code | integer | 响应状态码,0表示成功 |
| message | string | 响应消息 |
| data | object | 响应数据对象,详见ResponseData结构定义 |
ResponseData结构定义
| 参数名称 | 类型 | 参数描述 |
| couldCancel | boolean | 是否可以取消订单,true-可取消,false-不可取消 |
| cancelFee | string | 取消费,单位元,如:2.00(有取消费时需告知用户) |
5.4 查询跑腿订单详情
输入参数结构
| 参数名称 | 类型 | 是否必填 | 参数描述 |
| orderCode | string | 是 | 订单ID |
返回参数结构
| 参数名称 | 类型 | 参数描述 |
| code | integer | 响应状态码,0表示成功 |
| message | string | 响应消息 |
| data | object | 响应数据对象,详见ResponseData结构定义 |
ResponseData结构定义
| 参数名称 | 类型 | 参数描述 |
| orderCode | string | 订单ID |
| orderStatusText | string | 订单状态文案,如:派单中、取件中、送件中、已完成等 |
| spName | string | 运力商名称,如:顺丰同城、达达、京东秒送等 |
| expressTypeName | string | 送件类型名称,如:特惠跑腿、极速跑腿 |
| riderName | string | 骑手姓名 |
| riderPhone | string | 骑手手机号 |
| deliveryTime | integer | 预计送达时间,Unix时间戳(秒) |
| totalFee | string | 总费用,单位元 |
| payFee | string | 实际费用(已扣除优惠后),单位元 |
| paidFee | string | 已支付费用,单位元 |
| couponFee | string | 优惠费用,单位元 |
| cancelFee | string | 取消费,单位元(有值时需告知用户) |
| refundFee | string | 退款费用,单位元 |
| waitRefundFee | string | 待退款费用,单位元 |
| customerInfo | List | 客服信息列表,详见CustomerInfo结构定义 |
| orderSuggestion | string | 大模型话术建议,可直接参考该字段组织回复话术 |
CustomerInfo结构定义
| 参数名称 | 类型 | 参数描述 |
| title | string | 客服标题,如:顺丰同城电话客服 |
| phones | List | 客服电话列表,示例:["4001881888"] |
| onlineTimeInfos | List | 客服在线时间列表,示例:["8:00-22:00"] |
5.5 查询进行中的跑腿订单
输入参数结构
本工具无需入参(参数对象为空)。
返回参数结构
| 参数名称 | 类型 | 参数描述 |
| code | integer | 响应状态码,0表示成功 |
| message | string | 响应消息 |
| data | object | 响应数据对象,详见ResponseData结构定义 |
ResponseData结构定义
| 参数名称 | 类型 | 参数描述 |
| hasOnGoingOrder | boolean | 是否有进行中订单,true-有,false-无 |
| orderCode | string | 进行中的订单ID,hasOnGoingOrder=true 时有值,可用于后续查询订单详情;无进行中订单时为空字符串 |
| orderStatus | integer | 订单状态码,无进行中订单时为 0 |
| orderStatusText | string | 订单状态描述,如:派单中、已接单、配送中等 |
| spName | string | 运力商名称 |
| expressTypeName | string | 送件类型名称,如:极速取送、特惠取送 |
5.6 取消跑腿订单
输入参数结构
| 参数名称 | 类型 | 是否必填 | 参数描述 |
| orderCode | string | 是 | 订单ID |
返回参数结构
| 参数名称 | 类型 | 参数描述 |
| code | integer | 响应状态码,0表示成功,非0表示失败 |
| message | string | 错误描述信息,成功时为空字符串 |
5.7 创建跑腿订单
输入参数结构
| 参数名称 | 类型 | 是否必填 | 参数描述 |
| estimatePriceRecordId | string | 是 | 询价缓存Key,由 runerrand_estimate_price 询价接口返回,创建订单时必填 |
| expressSkuInfos | List | 是 | 用户勾选的SKU列表,当前仅支持单选,传入询价接口返回的 skuId,示例:["600018_1"] |
| userPhone | string | 否 | 用户下单手机号 |
返回参数结构
| 参数名称 | 类型 | 参数描述 |
| code | integer | 响应状态码,0表示成功 |
| message | string | 响应消息 |
| data | object | 响应数据对象,详见ResponseData结构定义 |
ResponseData结构定义
| 参数名称 | 类型 | 参数描述 |
| orderCode | string | 订单ID,后续查询订单状态、取消订单时使用 |
| payInfo | PayInfo | 支付信息,详见PayInfo结构定义 |
PayInfo结构定义
| 参数名称 | 类型 | 参数描述 |
| tradeType | integer | 支付方式,1-微信小程序拉起收银台支付,2-扫码支付 |
| prepayId | string | 预支付订单ID,tradeType=1 时有效,示例:wx07506492195240d3450000013620263000 |
| paySign | string | 支付签名,tradeType=1 时有效 |
| nonceStr | string | 随机字符串,tradeType=1 时有效,示例:ZZYHVRTYLWUTIJBKBETWZURI |
| signType | string | 签名算法,tradeType=1 时有效,示例:RSA |
| timeStamp | string | 时间戳(秒),tradeType=1 时有效,示例:1777129041 |
| codeUrl | string | 微信支付二维码URL,tradeType=2 时有效 |
| scanUrl | string | 扫码支付页地址,tradeType=2 时有效 |