Estados internos del e-CF¶

Nuestra API expone su propio vocabulario de estados, que cubre el ciclo completo: la recepción en la API, la transmisión a la DGII, la resolución de ésta y los fallos del sistema. Cada estado se devuelve como tres campos:

Campo	Para qué sirve
`status_code`	Número estable: no se reordena ni se reutiliza. Úselo si guarda el estado en su BD.
`status`	Slug técnico. Úselo en su código: es autoexplicativo.
`status_description`	Texto en español, listo para mostrar al usuario final.

Estos tres campos viajan dentro de document (el 202, el detalle, el reenvío de un folio) o de data (el listado, dgii-status, track-ids). No los confunda con el status de la raíz de la respuesta, que sólo vale success o error y dice si la petición salió bien, no cómo va el e-CF (cómo responde la API).

Consulte el catálogo vivo en GET /api/v1/statuses (no necesita declarar empresa: es igual para todos):

{
  "status": "success",
  "message": "Consulta exitosa.",
  "data": [
    {
      "code": 1,
      "slug": "received",
      "name": "Recibido",
      "description": "El e-CF fue recibido, validado y encolado para su envío a la DGII.",
      "is_final": false,
      "is_valid_fiscally": false
    },
    { "code": 2, "slug": "rejected_validation", "…": "…" }
  ]
}

Catálogo¶

Código	Slug	Nombre	¿Final?	¿Validez fiscal?	Descripción
1	`received`	Recibido	No	No	El e-CF fue recibido, validado y encolado para su envío a la DGII.
2	`rejected_validation`	Rechazado en validación	Sí	No	No superó las validaciones previas al envío; no se transmitió a la DGII: su e-NCF no llegó a usarse ante ella.
3	`in_process_dgii`	En proceso en la DGII	No	No	Transmitido; la DGII devolvió TrackID pero aún no resuelve. Se consulta automáticamente.
4	`accepted_dgii`	Aceptado	Sí	Sí	La DGII aceptó el e-CF: tiene validez fiscal.
5	`conditionally_accepted_dgii`	Aceptado condicional	Sí	Sí	Aceptado con observaciones que no ameritan rechazo. Tiene validez fiscal, pero corrija para envíos futuros.
6	`rejected_dgii`	Rechazado por la DGII	Sí	No	Rechazado: el comprobante es nulo para fines tributarios. Si `sequence_reusable` es `true`, la DGII da la secuencia por no utilizada y puede anularla.
7	`not_found_dgii`	No encontrado en la DGII	No	No	La DGII aún no encuentra el TrackID. Es transitorio.
8	`unresolved`	Sin resolución	Sí	No	Se agotaron las consultas sin que la DGII resolviera. Requiere revisión manual.
9	`system_error`	Error del sistema	No	No	Error interno al construir, firmar o transmitir. No es un rechazo de la DGII; se reintenta.

Transiciones¶

                        ┌──────────────────────── 2 rejected_validation  (fin; nunca llegó a la DGII)
                        │
  (POST) ──► 1 received ─┤
                        │            ┌──► 4 accepted_dgii                 (fin, válido) ──► PDF
                        └─► 3 in_process_dgii ──┼──► 5 conditionally_accepted_dgii (fin, válido) ──► PDF
                             ▲     │            ├──► 6 rejected_dgii      (fin, nulo)
                             │     │            └──► 8 unresolved         (fin, revisión manual)
                             │     └──► 7 not_found_dgii ──┐
                             └───────────────────────────────┘  (se reconsulta)

  cualquier punto ──► 9 system_error ──► (reintento automático) ──► vuelve al flujo

Dónde aparece el TrackID¶

El TrackID es el identificador que la DGII da a un envío por el servicio de recepción de e-CF. Según el camino que siga el comprobante, aparece (o no) así:

