Zise Developers

快速开始

15 分钟跑通第一笔调用。

1 · 拿到凭据

在商户后台「开发者 → API Keys」创建一把 sandbox Key。创建时会一次性

返回三个值：

| 值 | 用途 | 我方是否保存 |

|---|---|---|

| client_id | 换令牌时标识你是谁 | 是（常驻列表可见） |

| api_key | 换令牌的密钥 | 只存哈希，丢了只能新建一把 |

| signing_key | 请求签名的对称密钥 | 是（HMAC 是对称的，单向哈希验不了签名） |

live 环境的 Key 必须配 IP 白名单（强制非空）。

2 · 换取访问令牌


POST https://api-sandbox.zise.com/v1/connect/token
x-client-id: zc_test_7f3a9b2e4c1d
x-api-key: sk_test_••••••••••••

→ 200
{
  "auth_token": "eyJhbGciOiJIUzI1NiIs…",
  "expired_at": 1754872200,
  "token_type": "Bearer",
  "scopes": ["members:write","members:read", …]
}

有效期 30 分钟。多令牌可并存 —— 你的多个进程各换各的，不会互相踢掉

（这一点与某些同类平台相反，那个行为在多进程侧是个坑）。

签发限流 20 次/分钟：令牌该被缓存复用，高频换取本身是接入错误的信号。

3 · 给写请求签名

签名串五段，换行连接，顺序不可换：


POST
/v1/members
1754870400
2b7e1516-…-0f3c
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855


x-signature = base64(HMAC-SHA256(signing_key, 签名串))

三件容易踩的事：

键序，签名会恒不匹配 —— 而报错长得像「密钥配错了」。

而一笔重放的付款就是第二笔真实付款。

4 · 建一个会员


POST /v1/members
x-auth-token: Bearer eyJ…
x-idempotency-key: 6f1c2d80-…-9a4e     ← UUID v4，写请求必带
x-timestamp / x-nonce / x-signature

{ "external_member_id": "u_88213", "email": "a@example.com" }

→ 201
{ "id": "mem_…", "external_member_id": "u_88213", "kyc_level": 0, … }

external_member_id 是你自己体系里的用户 ID —— 之后所有会员作用域的

调用都用它切入（x-on-behalf-of: u_88213）。

5 · 上报一笔入金

你在自己的托管侧收到链上转账之后，调这个接口让会员余额增加：


POST /v1/deposits
x-on-behalf-of: u_88213

{ "asset": "USDT", "amount": "100.000000", "reference": "0xabc…" }

reference 是你的业务流水号（通常是链上交易哈希）。它进幂等键 ——

重复上报同一笔时我方返回 replayed: true 而不会记第二笔余额。

6 · 接 Webhook

在商户后台配一个 https 端点。我方推送时带：


z-signature: t=<unix秒>,v1=<base64>
v1 = HMAC-SHA256(webhook_secret, "<t>." + rawBody)

四件必须做的事：

1. 校验签名，并检查 t 在 ±300 秒内（防重放）；

2. 按 event_id 幂等 —— 我方保证至少一次，不保证恰好一次；

3. 按 status_version 向前合并 —— 收到倒序事件应丢弃。少了它，

一次慢响应会把「已到账」打回「处理中」；

4. 任意 2xx 即算成功，响应体我方不解析。超时 10 秒。

失败退避 5 次（1min / 5min / 30min / 2h / 6h），之后转 dead 并在商户后台

告警。不会静默丢弃。

上线前

去看「Go-live 检查清单」。其中最容易漏的一条：沙盒配额不高于生产

（我方两边取生产值），所以沙盒压测通过 = 生产也不会被限流。