factadesarrolladores API 0.1.0-esqueleto

Facturas pendientes y reintento

Una emisión puede terminar sin que usted sepa si Hacienda selló el documento: el servicio del Ministerio no contestó, su conexión se cortó, Facta le devolvió un 503, o la respuesta trajo una advertencia. En todos esos casos hay una sola regla:

Qué es un documento pendiente

Está pendiente un documento que Facta ya firmó y cuyo correlativo ya se gastó, pero que Hacienda todavía no ha dicho si acepta o rechaza. Existe, es suyo, y se le debe a Hacienda. Se arregla terminándolo, no creando otro.

Paso 1. Liste lo pendiente

curlTerminal
curl "$FACTA_API_BASE_URL/v1/dte/pendientes" \
  -H "X-Facta-Key: $FACTA_API_KEY"

Responde, del más antiguo al más nuevo, solo con datos del documento (nunca el documento ni el receptor):

jsonrespuesta 200
{
  "pendientes": [
    {
      "codigoGeneracion": "7875BC7A-9580-441D-94E4-FA455E9D8BD0",
      "numeroControl": "DTE-01-M001P001-000000000000417",
      "tipoDte": "01",
      "estado": "firmado",
      "firmadoEn": "2026-10-30T17:41:02Z",
      "antiguedadSegundos": 840,
      "intentos": 0,
      "ultimaRespuestaMh": null,
      "plazo": { "venceEn": "2026-10-31T17:41:02Z", "vencido": false, "requiereContingencia": false },
      "reintentable": true,
      "motivoNoReintentable": null
    }
  ],
  "siguiente": null
}
  • reintentable: true significa que usted puede terminarlo desde la API. Si es false, motivoNoReintentable dice por qué: documento_de_la_aplicacion (lo emitió la aplicación; se reintenta desde Documentos → Pendientes con Hacienda), sin_copia_firmada o rechazado.
  • ?estado=rechazado lista los que Hacienda negó y esperan corrección.
  • plazo.requiereContingencia pasa a true cuando pasaron más de 24 horas desde la firma. Ya no es el camino normal de transmisión: conviene declarar el Evento de Contingencia desde la aplicación. Facta no bloquea el reintento por eso: pregunta a Hacienda, que es quien decide.

Paso 2. Reintente, con la misma firma

curlTerminal
curl -X POST "$FACTA_API_BASE_URL/v1/dte/7875BC7A-9580-441D-94E4-FA455E9D8BD0/reintentar" \
  -H "X-Facta-Key: $FACTA_API_KEY" \
  -H "X-Facta-Sign-Key: $FACTA_SIGN_KEY"

Necesita la misma contraseña del vault de firma que una emisión (de ahí salen las credenciales de Hacienda). No firma nada nuevo ni gasta un número: reenvía los mismos bytes del mismo documento. Antes de enviar, le pregunta a Hacienda qué sabe de ese código:

Hacienda diceQué hace FactaUsted recibe
«Ya lo sellé»No reenvía nada. Completa el registro y cierra el correlativo.200 con estado: "sellado", via: "consulta"
«No lo recibí»Reenvía los mismos bytes.200 sellado, via: "retransmision"
«Lo rechacé»Registra el rechazo.422 mh_rejected con las palabras de Hacienda
(no contesta)No cambia nada.202 estado: "pendiente": repita más tarde

Repetir la llamada sobre un documento ya sellado no hace nada (via: "ya_asentado"). Dos reintentos al mismo tiempo no transmiten dos veces: el segundo recibe 409 retry_in_progress con Retry-After.

Un 422 mh_rejected se corrige con una petición nueva que reutilice ese mismo número (§167), como cuenta Contingencia y resultados inciertos; no se arregla reintentando.

Qué hacer en cada situación

Lo que veQué significaQué hacer
503 service_unavailable con Retry-AfterAlgo de Facta no contestó. Si dice que no se pudo dejar constancia del documento firmado, no se envió nada a Hacienda y el correlativo se devolvió.Espere Retry-After y repita la misma petición con la misma Idempotency-Key. Es seguro.
202 contingencia al emitirFirmado; Hacienda no contestó.Guarde jws y numeroControl. Más tarde, GET /v1/dte/pendientes y POST …/reintentar. No emita otra vez.
Su proceso se cayó o se cortó la conexiónNo sabe si llegó.Repita con la misma llave y el mismo cuerpo; o GET /v1/dte/pendientes.
200 con advertencias: indice_pendienteEl documento está sellado, pero su registro en Facta DTE no se pudo escribir. La respuesta trae documento y jws: guárdelos.Llame a POST …/reintentar: termina el registro sin reenviar nada. No emita otra vez.
200 con advertencias: reserva_sin_asentarSellado e indexado; falta cerrar el correlativo.Llame a POST …/reintentar. No emita otra vez.

Idempotencia, ahora más estricta

Desde el 30 de octubre de 2026 la Idempotency-Key es más estricta: una llave que dio origen a un documento queda atada a esa venta para siempre. La respuesta guardada se conserva 7 días; pasado ese tiempo, repetir la misma llave con el mismo cuerpo devuelve el documento que ya existe (nunca uno nuevo), y la misma llave con otro cuerpo es siempre 422 idempotency_key_reuse. Use una llave distinta por cada venta, para siempre. Los detalles están en Idempotencia y reintentos.

Con el SDK de TypeScript

typescript
const pendientes = await facta.listPendingDocuments();

for (const doc of pendientes.pendientes) {
  if (!doc.reintentable) continue; // los de la aplicación se reintentan allí
  const resultado = await facta.retryDocument(doc.codigoGeneracion);
  console.log(resultado.estado, resultado.via);
}

Estos métodos llegan con la versión del SDK que acompaña a esta guía: compruebe la versión publicada en npm. Hasta entonces, las dos rutas se llaman con HTTP directo, como arriba.

Para su sistema

Conviene que cada venta tenga cuatro estados: sellada, firmada sin sello (pendiente), rechazada y sin emitir. Después de cualquier emisión dudosa, revise lo pendiente antes de decidir nada. Y nunca resuelva un 503 o un corte inventando una llave nueva.

Otras guías

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

↑ ↓ moverse Enter abrir Esc cerrar