La API de Cairos, documentada antes de estar abierta
Una API REST sobre HTTPS, con claves Bearer, JSON en los dos sentidos y webhooks firmados. Aquí está el contrato entero: rutas, permisos, errores, paginación e idempotencia. Lo que todavía no está es la puerta abierta, y eso lo dice la página antes que nada.
Una factura se crea en borrador y se emite en una segunda llamada. Entre las dos hay una diferencia legal, no de estilo.
La API está en marcha. Esto es lo que hay hoy y lo que no
Funciona. Las rutas de esta documentación están desplegadas y respondiendo en https://erp.cairos.es/api/v1/. Los ejemplos de estas páginas se pueden copiar y ejecutar. La especificación completa está en openapi.json, que es lo que importan Make y n8n.
Las claves te las creas tú, desde Desarrolladores en tu cuenta de Cairos. Empieza con una cai_test_: trabaja contra tus datos de verdad pero no registra en VeriFactu ni envía correos, así que puedes montar tu integración sin ensuciar una serie de facturación.
Y lo que todavía NO hay, dicho sin adornos: ningún conector oficial. Ni app de Shopify, ni plugin de WooCommerce, ni módulo publicado en Make o n8n. Con la API y su especificación se pueden construir —para eso están las guías de esta sección— pero construirlos es trabajo, y ese trabajo no está hecho.
Si montas algo con esto, escríbenos a hola@cairos.es. Nos interesa especialmente lo que te falte del contrato: es lo que decide qué se amplía primero.
Tres cosas, y están puestas en este orden a propósito
No es una API «por tener API». Se ha diseñado mirando a quién la va a usar de verdad, y el orden de esta lista es el orden en el que se han decidido las cosas cuando había que elegir.
Llevar los pedidos de tu tienda a facturas
Una tienda en WooCommerce o en Shopify que factura sola, con la numeración correlativa donde tiene que estar: en el ERP, no en la tienda.
Automatizar sin escribir código
Con Make o n8n, que hablan HTTP y no necesitan un conector oficial para llamar a una API bien hecha.
Sacar los datos si eres asesoría
Listados de facturas y gastos de la cuenta de un cliente, con una clave de sólo lectura que no puede tocar nada. Más en asesorías.
Todo lo que hay que saber, en una pantalla
Si sólo vas a leer una tabla de esta web, que sea ésta.
| Cómo es | Dónde está explicado | |
|---|---|---|
| Base | https://erp.cairos.es/api/v1Sólo HTTPS. Una llamada por HTTP no se redirige: se rechaza. | Empezar |
| Autenticación | Cabecera Authorization: Bearer cai_live_…. Sin cookies, sin OAuth y sin sesión. | Autenticación |
| Permisos | Diez scopes por recurso y por operación. Un scope de escritura no incluye el de lectura. | Scopes |
| Formatos | JSON de ida y de vuelta. Importes en decimales, fechas en AAAA-MM-DD, horas en UTC. | Referencia |
| Errores | Siempre el mismo sobre: error.codigo, error.mensaje y error.detalles. Siete códigos y ni uno más. | Errores |
| Paginación | Por cursor: ?limite= (50 por defecto, 200 de tope) y ?desde=. Nunca por número de página. | Paginación |
| Escrituras seguras | Cabecera Idempotency-Key en todo lo que crea algo. No es opcional de hecho: es lo que impide facturar dos veces. | Idempotencia |
| Avisos salientes | Webhooks firmados con HMAC-SHA256, con la marca de tiempo dentro de lo firmado. | Webhooks |
| Especificación | GET /api/v1/openapi.json, que es la fuente de la verdad del esquema campo a campo. | Referencia |
Esta tabla y el resto de la sección se escriben contra el contrato que se está implementando. Si encuentras una diferencia entre lo que dice una página y lo que devuelve la API, gana la API y la página se corrige: escribe a hola@cairos.es.
Las once páginas de esta sección
Si nunca has llamado a esta API, la primera es la única que necesitas ahora mismo.
Empezar en cinco minutos
Conseguir la clave, hacer la primera llamada y emitir la primera factura. Con curl, JavaScript y PHP.
Autenticación y scopes
Claves de producción y de pruebas, qué cambia entre las dos, y los diez permisos con lo que abre cada uno.
Referencia de recursos
Organización, contactos, productos, gastos, facturas, cobros y webhooks. Ruta a ruta.
Errores, paginación y límites
Los siete códigos, cómo se recorre una lista larga y qué hacer con un 429.
Idempotencia
Por qué existe la cabecera y por qué en una serie de facturación no se arregla borrando.
Webhooks
Los seis sucesos, cómo se comprueba la firma y cómo se sobrevive a un reenvío.
WooCommerce
El enganche en PHP: del pedido pagado a la factura emitida, sin duplicar.
Shopify
Webhook de Shopify, servicio intermedio y factura. Qué comprueba cada lado.
Make
Un escenario con el módulo HTTP, cabeceras propias y control de errores.
n8n
Nodo HTTP Request con credencial de cabecera, y nodo Webhook para recibir.
Y lo que se conecta sin API
CSV, Excel, norma 43 y SEPA. Sigue siendo la vía más usada en España.
La API está en español, y la aplicación también
Los recursos, los parámetros, los nombres de campo y los códigos de error están en castellano: /facturas y no /invoices, limite y no limit, no_encontrado y no not_found. Cairos es un ERP español y no mantiene un segundo juego de nombres en inglés. Lo decimos arriba porque quien integra puede no hablar español, y enterarse a mitad del trabajo es peor que saberlo antes de empezar.
Tres cosas que conviene saber antes de escribir código
Una factura no se crea emitida. Se crea en borrador y se emite con una segunda llamada a /facturas/{id}/emitir. No es un capricho de diseño: al emitir es cuando se asigna el número correlativo de la serie y cuando se genera el registro de VeriFactu, y ninguna de las dos cosas se puede deshacer. Separarlo en dos pasos te deja comprobar el borrador antes de que ocurra lo irreversible.
Nada se borra. Una factura emitida no se elimina: se rectifica. Es lo que exige el reglamento de facturación, y por eso la API no tiene un DELETE de facturas emitidas por mucho que lo busques.
Cada organización tiene sus claves. No hay una clave que vea varias empresas. Si llevas diez clientes, son diez claves, y eso es una propiedad del diseño y no una limitación pendiente de resolver: es lo que impide que un fallo tuyo escriba en la contabilidad de otro.
¿Vas a integrar algo? Cuéntanoslo antes de empezar
Mientras la API no esté abierta las claves se dan a mano, así que hay una persona al otro lado. Aprovéchalo: si nos dices qué quieres montar, te decimos si hoy se puede o todavía no.
Preguntas sobre la API
/api/v1 existe y responde sin mandarte al inicio de sesión, pero las rutas concretas devuelven 404 porque aún se están escribiendo, y las claves no se crean solas desde la cuenta. Lo que sí es firme es el contrato de esta documentación: puedes montar tu integración contra él hoy. Escribe a hola@cairos.es y te avisamos en cuanto haya contra qué llamar. Cuando abra, se dirá aquí el mismo día y sin haber prometido antes una fecha.cai_test_, que es algo distinto y conviene entenderlo antes de empezar: trabajan contra los mismos datos que las de producción, pero no registran en VeriFactu ni envían correos. Sirven para desarrollar sin ensuciar una serie de facturación de verdad. No son una base de datos aparte: lo que crees con una clave de pruebas lo verás en tu cuenta. Está explicado en autenticación.GET /api/v1/openapi.json, con la que un generador de clientes te saca el tuyo en el lenguaje que uses. Los ejemplos de estas páginas son curl, fetch y cURL de PHP a pelo, sin dependencias./facturas y no /invoices, limite y no limit.El contrato ya está cerrado. Puedes empezar a diseñar contra él
Rutas, permisos, errores y firma no van a cambiar debajo de ti. Lo único que falta es que te demos la clave, y eso se pide por correo.
API v1 · JSON sobre HTTPS · Webhooks firmados · Especificación OpenAPI