factadesarrolladores API 0.1.0-esqueleto

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.

curlTerminal
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), con Idempotency-Replayed: true e Idempotency-Replay-Source: rebuilt. Nunca emite uno nuevo.
  • Repetir con otro cuerpo es 422 idempotency_key_reuse siempre, 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ó. Espere Retry-After y repita la misma petición con la misma Idempotency-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

Escriba para buscar Por ejemplo: idempotencia, contingencia, 422, emitir.

↑ ↓ moverse Enter abrir Esc cerrar