Introducción
Qué hace Cufy, en qué ambiente emite tu cuenta del sandbox y por dónde empezar.
Cufy emite facturación electrónica colombiana desde tu sistema. Tú envías los datos de la venta por HTTP; Cufy numera la factura, la firma, la envía a la DIAN, genera el PDF y el XML, y te avisa cuando hay respuesta.
Tú no envías el emisor, el consecutivo, el CUFE ni la firma: los pone Cufy. Tú envías comprador, líneas, impuestos, totales y forma de pago.
Todas las peticiones van a la misma dirección, con tu API key en el encabezado X-API-Key:
curl https://api-sandbox.cufy.co/v1/company \
-H "X-API-Key: TU_API_KEY"Qué puedes hacer
| Quieres | Empieza por |
|---|---|
| Emitir una factura | Crear una factura |
| Revisar una factura antes de emitirla | Ciclo de vida de una factura |
| Corregir o anular algo ya emitido | Notas crédito y débito — hoy no se firman, ver abajo |
| Saber qué respondió la DIAN | Ciclo de vida de una factura |
| Descargar el PDF o el XML firmado | Archivos descargables |
| Que te avisemos en lugar de preguntar | Webhooks |
| Enviarle la factura al comprador | Entrega al comprador |
Qué todavía no puedes hacer
El sandbox emite con un emisor de pruebas compartido, y eso le pone un techo. No es un error tuyo:
| Todavía no | Por qué | Qué hacer mientras tanto |
|---|---|---|
| Emitir notas crédito o débito | La autorización de firma del emisor compartido solo cubre facturas. La nota se admite y se queda sin firmar. | Nada: las notas están documentadas para que las tengas listas el día que se habiliten. |
Tampoco hay retenciones, anticipos ni monedas distintas del peso. La lista completa de lo que sí admite cada campo está en Catálogos y códigos.
Ambientes
Cada API key pertenece a una empresa y un ambiente. No hay encabezado ni parámetro para cambiar de ambiente: una clave del sandbox nunca emite en producción.
| Ambiente | Qué es | Qué pasa con la DIAN |
|---|---|---|
qualification | Habilitación. Es el ambiente de tu cuenta del sandbox. | Sí: se envía al ambiente de pruebas de la DIAN y ves su respuesta real. Sin validez fiscal. |
simulation | Respuestas inventadas (SIMULATION_ONLY), sin firma ni envío. Tu cuenta del sandbox no lo usa. | No se envía nada. |
production | Emisión con validez fiscal. | Deshabilitado: responde 403 ENVIRONMENT_DISABLED. |
Cada documento te dice en cuál nació, en su campo environment.
Por dónde empezar
Empieza aquí
Crea tu cuenta, copia tu API key y emite tu primera factura de prueba.
Colección de Postman
El mismo recorrido sin escribir código: importas, pegas tu key y corres.
Crear una factura
Cada campo del cuerpo, con su explicación y un ejemplo completo.
Ejemplos por caso
Facturas listas para copiar: contado, crédito, IVA 0 %, varias tarifas.
Webhooks
Registrar un destino, verificar la firma y no perder avisos.
Errores e idempotencia
Qué hacer con cada código y cómo reintentar sin duplicar facturas.
¿No conoces los términos? Glosario. ¿No sabes qué código va en un campo? Catálogos y códigos.
Convenciones de esta documentación
- Los ejemplos apuntan a
https://api-sandbox.cufy.coy usan datos ficticios. ReemplazaTU_API_KEYpor la tuya. - Cantidades, precios e impuestos viajan como texto (
"10000.00"), no como números, para que no se pierdan decimales. - Toda petición que crea o cambia algo exige el encabezado
Idempotency-Key. Guarda el cuerpo y la clave antes del primer envío (ver Errores e idempotencia). - Tolera campos, estados y códigos que no conocías: la API puede añadirlos sin avisar. Que aparezca uno nuevo no significa éxito ni autoriza volver a emitir.
- La referencia publica únicamente las operaciones conectadas. Una ruta que no aparece responde
422 UNSUPPORTED_OPERATION.