Camino	`track_id`
Respuesta `202` al emitir (cualquier tipo)	Siempre `null`: la transmisión ocurre después, en segundo plano.
Tipos completos (todos, y el 32 de RD$250.000 o más)	Llega al transmitirse: el documento pasa a `in_process_dgii` con `track_id` y se resuelve por sondeo hasta un estado final.
Estados finales (`accepted_dgii`, `conditionally_accepted_dgii`, `rejected_dgii`, `unresolved`)	Lo conservan: una vez asignado, el detalle, el listado y el reenvío de un folio siguen devolviendo el mismo `track_id`. Sólo cambia si el comprobante se transmite de nuevo: cada envío añade un TrackID, y todos se ven en `GET /api/v1/documents/{identificador}/track-ids`.
Resumen RFCE (factura de consumo, tipo 32, por debajo de RD$250.000)	No existe nunca. La DGII resuelve en la misma llamada: el documento pasa de `received` a un estado final (`accepted_dgii`, `conditionally_accepted_dgii` o `rejected_dgii`) con `track_id` en `null`. Es lo esperado (ecf-32.md).

Dónde verlo, por endpoint:

POST /api/v1/documents/{tipo} (el 202) y el reenvío de un folio que ya existe traen el track_id del documento: null hasta transmitir y el valor asignado después (en el resumen del 32 por debajo de RD$250.000, siempre null).
GET /api/v1/documents/{identificador} (el detalle) y cada elemento de GET /api/v1/documents (el listado) traen el track_id del documento en su estado actual: null antes de transmitir, relleno desde in_process_dgii y conservado en los estados finales.
GET /api/v1/documents/{identificador}/track-ids trae nuestro_track_id (el que tenemos registrado) y envios[].track_id (cada envío que la DGII registró para ese e-NCF) (consultas-dgii.md).

Para un resumen, in_process_dgii o not_found_dgii sin track_id es posible pero excepcional: sólo si la DGII no resolviera el resumen en su respuesta; en ese caso lo seguimos consultando nosotros por e-NCF (no hay TrackID por el que preguntar) hasta que resuelva, igual que en los demás tipos. En cualquier caso, su forma de seguir un documento es la misma: GET /api/v1/documents/{identificador} hasta un estado final (README).

Cómo tratar cada estado en su integración¶

Si recibe	Qué debe hacer
`received` (1)	Guarde el `identificador` (y el `document_id`). No hace falta reenviar: si duda de que llegó, reenvíe el mismo folio y se le responde con el documento que ya existe. Consulte el estado más tarde.
`rejected_validation` (2)	Corrija el JSON según `errors` y reenvíe. Si es un `422` no se creó nada: reenvíe con el mismo e-NCF. Si el documento ya existía y se detuvo dentro de la cola (p. ej. una nota de crédito que cruzó los 30 días), ese folio queda ocupado: use otro, y anule el que no usó.
`in_process_dgii` (3) / `not_found_dgii` (7)	Espere y vuelva a consultar. Son transitorios.
`accepted_dgii` (4) / `conditionally_accepted_dgii` (5)	El comprobante es válido: ya puede entregarlo. Con el detalle del documento recibe además su XML firmado y su PDF (`archivos`, en base64; el PDF llega unos segundos después de la aceptación). Con el 5, revise `errors` y corrija para el futuro.
`rejected_dgii` (6)	El comprobante es nulo. Revise `errors` y emita el corregido con otro folio (un folio tiene un solo documento, así que no se reenvía el rechazado). Si `sequence_reusable` es `true`, la DGII da esa secuencia por no utilizada: puede anularla.
`unresolved` (8)	Contáctenos: requiere revisión manual.
`system_error` (9)	Nada: se reintenta automáticamente. Si persiste, contáctenos.

Relación con los códigos de la DGII¶

La DGII devuelve su propio código en la consulta de resultado. Nosotros lo traducimos:

Código DGII	Estado DGII	Nuestro estado
0	No encontrado	7 `not_found_dgii`
1	Aceptado	4 `accepted_dgii`
2	Rechazado	6 `rejected_dgii`
3	En Proceso	3 `in_process_dgii`
4	Aceptado Condicional	5 `conditionally_accepted_dgii`

Los estados 1, 2, 8 y 9 son nuestros: describen etapas que la DGII no conoce (recepción en la API, rechazo por nuestras validaciones, agotamiento de consultas y fallos internos).