Notas crédito y débito

Una factura enviada a la DIAN no se edita ni se borra. Para cambiar lo que dice, emites una nota que la referencia:

• Nota crédito (NC): rebaja la factura. La devolución de un producto, un descuento que no aplicaste, una anulación.
• Nota débito (ND): aumenta la factura. Un cargo que faltó, un interés de mora.

Las dos se envían casi igual que una factura, con tres campos más que dicen a qué documento se refieren y por qué.

Antes de empezar

• La factura original tiene que ser tuya, del mismo ambiente, y estar validada por la DIAN. Una factura que todavía está en proceso no admite notas.
• Necesitas su id (el que te devolvió POST /v1/invoices, no su número ni su CUFE).
• Necesitas el id del rango de numeración de notas, que es distinto del de facturas.

Cuánto puedes ajustar

Antes de emitir una NC, pregunta cuánto queda por ajustar. No lo calcules desde el precio de la factura original: si ya emitiste notas antes, o si hay una ND validada de por medio, el saldo cambió.

curl https://api-sandbox.cufy.co/v1/documents/DOCUMENTO_ID/credit-balance \
  -H "X-API-Key: TU_API_KEY"

La respuesta trae una entrada por cada línea de la factura original:

Esta consulta es informativa: al admitir la nota, Cufy vuelve a comprobar el saldo bajo bloqueo. Que el saldo alcance ahora no garantiza que alcance dentro de un minuto si tienes otra nota en vuelo.

Encabezados

Qué documento corrige y por qué

Estos tres campos son lo único que distingue una nota de una factura.

Datos generales

Iguales a los de una factura, con dos diferencias:

Comprador y líneas

El buyer va completo otra vez y tiene que coincidir con el de la factura original. Cufy lo contrasta; si cambiaste el comprador, la nota se rechaza.

Las lines tienen exactamente la misma forma que en una factura (ver Crear una factura), pero describen lo que ajustas, no lo que vendiste:

• Para devolver una unidad de tres, la línea lleva quantity: "1", no "3".
• net_amount e impuestos se calculan sobre esa cantidad.
• No puedes ajustar más de lo que dice remaining en el saldo.

adjustments, tax_totals, withholding_totals, totals y payment funcionan igual que en la factura y son obligatorios; envía [] donde no tengas nada.

Ejemplo: devolver una unidad

Sobre una factura de tres unidades a 10.000 con IVA 19 %, para devolver una:

{
  "document_type": "credit_note",
  "external_reference": "DEV-001",
  "profile_id": "co-referenced-note-cop-v1",
  "numbering_range_id": "a91b0c32-5f4e-4c8a-9d21-7b6e5a4c3d2f",
  "issued_at": "2026-09-20T15:30:00-05:00",
  "currency": "COP",
  "original_document_id": "3f6c1d88-2a4b-4e91-b7c5-0d9e8f7a6b5c",
  "discrepancy_reason": {
    "code": "1",
    "description": "Devolución de una unidad"
  },
  "adjustment_scope": "partial",
  "buyer": {
    "party_type": "person",
    "identification": { "type_code": "13", "number": "1000000000" },
    "name": "Cliente de prueba",
    "tax_registration": {
      "responsibility_codes": ["R-99-PN"],
      "tax_scheme_codes": ["01"]
    }
  },
  "lines": [
    {
      "id": "1",
      "description": "Servicio de prueba",
      "product_identification": { "scheme_code": "999", "value": "SERV-001" },
      "quantity": "1",
      "unit_code": "94",
      "unit_price": "10000.00",
      "price_base_quantity": "1",
      "net_amount": "10000.00",
      "taxes": [
        {
          "code": "01",
          "rate": "19",
          "taxable_amount": "10000.00",
          "amount": "1900.00"
        }
      ],
      "adjustments": [],
      "withholdings": []
    }
  ],
  "adjustments": [],
  "tax_totals": [
    {
      "code": "01",
      "rate": "19",
      "taxable_amount": "10000.00",
      "amount": "1900.00"
    }
  ],
  "withholding_totals": [],
  "totals": {
    "line_extension_amount": "10000.00",
    "tax_exclusive_amount": "10000.00",
    "tax_inclusive_amount": "11900.00",
    "allowance_total_amount": "0.00",
    "charge_total_amount": "0.00",
    "prepaid_amount": "0.00",
    "payable_rounding_amount": "0.00",
    "payable_amount": "11900.00"
  },
  "payment": { "terms": "cash", "means_code": "10" }
}

Envíalo a POST /v1/credit-notes. La respuesta es la misma que la de una factura: un id, un estado y, más tarde, el número, el CUFE y la respuesta de la DIAN.

Si quieres comprobar el cuerpo sin emitir nada, POST /v1/credit-note-validations acepta el mismo JSON y responde valid. Las notas débito no tienen prevalidación.

Ejemplo: cobrar un interés

Una nota débito cambia tres cosas: document_type, el motivo y que reference_id pasa a ser obligatorio.

{
  "document_type": "debit_note",
  "external_reference": "INT-001",
  "profile_id": "co-referenced-note-cop-v1",
  "discrepancy_reason": {
    "code": "3",
    "description": "Intereses por mora",
    "reference_id": "1"
  },
  "adjustment_scope": "partial"
}

El resto del cuerpo es idéntico al de la nota crédito. Va a POST /v1/debit-notes, con su propia Idempotency-Key.

Reglas que conviene saber

• Una nota a la vez. Recibir 202 no significa que la nota esté validada. Si envías la siguiente sin esperar, la segunda puede chocar con el saldo que reservó la primera.
• El orden importa. Se admite una nota crédito después de una nota débito validada. Al revés no: una ND sobre una factura que ya tiene una NC activa se rechaza.
• Facturas viejas conservan sus reglas. Una nota sobre una factura emitida con reglas anteriores hereda esas reglas y exige el mismo comprador. La prevalidación lo avisa con BUYER_PROFILE_INHERITED.
• No se admiten facturas ajenas. Este perfil solo referencia documentos emitidos por tu propia cuenta.

Si algo sale mal

La referencia completa está en POST /v1/credit-notes, POST /v1/debit-notes y GET /v1/documents/{id}/credit-balance.