DEVSDESIGN — DEVELOPERS & DESIGN

API v1 · contrato 1.0.0

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

CampoObligatorioDescripción
company_idSíEmpresa emisora (cmp_…).
typeSíTipo de e-CF: 31, 32, 33, 34, 41, 43, 44, 45, 46 o 47.
issue_dateSíFecha de emisión en formato AAAA-MM-DD.
income_typeSíTipo de ingreso según la codificación de la DGII, por ejemplo "01".
paymentSíCondición de pago y, opcionalmente, el detalle de las formas de pago.
buyerSíDatos del comprador: RNC o cédula, nombre y, si aplica, correo.
itemsSíLíneas del comprobante: descripción, cantidad, precio unitario e impuestos.
currencyNoMoneda. Por defecto, pesos dominicanos (DOP).
encfNoe-NCF específico. Si lo omites, la API asigna el siguiente disponible (recomendado).
referencesSegún tipoComprobante que se modifica. Obligatorio en notas de crédito y débito.
external_referenceNoTu identificador interno, para conciliar con tu sistema.
metadataNoDatos 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:

EstadoSignificadoTerminal
queuedRecibido y en cola de procesamiento.No
acceptedAceptado por la DGII.Sí
accepted_conditionalAceptado con observaciones.Sí
rejectedRechazado por la DGII. Revisa dgii_code.Sí
invalidNo superó la validación previa; no se envió a la DGII.Sí
contingency_offlineSin conexión con la DGII; se reenviará automáticamente.No

Consultar el estado

GET /v1/documents/{id}/status
{
  "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}/xml devuelve el XML firmado.
  • GET /v1/documents/{id}/pdf?format=a4 devuelve la representación impresa en hoja completa.
  • GET /v1/documents/{id}/pdf?format=pos devuelve 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:

POST /v1/received-documents/{id}/commercial-response
{
  "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.