Idempotencia

Las redes fallan. Cuando una solicitud se queda sin respuesta no puedes saber si Flashpi la recibió, y volver a enviarla a ciegas podría emitir la misma factura dos veces, con dos secuenciales y dos claves de acceso. Por eso todo POST de la API de facturación acepta un encabezado Idempotency-Key: reintenta con la misma clave y Flashpi responde con el resultado de la primera solicitud en lugar de repetir el trabajo.

curl https://api.flashpi.com.ec/v1/invoices \
  -H "Authorization: Bearer $FLASHPI_API_KEY" \
  -H "Idempotency-Key: 6f1c2a9e-3b7d-4e8a-9c41-2d5f8b0e7a13" \
  -H "Content-Type: application/json" \
  -d @invoice.json

Elegir una clave

• De 1 a 255 caracteres ASCII visibles (sin espacios). Una clave mal formada recibe 400 invalid_idempotency_key.
• Usa una clave por cada operación que debe ocurrir una sola vez: un UUID generado al crear el pedido, o tu propio ID de la operación (order-PO-4812, return-RMA-2291). Guárdala con la operación, para que un reintento después de una caída la reutilice.
• Nunca reutilices una clave para otra operación.

Cómo funciona

Situación	Respuesta
Primera solicitud con la clave	Se procesa con normalidad.
Misma clave, misma solicitud, después de que la primera tuvo éxito	La primera respuesta otra vez (mismo estado y cuerpo), con el encabezado Idempotent-Replayed: true. No se vuelve a emitir nada.
Misma clave, misma solicitud, mientras la primera sigue en curso	409 idempotency_key_in_progress. Espera un momento y reintenta.
Misma clave, solicitud distinta	422 idempotency_key_reused.
Misma clave después de que la primera solicitud falló	Se procesa como nueva: una solicitud fallida (cualquier respuesta de error) no se queda con su clave, así que puedes corregir la solicitud y enviarla con la misma clave.

• Dos solicitudes son la misma cuando coinciden el método, la ruta con su query string y el cuerpo JSON. El orden de las claves del JSON no importa; cualquier otra diferencia sí.
• Las claves pertenecen a tu cuenta y al ambiente de la llave: una llave de prueba y una de producción nunca las comparten.
• Solo se recuerdan las respuestas exitosas (2xx). Una respuesta repetida no trae el encabezado Location; el id del cuerpo da la misma ruta.
• Una respuesta repetida es la primera respuesta tal como era entonces. Para conocer el estado actual de un comprobante, consúltalo con GET /v1/documents/{id}.

Retención: 24 horas

Flashpi recuerda una clave durante 24 horas desde su primer uso. Después, la misma clave se procesa como una solicitud nueva, con una excepción que protege tus comprobantes:

• Una clave que creó un comprobante queda ligada a ese comprobante para siempre. Una solicitud posterior con ella, aun después de 24 horas, recibe 422 idempotency_key_reused con el documentId del comprobante que creó, nunca un segundo comprobante.

{
  "type": "https://flashpi.com.ec/docs/en/errors/idempotency_key_reused",
  "title": "Idempotency key reused",
  "status": 422,
  "detail": "A document was already created with this Idempotency-Key. Use a new key for a new document.",
  "instance": "/v1/invoices",
  "code": "idempotency_key_reused",
  "errors": [],
  "requestId": "01a15fe0-7a41-7b3c-a9d2-5e8c1f4b6a09",
  "documentId": "01a1412b-ae38-7c39-8c71-16d2b5dfc472"
}

Nota

La retención de 24 horas y si el encabezado pasa a ser obligatorio al crear comprobantes todavía están por confirmarse antes del lanzamiento. Hoy el encabezado es opcional en todo POST, y se recomienda mucho enviarlo en cada solicitud.

Reintentar sin riesgo

1. Genera la clave una vez por operación y consérvala.
2. Reintenta ante errores de red, tiempos de espera agotados y respuestas 5xx con la misma clave y el mismo cuerpo, esperando cada vez más entre intentos (por ejemplo 1, 2, 4 y 8 segundos).
3. Ante 409 idempotency_key_in_progress, espera y reintenta.
4. No reintentes sin cambios una respuesta 4xx: primero corrige la solicitud. Una solicitud corregida puede reutilizar la clave, porque la fallida no se quedó con ella.