API de facturas

Endpoints v1 para emitir facturas de crédito fiscal (E31), consumo (E32) y los cuatro casos especiales: regímenes especiales, gubernamental, exportación y pagos al exterior. El mismo flujo cubre el ciclo completo: validación, firma, envío DGII y respuesta.

Resumen

Las facturas E31, E32, E44, E45 y E46 comparten el mismo DTO (V1CreateInvoiceDto + V1LineDto + V1PaymentDto), las mismas operaciones (list, get, create, void, edit-amount, edit-text) y la misma respuesta de creación ({ documentId, consultationUrl }). El pago al exterior (E47) vive en esta página, pero su contrato es el de un gasto: usa supplierId y tipoBienServicioComprado. Dos avisos antes de empezar: las cinco rutas de listado de facturas devuelven la misma lista, con todos los tipos mezclados, y si omites payments al crear, la factura queda saldada con la forma de pago por defecto. En esta página se documenta el patrón con E32 como referencia.

Operaciones disponibles

Atajos a las operaciones documentadas con detalle abajo (E31, E32). Las operaciones de E44–E47 comparten la misma forma de cuerpo y aparecen agrupadas por familia en casos especiales.

• GET /api/v1/consumer-invoices — Devuelve un PagedResult con todas las facturas del espacio de trabajo; esta ruta no filtra por tipo de e-CF.
• GET /api/v1/consumer-invoices/{id} — Devuelve el detalle completo de una factura de consumo (E32) por id.
• POST /api/v1/consumer-invoices — Emite una factura de consumo (E32) con receptor opcional y líneas de detalle.
• POST /api/v1/consumer-invoices/{id}/void — Anula la factura; si la DGII ya la aceptó, emite una nota de crédito (E34) y devuelve su creditNoteId.
• POST /api/v1/consumer-invoices/{id}/edit-amount — Emite una nota de crédito (E34) que corrige los montos de la factura y devuelve el documentId de esa nota; el original no se modifica.
• POST /api/v1/consumer-invoices/{id}/edit-text — Emite una nota de crédito (E34) que corrige la descripción de las líneas de la factura y devuelve el documentId de esa nota; el original no se modifica.
• GET /api/v1/fiscal-credit-invoices — Devuelve un PagedResult con todas las facturas del espacio de trabajo; esta ruta no filtra por tipo de e-CF.
• GET /api/v1/fiscal-credit-invoices/{id} — Devuelve el detalle completo de una factura de crédito fiscal (E31).
• POST /api/v1/fiscal-credit-invoices — Emite una factura de crédito fiscal (E31) para un cliente activo de tu catálogo.
• POST /api/v1/fiscal-credit-invoices/{id}/void — Anula la factura; si la DGII ya la aceptó, emite una nota de crédito (E34) y devuelve su creditNoteId.
• POST /api/v1/fiscal-credit-invoices/{id}/edit-amount — Emite una nota de crédito (E34) que corrige los montos de la factura y devuelve el documentId de esa nota; el original no se modifica.
• POST /api/v1/fiscal-credit-invoices/{id}/edit-text — Emite una nota de crédito (E34) que corrige la descripción de las líneas de la factura y devuelve el documentId de esa nota; el original no se modifica.

Facturas de consumo (E32)

El recurso /consumer-invoices emite el comprobante E32. La factura se acepta inmediatamente si los datos pasan validación; el estado final viaja después por webhook.

Ejemplo: crear E32

curl -X POST https://tuempresa.factura.com.do/api/v1/consumer-invoices \
  -H "X-Api-Key: $FACTURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "b1a2c3d4-e5f6-4789-abcd-1234567890ab",
    "sequence": "E320000000001",
    "issuedAt": "2026-05-08T10:00:00Z",
    "paymentTermId": 1,
    "limitDate": "2026-05-08T10:00:00Z",
    "currencyId": 1,
    "currencyRate": 1,
    "lines": [
      {
        "code": "SRV-001",
        "order": 1,
        "description": "Consultoría",
        "isService": true,
        "quantity": 1,
        "unitId": 1,
        "unitPrice": 4500.00,
        "isExempt": false,
        "taxes": [{ "taxId": "3a5e98e0-33ff-44be-bd37-e3f9b35a25e2", "rate": 18.0, "taxTypeId": 1 }]
      }
    ],
    "payments": [
      { "reference": "REF-1", "amount": 5310.00 }
    ]
  }'

