• OpenAPI 简介
  • 小程序 OpenAPI SDK 总览
  • 签名算法
  • 基础能力
  • 触达与营销
  • 支付
  • 运营
  • 生活服务
  • 核销工具解决方案
  • 通用能力
  • poi基础能力
  • CPS佣金设置与查询
  • 生活服务交易系统(全融合版)
  • 通用参数
  • 错误码和返回码
  • 查询接口
  • 预下单
  • 营销算价
  • 支付
  • 核销
  • 分账
  • 退货退款
  • 生活服务交易系统(账号融合版)
  • 历史版本(不推荐使用)
  • 垂直行业
  • 其它
  • 开发者请求公共参数

    所有 OpenAPI 接口均需要设置这几个字段,API 文档中将不再重复解释。

    字段名

    类型

    位置

    是否必填

    字段说明

    Content-Type

    string

    Header

    固定值:application/json

    access-token

    string

    Header

    调用/oauth/client_token/生成的token,此token不需要用户授权。示例: clt.xxx

    平台请求公共参数

    注意:这里是平台调用开发者扩展点时发送给开发者的请求

    字段名

    类型

    位置

    是否必填

    字段说明

    取值范例

    Content-Type

    string

    Header

    固定值:application/json

    application/json

    Byte-Identifyname

    string

    Header

    开发者回调路径,不包含域名

    /order/create_order_callback_url

    Byte-Logid

    string

    Header

    日志id,请参考-签名算法

    20230504163800ABA7347CE4F5

    Byte-Nonce-Str

    string

    Header

    随机字符串,请参考-签名算法

    Bhw73xUDN91kova0f3KkVegl0WPpz9BZ

    Byte-Signature

    string

    Header

    请求包签名,请参考-签名算法

    mx0xMwumjHScvSjFHjKTvSlBJu1G2aw==

    Byte-Timestamp

    string

    Header

    请求时间戳,精度:秒,请参考-签名算法

    1683189481

    签名算法

    • 外部开发者请求代运营交易系统接口

    如上面的请求公共参数说明,代运营交易系统的 OpenAPI 接口均使用 access-token 参数鉴权,不需要添加额外的签名参数。

    • 代运营交易系统请求外部开发者的接口

    当代运营交易系统需要回调开发者接口时,比如预下单回调、支付完成通知等场景,代运营交易系统会在 header 中添加签名参数,开发者需要对签名参数进行校验。

    具体的签名算法请参考-签名算法-签名验证

    响应公共参数

    extra 信息

    名称

    类型

    是否必填

    描述

    示例值

    error_code

    int

    错误码,0为成功

    0

    description

    string

    错误码描述

    success

    sub_error_code

    int

    子错误码

    0

    sub_description

    string

    子错误码描述

    success

    logid

    string

    请求id

    2022092115392201020812109511046

    now

    int

    时间戳

    1663815603

    关于 xxx_entry_schema 的前置说明

    在接入的 open-api 中,有些 open-api 会有一个叫 xxx_entry_schema 的参数,这个参数是小程序某个页面的跳转地址,比如在下单场景中平台调用开发者预下单接口后会要求开发者返回一个叫 order_entry_schema 的字段,因为小程序的订单会展示的抖音 app 的订单中心,用户从抖音订单中心进入小程序订单详情页的时候需要一个跳转地址,这个地址就是开发者返回的 order_entry_schema 字段。请注意凡是使用 path+params 字段的方式传递小程序 xx 详情页跳转地址的位置,path 和 params 都必须严格符合下列规范,后续相关文档字段说明中将不再在各处对此规范约束进行说明

    名称

    类型

    是否必传

    描述

    正确示例

    错误示例

    path

    string

    小程序xxx详情页跳转路径,没有前导的“/”路径后不可携带query参数,路径中不可携带『?:  &  *』等特殊字符,路径只可以是『英文字符、数字、_、/ 』等组成,长度<=512byte

    page/path/index

    page/path/index?id=1234

    page/path:hello/index

    params

    string

    xx情页路径参数,自定义的json结构,序列化成字符串存入该字段,平台不限制,但是写入的内容需要能够保证生成访问xx详情的schema能正确跳转到小程序内部的xx详情页,长度须<=512byte,params内key不可重复。

    {"id":1234,"name":hello}

    {"id":1234,"id":2334,"name":hello}

    字段和格式约定

    重要 ID 字段说明

    • 抖音开平交易系统内部使用的单号输出给开发者时,一般以 xxx_id 进行命名,如 order_id、item_order_id、refund_id 等。
    • 开发者系统的单号输出给开发者一般以 xxx_no 进行命名,如 out_order_no、out_refund_no 等。

    ID 字段

    说明

    order_id

    用户下单时,交易模板为用户的交易订单生成的交易订单号,即抖音开放平台系统内部的订单号。

    out_order_no

    开发者系统生成的交易单号。

    用户下单时,抖音开放平台交易模板会将下单的请求发送到开发者的系统,此时请求参数里会携带交易模板内部系统生成的交易单号 order_id。

    当开发者系统确认并返回给抖音开放平台交易系统成功时,此返回中应携带开发者系统为本次交易生成的订单号,也就是 out_order_no。同时,在开发者处理请求的时候,应自行将交易模板系统的内部订单号 order_id 和自己系统生成的订单号 out_order_no 进行唯一关联(一对一关联)。

    item_order_id

    用户下单的单个订单里券的数量可能是 N 张,对应这 N 张券,交易模板会为每一张券生成一个内部的虚拟券 ID,即 item_order_id,这个券 ID 在核销和退款流程里会被用到。

    重要字段的格式和约束说明

    • 对于系统涉及到的订单号类 ID,如果没有特殊说明则默认合法格式如下:
      • <= 64 byte
      • 由 ASCII 英文字符、数字组成,区分大小写
    • 用户、商户、商家等身份类id标志,如果没有特殊说明则默认合法格式如下:
      • <= 32 byte
      • 由 ASCII 英文字符、数字组成,区分大小写
    • 金额的单位,统一为分。
    • URL 类字段长度必须 <= 512 byte,支持 UTF-8 字符集,不支持 Unicode 字符。
    • 时间类型的相关字段有 string 和 int 两种类型:
      • string 类型时间如无特殊说明,则格式为 yyyy-MM-dd HH:mm:ss。
      • int 型时间则为系统时间戳,单位为毫秒,即 1970 年 1 月 1 日到当前时间所走过的毫秒数。
    • 开发者传递的透传字段,长度不得超过 2048 byte,格式不限,不支持二进制数据。
    • 所有接口默认支持字符集为 UTF-8,不支持 Unicode 字符集,所有字段都不支持二进制数据传递(非二进制安全)。
    该文档是否有帮助?