--- title: "API de notas de crédito" description: "Endpoints v1 para emitir notas de crédito (E34): anular o corregir un comprobante posterior al período fiscal." canonical: https://factura.com.do/desarrolladores/notas-credito lang: es generator: factura.com.do docs-index --- Recurso · E34 # API de notas de crédito El recurso `/credit-notes` emite notas de crédito (E34) que enlazan con un comprobante original (E31 o E32). La DGII reconoce la nota como reverso oficial de la operación y deduce el ITBIS asociado. ## Resumen Una nota de crédito se emite cuando ya cerraste el período fiscal o cuando necesitas dejar trazabilidad explícita de una devolución, descuento posterior o anulación. Si todavía estás dentro del flujo de emisión y solo quieres descartar el comprobante, usa `POST /api/v1/consumer-invoices/{id}/void` o el equivalente de E31\. La nota es la herramienta correcta cuando la operación ya se reportó. ## Operaciones disponibles - [ 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 Estable 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. ](#) | 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 receptor o por el e-CF original referenciado. | [ GET /api/v1/credit-notes/{id} X-Api-Key Estable Devuelve el detalle completo de una nota de crédito (E34). ](#) | Nombre | Tipo | Descripción | | ------- | ----------------------- | ------------------------- | | id path | string (uuid) Requerido | Identificador de la nota. | [ POST /api/v1/credit-notes X-Api-Key Estable Emite una nota de crédito (E34) referenciando un comprobante original. ](#) | Nombre | Tipo | Descripción | | ----------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | branchId body | string (uuid) Requerido | Identificador de la sucursal emisora dentro del espacio de trabajo. | | sequence body | string Opcional | 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 Opcional | Referencia externa libre del emisor (orden, ticket, ID en tu sistema). | | issuedAt body | string (ISO 8601) Requerido | Fecha de emisión de la nota. | | 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. | | customerId body | string (uuid) Opcional | Receptor de la nota. Obligatorio si el comprobante original era E31. | | currencyId body | integer Requerido | Identificador de la moneda de la nota. | | 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 la nota. | | referenceCreatedAt body | string (ISO 8601) Requerido | Fecha de emisión del comprobante original (E31 o E32) que la nota corrige. | | referenceSequence body | string Requerido | 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 Requerido | Código DGII del motivo. \`1\` anula el comprobante original, \`2\` corrige texto y \`3\` corrige montos. | | lines body | V1LineDto\[\] Requerido | Líneas a corregir o anular. Pueden ser totales (anulación) o parciales (devolución). | | payments body | V1PaymentDto\[\] Opcional | Pagos asociados a la nota. Suele ir vacío en notas de crédito. | ## Ejemplo: emitir nota de crédito Una devolución parcial referencia el comprobante original por su NCF (`referenceSequence`) y su fecha de emisión (`referenceCreatedAt`), más un `modificationCode` que indica el motivo según la DGII: `1` anula el comprobante original, `2` corrige texto y `3` corrige montos (el caso de una devolución parcial). Las líneas describen lo que se devuelve, con sus impuestos asociados. El campo `sequence` se ignora: la nota siempre toma el siguiente NCF de la secuencia activa. Si no existe un documento con ese `referenceSequence`, la API responde `404` con `{ message }`. Ten en cuenta que `/credit-notes` y `/debit-notes` listan la misma mezcla de notas de crédito y de débito. 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(); ``` Respuesta response.json ``` { "documentId": "4a7d1ed4-14f0-4c2b-9e8a-3f5b6c7d8e90", "consultationUrl": "https://ecf.dgii.gov.do/ecf/ConsultaTimbre?RNCEmisor=131000001&ENCF=E340000000001&…" } ``` ### Ejemplo: 400 cuando el monto propuesto excede la factura original Cuando el `modificationCode` es "Corrige Monto", el handler compara el total de la nota contra el total de la factura original referenciada. Si lo excede, devuelve el cuerpo abajo (montos formateados con la cultura del servidor). 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)." } ``` ## Anular vs. corregir parcial El cuerpo es idéntico para ambos casos. La diferencia está en las líneas: - **Anulación total**: replica todas las líneas del comprobante original con las mismas cantidades. La DGII anula el efecto fiscal completo. - **Devolución parcial**: incluye solo las líneas afectadas con la cantidad o monto a revertir. El comprobante original mantiene el saldo no devuelto. V1 no expone void de notas de crédito El slice `V1CreditNoteSlice` publica solo `list`, `get` y `create`; no expone `POST .../void`. Si emites una nota de crédito por error, la corrección desde V1 es emitir una nota de débito (E33) que reverse el efecto. El evento `nota_credito.anulated` existe en el catálogo de webhooks porque el dominio sí permite anular vía endpoints internos no públicos; tu integración no debe contar con ello en V1. ## Siguientes pasos Siguiente paso ## Continúa por aquí - [ Notas de débito Comprobante E33 para incrementar el monto de un comprobante anterior. ](/desarrolladores/notas-debito) - [ Facturas Crea el comprobante E31 o E32 que esta nota corrige. ](/desarrolladores/facturas) - [ Webhooks Suscribe dgii.aprobado para conocer el estado final de la nota. ](/desarrolladores/webhooks)