Make: cuatro módulos HTTP y ninguna app
No hay app oficial de Cairos en Make, y para lo que hay que hacer tampoco hace falta. Con el módulo HTTP y una conexión por clave se monta el recorrido entero de un pedido a una factura emitida.
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.
No hay app oficial de Cairos en Make
No está publicada y no hay fecha. Lo que hay es la API y esta página, que te dice exactamente qué enganchar y con qué código. Es menos cómodo que instalar algo y es lo que hay hoy; decirlo así te ahorra buscar un conector que no existe.
El módulo que se usa
El de siempre cuando no hay app: HTTP. Y dentro de HTTP, el que hace la petición con autenticación por clave, que existe justamente para no dejar la clave escrita a la vista en el escenario.
La diferencia entre usar ese módulo y el HTTP genérico no es cosmética. Con el genérico, la cabecera Authorization con tu clave dentro queda escrita en el escenario, y cualquiera de tu equipo que lo abra la ve y se la lleva. Con la conexión por clave, la clave vive en el llavero de Make y el escenario sólo la referencia.
| Campo de la conexión | Qué poner |
|---|---|
| Nombre de la clave (cabecera) | Authorization |
| Valor | Bearer cai_live_TU_CLAVE — con la palabra Bearer y el espacio |
| Dónde va | En la cabecera, no en la consulta |
El fallo más repetido montando esto es poner sólo la clave, sin Bearer delante. Sale un 401 no_autenticado y parece que la clave está mal cuando lo que falta es una palabra.
Un escenario completo: de un pedido a una factura
Cuatro módulos. El primero cambia según de dónde venga el pedido; los otros tres son siempre los mismos.
| # | Módulo | Qué hace |
|---|---|---|
| 1 | Disparador | Un webhook personalizado al que apunta tu tienda, o el módulo de vigilancia de la app que uses. Aquí entra el pedido. |
| 2 | HTTP · petición con clave | POST a /contactos. Cuerpo JSON con nombre, NIF y correo del pedido. |
| 3 | HTTP · petición con clave | POST a /facturas con las líneas y el id del contacto del paso 2. |
| 4 | HTTP · petición con clave | POST a /facturas/{id}/emitir, con el id del paso 3. |
El cuerpo del paso 3, tal cual se pega en el campo de contenido del módulo, sustituyendo lo que está entre llaves por lo que traiga tu disparador:
{
"contacto_id": "el id que devolvió el paso 2",
"serie": "WEB",
"fecha": "la fecha del pedido, en AAAA-MM-DD",
"lineas": [
{
"concepto": "el nombre del artículo",
"cantidad": 1,
"precio": 180.00,
"iva": 21
}
]
}Y en cabeceras de cada módulo, dos, además de la que pone la conexión:
Content-Type: application/json
Idempotency-Key: make-1042La llave de idempotencia, que en Make importa más que en ningún sitio
Make reintenta escenarios, y ése es todo el problema
Un escenario que falla a mitad se puede volver a ejecutar, entero, desde la cola de incompletos. Si el módulo que falló era el cuarto, los tres primeros se ejecutan otra vez, y el segundo crea otro contacto y el tercero otra factura. Con la cabecera puesta, la segunda ejecución devuelve la misma factura y no pasa nada.
La llave tiene que salir del identificador del pedido del disparador, no de una función de aleatorio ni de la fecha actual: si cambia entre la ejecución y la repetición, no sirve de nada. Y una distinta por operación: make-1042 para crear la factura y make-1042-emitir para emitirla.
Por qué esto importa tanto y qué pasa cuando falta, en idempotencia.
Control de errores
Sin control de errores, un módulo que devuelve 422 detiene el escenario y lo manda a la cola. Con él, se puede decidir qué hacer, y la decisión no es la misma para todos los códigos:
| Lo que devuelve Cairos | Qué poner en el gestor de errores |
|---|---|
429 o 500 | Reintentar. Son los dos únicos que tiene sentido repetir, y con la llave puesta repetir es gratis. |
422 datos_invalidos | Ignorar y avisar a un canal. El dato viene mal del otro sistema y repetir dará el mismo error. error.detalles dice qué campo. |
401 o 403 | Parar y avisar. Es la conexión o el scope: reintentar sólo consume operaciones. |
Los siete códigos, con cuáles se reintentan, están en errores y límites.
Y un consejo que ahorra operaciones de tu plan: no montes un escenario que consulte Cairos cada cinco minutos por si hay algo nuevo. Suscríbete a un webhook y que el escenario arranque cuando pase algo. Es más barato, más rápido y no gasta el límite de la API.
Si esto te va a costar más de una tarde, mira n8n
No es una recomendación en contra de Make: es que n8n tiene un nodo de código donde comprobar la firma de un webhook, y en Make eso es más incómodo. Si sólo vas a llamar a Cairos, Make va perfectamente; si además vas a recibir sucesos firmados, el otro te va a dar menos guerra.
Preguntas sobre Make
Authorization y el valor Bearer más la clave. Así queda en el llavero de Make y no escrita en el escenario, donde la vería cualquiera de tu equipo.Bearer y el espacio delante de la clave. Es el fallo número uno montando esto.Idempotency-Key eso significa una segunda factura; con ella, la segunda ejecución devuelve la primera factura y no duplica nada.POST /webhooks. Es mucho mejor que consultar cada pocos minutos, que gasta operaciones para enterarse de que no ha pasado nada.Monta el escenario y déjalo esperando la clave
Las rutas y los cuerpos son los definitivos. Lo único que falta es que la API abra.
Módulo HTTP · Conexión por clave · Idempotency-Key del pedido