Notas crédito y débito

Una factura aceptada no se edita: se corrige con una nota crédito (reduce o anula) o una nota débito (aumenta). Se emiten con el mismo POST /v1/companies/{company_id}/documents que una factura, cambiando type y agregando correction.

Nota	type	Conceptos (correction.concept)
Crédito	credit_note	partial_return, annulment, discount, price_adjustment, early_payment_discount, volume_discount
Débito	debit_note	interest, expenses, value_change, other

annulment exige billing_reference. Las reglas de cada campo están en la referencia de campos (correction).

Qué necesitas

1. Una factura aceptada. Consulta su number, su cufe y su fecha de emisión (issue_date, formato YYYY-MM-DD) con GET .../documents/{document_id}.
2. La referencia debe ser exactamente la de esa factura: número y CUFE. Una referencia a una factura de otra empresa no cuenta.
3. No necesitas resolution_id: las notas usan siempre su propia serie (NC o ND) y la API ignora el que envíes. Ver numeración y series.

Nota crédito con referencia

curl -s -X POST "https://api.foliios.com/v1/companies/$FOLIIOS_COMPANY_ID/documents" \
  -H "Authorization: Bearer $FOLIIOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: devolucion-1042" \
  -d '{
    "type": "credit_note",
    "customer": {
      "identification": {"type": "nit", "number": "900373076"},
      "name": "Comercializadora Andina S.A.S.",
      "emails": ["facturas@andina.example"]
    },
    "lines": [{"description": "Devolución de 1 hora", "quantity": "1", "unit_price": "4000.00",
               "taxes": [{"scheme": "iva", "percent": "19"}]}],
    "correction": {
      "concept": "partial_return",
      "description": "Devolución de 1 hora",
      "billing_reference": {"number": "SBX1", "cufe": "EL_CUFE_DE_LA_FACTURA", "issue_date": "2026-11-04"}
    }
  }'

Nota débito

curl -s -X POST "https://api.foliios.com/v1/companies/$FOLIIOS_COMPANY_ID/documents" \
  -H "Authorization: Bearer $FOLIIOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: interes-1042" \
  -d '{
    "type": "debit_note",
    "customer": {
      "identification": {"type": "nit", "number": "900373076"},
      "name": "Comercializadora Andina S.A.S.",
      "emails": ["facturas@andina.example"]
    },
    "lines": [{"description": "Intereses por mora", "quantity": "1", "unit_price": "500.00"}],
    "correction": {
      "concept": "interest",
      "description": "Intereses por mora",
      "billing_reference": {"number": "SBX1", "cufe": "EL_CUFE_DE_LA_FACTURA", "issue_date": "2026-11-04"}
    }
  }'

Las dos notas en Python

Parte de la factura aceptada (factura, tal como la devuelve GET). Usa el helper llamar del inicio rápido.

from foliios_inicio import EMPRESA, llamar


def referencia(factura):
    return {
        "number": factura["number"],
        "cufe": factura["cufe"],
        "issue_date": factura["issued_at"][:10],
    }


def emitir_nota(factura, tipo, concepto, descripcion, linea, clave):
    cuerpo = {
        "type": tipo,
        "customer": {
            "identification": factura["customer"]["identification"],
            "name": factura["customer"]["name"],
        },
        "lines": [linea],
        "correction": {
            "concept": concepto,
            "description": descripcion,
            "billing_reference": referencia(factura),
        },
    }
    estado, nota, _ = llamar(
        "POST", f"/v1/companies/{EMPRESA}/documents", cuerpo, {"Idempotency-Key": clave}
    )
    assert estado == 202, nota
    return nota


credito = emitir_nota(
    factura, "credit_note", "partial_return", "Devolución de 1 hora",
    {"description": "Devolución de 1 hora", "quantity": "1", "unit_price": "4000.00"},
    "devolucion-1042",
)
debito = emitir_nota(
    factura, "debit_note", "interest", "Intereses por mora",
    {"description": "Intereses por mora", "quantity": "1", "unit_price": "500.00"},
    "interes-1042",
)

Nota sin referencia a una factura

Si la nota no corrige una factura concreta, en lugar de billing_reference envía period (start y end en YYYY-MM-DD, con end igual o posterior a start). Debes enviar exactamente uno de los dos.

Cómo termina

Una nota sigue el mismo ciclo que una factura: pending, sending, accepted o rejected (estados). Un rechazo se corrige y se reenvía como cualquier otro (rechazos y reenvío); el número de una nota nunca se reutiliza.

Nota

Las notas crédito y débito no tienen contingencia del facturador: cuando el problema se supera, se emiten con normalidad. Ver contingencia.

Si falla

• La DIAN rechaza una nota cuya factura referenciada no existe o no fue aceptada (reglas CBG04a en la nota crédito y DBG04a en la nota débito). En el sandbox puedes provocarlo con el escenario note_reference_not_found, y solo con él: el sandbox no comprueba por sí solo que la factura exista. Ver escenarios.
• 409 note_series_not_configured: la serie de notas de la empresa no está configurada; un administrador debe elegir su prefijo en el portal.
• 422 validation_failed con correction: revisa que el concepto corresponda al tipo y que envíes exactamente uno de billing_reference o period.