Errores específicos de Pay-In
Además de los Códigos HTTP y Errores generales de la plataforma, el módulo de Pay-In / Cobros QR cuenta con un conjunto de reglas de negocio específicas.
Cuando una petición no cumple con estas reglas, la API responderá con un código de error programático descriptivo dentro del JSON para facilitar su manejo.
Catálogo de Errores de Negocio (Pay-In)
A continuación se detallan los códigos más comunes devueltos en el campo code de la respuesta de error cuando se opera con códigos QR:
Código de Error (code) | HTTP Status | Descripción / Causa | Acción recomendada |
|---|---|---|---|
invalid_business_code | 422 Unprocessable Entity | El código de negocio (business_code) enviado no coincide con el registrado para tu cuenta o se encuentra inactivo. | Verificar que el valor del business_code provisto por Vendis esté configurado correctamente en las variables de entorno de tu servidor. |
amount_out_of_range | 422 Unprocessable Entity | El monto (amount) está fuera de los rangos permitidos. Por ejemplo, es menor al mínimo de 1.00 o supera los límites permitidos de transacciones por QR. | Validar que el valor del monto en tu frontend sea mayor a 1.00 antes de enviar la petición de cobro. |
qr_expiration_invalid | 422 Unprocessable Entity | La fecha y hora de expiración (qr_expiration) enviada ya ha pasado (está en el pasado) o supera el límite máximo permitido (ej. más de 30 días en el futuro). | Asegurarse de enviar fechas válidas en formato UTC o con la zona horaria correcta en formato Y-m-d H:i:s. |
qr_already_paid | 409 Conflict / 422 | Estás intentando realizar una operación o consulta sobre un código QR que ya se encuentra pagado y que no admite más transacciones. | Evitar reenviar peticiones sobre identificadores ya marcados como PAID en tu sistema. Genera un nuevo QR para un nuevo intento de cobro. |
bank_provider_offline | 503 Service Unavailable | El banco emisor o la red bancaria delegada está experimentando intermitencias temporales en su servicio de generación de QRs. | Mostrar un aviso amigable de "Servicio Bancario Temporalmente Fuera de Servicio" y sugerir al cliente que intente de nuevo en un par de minutos. |
Ejemplos de Respuestas de Error
Ejemplo 1: Monto Inválido (amount_out_of_range)
Ocurre si intentas generar un QR por un monto de 0.50 centavos, el cual está por debajo del mínimo de la red:
{
"type": "validation_error",
"code": "amount_out_of_range",
"message": "El monto del QR debe ser igual o mayor a 1.00 BOB."
}
Ejemplo 2: Expiración de Fecha Incorrecta (qr_expiration_invalid)
Ocurre si envías una fecha de expiración que ya transcurrió en el servidor de Vendis:
{
"type": "validation_error",
"code": "qr_expiration_invalid",
"message": "La fecha de expiración no puede ser anterior a la fecha y hora actual."
}
Ejemplo 3: Código de Negocio Inválido (invalid_business_code)
{
"type": "validation_error",
"code": "invalid_business_code",
"message": "El código de negocio provisto no es válido o no está autorizado para este dispositivo."
}