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 — 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} — Devuelve el detalle completo de una nota de crédito (E34).
• POST /api/v1/credit-notes — Emite una nota de crédito (E34) referenciando un comprobante original.

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.

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": []
  }'

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();

{
  "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).

{
  "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.

Next steps