Idempotencia

La idempotencia asegura que, sin importar cuántas veces invoques la misma operación con los mismos parámetros, se te garantice el mismo resultado final. Esto es especialmente útil para operaciones sensibles que podrían implicar una posible pérdida de dinero o una mala experiencia para los clientes en escenarios como cargos duplicados no intencionados o pagos a una cuenta bancaria.

Con el producto de Débito Directo de Belvo, puedes proporcionar una Idempotency-Key en los encabezados de una solicitud HTTP para mitigar el riesgo de llamadas duplicadas a un recurso. Recomendamos usar un UUID generado como clave.

Métodos compatibles

Actualmente, las claves de idempotencia son compatibles con la siguiente operación de API:

Crear una Solicitud de Pago

Ciclo de vida de una clave de idempotencia

Después de una llamada API exitosa (con un código de estado HTTP 200 o 201), nuestro sistema almacena en caché la respuesta junto con su clave de idempotencia correspondiente. Cualquier solicitud repetida utilizando la misma clave dentro de las 24 horas devolverá el resultado en caché en lugar de ejecutar la operación nuevamente.

Política de expiración

Las claves de idempotencia tienen un Tiempo de Vida (TTL) de 24 horas después de la marca de tiempo de la solicitud inicial. Una vez que este período ha pasado, una clave reutilizada se trata como una nueva solicitud, lo que desencadena una operación nueva y almacena la nueva respuesta.

Mensajes de error de idempotencia

Recibirás un error relacionado con tu clave de idempotencia en los siguientes casos:

Caso	Descripción	Código HTTP	Mensaje de error
Uso Concurrente de Clave	Envías la misma clave de idempotencia para solicitudes concurrentes	`400`	`Concurrent use of idempotency key`
Cambio de Parámetros de Solicitud	Haces una solicitud con una clave no expirada con un payload diferente al de la solicitud inicial.	`400`	`Different input for unexpired idempotency key`

Lista blanca de IP

En Belvo, la seguridad de tus datos y operaciones es una prioridad principal. Por lo tanto, ofrecemos una función de lista blanca opcional, pero altamente recomendada, para nuestra API de Débito Directo.

Esta función añade una capa extra de seguridad ya que asegura que cada solicitud de API se origine desde una dirección IP preaprobada, junto con tus claves de API. Incluso si tus claves de API son comprometidas, el riesgo de acceso no autorizado se reduce significativamente, ya que solo se reconocerán solicitudes de IPs de confianza.

Solicitudes desde direcciones IP no aprobadas

Las solicitudes realizadas desde direcciones IP no aprobadas recibirán un error 401 Unauthorized.

Cómo configurar la lista blanca de IP

Para configurar la lista blanca de IP, por favor contacta a support-directdebit@belvo.com con la siguiente información:

Nombre de la empresa
Lista de IPs que deseas incluir en la lista blanca

Cuerpo de Correo Electrónico de Ejemplo

Hello,

I would like to request the following IP addresses to be whitelisted for my Belvo Direct Debit integration:

- ip_address_1
- ip_address_2

Thank you,

your_company_name

Nuestro equipo se pondrá en contacto si necesitan más información o una vez que las IPs hayan sido incluidas en la lista blanca.