SPI 接入

我的收藏

当开发者本次接入的解决方案能力中，涉及需要接收平台主动推送的事件通知、业务状态变更或异步数据回调时（如用户授权事件、支付结果通知、内容审核回调等），必须在此完成对应 SPI 接口地址的注册与连通性验证。

场景和接口

在对接的解决方案、能力文档中查看需要接入的 SPI 接口。

2.消息推送回调接口说明

仅支持https协议，接口实现大致流程：

HTTP method

POST

请求头字段

字段	说明
Content-Type	固定值application/json
X-Bytedance-Logid	请求LogId,用于排查问题
x-life-clientkey	服务商应用的client_key
x-life-sign	抖音侧签名，开发者可根据签名判断该消息是否来自抖音开放平台，参考文档签名规则

请求体字段

请求参数需参考具回调接口的文档说明

开发者响应请求

验签方式

对收到的请求，按照文档SPI验签进行签名验证，以判断该消息是否来自抖音开放平台。

加密字段解密

对请求参数中的加密字段，若需进行解密，参考文档：加密字段解密

响应体

响应体包含data，data包括错误码error_code、错误描述description和其他业务数据字段，error_code为0时表示成功，非0表示失败

字段	类型	说明
data	Struct	响应数据体
description	String	失败原因
error_code	Int32	错误码，0为成功，非0为失败

成功响应示例：

{
    "data": {
        "error_code": 0,
        "description": "success",
        "certificate": {
            "amount": {
                "merchant_ticket_amount": 32,
                "original_amount": 1,
                "pay_amount": 2
            },
            "encrypted_code": "111"
        }
    }
}

错误响应示例：

{
    "data": {
        "description": "参数不合法",
        "error_code": 2100005
    }
}

错误码

需参考具体回调接口的文档说明

限流

限流值查看

路径：抖音开放平台/服务商平台->控制台->生活服务商家应用->开发配置-接口限流

注：只能看到应用开通权限的接口情况（根据接口类型进行区分）

若不满足业务场景，需要调整限流值，可联系抖音技术

接入流程

前置条件

•

参考文档已完成 IP 白名单配置。

•

权限要求（具体接口要求需要参考回调接口文档中的说明），一般有：

◦

能力申请，路径：抖音开放平台/服务商平台>控制台>应用详情>解决方案->xxx解决方案

◦

商家授权，路径：抖音来客>店铺管理>服务应用授权

配置回调步骤

第一步：在解决方案接入详情页左侧导航栏选中基础配置-SPI配置。

第二步：点击页面右上角的添加按钮，打开添加SPI弹窗。

第三步：在弹窗中选择回调场景，输入回调场景对应的回调地址，输入完成后单击确定按钮。

第四步：填写完成所有的 SPI 信息后，点击下一步按钮保存即可。

更多说明：配置后，与回调场景关联的所有解决方案及能力都可使用该地址。

地址配置要求

输入的回调地址必须以 https:// 开头，暂不支持 HTTP 协议，必须保证连通性；

常见问题

问题	建议方案
正式环境的SPI回调地址配置后收不到请求	1.请先检查是没有收到请求还是收到请求了但开发者服务内部错误了 2.接口契约：统一使用 POST 且 Content-Type: application/json 3.前置条件与权限检查 ◦是否完成“IP 白名单配置” ◦有能力权限要求时，是否已完成能力申请 ◦商家授权是否完成 4.请确认SPI地址配置是否正确 ◦确认配置的应用是否有误，请核对应用 ◦确认地址中是否有空格（粘贴后自查是否含空格或不可见字符），以及接口是否可以正常调用 ◦SPI回调地址目前只支持https协议，不支持HTTP协议，历史已配置HTTP地址可正常使用，新增和修改必须https 5.请确认开发者服务器或防火墙是否有拦截请求 6.若以上都没问题，请进线抖音技术反馈
验收过程中配置的SPI接口地址正式上线后是否不能再修改	应用正式上线后可以更改但需要谨慎修改，修改后将对线上生效，若新接口地址不通或稳定性问题将影响线上业务