Límites por proveedor (expirationTime)
Visión general
La API Avista expone un piso y un techo a nivel de plataforma para el expirationTime (en segundos) de las cobranzas PIX:
- Mínimo:
30(30 segundos) - Máximo:
604800(7 días) - Predeterminado:
86400(24 horas)
Más allá de estos límites, la API rechaza la solicitud con un error de validación. Adicionalmente, cada proveedor PIX detrás de su cuenta puede imponer sus propios límites, más estrictos. Cuando expirationTime es menor que el mínimo del proveedor de la cuenta, la API responde 400 Bad Request con errorCode igual a PROVIDER_EXPIRATION_BELOW_MINIMUM y el mínimo aceptado en el detalle.
Tabla de límites por proveedor
| Proveedor | Mínimo | Máximo | Granularidad | Observación |
|---|---|---|---|---|
| Woovi | 300 (5 min) | 604800 (7 días) | segundos | Límite impuesto por la API de Woovi |
| BRZip | 30 (30 s) | 604800 (7 días) | segundos | — |
| Magen | 30 (30 s) | 604800 (7 días) | segundos | — |
| Hyperwallet | 30 (30 s) | 604800 (7 días) | segundos | — |
| GolPix | 86400 (1 día) | 604800 (7 días) | días | La API de GolPix solo acepta expiresInDays (entero 1–30). Los valores menores a un día son rechazados para evitar sorpresas silenciosas. Los valores que no son múltiplos de 86400 se redondean hacia arriba al siguiente día completo. |
Forma del error
Cuando el expirationTime enviado es menor que el mínimo del proveedor de la cuenta:
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"
}Use details.providerMinSeconds para reintentar la solicitud con el valor mínimo aceptado.
¿Cómo saber qué proveedor utiliza mi cuenta?
La configuración de proveedor es por cuenta y se define al crear la cuenta. Contacte a su gerente de integración o consulte el panel administrativo si no está seguro de qué proveedor está activo. Para la mayoría de las integraciones esto es transparente, excepto cuando necesita ventanas de expiración menores a 5 minutos en una cuenta Woovi (o menores a 1 día en una cuenta GolPix).