--- title: "Purchases API" description: "v1 endpoints for recording purchase documents (E41) issued to informal suppliers not registered with the DGII." canonical: https://factura.com.do/en/desarrolladores/compras lang: en generator: factura.com.do docs-index --- Resource · E41 # Purchases API The `/purchase-invoices` resource issues E41 documents for informal suppliers (not registered with the DGII). The API requires the supplier to exist and be active in your catalog; the document is recorded as E41 in your purchase reports. E41 covers purchases from informal suppliers: you issue the e-CF on behalf of the supplier because the supplier is not a registered DGII taxpayer and cannot issue E31\. If the supplier is registered, use the E31 they issue themselves. The body reuses the same line, tax and withholding shape as sales invoices. ## Overview Before saving, the API validates that `supplierId` references an active supplier in your catalog and that the supplier is not marked as registered with the DGII (`isRegisteredInDGII = false`). If the sum of payments does not match the document total, the API also responds `400`. ## Available operations - [ 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 Stable Devuelve un PagedResult con los gastos, compras y pagos al exterior del espacio de trabajo; esta ruta no filtra por tipo de e-CF. ](#) | Name | Type | Description | | ---------------- | ---------------- | -------------------------------------------------------------- | | pageNumber query | integer Optional | Página solicitada. Por defecto 1. | | pageSize query | integer Optional | Tamaño de página. Por defecto 10\. La API no impone un máximo. | | search query | string Optional | Filtra por número, RNC del proveedor o nombre. | [ GET /api/v1/purchase-invoices/{id} X-Api-Key Stable Devuelve el detalle completo de un comprobante de compra (E41). ](#) | Name | Type | Description | | ------- | ---------------------- | ------------------------------ | | id path | string (uuid) Required | Identificador del comprobante. | [ POST /api/v1/purchase-invoices X-Api-Key Stable Registra un comprobante de compra (E41) emitido al espacio de trabajo por un proveedor. ](#) | Name | Type | Description | | ----------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | branchId body | string (uuid) Required | Sucursal receptora dentro del espacio de trabajo. | | sequence body | string Optional | 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 Optional | Referencia externa libre del emisor (orden, ticket, ID en tu sistema). | | issuedAt body | string (ISO 8601) Required | Fecha de emisión del comprobante. | | paymentTermId body | integer Required | Identificador del término de pago aplicable. | | limitDate body | string (ISO 8601) Required | Fecha límite asociada al término de pago. | | supplierId body | string (uuid) Optional | 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 Required | Identificador de la moneda del comprobante. | | currencyRate body | decimal Required | Tasa de cambio aplicada (1 cuando la moneda coincide con DOP). | | freight body | decimal Optional | Monto del flete o transporte cuando aplica. | | notes body | string Optional | Notas libres impresas en el comprobante. | | tipoBienServicioComprado body | integer Required | 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\[\] Required | Líneas con producto, cantidad, precio, ITBIS y retenciones aplicables. | | payments body | V1PaymentDto\[\] Optional | 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 Stable Anula el comprobante; si la DGII ya lo aceptó, emite una nota de crédito (E34) y devuelve su creditNoteId. ](#) | Name | Type | Description | | ------- | ---------------------- | ---------------------------------------- | | id path | string (uuid) Required | Identificador del comprobante de compra. | [ POST /api/v1/purchase-invoices/{id}/edit-amount X-Api-Key Stable 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. ](#) | Name | Type | Description | | --------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | id path | string (uuid) Required | Identificador del comprobante. | | lines body | V1EditAmountLineDto\[\] Required | 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 Required | Posición de la línea en el comprobante original (1 para la primera, 2 para la segunda…). | | lines\[\].quantity body | decimal Optional | Nueva cantidad. Solo se aplica si se envía. | | lines\[\].unitPrice body | decimal Optional | Nuevo precio unitario. Solo se aplica si se envía. | | lines\[\].discount body | decimal Optional | Nuevo descuento aplicable a la línea. | | lines\[\].recharge body | decimal Optional | Nuevo recargo aplicable a la línea. | | lines\[\].taxes body | V1TaxDto\[\] Optional | Nueva lista de impuestos aplicables a la línea. | | lines\[\].withholdings body | V1WithholdingDto\[\] Optional | Nueva lista de retenciones aplicables a la línea. | [ POST /api/v1/purchase-invoices/{id}/edit-text X-Api-Key Stable 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. ](#) | Name | Type | Description | | -------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- | | id path | string (uuid) Required | Identificador del comprobante. | | lines body | V1EditTextLineDto\[\] Required | 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 Required | Posición de la línea en el comprobante original (1 para la primera, 2 para la segunda…). | | lines\[\].description body | string Required | Nueva descripción a imprimir en la línea. | ## Example: record a purchase document The body includes `supplierId` (reference to the contacts catalog), `tipoBienServicioComprado` (606 classification, 1 to 11), `sequence` (optional: if omitted, the next E41 NCF from the active sequence is used) and the lines with their taxes and withholdings. Always send `tipoBienServicioComprado`: the API does not validate it and, if missing, silently stores 0 and the 606 comes out wrong. Also note that the `/purchase-invoices` list returns expenses, purchases and foreign payments mixed, and that `edit-amount` and `edit-text` issue a new debit note (E33) instead of editing the purchase. The immediate response is the same as the rest of the resource: `documentId` and `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(); ``` Response response.json ``` { "documentId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "consultationUrl": "https://ecf.dgii.gov.do/ecf/ConsultaTimbre?RNCEmisor=131000001&ENCF=E410000000001&…" } ``` ### Example: 400 when the supplier is registered with the DGII 400-proveedor-registrado.json ``` { "success": false, "message": "No se puede crear un Comprobante de Compras (E41) para un proveedor registrado en la DGII." } ``` ## Supplier validation E41 is reserved for informal suppliers. Before accepting the POST the API checks two conditions against the workspace catalog: the supplier must be active and must not be marked as registered with the DGII. If either fails, it responds `400` with `{ success: false, message }`. If the supplier issues e-CF, receive the E31 instead When the supplier is registered with the DGII, the correct flow is for them to issue you an E31 and for you to record it. Use [RNC validation](/en/desarrolladores/catalogo) before registering new suppliers to decide whether the contact should be informal (E41) or a formal taxpayer (incoming E31). ## Next steps Next step ## Continue here - [ Minor expenses E43 document for disbursements without a formal supplier invoice. ](/en/desarrolladores/gastos) - [ Contacts Create or update suppliers before recording purchases. ](/en/desarrolladores/contactos) - [ Catalog RNC validation, taxes and available withholdings. ](/en/desarrolladores/catalogo)