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

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}.
La referencia debe ser exactamente la de esa factura: número y CUFE. Una referencia a una factura de otra empresa no cuenta.
No necesitas resolution_id: las notas usan siempre su propia serie (NC o ND). Si lo envías, debe ser el de esa serie, que es el resolution_id que la API devuelve para la nota; el de una factura responde 422 validation_failed con el campo resolution_id y el código not_allowed, sin consumir número. Una nota emitida antes de que existieran las series propias devuelve el resolution_id de su factura: no lo copies en una nota nueva. 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 in (200, 201, 202), nota   # 201: aceptada
    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), y su emisión responde igual: 201, 200 o 202 (qué responde la emisión). Un rechazo se corrige y se reenvía como cualquier otro (rechazos y reenvío); el número de una nota nunca se reutiliza.

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 resolution_id y el código not_allowed: la nota trae un resolution_id que no es el de su serie; quita el campo. Lo recibes también si repites una nota ya emitida con su misma Idempotency-Key y el resolution_id de una factura en el cuerpo: esa repetición no devuelve el documento original. La nota no se emitió dos veces; consúltala con GET .../documents/{document_id}.
422 validation_failed con correction: revisa que el concepto corresponda al tipo y que envíes exactamente uno de billing_reference o period.
422 validation_failed con withholdings (withholdings_in_note) o con prepaid_payments (prepaid_payments_in_credit_note): una nota crédito o débito no lleva retenciones y una nota crédito no lleva anticipos. Quita el campo y repite con la misma Idempotency-Key: el rechazo no tomó número.