Emitir comprobantes
Cómo enviar un e-CF, seguir su estado y descargar el XML y el PDF.
Emitir un comprobante
Todos los tipos de e-CF se emiten con la misma operación: POST /v1/documents. Requiere el permiso documents:write y el encabezado Idempotency-Key.
Campos principales
| Campo | Obligatorio | Descripción |
|---|---|---|
company_id | Sí | Empresa emisora (cmp_…). |
type | Sí | Tipo de e-CF: 31, 32, 33, 34, 41, 43, 44, 45, 46 o 47. |
issue_date | Sí | Fecha de emisión en formato AAAA-MM-DD. |
income_type | Sí | Tipo de ingreso según la codificación de la DGII, por ejemplo "01". |
payment | Sí | Condición de pago y, opcionalmente, el detalle de las formas de pago. |
buyer | Sí | Datos del comprador: RNC o cédula, nombre y, si aplica, correo. |
items | Sí | Líneas del comprobante: descripción, cantidad, precio unitario e impuestos. |
currency | No | Moneda. Por defecto, pesos dominicanos (DOP). |
encf | No | e-NCF específico. Si lo omites, la API asigna el siguiente disponible (recomendado). |
references | Según tipo | Comprobante que se modifica. Obligatorio en notas de crédito y débito. |
external_reference | No | Tu identificador interno, para conciliar con tu sistema. |
metadata | No | Datos libres que quieras conservar junto al comprobante. |
La lista completa de campos está en la referencia.
Importes como texto. Envía cantidades y precios como cadenas ("1000.0000"), no como números. Así se conserva la precisión decimal que exige el cálculo fiscal.
Ciclo de vida y estados
La respuesta inicial siempre es queued. Después el comprobante avanza hasta un estado terminal:
| Estado | Significado | Terminal |
|---|---|---|
queued | Recibido y en cola de procesamiento. | No |
accepted | Aceptado por la DGII. | Sí |
accepted_conditional | Aceptado con observaciones. | Sí |
rejected | Rechazado por la DGII. Revisa dgii_code. | Sí |
invalid | No superó la validación previa; no se envió a la DGII. | Sí |
contingency_offline | Sin conexión con la DGII; se reenviará automáticamente. | No |
Consultar el estado
{
"id": "doc_01hf…",
"status": "accepted",
"fiscal_status": "accepted",
"dgii_code": null,
"sequence_reusable": false
}
sequence_reusable indica si el e-NCF puede volver a usarse porque el comprobante no llegó a tener efecto fiscal.
XML firmado y representación impresa
GET /v1/documents/{id}/xmldevuelve el XML firmado.GET /v1/documents/{id}/pdf?format=a4devuelve la representación impresa en hoja completa.GET /v1/documents/{id}/pdf?format=posdevuelve el formato de ticket de 80 mm.
Ambos formatos incluyen el código QR de consulta. La API verifica la integridad de cada artefacto antes de entregarlo.
Historial de eventos
GET /v1/documents/{id}/events devuelve, en orden cronológico, todo lo que ocurrió con el comprobante: recepción, validación, firma, envío y respuesta. Es la mejor fuente para diagnosticar un caso concreto.
Notas de crédito y débito
Se emiten igual que una factura, con type 34 o 33, e indicando en references el comprobante que modifican. La API rechaza la solicitud con 422 si faltan las referencias exigidas para ese tipo.
Comprobantes recibidos
Cuando otra empresa te envía un e-CF, puedes registrar tu respuesta comercial:
{
"decision": "approved",
"reason": null
}
decision admite approved o rejected. Requiere el permiso received:write.
¿Algo no está claro o falta en esta página? Escríbenos por el centro de soporte.