Skip to main content
La API de Fintoc admite solicitudes idempotentes. Puedes reintentar una solicitud idempotente sin ejecutar la misma operación dos veces. Usa la idempotencia en solicitudes de creación de recursos que podrías reintentar después de un error de red. Algunos ejemplos son los cargos, las intenciones de pago y las transferencias. Si ocurre un error de conexión después de enviar una solicitud idempotente, puedes reintentarla sin crear un segundo objeto. Para realizar una solicitud idempotente, incluye el encabezado Idempotency-Key: <idempotency-key-value>. Una clave de idempotencia es un valor único que genera tu cliente. Fintoc usa esta clave para reconocer los reintentos de una misma solicitud. Usa UUID de versión 4 o cadenas aleatorias con suficiente entropía para evitar colisiones. Las claves de idempotencia pueden contener hasta 255 caracteres. Fintoc guarda el código de estado y el cuerpo de la respuesta de la primera solicitud para cada clave de idempotencia, tanto si la solicitud tiene éxito como si falla. Las solicitudes posteriores con la misma clave devuelven el resultado guardado, incluidos los errores 4xx y 5xx. Las respuestas repetidas incluyen el encabezado Idempotent-Replayed: true.
Autenticación necesariaFintoc no guarda un resultado idempotente cuando falla la autenticación porque la solicitud no llega al endpoint de la API.
En cada reintento, la capa de idempotencia compara los parámetros de la solicitud con los parámetros originales. Si los parámetros son diferentes, Fintoc devuelve un error 400 Bad Request con el código invalid_idempotent_request. Si envías una solicitud mientras otra solicitud anterior con la misma clave sigue en curso, Fintoc no la procesa una segunda vez. Fintoc espera hasta cerca de 1 segundo el primer resultado y lo devuelve. Si la primera solicitud no ha terminado para entonces, Fintoc devuelve un error 503 Service Unavailable con el código idempotency_unavailable. Fintoc no guarda esta respuesta 503. Reintenta más tarde con la misma clave para obtener el resultado de la primera solicitud.

​
Reintentar una transferencia de forma segura

Una respuesta 5xx o un timeout aún pueden significar que Fintoc creó la transferencia. Como Fintoc repite una respuesta 5xx guardada, reintentar con la misma clave devuelve el mismo error y no te dice si la transferencia existe. Para evitar enviar un pago dos veces:
  1. Guarda tu propio identificador de cada pago en la metadata de la transferencia, y envía un Idempotency-Key por pago.
  2. Si la solicitud expira o la conexión se corta antes de recibir una respuesta, reintenta con la misma clave. Obtienes el resultado guardado o el resultado de un nuevo intento.
  3. Si recibes una respuesta 5xx, lista las transferencias con account_id, direction=outbound y since justo antes de tu solicitud. Busca una transferencia con tu identificador en metadata.
  4. Si encuentras la transferencia, sigue su estado y sus webhooks. Si no la encuentras, crea la transferencia con un nuevo Idempotency-Key.
Fintoc puede eliminar automáticamente las claves de idempotencia cuando tienen al menos 24 horas. Si reutilizas una clave después de que Fintoc elimina el resultado original, la API procesa la solicitud como nueva. Todas las solicitudes POST aceptan claves de idempotencia. Enviar claves de idempotencia en solicitudes GET y DELETE no tiene efecto porque estas solicitudes son idempotentes por definición. Los siguientes ejemplos crean un cargo con una clave de idempotencia. Puedes reintentar la solicitud sin crear un cargo duplicado.