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
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):
{
"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: truesignifica que usted puede terminarlo desde la API. Si esfalse,motivoNoReintentabledice por qué:documento_de_la_aplicacion(lo emitió la aplicación; se reintenta desde Documentos → Pendientes con Hacienda),sin_copia_firmadaorechazado.?estado=rechazadolista los que Hacienda negó y esperan corrección.plazo.requiereContingenciapasa atruecuando 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
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 dice | Qué hace Facta | Usted 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 ve | Qué significa | Qué hacer |
|---|---|---|
503 service_unavailable con Retry-After | Algo 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 emitir | Firmado; 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ón | No sabe si llegó. | Repita con la misma llave y el mismo cuerpo; o GET /v1/dte/pendientes. |
200 con advertencias: indice_pendiente | El 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_asentar | Sellado 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
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
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 →