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 — 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.

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.

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&…"
}

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

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

Siguientes pasos