Numeración y series NC y ND

Cada documento lleva un número: un prefijo y un consecutivo (SBX1, SETP990000000…). Salen de una resolución de numeración, un rango que la DIAN autoriza a tu empresa.

Resoluciones

Una resolución tiene prefijo, rango (desde y hasta), fechas de vigencia y un modo:

Modo	Cómo se numera
Automático	foliios asigna el siguiente número. Si envías number, la solicitud falla con 422 numbering_mode_mismatch.
Manual	Tú envías number en cada documento. Sin él, 422 numbering_mode_mismatch. Si otro documento ya lo tiene, 409 number_already_used, con el id y el estado de ese documento.

Una empresa puede tener varias resoluciones (por punto de venta, por modo…), por eso una factura indica su resolución en resolution_id, que no se infiere. En el sandbox la resolución es siempre 18760000000000, con prefijo SBX y modo automático.

Antes de tomar un número, foliios comprueba la resolución con la fecha de hoy en Colombia:

• 422 resolution_not_found: el resolution_id no existe para la empresa en ese ambiente.
• 422 resolution_expired o 422 resolution_not_yet_valid: fuera de la vigencia.
• 422 number_out_of_range: número manual fuera del rango.

Una solicitud inválida no consume número.

Series de notas crédito y débito

Las notas no usan la resolución de la factura. Cada empresa tiene dos series propias, una de notas crédito (prefijo NC) y otra de notas débito (prefijo ND):

• Al emitir una nota, foliios usa siempre la serie de su tipo. Por eso, para una nota, el resolution_id no hace falta: omítelo. Si lo envías, debe ser el de la serie de esa nota (el que la API devuelve para ella); cualquier otro, como el de una factura, responde 422 validation_failed con resolution_id / not_allowed.
• Los números de las series de notas nunca se reciclan, ni siquiera tras un rechazo.
• Si la serie de una empresa no está configurada, la emisión de esa nota responde 409 note_series_not_configured; un administrador debe elegir su prefijo en el portal.

Ver notas crédito y débito.

Cuándo queda libre un número

Un número queda ocupado desde que se asigna. Se libera cuando la DIAN rechaza el documento y, en modo manual, cuando el documento falló sin haberse firmado nunca:

Estado del documento	¿Número libre?
pending, sending, dian_unavailable, contingency, accepted	No
failed sin cufe, con invalid_document o rendering_failed	Sí en modo manual: nada del documento llegó a la DIAN. En modo automático el número no se vuelve a asignar
cualquier otro failed	No (conserva el número)
rejected	Sí en facturas: en modo automático vuelve al pool; en modo manual puedes reclamarlo con otro documento. En notas, nunca se recicla

Cada documento lo dice en el campo number_reusable (true o false), y el evento document.failed lo trae en data.number_reusable. Habla solo de ese documento: si otro ya tomó el número, lo sabrás por el 409 al pedirlo. En modo automático no eliges el número: el de un rechazo vuelve al pool y lo recibe el siguiente documento.

Para reutilizar en modo manual el número de un documento failed, emite el documento corregido con ese número y una Idempotency-Key nueva: con la misma clave recibes otra vez el failed original (idempotencia y reintentos). El documento que falló sigue consultable.

Al corregir y reenviar un rechazo, el documento conserva su número. Si en modo manual reutilizaste el número de un documento rejected para otro, el reenvío responde 409 number_already_used. Mientras un documento espera la verificación de la DIAN, pedir su número responde 409 number_in_verification: espera o reintenta la verificación.

Los dos 409 dicen qué documento tiene el número, cuando se conoce: holder_document_id (su id) y holder_status (su estado) en la raíz del error. Consúltalo con GET .../documents/{id} antes de decidir.

Los rangos, los prefijos y las vigencias los define la DIAN; qué hace foliios con ellos y qué te corresponde a ti está en responsabilidades.