Make: quatre mòduls HTTP i cap app
No hi ha app oficial de Cairos a Make, i per al que s'ha de fer tampoc no cal. Amb el mòdul HTTP i una connexió per clau es munta el recorregut sencer d'una comanda a una factura emesa.
L'API està en marxa. Això és el que hi ha avui i el que no
Funciona. Les rutes d'aquesta documentació estan desplegades i responent a https://erp.cairos.es/api/v1/. Els exemples d'aquestes pàgines es poden copiar i executar. L'especificació completa és a openapi.json, que és el que importen Make i n8n.
Les claus te les crees tu, des de Desenvolupadors al teu compte de Cairos. Comença amb una cai_test_: treballa contra les teves dades de veritat però no registra a VeriFactu ni envia correus, així que pots muntar la teva integració sense embrutar una sèrie de facturació.
I el que encara NO hi ha, dit sense adorns: cap connector oficial. Ni app de Shopify, ni plugin de WooCommerce, ni mòdul publicat a Make o n8n. Amb l'API i la seva especificació es poden construir —per això hi ha les guies d'aquesta secció— però construir-los és feina, i aquesta feina no està feta.
Si muntes alguna cosa amb això, escriu-nos a hola@cairos.es. Ens interessa especialment el que et falti del contracte: és el que decideix què s'amplia primer.
No hi ha app oficial de Cairos a Make
No està publicada i no hi ha data. El que hi ha és l'API —amb la seva llista d'esdeveniments, la seva OpenAPI i els seus webhooks— i aquesta pàgina, que et diu exactament què connectar i amb quin codi. Dins de Cairos hi ha, a més, receptes ja muntades i un flux d'n8n descarregable, a API i integracions → Comença.
Si la teva botiga és de PrestaShop, aquest és el teu camí
Cairos connecta només amb Shopify, WooCommerce i Odoo. Amb PrestaShop encara no, i està a mitges a propòsit: el tipus d'IVA de cada línia no ve a la línia —cal resoldre'l contra dos recursos més de la seva API—, els cupons són un recurs a part que s'aplica a la comanda i no a les línies, i cada botiga anomena d'una manera diferent l'estat que significa «venut», perquè aquests estats els edita el comerciant. Facturar tres de cada quatre comandes i inventar-se l'IVA de la quarta és pitjor que dir que no: el «no» es veu el primer dia i l'IVA mal posat es veu al 303.
Mentrestant, les seves comandes entren perfectament per aquí: PrestaShop sap avisar una adreça quan entra una comanda, i el que hi ha a sota és exactament el mateix recorregut que explica aquesta pàgina.
El mòdul que es fa servir
El de sempre quan no hi ha app: HTTP. I dins d'HTTP, el que fa la petició amb autenticació per clau, que existeix justament per no deixar la clau escrita a la vista a l'escenari.
La diferència entre fer servir aquest mòdul i l'HTTP genèric no és cosmètica. Amb el genèric, la capçalera Authorization amb la teva clau a dins queda escrita a l'escenari, i qualsevol del teu equip que l'obri la veu i se l'emporta. Amb la connexió per clau, la clau viu al clauer de Make i l'escenari només la referencia.
| Camp de la connexió | Què posar |
|---|---|
| Nom de la clau (capçalera) | Authorization |
| Valor | Bearer cai_live_TU_CLAVE — amb la paraula Bearer i l'espai |
| On va | A la capçalera, no a la consulta |
L'errada més repetida muntant això és posar només la clau, sense Bearer al davant. Surt un 401 no_autenticado i sembla que la clau està malament quan el que falta és una paraula.
Un escenari complet: d'una comanda a una factura
Quatre mòduls. El primer canvia segons d'on vingui la comanda; els altres tres són sempre els mateixos.
| # | Mòdul | Què fa |
|---|---|---|
| 1 | Activador | Un webhook personalitzat al qual apunta la teva botiga, o el mòdul de vigilància de l'app que facis servir. Aquí entra la comanda. |
| 2 | HTTP · petició amb clau | POST a /contactos. Cos JSON amb nom, NIF i correu de la comanda. |
| 3 | HTTP · petició amb clau | POST a /facturas amb les línies i l'id del contacte del pas 2. |
| 4 | HTTP · petició amb clau | POST a /facturas/{id}/emitir, amb l'id del pas 3. |
El cos del pas 3, tal qual s'enganxa al camp de contingut del mòdul, substituint el que hi ha entre claus pel que porti el teu activador:
{
"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 aquests noms tal qual. Els quatre que s'escriuen malament sempre són fecha_emision (no «fecha»), descripcion (no «concepto»), tipo_iva (no «iva») i, al pas 2, tipo amb valor customer (no «cliente»). L'API no ignora un camp que no coneix: retorna 422 anomenant-lo, així que si un mòdul es posa vermell amb aquest codi, el primer és mirar error.detalles.campos.
I a capçaleres de cada mòdul, dues, a més de la que posa la connexió:
Content-Type: application/json
Idempotency-Key: make-1042La clau d'idempotència, que a Make importa més que enlloc
Make reintenta escenaris, i aquest és tot el problema
Un escenari que falla a mitges es pot tornar a executar, sencer, des de la cua d'incomplets. Si el mòdul que va fallar era el quart, els tres primers s'executen un altre cop, i el segon crea un altre contacte i el tercer una altra factura. Amb la capçalera posada, la segona execució retorna la mateixa factura i no passa res.
La clau ha de sortir de l'identificador de la comanda de l'activador, no d'una funció d'aleatori ni de la data actual: si canvia entre l'execució i la repetició, no serveix de res. I una de diferent per operació: make-1042 per crear la factura i make-1042-emitir per emetre-la.
Per què això importa tant i què passa quan falta, a idempotència.
Control d'errors
Sense control d'errors, un mòdul que retorna 422 atura l'escenari i el mana a la cua. Amb ell, es pot decidir què fer, i la decisió no és la mateixa per a tots els codis:
| El que retorna Cairos | Què posar al gestor d'errors |
|---|---|
429 o 500 | Reintentar. Són els dos únics que té sentit repetir, i amb la clau posada repetir és gratis. |
422 datos_invalidos | Ignorar i avisar un canal. La dada ve malament de l'altre sistema i repetir donarà el mateix error. error.detalles diu quin camp. |
401 o 403 | Parar i avisar. És la connexió o el scope: reintentar només consumeix operacions. |
Els set codis, amb quins es reintenten, són a errors i límits.
I un consell que estalvia operacions del teu pla: no muntis un escenari que consulti Cairos cada cinc minuts per si hi ha res nou. Subscriu-te a un webhook i que l'escenari arrenqui quan passi alguna cosa. És més barat, més ràpid i no gasta el límit de l'API.
Si això et costarà més d'una tarda, mira n8n
No és una recomanació en contra de Make: és que n8n té un node de codi on comprovar la signatura d'un webhook, i a Make això és més incòmode. Si només vas a cridar Cairos, Make va perfectament; si a més vas a rebre esdeveniments signats, l'altre et donarà menys guerra.
Preguntes sobre Make
Authorization i el valor Bearer més la clau. Així queda al clauer de Make i no escrita a l'escenari, on la veuria qualsevol del teu equip.Bearer i l'espai davant de la clau. És l'errada número u muntant això.Idempotency-Key això vol dir una segona factura; amb ella, la segona execució retorna la primera factura i no duplica res.POST /webhooks. És molt millor que consultar cada pocs minuts, que gasta operacions per assabentar-se que no ha passat res.openapi.json?version=3.0: Make encara no digereix el type: ["string","null"] d'OpenAPI 3.1 i o s'encalla en importar o et deixa mal tipats els camps que poden venir buits. És el mateix contracte, traduït.Munta l'escenari i prova'l amb una clau de proves
Les rutes i els cossos són els que accepta el servidor avui. Crea una clau cai_test_ i llança l'escenari: no registra a VeriFactu ni envia correus.
Mòdul HTTP · Connexió per clau · Idempotency-Key de la comanda