Colección de Postman
Descarga la colección del sandbox, pega tu API key y emite una factura de prueba sin escribir código.
Todavía no lo hemos anunciado
El sandbox funciona: sandbox.cufy.co y api-sandbox.cufy.co ya responden, y las facturas llegan a la DIAN de habilitación. Lo que falta es terminar de probarlo con gente nueva, así que algún detalle puede cambiar antes del anuncio.
Si prefieres ver la API funcionando antes de escribir código, esta colección hace el recorrido completo: envía una factura de prueba, consulta qué respondió la DIAN y descarga el PDF. Lo único que escribes es tu API key.
Sirve igual en Postman y en Bruno, que importa colecciones de Postman.
Descarga
Los dos se importan igual: Import y suéltalos en la ventana.
Consigue tu API key
Entra a sandbox.cufy.co, crea tu cuenta y, en API keys, elige Crear API key. Cópiala: solo se muestra una vez. Si ya tienes una guardada, sirve.
Pega la key en el ambiente
Arriba a la derecha, elige el ambiente Cufy · Sandbox. Ábrelo y pega tu key en la variable api_key. No toques base_url; las demás variables las llenan las peticiones mientras corren.
La key queda guardada en tu computador, en el ambiente de Postman. Trátala como una contraseña: no compartas ese archivo después de llenarlo.
Ejecuta la carpeta «1. Tu primera factura»
Sus peticiones van en orden y cada una deja lo que la siguiente necesita:
| Petición | Qué hace |
|---|---|
| Comprobar que el sandbox responde | Lo único que no lleva API key: dice si el servicio está en pie. |
| Comprobar tu API key | Responde 200 si tu key sirve, y confirma que estás en habilitación (pruebas). |
| Ver tu empresa de pruebas | La empresa que tu cuenta ya tiene lista para facturar. |
| Buscar tu rango de numeración | La lista trae un rango por tipo de documento; guarda el de las facturas. |
| Revisar la factura antes de enviarla | Aplica las reglas sin numerar, firmar ni enviar nada. |
| Enviar la factura | Responde 202 y guarda el document_id. |
| Reenviar la misma factura | La misma Idempotency-Key: responde la misma factura, no crea otra. |
| Consultar qué respondió la DIAN | Repítela hasta que processing_status diga completed. |
| Ver los archivos de la factura | Guarda el identificador del PDF y el del XML firmado. |
| Descargar el PDF | Save response → Save to a file para bajarlo. |
| Descargar el XML firmado | El documento fiscal; el PDF es su representación. |
Puedes correrlas una por una o con el Runner de Postman. Si las corres seguidas, la consulta a la DIAN puede llegar antes que la respuesta: vuelve a ejecutar esa petición y la siguiente.
Qué más trae
- Consultar tus documentos: la lista de lo que has enviado, el resultado de un envío y a quién se le entregó la factura.
- Webhooks: tus destinos, los avisos generados y si tu receptor contestó. Cómo verificar la firma está en Webhooks.
- Catálogos y estado: los códigos que pide la DIAN y el estado del servicio.
- Clientes guardados: guardar un cliente, buscarlo y facturar con su
customer_iden lugar del comprador completo. Ver Clientes guardados.
Lo que la colección no hace
- No emite notas crédito ni débito. El emisor de pruebas compartido del sandbox solo está autorizado para facturas.
- No envía correos. El sandbox solo le escribe al correo con el que registraste tu cuenta, así que la factura se emite sin pedir entrega.
- No crea ni revoca API keys. Eso se hace en el panel.
Cuando algo falla
Cada respuesta trae un request_id; guárdalo si necesitas escribirnos. Los códigos y qué hacer con cada uno están en Errores.
El sandbox admite 50 documentos al día y 60 peticiones por minuto. Al pasarte responde 429 con Retry-After: espera esos segundos y reintenta con la misma Idempotency-Key. Una petición rechazada por el límite no gasta número ni cupo.
¿Prefieres código? El mismo recorrido, en cURL, Node.js, PHP y Python, está en Empieza aquí.