Idempotencia, plazos y reversos

Próximamente

Comportamiento implementado y probado; todavía sin sandbox ni servidor público.

El Autorizador JSON se diseñó con una promesa: ningún reintento produce un doble cargo y toda operación incierta termina reversada y confirmada. Para cumplirla necesita tu Idempotency-Key.

La Idempotency-Key

• Obligatoria en todos los POST: autorizar, reversar, capturar, devolver y la vista ISO.
• Entre 16 y 64 caracteres [A-Za-z0-9_-]. Usa tu número de pedido con un sufijo de intento, por ejemplo PED-2026-000123-v1.
• Es única para siempre dentro de tu cliente: no la reutilices para otra operación, ni siquiera días después.
• Cada operación sobre una original (reverso, captura, devolución) lleva su propia clave.

Reintentas con…	Resultado
La misma clave y el mismo cuerpo	La misma respuesta guardada. Nunca un segundo envío al emisor
La misma clave y el mismo cuerpo, mientras la original sigue en vuelo	INDETERMINADA (consulta más tarde)
La misma clave y otro cuerpo	422 IDEMPOTENCIA_CUERPO_DISTINTO, con el idAutorizacion que ya usa esa clave. Nada se envía
Otra clave	Una operación nueva. Úsala solo si la anterior terminó RECHAZADA y quieres intentarlo de nuevo

El cuerpo se compara en forma canónica (claves ordenadas, sin espacios): reordenar las propiedades del JSON no cambia la huella.

El plazo y el reverso automático

El autorizador espera la respuesta del emisor como máximo 2.500 ms (valor por defecto; FINORA puede ajustarlo por cliente entre 1.000 y 2.999 ms). Si el plazo vence, si el emisor responde 91, 94 o 96, o si la conexión se cae después de escribir el mensaje, la operación queda INDETERMINADA y el autorizador, en la misma transacción, programa el reverso 0400.

Puntos clave:

• Una INDETERMINADA nunca se convierte en APROBADA. Aunque el emisor apruebe tarde, el autorizador vuelve a reversar. Su estado final es siempre REVERSADA.
• REVERSADA solo se declara después de confirmarla contra el libro del emisor, no por haber recibido un 00 al reverso.
• El reverso automático sale con el importe solicitado y el emisor deshace lo que tenga registrado, incluida una aprobación parcial.

Así se ve una INDETERMINADA recién respondida:

{
  "idAutorizacion": "01JBX3A7K2M4N6P8R0S2T4V6W8",
  "operacion": "COMPRA",
  "resultado": "INDETERMINADA",
  "estado": "INDETERMINADA",
  "codigoRespuesta": "91",
  "mensaje": "Sin respuesta en el plazo; se envió el reverso",
  "codigoAutorizacion": null,
  "rrn": "629300000123",
  "stan": "000457",
  "monto": { "solicitado": "1250.00", "aprobado": null, "moneda": "928", "devuelto": null },
  "referenciaTasa": null,
  "reverso": { "estado": "REVERSANDO", "intentos": 1, "confirmadoEn": null },
  "referenciaCliente": "PED-2026-000123",
  "iso": { "mtiRespuesta": null },
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "latenciaMs": 2500
}

estado es el estado de la solicitud en el libro del autorizador; reverso muestra el avance del reverso automático (REVERSANDO, REVERSO_RESPONDIDO, REVERSADA o DISCREPANCIA). Y, un rato después, al consultarla con GET:

{
  "resultado": "INDETERMINADA",
  "estado": "REVERSADA",
  "codigoRespuesta": "91",
  "mensaje": "Reverso confirmado contra el libro",
  "reverso": { "estado": "REVERSADA", "intentos": 2, "confirmadoEn": "2026-10-20T18:07:40Z" }
}

Qué hacer en cada caso

• Tu propio timeout. Configura tu cliente HTTP con un tiempo de espera algo mayor que el plazo del autorizador (por ejemplo, 5 s). Si aun así no recibes respuesta, no pidas un reverso a ciegas ni cambies de clave: reintenta con la misma Idempotency-Key. Recibirás la respuesta guardada o INDETERMINADA, y en ambos casos sabrás qué pasó.
• NO_ENVIADA (HTTP 503). Nada salió hacia el emisor (no disponible, saturado o con el circuito abierto). Respeta Retry-After (1 s) y reintenta con la misma clave: el autorizador vuelve a validar las reglas y reutiliza los mismos datos de red.
• RECHAZADA. Repetir la misma clave devuelve el mismo rechazo. Si el titular quiere intentarlo de nuevo (por ejemplo, con otra credencial), es una operación nueva con otra clave.

Avisos de reverso

Próximamente

El contrato define avisos firmados autorizacion.reversada y autorizacion.indeterminada_resuelta (cabecera X-Finora-Signature: t=<epoch>,v1=<hmac-sha256>), pero aún no se emiten. Mientras tanto, consulta el estado con GET /v1/authorizations/{id}.

Si tu cliente queda suspendido

Un cliente suspendido o dado de baja recibe 403 CLIENTE_SUSPENDIDO en todo salvo en los reversos: un cliente suspendido siempre puede deshacer las operaciones aprobadas que tenga vivas, y uno dado de baja puede hacerlo durante la ventana de reversos que se acuerde en la baja.