Z Zise Developers

沙盒

沙盒是一个独立的商户主体,不是生产库上的一个开关。


https://api-sandbox.zise.com

你的沙盒 Key 与 Live Key 是两把,各自解析到各自的主体。跨环境凭据一律拒

返回专门的码 environment_mismatch(不是笼统的「凭据无效」)。

隔离到什么程度

隔离
会员、订单、账本✅ 独立主体,Live 查不到沙盒建的会员
Webhook 投递✅ 投递行带环境,沙盒事件不会推到 Live 端点
业务线开关与三段成本跟随母体
上游(UQPAY / PhotonPay / Paydify / Cobo)见下

⚠ 上游故障注入目前是空操作

/v1/sandbox/* 下有设置上游行为(timeout / unknown / unknown_status / reject

的端点,它们会返回 200 并回显你设的值。

但四家上游的客户端目前一个都不读这个设置。 也就是说:注入之后,

后续每一单仍然打真实上游、用真实凭据

这一条写在这里是因为它的失败形态最坏:你会以为自己的「结果不明」分支已经测过,

而那正是「既退款又付款」的路径 —— 它第一次真实发生会在生产上。

在这条修好之前,请不要依赖沙盒去验证上游异常路径。 需要联调这几条路径时

联系你的客户经理,我方在受控环境里配合你走一遍。

其余的沙盒能力(建会员、上报入金、查余额、下单、收 webhook)是真的可用。

一键重置

POST /v1/sandbox/reset 清掉沙盒的调用日志与投递日志。

⚠ 它不种任何固件 —— 重置之后你需要自己重新建会员、上报入金。

不要指望它给你一套现成的测试数据。

建议的联调顺序

1. 换令牌,确认签名串拼对了(错误码是 invalid_signature 而不是 401)

2. POST /v1/members 建一个会员

3. POST /v1/deposits 上报一笔入金 —— 这是唯一能凭空造出余额的口

4. GET /v1/balances 确认八个桶里 available 涨了

5. 跑一条最简单的业务线:POST /v1/exchange/quotesPOST /v1/exchange/orders

6. 配一个 webhook 端点,确认收到 exchange.order.executed验签通过

第 6 步不要跳。签名验不过是接入期最常见的一类工单,而它在你自己的环境里

比在我方这边好排查得多。