Notas crédito y débito

Emitir notas crédito y débito sobre facturas validadas en habilitación, consultando el saldo ajustable.

Las notas requieren una factura original de la misma empresa y ambiente, ya validada en habilitación, con su configuración y autorización de firma vigentes. Emitir una nota puede enviar trabajo a la DIAN de pruebas.

Alcance

Nota crédito (NC): motivos 1 y 2. Nota débito (ND): motivo 3. Consulta la matriz fiscal y GET /v1/capabilities.
Las ND no tienen prevalidación HTTP.
El flujo probado es factura → ND aceptada → NC parcial aceptada → NC por el remanente. Ese caso fue aceptado en habilitación; no se presenta como conformidad DIAN completa.

Nota crédito

Consulta el saldo ajustable con GET /v1/documents/{original_id}/credit-balance. No lo reconstruyas desde el precio histórico.

Prevalida con POST /v1/credit-note-validations y comprueba valid.

Guarda cuerpo y clave, y admite con POST /v1/credit-notes.

Nota débito

Admite con POST /v1/debit-notes usando su propio cuerpo y su propia clave.

Reglas

Una nota pendiente bloquea ajustes incompatibles. No envíes la siguiente solo porque recibiste 202: espera el resultado.
Las notas sobre una factura con reglas v1 heredan esas reglas y exigen el mismo comprador; la prevalidación lo indica con BUYER_PROFILE_INHERITED.
Plantillas sintéticas: ND mixta, NC parcial y NC total. Sustituye IDs, referencia, fechas y datos fiscales de forma coherente: no apuntan a documentos existentes.

Ejemplo TypeScript

backend/examples/notes.ts verifica la capacidad y, para NC, consulta el saldo y prevalida antes de admitir una sola vez. El llamante guarda cuerpo y clave antes de ejecutarlo:

import { readFile } from 'node:fs/promises';
import { submitNote } from './dist/backend/examples/notes.js';
import { createClient } from './dist/backend/examples/integration.js';

const { secret } = JSON.parse(await readFile('.local/credentials-qualification.json', 'utf8'));
const input = JSON.parse(await readFile('.local/note-prepared.json', 'utf8'));
// Archivo privado ya preparado y conservado; usar una clave estable para esta nota.
const result = await submitNote('http://127.0.0.1:3000', secret, input, 'note-prepared-001');
const state = await createClient('http://127.0.0.1:3000', secret).pollDocument(
  result.admission.document_id,
);
console.log(state.state, state.document.dian.status);

Ejemplo curl

Prepara .local/qualification.headers (0600) con X-API-Key, Content-Type: application/json e Idempotency-Key de la nota. Con el original y el cuerpo ya preparados:

curl --silent --show-error --max-time 15 --retry 0 \
  --header @.local/qualification.headers \
  --output .local/note-admission.json --write-out '%{http_code}\n' \
  --data-binary @.local/note-prepared.json \
  http://127.0.0.1:3000/v1/credit-notes

El ejemplo no sigue redirecciones ni reintenta el POST. En un servicio remoto, usa HTTPS y el origen aprobado.