跳到正文
Indiana
控制台
开发文档
章节目录 / 请求约定

请求约定

API 地址、请求头、凭据、幂等重试与错误格式。

API v1更新于

地址与路径

生产 API 是 https://api.tinker.cash，开发测试 API 是 https://api.dev.tinker.cash。所有接口位于 /api/v1/ 下；普通操作每个接口一个路径，Funnel 命令共用 POST /api/v1/funnels。

request.httpShell
POST https://api.tinker.cash/api/v1/customers/getAuthorization: Bearer <SERVER_KEY>X-Indiana-Protocol: 0.6Content-Type: application/json { "lookup": { "type": "externalUserId", "value": "user-42" } }

请求头

请求头
请求头要求
Authorization恰好一个 Bearer <凭据>。
X-Indiana-Protocol必填：0.6。缺失或不支持返回 400 UNSUPPORTED_PROTOCOL_VERSION。
Content-Type非 GET 请求使用 application/json。
X-Indiana-Project / X-Indiana-Environment可选的作用域断言，两者同时提供：App UUID 与 sandbox／live；必须与凭据一致，不能切换租户。
X-Indiana-SDK-Version可选，SDK 自动发送。
OriginServer Key 请求不能带；浏览器请求的 Origin 必须已在 Console 登记。

请求头

  • Authorization

    要求
    恰好一个 Bearer <凭据>。

  • X-Indiana-Protocol

    要求
    必填：0.6。缺失或不支持返回 400 UNSUPPORTED_PROTOCOL_VERSION。

  • Content-Type

    要求
    非 GET 请求使用 application/json。

  • X-Indiana-Project / X-Indiana-Environment

    要求
    可选的作用域断言，两者同时提供：App UUID 与 sandbox／live；必须与凭据一致，不能切换租户。

  • X-Indiana-SDK-Version

    要求
    可选，SDK 自动发送。

  • Origin

    要求
    Server Key 请求不能带；浏览器请求的 Origin 必须已在 Console 登记。
  • GET 操作不接受请求体或查询参数；其他操作同样拒绝查询参数。
  • 成功响应包含 requestId 与 scope，并带 X-Request-Id 和 Cache-Control: no-store。通常是 HTTP 200；submitUsageBatch 和处理中的 Funnel 决策返回 202。

凭据

凭据类型
凭据前缀持有方用途
Server Keygg_sk_你的后端按 Key 绑定的 App、环境和权限调用服务端操作。
Customer Tokengg_ct_浏览器 / App以一个 Customer 的身份调用允许 Customer 使用的操作。
Run Tokengg_fr_浏览器 / App / 后端只用于自己的 Funnel Run，并需附带原身份证明。
环境 UUID—公开读取已发布的公开配置与网页实验；不鉴权。

凭据类型

  • Server Key

    前缀
    gg_sk_
    持有方
    你的后端
    用途
    按 Key 绑定的 App、环境和权限调用服务端操作。

  • Customer Token

    前缀
    gg_ct_
    持有方
    浏览器 / App
    用途
    以一个 Customer 的身份调用允许 Customer 使用的操作。

  • Run Token

    前缀
    gg_fr_
    持有方
    浏览器 / App / 后端
    用途
    只用于自己的 Funnel Run，并需附带原身份证明。

  • 环境 UUID

    前缀
    —
    持有方
    公开
    用途
    读取已发布的公开配置与网页实验；不鉴权。

每次调用都检查凭据、权限、App／环境／Customer 作用域与来源。Customer Token 不能选择其他 Customer；Server Key 代表后端接入权限，不代表最终用户身份。

相关：权限列表

幂等与重试

  • 写操作带有业务 ID：requestId、eventId 或 idempotencyKey。在第一次发送前生成并持久保存，结果未知时用同一个 ID 和完全相同的输入重放；同一 ID 换了输入会返回 CONFLICT（IDEMPOTENCY_CONFLICT）。
  • 响应里的 requestId 与 X-Request-Id 只标识这一次 HTTP 尝试，用于排查，不要拿来替换业务 ID。
  • 异步业务（购买、变更、退款、开票、用量批次、Funnel 决策）返回操作 ID；超时后读取原操作，不要新建第二个。

错误格式

error.jsonJSON
{  "requestId": "<HTTP_ATTEMPT_ID>",  "error": {    "code": "FORBIDDEN",    "message": "This credential cannot perform this operation.",    "retryable": false,    "recovery": "check_permissions"  }}

按 error.code、retryable 与 recovery 处理，不要解析 message。error.reason 可选；需要等待时响应带 Retry-After（秒）。

相关：错误码与恢复