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.

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 e ignora el resolution_id que llegue. Por eso, para una nota, ese campo no hace falta.
• 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. Solo se libera cuando la DIAN rechaza el documento:

Estado del documento	¿Número libre?
pending, sending, dian_unavailable, contingency, accepted	No
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

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 rangos, los prefijos y las vigencias los define la DIAN; qué hace foliios con ellos y qué te corresponde a ti está en responsabilidades.