Como funciona
CUCU usa API Keys con formato estilo Stripe para autenticacion. Un solo header (X-API-Key)
en cada request es todo lo que necesitas. Sin OAuth, sin tokens temporales, sin flujos complejos.
La key determina automaticamente el tenant (empresa), el ambiente (sandbox o produccion)
y los permisos de acceso.
Tipos de API Keys
- Sandbox (sk_test_)
- Produccion (sk_live_)
Las keys de sandbox conectan al SIAT Piloto del SIN. Las facturas emitidas son de prueba
y no tienen validez fiscal.
| Propiedad | Valor |
|---|---|
| Prefijo | sk_test_ |
| Ambiente SIAT | Piloto (ambiente 2) |
| Validez fiscal | No |
| Costo | Incluido en tu plan |
| Uso recomendado | Desarrollo, testing, demos, integracion |
Autenticacion via header
Incluye tu API Key en el headerX-API-Key de cada request. No se acepta autenticacion via
query params, body, ni Basic Auth.
Buenas practicas de seguridad
Variables de entorno
Almacena la API Key en variables de entorno o en un secret manager (Vault, Infisical, AWS Secrets Manager).
Nunca hardcodees la key directamente en el codigo fuente.
Separa ambientes
Usa
sk_test_ en desarrollo y testing, sk_live_ exclusivamente en produccion. Nunca mezcles
keys entre ambientes en el mismo despliegue.Solo backend
Las keys
sk_live_ deben vivir exclusivamente en tu servidor backend. Nunca las expongas en
aplicaciones frontend, moviles o repositorios publicos.Rota periodicamente
Regenera tu API Key desde el dashboard si sospechas una filtracion o como practica periodica.
La key anterior se revoca inmediatamente al generar una nueva.
Patrones recomendados por lenguaje
Node.js / JavaScript
Node.js / JavaScript
Python
Python
Go
Go
PHP
PHP
Errores de autenticacion
Cuando la autenticacion falla, la API responde con un JSON estructurado que indica la causa exacta:| HTTP Code | Codigo interno | Causa | Solucion |
|---|---|---|---|
401 | UNAUTHORIZED | API Key no enviada | Incluir header X-API-Key en el request |
401 | UNAUTHORIZED | API Key invalida | Verificar que la key existe y no tiene errores tipograficos |
401 | UNAUTHORIZED | API Key revocada | Generar una nueva key desde el dashboard |
401 | UNAUTHORIZED | Tenant inactivo | Contactar soporte; la cuenta asociada esta desactivada |
403 | FORBIDDEN | Sin permisos | La key no tiene acceso al recurso solicitado |
Endpoints publicos (sin autenticacion)
Estos endpoints no requieren API Key y pueden ser accedidos directamente:| Endpoint | Metodo | Descripcion |
|---|---|---|
/api/v1/ping | GET | Health check del servidor |
/api/v1/info | GET | Informacion del servidor (version, uptime) |
/api/v1/public/invoice/{cuf}/pdf | GET | Descarga publica del PDF de una factura |
/api/v1/public/invoice/{cuf}/xml | GET | Descarga publica del XML firmado |
/api/v1/public/invoice/{cuf}/status | GET | Estado publico de una factura |
/f/{cuf} | GET | Pagina publica de verificacion de factura (estilo SIAT) |
/api/v1/ai/status | GET | Estado de los servicios de IA (Qdrant, embeddings) |
Los endpoints publicos de factura usan el CUF (Codigo Unico de Facturacion) como identificador.
Esto permite compartir URLs de descarga directamente con clientes sin exponer credenciales.
Rotacion de API Keys
Rotar tu API Key es una practica recomendada de seguridad. Cuando generas una nueva key desde el dashboard, la key anterior se revoca inmediatamente.Genera una nueva key
Accede a tu dashboard en app.cucu.bo y navega a Configuracion > API Keys.
Haz clic en Regenerar key para el ambiente deseado (sandbox o produccion).
Actualiza tu aplicacion
Reemplaza la key antigua en tus variables de entorno o secret manager con la nueva key.
Despliega la actualizacion.
SDKs (proximamente)
Estamos desarrollando SDKs oficiales para los lenguajes mas populares. Mientras tanto, la API REST funciona con cualquier cliente HTTP en cualquier lenguaje.Node.js SDK
npm install @cucu/sdkEn desarrollo. Lanzamiento estimado Q2 2026.Python SDK
pip install cucu-sdkEn desarrollo. Lanzamiento estimado Q2 2026.Go SDK
go get github.com/cucuapi/cucu-goEn planificacion. Lanzamiento estimado Q3 2026.Quieres que prioricemos un SDK en particular? Escribe a dev@cucu.bo y cuentanos
que lenguaje usas. Tambien aceptamos contribuciones open source.