const res = await fetch(
  "https://tuempresa.factura.com.do/api/v1/consumer-invoices",
  {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.FACTURA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(invoice),
  },
);
if (!res.ok) throw new Error(`factura.com.do: ${res.status}`);
const { documentId, consultationUrl } = await res.json();

{
  "documentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "consultationUrl": "https://ecf.dgii.gov.do/ecf/ConsultaTimbre?RNCEmisor=131000001&ENCF=E310000000001&…"
}

Ejemplo: respuesta 200 con success: false al anular dos veces

El slice de void devuelve el resultado del handler tal cual: la respuesta llega con 200 OK aunque success sea false. Lee siempre el campo success antes de asumir que la operación tuvo efecto. Si la DGII ya había aceptado la factura, anular no la anula en el acto: emite una nota de crédito (E34) y devuelve su id en creditNoteId; la factura queda anulada cuando la DGII aprueba esa nota. Del mismo modo, edit-amount y edit-text no editan la factura: emiten una E34 nueva y devuelven el documentId de esa nota.

{
  "documentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "creditNoteId": null,
  "success": false,
  "message": "Error al anular factura: Invoice is already cancelled."
}

Crédito fiscal (E31)

El recurso /fiscal-credit-invoices emite el comprobante E31, requerido para receptores con RNC. El cuerpo es el mismo de E32 más customerId y withholdings opcionales por línea. Antes de aceptar el POST la API valida que el cliente referenciado esté activo en tu catálogo y que el cuerpo cumpla la regla específica del E31: al menos un impuesto por documento.

Ejemplo: crear E31 con retención

curl -X POST https://tuempresa.factura.com.do/api/v1/fiscal-credit-invoices \
  -H "X-Api-Key: $FACTURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "b1a2c3d4-e5f6-4789-abcd-1234567890ab",
    "sequence": "E310000000001",
    "customerId": "5f0c3a8e-2b7d-4c1e-9a6f-3d8b2e1c7a40",
    "issuedAt": "2026-05-08T10:00:00Z",
    "paymentTermId": 1,
    "limitDate": "2026-06-07T10:00:00Z",
    "currencyId": 1,
    "currencyRate": 1,
    "lines": [
      {
        "code": "PROD-21",
        "order": 1,
        "description": "Servicio profesional facturado a empresa",
        "isService": true,
        "quantity": 10,
        "unitId": 1,
        "unitPrice": 2500.00,
        "taxes": [{ "taxId": "3a5e98e0-33ff-44be-bd37-e3f9b35a25e2", "rate": 18.0, "taxTypeId": 1 }],
        "withholdings": [{ "withholdingId": "0b6d81a6-083c-449e-8791-770ff5b3379d", "rate": 10.0 }]
      }
    ],
    "payments": [
      { "reference": "TR-2026-05-001", "amount": 28750.00 }
    ]
  }'

{
  "documentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "consultationUrl": "https://ecf.dgii.gov.do/ecf/ConsultaTimbre?RNCEmisor=131000001&ENCF=E310000000001&…"
}

Casos especiales (E44–E47)

E44, E45 y E46 reusan el cuerpo y los verbos de E31/E32, sin campos adicionales: los slices solo cambian el tipo de comprobante. E47 tiene su propio contrato, descrito en su sección.

Regímenes especiales (E44)

Comprobante para receptores con regímenes tributarios especiales. Ruta canónica: POST /api/v1/special-regime-invoices. Usa el mismo V1CreateInvoiceDto de E32, sin campos adicionales.

• GET /api/v1/special-regime-invoices — Devuelve un PagedResult con todas las facturas del espacio de trabajo; esta ruta no filtra por tipo de e-CF.
• GET /api/v1/special-regime-invoices/{id} — Devuelve el detalle completo de una factura de régimen especial (E44) por id.
• POST /api/v1/special-regime-invoices — Emite una factura de régimen especial (E44) destinada a contribuyentes acogidos a regímenes especiales de la DGII.
• POST /api/v1/special-regime-invoices/{id}/void — Anula la factura; si la DGII ya la aceptó, emite una nota de crédito (E34) y devuelve su creditNoteId.
• POST /api/v1/special-regime-invoices/{id}/edit-amount — Emite una nota de crédito (E34) que corrige los montos de la factura y devuelve el documentId de esa nota; el original no se modifica.
• POST /api/v1/special-regime-invoices/{id}/edit-text — Emite una nota de crédito (E34) que corrige la descripción de las líneas de la factura y devuelve el documentId de esa nota; el original no se modifica.

