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 info@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 —con su lista de eventos, su OpenAPI y sus webhooks— y esta página, que te dice exactamente qué enganchar y con qué código. Dentro de Cairos hay además recetas ya montadas y un flujo de n8n descargable, en API e integraciones → Empezar.
Si tu tienda es de PrestaShop, éste es tu camino
Cairos conecta solo con Shopify, WooCommerce y Odoo. Con PrestaShop todavía no, y está a medias a propósito: el tipo de IVA de cada línea no viene en la línea —hay que resolverlo contra otros dos recursos de su API—, los cupones son un recurso aparte que se aplica al pedido y no a las líneas, y cada tienda llama de una manera distinta al estado que significa «vendido», porque esos estados los edita el comerciante. Facturar tres de cada cuatro pedidos e inventarse el IVA del cuarto es peor que decir que no: el «no» se ve el primer día y el IVA mal puesto se ve en el 303.
Mientras tanto, sus pedidos entran perfectamente por aquí: PrestaShop sabe avisar a una dirección cuando entra un pedido, y lo que hay debajo es exactamente el mismo recorrido que cuenta esta página. Contado para quien vende y no para quien programa, está en Cairos y PrestaShop.
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_emision": "la fecha del pedido, en AAAA-MM-DD",
"lineas": [
{
"descripcion": "el nombre del artículo",
"cantidad": 1,
"precio": 180.00,
"tipo_iva": 21
}
]
}Copia esos nombres tal cual. Los cuatro que se escriben mal siempre son fecha_emision (no «fecha»), descripcion (no «concepto»), tipo_iva (no «iva») y, en el paso 2, tipo con valor customer (no «cliente»). La API no ignora un campo que no conoce: devuelve 422 nombrándolo, así que si un módulo se pone rojo con ese código, lo primero es mirar error.detalles.campos.
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.openapi.json?version=3.0: Make todavía no digiere el type: ["string","null"] de OpenAPI 3.1 y o se atasca al importar o te deja mal tipados los campos que pueden venir vacíos. Es el mismo contrato, traducido.Monta el escenario y pruébalo con una clave de pruebas
Las rutas y los cuerpos son los que acepta el servidor hoy. Crea una clave cai_test_ y lanza el escenario: no registra en VeriFactu ni manda correos.
Módulo HTTP · Conexión por clave · Idempotency-Key del pedido