Consultas en vivo contra la DGII¶

Tres endpoints que preguntan a la DGII en el momento, en lugar de leer nuestro registro. Existen porque los dos registros pueden divergir, y cuando divergen el que vale es el de ellos.

Endpoint	Para qué
`GET /api/v1/documents/{identificador}/dgii-status`	Estado de un e-CF suyo en la DGII, y en qué se diferencia de lo que tenemos
`GET /api/v1/documents/{identificador}/track-ids`	Los envíos que la DGII registra para ese e-CF
`GET /api/v1/received-documents/{eNCF}/dgii-status`	Si un comprobante que le enviaron tiene validez fiscal

Todos requieren el token de siempre (Authorization: Bearer …) y sólo devuelven comprobantes de una empresa de las que su token tiene habilitadas (tokens-y-permisos.md). Cómo se dice cuál:

Los dos de un e-CF suyo se piden por su identificador (el RNC del emisor seguido del e-NCF, p. ej. 133802074E310000000077), y la empresa es su prefijo: no llevan emisor_rnc. Si lo mandan, tiene que ser el mismo.
El de un e-CF que recibió es de un tercero: el e-NCF no es suyo, así que ahí la empresa va, como siempre, en el parámetro emisor_rnc.

La consulta que conviene conocer: validez fiscal de lo que recibe¶

Cuando un proveedor le envía un e-CF, verificamos su firma digital antes de acusar recibo. Eso no significa que el comprobante sea válido ante la DGII. La firma demuestra quién lo emitió y que no se alteró; que la DGII lo haya aceptado es otra cosa, y puede haberlo rechazado.

Antes de dar por bueno un crédito fiscal:

GET /api/v1/received-documents/E310000000099/dgii-status?emisor_rnc=133802074
Authorization: Bearer <su-token>

{
  "status": "success",
  "message": "Consulta exitosa.",
  "data": {
    "encontrado": true,
    "valido_fiscalmente": false,
    "status_code": 6,
    "status": "rejected_dgii",
    "codigo_dgii": 2,
    "estado_dgii": "Rechazado",
    "rnc_emisor": "131880738",
    "e_ncf": "E310000000099",
    "monto_total": 2360,
    "total_itbis": 360,
    "fecha_emision": "10-08-2026",
    "fecha_firma": "10-08-2026 09:14:22",
    "rnc_comprador": "133802074",
    "codigo_seguridad": "aBc123",
    "id_extranjero": null,
    "emisor_rnc": "131880738",
    "acuse_emitido": true,
    "monto_registrado": 2360
  }
}

acuse_emitido: true con valido_fiscalmente: false es justo el caso interesante: el comprobante llegó bien y aun así no sustenta nada.

Ojo con emisor_rnc en la respuesta. En esta respuesta (y en las de GET /api/v1/received-documents), emisor_rnc es el RNC del proveedor que envió el e-CF, no el parámetro de la petición: el parámetro emisor_rnc de la consulta identifica a su empresa (la que recibió el comprobante). En el ejemplo, la consulta va por 133802074 (su empresa) y el comprobante lo emitió 131880738.

Estado de un e-CF propio, con las discrepancias¶

GET /api/v1/documents/133802074E310000000077/dgii-status
Authorization: Bearer <su-token>

Además de lo que devuelve la DGII, la respuesta trae el identificador, nuestro_status y una lista discrepancias —vacía cuando todo cuadra:

{
  "status": "success",
  "message": "Consulta exitosa.",
  "data": {
    "encontrado": true,
    "valido_fiscalmente": true,
    "status_code": 4,
    "status": "accepted_dgii",
    "codigo_dgii": 1,
    "estado_dgii": "Aceptado",
    "rnc_emisor": "133802074",
    "e_ncf": "E310000000077",
    "monto_total": 1180,
    "total_itbis": 180,
    "fecha_emision": "10-08-2026",
    "fecha_firma": "10-08-2026 09:14:22",
    "rnc_comprador": "131880738",
    "codigo_seguridad": "aBc123",
    "id_extranjero": null,
    "identificador": "133802074E310000000077",
    "nuestro_status_code": 8,
    "nuestro_status": "unresolved",
    "discrepancias": [
      "El estado en la DGII es \"accepted_dgii\" y aquí está registrado como \"unresolved\"."
    ]
  }
}

Se comparan tres cosas: el estado, el monto total y el código de seguridad. Ese último es el que importa de verdad: sale del hash de la firma, así que si no coincide, el comprobante que la DGII tiene registrado no es el que firmamos aquí.