Gubernamental (E45)

Para entidades gubernamentales receptoras. Ruta: POST /api/v1/government-invoices. Usa el mismo V1CreateInvoiceDto de E32, sin campos adicionales.

• GET /api/v1/government-invoices — Devuelve un PagedResult con todas las facturas del espacio de trabajo; esta ruta no filtra por tipo de e-CF.
• GET /api/v1/government-invoices/{id} — Devuelve el detalle completo de una factura gubernamental (E45) por id.
• POST /api/v1/government-invoices — Emite una factura gubernamental (E45) destinada a entidades del Estado dominicano.
• POST /api/v1/government-invoices/{id}/void — Anula la factura; si la DGII ya la aceptó, emite una nota de crédito (E34) y devuelve su creditNoteId.
• POST /api/v1/government-invoices/{id}/edit-amount — Emite una nota de crédito (E34) que corrige los montos de la factura y devuelve el documentId de esa nota; el original no se modifica.
• POST /api/v1/government-invoices/{id}/edit-text — Emite una nota de crédito (E34) que corrige la descripción de las líneas de la factura y devuelve el documentId de esa nota; el original no se modifica.

Exportación (E46)

Para exportaciones de bienes o servicios. Ruta: POST /api/v1/export-invoices. Usa el mismo V1CreateInvoiceDto de E32, sin campos adicionales.

• GET /api/v1/export-invoices — Devuelve un PagedResult con todas las facturas del espacio de trabajo; esta ruta no filtra por tipo de e-CF.
• GET /api/v1/export-invoices/{id} — Devuelve el detalle completo de una factura de exportación (E46) por id.
• POST /api/v1/export-invoices — Emite una factura de exportación (E46) destinada a receptores en el extranjero.
• POST /api/v1/export-invoices/{id}/void — Anula la factura; si la DGII ya la aceptó, emite una nota de crédito (E34) y devuelve su creditNoteId.
• POST /api/v1/export-invoices/{id}/edit-amount — Emite una nota de crédito (E34) que corrige los montos de la factura y devuelve el documentId de esa nota; el original no se modifica.
• POST /api/v1/export-invoices/{id}/edit-text — Emite una nota de crédito (E34) que corrige la descripción de las líneas de la factura y devuelve el documentId de esa nota; el original no se modifica.

Pagos al exterior (E47)

Para pagos a no domiciliados. Ruta: POST /api/v1/foreign-payments. No usa el contrato de E31/E32: el cuerpo es V1CreateForeignPaymentDto, con supplierId en lugar de customerId y el campo obligatorio tipoBienServicioComprado (clasificación del 606). Se comporta como un gasto: su listado devuelve gastos, compras y pagos al exterior mezclados, edit-amount y edit-text emiten una nota de débito (E33) y omitir payments no registra ningún pago.

• GET /api/v1/foreign-payments — Devuelve un PagedResult con los gastos, compras y pagos al exterior del espacio de trabajo; esta ruta no filtra por tipo de e-CF.
• GET /api/v1/foreign-payments/{id} — Devuelve el detalle completo de un pago al exterior (E47) por id.
• POST /api/v1/foreign-payments — Registra un pago al exterior (E47) realizado a un proveedor extranjero.
• POST /api/v1/foreign-payments/{id}/void — Anula el comprobante; si la DGII ya lo aceptó, emite una nota de crédito (E34) y devuelve su creditNoteId.
• POST /api/v1/foreign-payments/{id}/edit-amount — Emite una nota de débito (E33) que corrige los montos de el comprobante y devuelve el documentId de esa nota; el original no se modifica.
• POST /api/v1/foreign-payments/{id}/edit-text — Emite una nota de débito (E33) que corrige la descripción de las líneas de el comprobante y devuelve el documentId de esa nota; el original no se modifica.

Siguientes pasos