--- title: "Credit notes API" description: "v1 endpoints for issuing credit notes (E34): cancel or correct a document after the fiscal period has closed." canonical: https://factura.com.do/en/desarrolladores/notas-credito lang: en generator: factura.com.do docs-index --- Resource · E34 # Credit notes API The `/credit-notes` resource issues credit notes (E34) linked to an original document (E31 or E32). The DGII recognises the note as the official reversal of the transaction and deducts the associated ITBIS. ## Overview A credit note is issued after the fiscal period has closed or when you need explicit traceability for a return, a subsequent discount, or a cancellation. If you are still within the issuance flow and just want to discard the document, use `POST /api/v1/consumer-invoices/{id}/void` or its E31 equivalent. The note is the right tool once the transaction has been reported. ## Available operations - [ GET /api/v1/credit-notes ](#credit-notes-list)— Devuelve un PagedResult con las notas de crédito y de débito del espacio de trabajo; esta ruta no filtra por tipo de e-CF. - [ GET /api/v1/credit-notes/{id} ](#credit-notes-get)— Devuelve el detalle completo de una nota de crédito (E34). - [ POST /api/v1/credit-notes ](#credit-notes-create)— Emite una nota de crédito (E34) referenciando un comprobante original. [ GET /api/v1/credit-notes X-Api-Key Stable Devuelve un PagedResult con las notas de crédito y de débito 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 receptor o por el e-CF original referenciado. | [ GET /api/v1/credit-notes/{id} X-Api-Key Stable Devuelve el detalle completo de una nota de crédito (E34). ](#) | Name | Type | Description | | ------- | ---------------------- | ------------------------- | | id path | string (uuid) Required | Identificador de la nota. | [ POST /api/v1/credit-notes X-Api-Key Stable Emite una nota de crédito (E34) referenciando un comprobante original. ](#) | Name | Type | Description | | ----------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | branchId body | string (uuid) Required | Identificador de la sucursal emisora dentro del espacio de trabajo. | | sequence body | string Optional | Se ignora. La nota siempre toma el siguiente NCF de la secuencia E34 activa. Si no hay una secuencia E34 activa, la API 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 de la nota. | | 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. | | customerId body | string (uuid) Optional | Receptor de la nota. Obligatorio si el comprobante original era E31. | | currencyId body | integer Required | Identificador de la moneda de la nota. | | 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 la nota. | | referenceCreatedAt body | string (ISO 8601) Required | Fecha de emisión del comprobante original (E31 o E32) que la nota corrige. | | referenceSequence body | string Required | NCF del comprobante original que la nota corrige. Si no existe un documento con esa secuencia, la API responde \`404\` con \`{ message }\`. | | modificationCode body | integer Required | Código DGII del motivo. \`1\` anula el comprobante original, \`2\` corrige texto y \`3\` corrige montos. | | lines body | V1LineDto\[\] Required | Líneas a corregir o anular. Pueden ser totales (anulación) o parciales (devolución). | | payments body | V1PaymentDto\[\] Optional | Pagos asociados a la nota. Suele ir vacío en notas de crédito. | ## Example: issue a credit note A partial return references the original document by its NCF (`referenceSequence`) and its issue date (`referenceCreatedAt`), plus a `modificationCode` that indicates the reason per DGII rules: `1` cancels the original document, `2` corrects text and `3` corrects amounts (the partial-return case). The lines describe what is being returned, with their associated taxes. The `sequence` field is ignored: the note always takes the next NCF from the active sequence. If no document exists with that `referenceSequence`, the API responds `404` with `{ message }`. Note that `/credit-notes` and `/debit-notes` list the same mix of credit and debit notes. POST /api/v1/credit-notes cURL TypeScript credit-note.sh ``` curl -X POST https://tuempresa.factura.com.do/api/v1/credit-notes \ -H "X-Api-Key: $FACTURA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "branchId": "b1a2c3d4-e5f6-4789-abcd-1234567890ab", "issuedAt": "2026-05-08T10:00:00Z", "paymentTermId": 1, "limitDate": "2026-05-08T10:00:00Z", "customerId": "5f0c3a8e-2b7d-4c1e-9a6f-3d8b2e1c7a40", "currencyId": 1, "currencyRate": 1, "referenceCreatedAt": "2026-04-30T10:00:00Z", "referenceSequence": "E320000000123", "modificationCode": 3, "lines": [ { "code": "PROD-21", "order": 1, "description": "Devolución parcial mercancía dañada", "isService": false, "quantity": 2, "unitId": 1, "unitPrice": 2500.00, "taxes": [{ "taxId": "3a5e98e0-33ff-44be-bd37-e3f9b35a25e2", "rate": 18.0, "taxTypeId": 1 }] } ], "payments": [] }' ``` credit-note.ts ``` const res = await fetch( "https://tuempresa.factura.com.do/api/v1/credit-notes", { method: "POST", headers: { "X-Api-Key": process.env.FACTURA_API_KEY!, "Content-Type": "application/json", }, body: JSON.stringify({ branchId, issuedAt: new Date().toISOString(), paymentTermId: 1, limitDate: new Date().toISOString(), customerId, currencyId: 1, currencyRate: 1, referenceCreatedAt: originalIssuedAt, referenceSequence: originalSequence, modificationCode: 3, lines, payments: [], }), }, ); if (!res.ok) throw new Error(`factura.com.do: ${res.status}`); const { documentId, consultationUrl } = await res.json(); ``` Response response.json ``` { "documentId": "4a7d1ed4-14f0-4c2b-9e8a-3f5b6c7d8e90", "consultationUrl": "https://ecf.dgii.gov.do/ecf/ConsultaTimbre?RNCEmisor=131000001&ENCF=E340000000001&…" } ``` ### Example: 400 when the proposed amount exceeds the original invoice When `modificationCode` is "Corrige Monto", the handler compares the note total against the original invoice total. If it exceeds it, the response body below is returned (amounts formatted using the server's culture). 400-monto-excede-original.json ``` { "success": false, "message": "El monto de la nota de crédito ($3,000.00) no puede exceder el total de la factura original ($2,500.00)." } ``` ## Full cancellation vs. partial correction The request body is identical for both cases. The difference is in the lines: - **Full cancellation**: replicate all lines from the original document with the same quantities. The DGII cancels the full fiscal effect. - **Partial return**: include only the affected lines with the quantity or amount to reverse. The original document retains the unreturned balance. V1 does not expose void for credit notes The `V1CreditNoteSlice` publishes only `list`, `get` and `create`; it does not expose `POST .../void`. If you issue a credit note by mistake, the V1 correction is to issue a debit note (E33) that reverses the effect. The `nota_credito.anulated` event exists in the webhooks catalog because the domain does allow cancellation via non-public internal endpoints; your integration must not rely on that in V1. ## Next steps Next step ## Continue here - [ Debit notes E33 document to increase the amount of a previous document. ](/en/desarrolladores/notas-debito) - [ Invoices Create the E31 or E32 document that this note corrects. ](/en/desarrolladores/facturas) - [ Webhooks Subscribe to dgii.aprobado to track the final status of the note. ](/en/desarrolladores/webhooks)