开始接入

5 分钟快速接入

从应用凭证开始，获取令牌并完成第一次受保护接口调用。

前置条件

开始前，请确认平台管理员已经完成：

创建并启用 OpenAPI 应用。
将所需接口登记为启用状态。
给应用授权所需接口。
安全交付 app_key 和仅展示一次的 app_secret。
非生产环境下，提供对应环境的 HTTPS 基础地址。

仅在服务端使用

app_secret、Access Token 和 Refresh Token 都属于敏感凭证。不要放入浏览器代码、移动端安装包、URL 查询参数、Git 仓库或普通日志。

1. 配置连接信息

export OPENAPI_BASE_URL="https://backend.biotech-mkt.com"
export OPENAPI_APP_KEY="ak_xxx"
export OPENAPI_APP_SECRET="sk_xxx"

生产环境直接使用上面的基础地址；凭证必须替换为平台管理员提供的真实值。

2. 获取令牌

curl --request POST "https://backend.biotech-mkt.com/openapi/auth/token" \
  --header "Content-Type: application/json" \
  --data "{\"app_key\":\"$OPENAPI_APP_KEY\",\"app_secret\":\"$OPENAPI_APP_SECRET\"}"

成功响应：

立即把两个令牌写入服务端的安全存储。不要依赖示例中的绝对时间，客户端应使用响应实际返回的过期时间。

3. 验证调用身份

将刚获取的 Access Token 写入环境变量：

export OPENAPI_ACCESS_TOKEN="oat_xxx"

调用调试接口：

curl "https://backend.biotech-mkt.com/openapi/profile" \
  --header "Authorization: Bearer $OPENAPI_ACCESS_TOKEN"

当 HTTP 状态和响应 code 都为 200，且 data.app_key 与当前应用一致时，说明令牌、接口登记和应用授权均已生效。

4. 调用业务接口

curl --get "https://backend.biotech-mkt.com/openapi/v1/doudian/order/union-settlement-orders" \
  --header "Authorization: Bearer $OPENAPI_ACCESS_TOKEN" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20" \
  --data-urlencode "flow_point=SETTLE"

分页数据位于 data.list，总记录数位于 data.total。完整查询参数和字段说明见抖音精选联盟订单。

5. 接入后的最低要求

Access Token 到期前使用 Refresh Token 轮换令牌。
刷新成功后原令牌立即失效，必须原子替换保存的新令牌。
记录响应头 X-Request-Id，但不要记录完整凭证。
收到 429 时遵循 Retry-After，不要立即无限重试。
收到 401 时检查令牌是否过期、被吊销，或应用是否被禁用。

最后更新于 2026年8月26日