Tu empresa y su numeración
Qué datos tiene tu empresa en Cufy y de dónde sale el número de cada factura.
Tu cuenta del sandbox nace con una empresa de pruebas y sus rangos de numeración ya creados. No tienes que configurar nada: lo que necesitas de esta página es leer esos datos, sobre todo el id del rango con el que vas a numerar.
Todo lo de aquí se consulta con company:read o numbering:read, que cualquier clave tuya tiene.
Tu empresa
GET /v1/company devuelve el perfil con el que se emiten tus facturas: identificación fiscal, nombre y estado.
curl https://api-sandbox.cufy.co/v1/company \
-H "X-API-Key: TU_API_KEY"| Campo | Qué es |
|---|---|
id | El identificador de tu empresa. Aparece también en cada webhook, como company_id. |
environment | qualification en el sandbox. |
status | ready cuando la empresa puede emitir. |
profile | Los datos del emisor. En el sandbox son los del emisor de pruebas compartido, no los tuyos. |
La respuesta trae un ETag. Solo lo necesitas si vas a modificar el perfil, algo que una cuenta del sandbox no hace: el emisor es compartido y no se cambia.
Rangos de numeración
Un rango es el conjunto de números que tus documentos pueden usar, con su prefijo y su resolución. Cufy toma el siguiente número disponible cada vez que emites, en orden y sin repetir.
GET /v1/numbering-ranges los lista:
curl https://api-sandbox.cufy.co/v1/numbering-ranges \
-H "X-API-Key: TU_API_KEY"No tomes items[0]
La lista trae un rango por tipo de documento y no viene en el orden que esperas. Filtra siempre por document_type (invoice, credit_note o debit_note) y por status: "active". Emitir una factura con el rango de las notas devuelve 422 NUMBERING_TYPE_MISMATCH.
const ranges = await fetch('https://api-sandbox.cufy.co/v1/numbering-ranges', {
headers: { 'X-API-Key': process.env.CUFY_API_KEY },
}).then((r) => r.json());
const invoiceRange = ranges.items.find(
(range) => range.document_type === 'invoice' && range.status === 'active',
);De cada rango te interesan estos campos:
| Campo | Qué es | Ejemplo |
|---|---|---|
id | Lo que envías en numbering_range_id. | "3f6c…" |
document_type | Para qué documento sirve. | "invoice" |
prefix | Las letras que van antes del número. En habilitación, SETP. | "SETP" |
range_from y range_to | El primer y el último número autorizados. | 990000000 |
next_number | El número que se asignará al siguiente documento. | 990000259 |
status | Solo sirve active. | "active" |
valid_from y valid_until | La vigencia de la resolución. | "2026-12-31" |
Guarda el id en tu configuración, no el primer elemento de la lista. Si un día el rango se agota, la emisión responde 409 NUMBERING_EXHAUSTED y no crea documento ni consume nada.
Si algo va lento
GET /v1/status trae la última observación del ambiente y los incidentes abiertos. Sirve para explicarle a alguien por qué algo tarda, no para decidir sobre una factura: el estado de un documento solo lo dice el documento.