--- title: "API de compras" description: "Endpoints v1 para registrar comprobantes de compra (E41) emitidos a proveedores informales no registrados en la DGII." canonical: https://factura.com.do/desarrolladores/compras lang: es generator: factura.com.do docs-index --- Recurso · E41 # 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 ](#purchase-invoices-list)— 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} ](#purchase-invoices-get)— Devuelve el detalle completo de un comprobante de compra (E41). - [ POST /api/v1/purchase-invoices ](#purchase-invoices-create)— Registra un comprobante de compra (E41) emitido al espacio de trabajo por un proveedor. - [ POST /api/v1/purchase-invoices/{id}/void ](#purchase-invoices-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 ](#purchase-invoices-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 ](#purchase-invoices-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. [ GET /api/v1/purchase-invoices X-Api-Key Estable Devuelve un PagedResult con los gastos, compras y pagos al exterior del espacio de trabajo; esta ruta no filtra por tipo de e-CF. ](#) | Nombre | Tipo | Descripción | | ---------------- | ---------------- | -------------------------------------------------------------- | | pageNumber query | integer Opcional | Página solicitada. Por defecto 1. | | pageSize query | integer Opcional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | | search query | string Opcional | Filtra por número, RNC del proveedor o nombre. | [ GET /api/v1/purchase-invoices/{id} X-Api-Key Estable Devuelve el detalle completo de un comprobante de compra (E41). ](#) | Nombre | Tipo | Descripción | | ------- | ----------------------- | ------------------------------ | | id path | string (uuid) Requerido | Identificador del comprobante. | [ POST /api/v1/purchase-invoices X-Api-Key Estable Registra un comprobante de compra (E41) emitido al espacio de trabajo por un proveedor. ](#) | Nombre | Tipo | Descripción | | ----------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | branchId body | string (uuid) Requerido | Sucursal receptora dentro del espacio de trabajo. | | sequence body | string Opcional | Opcional. NCF E41 a usar (formato \`E410000000000\`). Si lo omites, la API toma el siguiente de la secuencia activa; si no hay una secuencia E41 activa, responde \`500\`. | | externalReference body | string Opcional | Referencia externa libre del emisor (orden, ticket, ID en tu sistema). | | issuedAt body | string (ISO 8601) Requerido | Fecha de emisión del comprobante. | | paymentTermId body | integer Requerido | Identificador del término de pago aplicable. | | limitDate body | string (ISO 8601) Requerido | Fecha límite asociada al término de pago. | | supplierId body | string (uuid) Opcional | Proveedor activo en el catálogo del espacio de trabajo y no registrado en la DGII (los registrados deben emitir E31). Opcional sólo si la integración no exige proveedor identificable. | | currencyId body | integer Requerido | Identificador de la moneda del comprobante. | | currencyRate body | decimal Requerido | Tasa de cambio aplicada (1 cuando la moneda coincide con DOP). | | freight body | decimal Opcional | Monto del flete o transporte cuando aplica. | | notes body | string Opcional | Notas libres impresas en el comprobante. | | tipoBienServicioComprado body | integer Requerido | Tipo de bienes y servicios comprados según la clasificación del formato 606 de la DGII (1 a 11). Envíalo siempre, porque la API no lo valida; si lo omites, guarda 0 sin avisar y el 606 sale con ese egreso mal clasificado. | | lines body | V1LineDto\[\] Requerido | Líneas con producto, cantidad, precio, ITBIS y retenciones aplicables. | | payments body | V1PaymentDto\[\] Opcional | Opcional. Pagos asociados al comprobante; cada elemento lleva referencia y monto. Si lo omites, no se registra ningún pago. | [ POST /api/v1/purchase-invoices/{id}/void X-Api-Key Estable Anula el comprobante; si la DGII ya lo aceptó, emite una nota de crédito (E34) y devuelve su creditNoteId. ](#) | Nombre | Tipo | Descripción | | ------- | ----------------------- | ---------------------------------------- | | id path | string (uuid) Requerido | Identificador del comprobante de compra. | [ POST /api/v1/purchase-invoices/{id}/edit-amount X-Api-Key Estable 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. ](#) | Nombre | Tipo | Descripción | | --------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | id path | string (uuid) Requerido | Identificador del comprobante. | | lines body | V1EditAmountLineDto\[\] Requerido | Lista de líneas a editar. Cada elemento referencia el orden de la línea original y los campos que se desean sobreescribir. | | lines\[\].order body | integer Requerido | Posición de la línea en el comprobante original (1 para la primera, 2 para la segunda…). | | lines\[\].quantity body | decimal Opcional | Nueva cantidad. Solo se aplica si se envía. | | lines\[\].unitPrice body | decimal Opcional | Nuevo precio unitario. Solo se aplica si se envía. | | lines\[\].discount body | decimal Opcional | Nuevo descuento aplicable a la línea. | | lines\[\].recharge body | decimal Opcional | Nuevo recargo aplicable a la línea. | | lines\[\].taxes body | V1TaxDto\[\] Opcional | Nueva lista de impuestos aplicables a la línea. | | lines\[\].withholdings body | V1WithholdingDto\[\] Opcional | Nueva lista de retenciones aplicables a la línea. | [ POST /api/v1/purchase-invoices/{id}/edit-text X-Api-Key Estable 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. ](#) | Nombre | Tipo | Descripción | | -------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------- | | id path | string (uuid) Requerido | Identificador del comprobante. | | lines body | V1EditTextLineDto\[\] Requerido | Lista de líneas a editar. Cada elemento referencia el orden de la línea original y la nueva descripción. | | lines\[\].order body | integer Requerido | Posición de la línea en el comprobante original (1 para la primera, 2 para la segunda…). | | lines\[\].description body | string Requerido | Nueva descripción a imprimir en la línea. | ## 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`. POST /api/v1/purchase-invoices cURL TypeScript purchase-invoice.sh ``` 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 } ] }' ``` purchase-invoice.ts ``` 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(); ``` Respuesta response.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 400-proveedor-registrado.json ``` { "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 }`. Si el proveedor sí emite e-CF, recibe el E31 Cuando el proveedor está registrado en la DGII, el flujo correcto es que él te emita un E31 y tú lo registres. Usa [la validación de RNC](/desarrolladores/catalogo) antes de cargar proveedores nuevos para decidir si el contacto va como informal (E41) o como contribuyente formal (E31 entrante). ## Siguientes pasos Siguiente paso ## Continúa por aquí - [ Gastos menores Comprobante E43 para egresos sin factura formal del proveedor. ](/desarrolladores/gastos) - [ Contactos Crea o actualiza proveedores antes de registrar compras. ](/desarrolladores/contactos) - [ Catálogo Validación de RNC, impuestos y retenciones disponibles. ](/desarrolladores/catalogo)