Ciclo de vida de un e-CF
Cuando llamas POST /api/v1/<recurso>, factura.com.do orquesta firma, envío y consulta de acuse contra la DGII. Esta página documenta el flujo conceptual; los endpoints internos del flujo no son superficie pública.
Resumen
El POST nunca espera al acuse de la DGII. Tu integración recibe la confirmación inmediata y el estado final llega después por webhook. Esa decisión protege tu latencia: la DGII puede tardar segundos o minutos según carga, y tu UI nunca queda esperando.
Cinco pasos del ciclo
- 01
Validación del request
Tipos, vigencias, permisos del tenant. Si algo está mal, factura.com.do responde 400 antes de tocar la DGII.
- 02
Construcción y firma del XML
Selección del converter por tipo e-CF (E31, E32 RFCE, E44…) y firma con el certificado digital del tenant.
- 03
Envío al servicio DGII
DGIIEcfService o DGIIRFCEService según el tipo. La DGII responde con un trackId y un status code (5/6/7/8).
- 04
Persistencia y respuesta inmediata
Documento + estado + traza quedan persistidos. Tu llamada original recibe { documentId, consultationUrl } sin esperar al acuse final.
- 05
Polling en background
DGIIStatusCheckBackgroundService refresca los estados de los documentos en proceso. Cuando hay cambio, factura.com.do dispara el webhook correspondiente.
Tipos de e-CF y recursos
Los diez tipos de e-CF que la DGII reconoce hoy se mapean a los recursos públicos de la API. Los slices internos cambian el converter al firmar, pero el contrato público es uniforme.
| Tipo | Nombre | Recurso V1 |
|---|---|---|
E31 | Crédito fiscal | /desarrolladores/facturas |
E32 | Consumo | /desarrolladores/facturas |
E33 | Nota de débito | /desarrolladores/notas-debito |
E34 | Nota de crédito | /desarrolladores/notas-credito |
E41 | Compras | /desarrolladores/compras |
E43 | Gastos menores | /desarrolladores/gastos |
E44 | Régimen especial | /desarrolladores/facturas#regimen-especial |
E45 | Gubernamental | /desarrolladores/facturas#gubernamental |
E46 | Exportación | /desarrolladores/facturas#exportacion |
E47 | Pago al exterior | /desarrolladores/facturas#pago-exterior |
Estados DGII
El status code DGII viaja en el campo data.StatusId del webhook y se mapea uno a uno con el evento dgii.*.
| Status | Evento webhook | Significado |
|---|---|---|
5 | dgii.aprobado | Documento aceptado en firme |
6 | dgii.rechazado | Documento rechazado; reconcilia con un GET al recurso para leer el motivo persistido |
7 | dgii.en_proceso | DGII evaluando; el polling sigue |
8 | dgii.aceptado_condicional | Aceptado con observaciones; registrar en bitácora |
Certificación y firma
Estas rutas acompañan el proceso de certificación como emisor electrónico. certifications guarda los datos del titular y la contraseña del certificado digital; certification/run-all genera, firma y envía a la DGII los comprobantes de prueba y responde un archivo .zip (con errores.txt si alguno falló), y sign-xml firma un XML propio con el certificado del espacio de trabajo. Las dos últimas responden 400 con { message } si no hay un certificado digital configurado. Todas exigen el plan Corporativo.
/api/v1/certifications X-Api-Key Estable Devuelve un PagedResult con los registros de certificación: titular, identificación, país, contacto y si ya tiene guardada la contraseña del certificado.
| Nombre | Tipo | Descripción |
|---|---|---|
search query | string Opcional | Término de búsqueda. |
pageNumber query | integer Opcional | Página solicitada. Por defecto 1. |
pageSize query | integer Opcional | Tamaño de página. Por defecto 10. |
isActive query | boolean Opcional | Filtra por registros activos o inactivos. |
/api/v1/certifications/{id} X-Api-Key Estable Devuelve un registro de certificación por su id.
| Nombre | Tipo | Descripción |
|---|---|---|
id path | string (uuid) Requerido | Identificador del registro de certificación. |
/api/v1/certifications X-Api-Key Estable Crea un registro de certificación con los datos del titular. Responde { certificationId, success, message }.
| Nombre | Tipo | Descripción |
|---|---|---|
name body | string Requerido | Nombre del titular. |
lastName body | string Requerido | Apellido del titular. |
identificationType body | integer Requerido | Tipo de identificación del titular. |
countryId body | integer Requerido | País del titular (ver `GET /api/v1/countries-lookup`). |
email body | string Requerido | Correo del titular. |
phone body | string Requerido | Teléfono del titular. |
/api/v1/certifications/{id} X-Api-Key Estable Reemplaza los datos del titular de un registro de certificación. Usa el mismo cuerpo que la creación.
| Nombre | Tipo | Descripción |
|---|---|---|
id path | string (uuid) Requerido | Identificador del registro de certificación. |
/api/v1/certifications/{id}/certificate-password X-Api-Key Estable Guarda la contraseña del certificado digital en un registro de certificación. Responde { certificationId, success, message }.
| Nombre | Tipo | Descripción |
|---|---|---|
id path | string (uuid) Requerido | Identificador del registro de certificación. |
certificatePassword body | string Opcional | Contraseña del certificado digital. |
/api/v1/certification/run-all X-Api-Key Estable Genera, firma y envía a la DGII los comprobantes de prueba de la certificación y responde un .zip con los PDF, el XML firmado del E32 y errores.txt si algo falló.
/api/v1/sign-xml X-Api-Key Estable Firma un XML con el certificado digital del espacio de trabajo y responde { signedXml, signedXmlBase64 }.
| Nombre | Tipo | Descripción |
|---|---|---|
xml body | string Opcional | XML a firmar, como texto. Envía este campo o `xmlBase64`. |
xmlBase64 body | string Opcional | XML a firmar, codificado en base64. Si envías los dos, se usa este. |