最佳实践

生产环境检查清单

幂等性回调错误处理安全

上线生产前请完成所有项。每项都链接到对应的章节。

幂等性

项目
所有创建请求均使用唯一且确定性的 `clientReference`。参见幂等性。
按 `id + status` 对 callback 去重，而非仅按 `id`。
去重存储持久化（Redis/DB），不要放在本地内存中。
去重 TTL ≥ 30 天。

回调

项目
所有 `POST /pix`、`POST /withdraw`、`POST /internal-transfer` 都已配置 `callbackUrl`。
Handler 在 5 秒内返回 `2xx`。重负载处理交给队列/worker。
已通过 curl + ngrok 用模拟 payload 测试。
Endpoint 限制为 Saq 官方 IP（向支持团队索取）。
已配置 `GET /user/callbacks` 用于审计排查。

多租户（如适用）

项目
所有创建请求中均传递 `virtualAccount`。
列表查询按 `virtualAccount` 过滤。
Callback 路由使用 `tx.virtualAccount`，并对未知租户设有兜底处理。
新租户接入无需重新部署（通过 DB 映射或动态配置完成）。

资金

项目
金额以分为单位的整数或 `NUMERIC(15,2)` 存储，绝不使用 `FLOAT`。
分 ↔ 雷亚尔的换算封装在 helper 中，并已测试。
Callback 中校验：收到的金额与订单预期金额一致。
手续费（`serviceFeeCharged`）已纳入对账。
遵守最低限额（收款 ≥ R$ 1，提现 ≥ R$ 0.01，QR ≥ R$ 0.10）。

安全

项目
Token 存放于 Secret Manager，而非版本控制中的 `.env`。
Token 绝不暴露给前端。
日志对 `Authorization` 头及敏感字段（`payerDocument`、`pixKey`）进行脱敏。
沙箱与生产使用各自独立的 token。
轮换计划已文档化（何时、何人、如何执行）。
大额按 Pix 键提现前先查询 DICT。

错误处理

项目
仅在 `5xx` 与 `429` 时重试，使用指数退避加抖动。
`4xx`（`429` 除外）不重试。
超时时先通过 `clientReference` 查询，再决定是否重建。
Saq 的 `requestId` 在所有错误中均被记录。
错误信息已翻译给终端用户（不直接暴露原始 `message`）。

分页与对账

项目
列表遍历使用 `hasNextPage`，而非 `data.length`。
`limit` ≤ 100。
每日对账任务交叉比对 `GET /user/transactions` 与本地订单表。
大数据量场景定时调用 `POST /user/report`。
状态差异触发告警。

可观测性

项目
结构化日志包含本地 `id` + Saq `id` + `endToEndId` + `clientReference`。
指标：创建成功率、p95 延迟、按类型分类的错误数。
告警：短窗口内 5xx 错误 > X%、callback 未处理超过 N 分钟。
分布式追踪（OpenTelemetry）传播 Saq 的 `requestId`。

环境

项目
开发与测试均使用沙箱。
生产仅用于真实金额与真实客户。
环境变量分离（`SAQ_TOKEN`、`SAQ_BASE_URL`）。
生产 webhook 使用稳定 URL（非临时隧道）。

运营

项目
故障 runbook：callback 停止到达、5xx 错误持续、余额不一致。
与 Saq 支持的直接联系方式（渠道、SLA）。
Callback 重发流程已文档化（`POST /user/callbacks/resend`）。
涉及提现或转账的功能均有回滚预案。

Tratamento de erros

4xx é erro seu (não retentar), 5xx é da Saq (retry com backoff), 429 é rate limit (aguardar) e timeout exige cuidado especial porque a operação pode ter sido aplicada. Esta página tem helper de retry e estratégia de logging.

2FA (Autenticação em dois fatores)

A 2FA é obrigatória para criar tokens de API e processar saques pelo dashboard. Use qualquer app autenticador TOTP (Google Authenticator, Microsoft Authenticator, 1Password, Authy ou similar) para gerar os códigos de 6 dígitos.

On this page

幂等性回调多租户（如适用）资金安全错误处理分页与对账可观测性环境运营