Idempotencia y reintentos
Idempotency-Key es obligatoria en toda ruta que no se pueda deshacer: las tres que gastan correlativo (emitir, prepare, sign) y la anulación. Sin ella, un reintento por timeout quemaría un segundo número, o mandaría un segundo evento contra un documento que el primero ya anuló.
Elíjala usted, y que signifique algo
Es un identificador que usted elige, no que el servidor genera. Si su sistema ya tiene uno para esta venta —el número de pedido, el ticket de caja—, ese es mejor que uno aleatorio: hace la operación idempotente entre reinicios de su proceso, no solo entre reintentos de una misma llamada en memoria.
curl -X POST "$FACTA_API_BASE_URL/v1/dte" \
-H "X-Facta-Key: $FACTA_API_KEY" \
-H "X-Facta-Sign-Key: $FACTA_SIGN_KEY" \
-H "Idempotency-Key: pedido-00417" \
-H "Content-Type: application/json" \
-d '{ "tipoDte": "01", "items": [{ "descripcion": "Café", "cantidad": 2, "precioUni": 1.5 }] }'Reglas, todas verificables
- Alcance
(llave, Idempotency-Key). Dos integradores pueden usar la misma cadena sin chocar, y ninguno puede leer la respuesta del otro. - La misma llave con el mismo cuerpo devuelve la respuesta guardada, con
Idempotency-Replayed: true. Eso incluye un rechazo del Ministerio: el reintento devuelve el mismo 422, sin quemar otro número. - La misma llave con otro cuerpo es
422 idempotency_key_reuse. Devolver la factura de ayer para la venta de hoy sería peor que fallar. - Mientras la primera está en vuelo, la segunda es
409 idempotency_in_flight. No se encola: el cliente reintenta. - La llave queda atada a su venta para siempre. Desde el 30 de octubre de 2026 esta regla es más estricta: una llave que dio origen a un documento no se libera nunca. La respuesta guardada se conserva 7 días; después se borra, pero Facta recuerda qué solicitud y qué documento eran.
- Repetir con el mismo cuerpo pasados los 7 días devuelve el documento que ya existe, reconstruido desde sus copias (estado, sello y totales; el archivo se baja con
GET /v1/dte/{codigoGeneracion}/file), conIdempotency-Replayed: trueeIdempotency-Replay-Source: rebuilt. Nunca emite uno nuevo. - Repetir con otro cuerpo es
422 idempotency_key_reusesiempre, también pasados los 7 días. - Una llave por venta, para siempre. No reutilice una llave para otra venta aunque haya pasado mucho tiempo. Si perdió la respuesta, repita con la misma llave y el mismo cuerpo, o consulte el documento (Facturas pendientes y reintento); nunca invente una llave nueva para volver a intentar la misma venta.
Dónde reintentar es seguro, y dónde no
Solo cinco condiciones se arreglan reintentando, y las cinco son casos donde nadie tomó todavía una decisión irreversible sobre su venta:
409 idempotency_in_flight— la primera petición sigue trabajando.503 service_unavailable/503 correlative_unavailable— algo de Facta no contestó. EspereRetry-Aftery repita la misma petición con la mismaIdempotency-Key. Si ya había firmado y no sabe qué pasó, mire lo pendiente antes de emitir.502 mh_unreachable— reservado; la versión actual nunca lo devuelve (ver abajo).
Y una que no se arregla reintentando igual:
424 mh_auth_failed— Hacienda no aceptó el usuario y la contraseña de transmisión (API) de la empresa. La persona titular debe actualizar la contraseña de la API del Ministerio en la app; en una emisión el documento ya quedó firmado y su correlativo gastado (details.codigoGeneracion,details.numeroControl), así que no lo emita otra vez.
Un 503 correlative_unavailable trae Retry-After. Si la base alcanzó a reservar el número cuando la petición ya había fallado, Facta lo devuelve antes de contestar: reintentar con la misma Idempotency-Key es seguro.
- El fallo de red del propio cliente, antes de recibir cualquier respuesta.
Nunca reintente un 4xx que no sea el 409 de arriba, y nunca reintente un rechazo (422 mh_rejected). Un rechazo es un veredicto sobre sus datos, no una caída — reintentar el mismo cuerpo solo repite el mismo veredicto guardado.
Por qué mh_unreachable está reservado y nunca aparece
Un 502 invitaría a reintentar, y reintentar una emisión que YA está firmada firmaría un segundo documento. Por eso todo fallo de transporte hacia el Ministerio —caída, timeout, una respuesta que no se puede leer— sale como 202 contingencia en vez de un 502: para cuando el fallo ocurre, el documento ya existe y se le debe a Hacienda. La guía Contingencia y resultados inciertos cuenta qué hacer con ese 202.
La anulación es la única ruta donde un 502 mh_unreachable sí puede ocurrir de verdad: ahí nada se firmó todavía cuando el transporte falla, así que reintentar con la misma Idempotency-Key es seguro y no anula dos veces.
Otras guías
Emitir un DTE
Cómo llamar a POST /v1/dte, qué llega firmado por dentro y las tres respuestas que puede recibir.
Leer →Nota de remisión (04) y retención (07)
Para qué sirve cada uno, quién puede emitirlos, cada campo con su razón, los códigos de retención, lo que se ignora y los errores que verá.
Leer →