集成指南
按提供商的限制（expirationTime）
概述
EYT API 为 expirationTime（以秒为单位）公开了平台级的下限和上限：
- 最小值：
30（30 秒） - 最大值：
604800（7 天） - 默认值：
86400（24 小时）
超出这些限制时，API 会以验证错误拒绝请求。此外，账户背后的每个 PIX 提供商可以施加自己的、更严格的限制。当 expirationTime 低于账户提供商的最小值时，API 返回 400 Bad Request，errorCode 设置为 PROVIDER_EXPIRATION_BELOW_MINIMUM，并在详情中包含可接受的最小值。 当它高于账户提供商的最大值时，errorCode 为 PROVIDER_EXPIRATION_ABOVE_MAXIMUM，details.providerMaxSeconds 给出可接受的上限。
按提供商的限制表
| 提供商 | 最小值 | 最大值 | 粒度 | 备注 |
|---|---|---|---|---|
| Woovi | 300（5 分钟） | 604800（7 天） | 秒 | 由 Woovi API 强制执行 |
| BRZip | 30（30 秒） | 604800（7 天） | 秒 | — |
| Magen | 30（30 秒） | 604800（7 天） | 秒 | — |
| Hyperwallet | 30（30 秒） | 604800（7 天） | 秒 | — |
| GolPix | 86400（1 天） | 604800（7 天） | 天 | GolPix API 只接受 expiresInDays（1–30 的整数）。小于 1 天的值会被拒绝，以避免静默意外。非 86400 整数倍的值会向上舍入到下一个整数天。 |
| OnlyUp | 30（30 秒） | 604800（7 天） | 秒 | — |
| FyHub | 30（30 秒） | 604800（7 天） | 秒 | — |
| Treeal | 30（30 秒） | 604800（7 天） | 秒 | — |
| AvivPay | 60（1 分钟） | 86400（24 小时） | 秒 | AvivPay API 接受 60 秒到 24 小时之间的值。超过 86400 时，API 返回 PROVIDER_EXPIRATION_ABOVE_MAXIMUM。 |
| NixFin | 30（30 秒） | 604800（7 天） | 秒 | — |
| a55 | 30（30 秒） | 604800（7 天） | 秒 | a55 API 最长接受 30 天，但以平台上限（7 天）为准。该值以秒为单位发送（expiresInSeconds），因此小于 1 天的窗口会被精确遵守。 |
| AvivPay IP | 30（30 秒） | 604800（7 天） | 秒 | 与 a55 使用相同的 API：最长接受 30 天，但以平台上限（7 天）为准。该值以秒为单位发送（expiresInSeconds），因此小于 1 天的窗口会被精确遵守。 |
错误结构
当提交的 expirationTime 小于账户提供商的最小值时：
HTTP/1.1 400 Bad Request
Content-Type: application/json{
"statusCode": 400,
"code": "PIX_PROVIDER_EXPIRATION_BELOW_MINIMUM",
"errorCode": "PROVIDER_EXPIRATION_BELOW_MINIMUM",
"message": "Provider woovi requires expirationTime >= 300s (got 30s)",
"userMessage": "O provedor woovi exige tempo mínimo de 300 segundos para expiração.",
"details": {
"provider": "woovi",
"providerMinSeconds": 300,
"granularity": "seconds",
"userExpirationTime": 30
},
"errorId": "<correlation-id>",
"timestamp": "2026-05-05T12:34:56.789Z",
"path": "/api/pix/cash-in",
"method": "POST"
}使用 details.providerMinSeconds 重试请求，使用接受的最小值。
如何知道我的账户使用哪个提供商？
提供商配置是按账户设置的，在账户创建时确定。如果不确定哪个提供商处于活动状态，请联系您的集成经理或查看管理面板。对于大多数集成而言这是透明的，除非您需要在 Woovi 账户上使用短于 5 分钟的过期窗口（在 GolPix 账户上使用短于 1 天的过期窗口，或在 AvivPay 账户上使用长于 24 小时的过期窗口）。