API de compras

El recurso /purchase-invoices emite comprobantes E41 para proveedores informales (no registrados en la DGII). La API exige que el proveedor exista activo en tu catálogo y queda registrado como E41 en tus reportes de compras.

El E41 cubre compras a proveedores informales: tú emites el e-CF a nombre del proveedor porque el proveedor no es contribuyente registrado en la DGII y no puede emitir E31. Si el proveedor figura registrado, usa el E31 que él mismo emite. El cuerpo reusa la misma forma de líneas, impuestos y retenciones que las facturas de venta.

Resumen

Antes de guardar, la API valida que supplierId referencie a un proveedor activo en tu catálogo y que ese proveedor no esté marcado como registrado en la DGII (isRegisteredInDGII = false). Si la suma de pagos no coincide con el total del documento, la API también responde 400.

Operaciones disponibles

• GET /api/v1/purchase-invoices — 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/purchase-invoices/{id} — Devuelve el detalle completo de un comprobante de compra (E41).
• POST /api/v1/purchase-invoices — Registra un comprobante de compra (E41) emitido al espacio de trabajo por un proveedor.
• POST /api/v1/purchase-invoices/{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/purchase-invoices/{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/purchase-invoices/{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.

Ejemplo: registrar comprobante de compra

El cuerpo incluye supplierId (referencia al catálogo de contactos), tipoBienServicioComprado (clasificación del 606, de 1 a 11), sequence (opcional: si lo omites, se usa el siguiente NCF E41 de la secuencia activa) y las líneas con sus impuestos y retenciones. Envía siempre tipoBienServicioComprado: la API no lo valida y, si falta, guarda 0 sin avisar y el 606 sale mal. Ten en cuenta también que el listado de /purchase-invoices devuelve gastos, compras y pagos al exterior mezclados, y que edit-amount y edit-text emiten una nota de débito (E33) nueva en lugar de editar la compra. La respuesta inmediata es la misma que el resto del recurso: documentId y consultationUrl.

curl -X POST https://tuempresa.factura.com.do/api/v1/purchase-invoices \
  -H "X-Api-Key: $FACTURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "b1a2c3d4-e5f6-4789-abcd-1234567890ab",
    "sequence": "E410000000001",
    "issuedAt": "2026-05-08T10:00:00Z",
    "paymentTermId": 1,
    "limitDate": "2026-05-08T10:00:00Z",
    "supplierId": "8c2e4f1a-6d3b-4a9e-b7c5-1f0d2e3a4b6c",
    "tipoBienServicioComprado": 2,
    "currencyId": 1,
    "currencyRate": 1,
    "lines": [
      {
        "code": "INSUMO-21",
        "order": 1,
        "description": "Insumos de oficina",
        "isService": false,
        "quantity": 5,
        "unitId": 1,
        "unitPrice": 1200.00,
        "taxes": [{ "taxId": "3a5e98e0-33ff-44be-bd37-e3f9b35a25e2", "rate": 18.0, "taxTypeId": 1 }],
        "withholdings": [{ "withholdingId": "0b6d81a6-083c-449e-8791-770ff5b3379d", "rate": 5.0 }]
      }
    ],
    "payments": [
      { "reference": "TR-2026-05-001", "amount": 6720.00 }
    ]
  }'

const res = await fetch(
  "https://tuempresa.factura.com.do/api/v1/purchase-invoices",
  {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.FACTURA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      branchId,
      sequence: "E410000000001",
      issuedAt: new Date().toISOString(),
      paymentTermId: 1,
      limitDate: new Date().toISOString(),
      supplierId,
      tipoBienServicioComprado: 2, // clasificación 606 (1 a 11); si falta, se guarda 0
      currencyId: 1,
      currencyRate: 1,
      lines,
      payments,
    }),
  },
);
if (!res.ok) throw new Error(`factura.com.do: ${res.status}`);
const { documentId, consultationUrl } = await res.json();

{
  "documentId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
  "consultationUrl": "https://ecf.dgii.gov.do/ecf/ConsultaTimbre?RNCEmisor=131000001&ENCF=E410000000001&…"
}

Ejemplo: 400 cuando el proveedor está registrado en la DGII

{
  "success": false,
  "message": "No se puede crear un Comprobante de Compras (E41) para un proveedor registrado en la DGII."
}

Validación del proveedor

El E41 se reserva para proveedores informales. Antes de aceptar el POST la API revisa dos condiciones contra el catálogo del espacio de trabajo: el proveedor debe estar activo y no debe estar marcado como registrado en la DGII. Si fallan, responde 400 con { success: false, message }.

Siguientes pasos