Cuándo usarla:

Un documento en unresolved (se agotó el sondeo automático) — es la forma de cerrarlo.
Cuadre periódico contra su contabilidad.
Cualquier duda sobre un comprobante del que no le llegó respuesta.

Los envíos de un e-CF¶

GET /api/v1/documents/133802074E310000000077/track-ids
Authorization: Bearer <su-token>

{
  "status": "success",
  "message": "Consulta exitosa.",
  "data": {
    "e_ncf": "E310000000077",
    "identificador": "133802074E310000000077",
    "nuestro_track_id": "b4c1…",
    "envios": [
      { "track_id": "b4c1…", "estado_dgii": "Aceptado",  "status": "accepted_dgii", "fecha_recepcion": "2026-08-12T09:00:00" },
      { "track_id": "9af0…", "estado_dgii": "Rechazado", "status": "rejected_dgii", "fecha_recepcion": "2026-08-10T09:00:00" }
    ],
    "transmitido_mas_de_una_vez": true
  }
}

Un mismo e-NCF puede tener más de un envío: la propia DGII lo advierte ("se pueden obtener múltiples TrackIds cuando se remiten varios e-CF con el mismo número de comprobante fiscal"). Pasa cuando un envío llega y su respuesta se pierde. Los envíos vienen del más reciente al más antiguo.

nuestro_track_id es el que tenemos registrado para el documento: null mientras no se haya transmitido (y siempre en el resumen de la factura de consumo, que no genera TrackID); al transmitirse llega con in_process_dgii y los estados finales lo conservan (estados.md).

No hace falta vigilarlo a mano en el caso normal: antes de retransmitir un comprobante cuyo envío anterior falló, comprobamos si la DGII ya lo tiene y adoptamos su TrackID en lugar de mandarlo otra vez. Este endpoint es para cuando quiere verlo usted.

El resumen (RFCE) de la factura de consumo¶

La factura de consumo (tipo 32) por debajo de RD$250.000 se transmite como resumen (RFCE), que no genera TrackID (ecf-32.md). Eso cambia lo que responden estas consultas para esos documentos:

Consulta Qué responde para un resumen

GET /documents/{identificador}/dgii-status Funciona igual que en los demás tipos: la consulta de estado se hace por e-NCF y la norma la extiende a los comprobantes remitidos como resumen. Es la forma de preguntarle a la DGII por una factura de consumo. Trae nuestro_status y discrepancias como siempre.

GET /documents/{identificador}/track-ids No está pensada para el resumen: no genera TrackID, así que nuestro_track_id es null y envios sale vacío ("envios": [], con transmitido_mas_de_una_vez: false) y la respuesta es un 200, no un error (comprobado contra testecf: la DGII contesta «TrackId no encontrado» a ese e-NCF y la API lo traduce a «sin envíos»). Que salga vacío no significa que la DGII no tenga el comprobante: use dgii-status, que sí lo encuentra por e-NCF.

Un documento de otro tipo también puede mostrar envios vacío, pero por otra razón: si la DGII aún no registra ningún envío para ese e-NCF (por ejemplo, porque no llegó a transmitirse).

En el uso normal no necesita estas consultas para un resumen: se resuelve en la misma llamada de transmisión y GET /api/v1/documents/{identificador} ya trae el estado final.

Errores¶

Código	Cuándo
`404`	El identificador no es de un e-CF de esa empresa (o, en la consulta de un recibido, el e-NCF no existe para la empresa indicada en `emisor_rnc`): «No se encontró el documento.» o «No se encontró el e-CF recibido.», con el texto largo en `data.detalle`. Se responde igual si no existe y si es de otra empresa.
`422`	Se manda `emisor_rnc` junto a un identificador cuyo prefijo es otro RNC: «La petición declara más de una empresa.»
`503`	El servicio de consulta de la DGII no responde — vuelva a intentarlo, no es un error de su petición

Todos llevan el envelope de siempre (cómo leerlo), con la explicación en data.detalle. El 503, en concreto:

{
  "status": "error",
  "message": "El servicio de consulta de la DGII no está disponible en este momento.",
  "data": {
    "detalle": "La DGII no respondió o contestó con un error. No es un fallo de su petición: reintente en unos minutos."
  }
}

El texto técnico de lo que respondió la DGII (o de por qué no respondió) no se devuelve: no le serviría para corregir nada y no es de su petición. Si el 503 persiste, contáctenos con la hora y el identificador del documento.

Estas consultas no se cachean: el objetivo es saber qué dice la DGII ahora.