n8n: HTTP Request per cridar i Code per verificar

La credencial, que es munta un sol cop

n8n no té node de Cairos, i no cal: el node HTTP Request crida qualsevol API. El que sí que convé muntar bé des del principi és la credencial, per no repetir la clau a cada node ni deixar-la escrita al flux.

Es crea una credencial de tipus Header Auth amb aquests dos valors:

Name:  Authorization
Value: Bearer cai_live_TU_CLAVE

A partir d'aquí, cada node HTTP Request fa servir aquesta credencial i no torna a saber res de la clau. Quan la rotis, es canvia en un sol lloc.

Cridar Cairos

Un node HTTP Request per operació. El que cal omplir és sempre el mateix:

I activa el reintent del mateix node només si has posat la clau d'idempotència. Un reintent d'un POST sense clau és la manera més ràpida d'acabar amb dues factures.

El cos, en mode JSON, amb les expressions d'n8n per prendre les dades del node anterior:

{
  "contacto_id": "{{ $json.id }}",
  "serie": "WEB",
  "fecha_emision": "{{ $now.format('yyyy-MM-dd') }}",
  "lineas": [
    {
      "descripcion": "{{ $('Pedido').item.json.titulo }}",
      "cantidad": 1,
      "precio": 180.00,
      "tipo_iva": 21
    }
  ]
}

Els noms van tal qual: fecha_emision, descripcion i tipo_iva. Un camp que no existeix no s'ignora, retorna 422 i el nomena a error.detalles.campos, així que aquest és el primer lloc on mirar quan el node es posa vermell.

Rebre esdeveniments de Cairos, que és on n8n brilla

Aquí és on n8n guanya les alternatives sense codi: té un node de codi on es pot comprovar la signatura d'un webhook, que és l'única cosa que no és negociable en obrir un extrem públic.

El muntatge són tres nodes:

const crypto = require("crypto");

const secreto = $env.CAIROS_SECRETO;
const entrada = $input.first().json;

// El cuerpo CRUDO, tal y como llegó. Si aquí usas el JSON ya
// convertido, la firma no cuadrará nunca y perderás una tarde.
const crudo = entrada.rawBody || entrada.body;
// La cabecera se llama "x-cairos-firma", en minuscula.
const cabecera = entrada.headers["x-cairos-firma"] || "";

const partes = Object.fromEntries(
  cabecera.split(",").map((t) => t.trim().split("="))
);

const ahora = Math.floor(Date.now() / 1000);
if (!partes.t || Math.abs(ahora - Number(partes.t)) > 300) {
  throw new Error("Suceso caducado o sin marca de tiempo");
}

const esperada = crypto
  .createHmac("sha256", secreto)
  .update(partes.t + "." + crudo)
  .digest("hex");

if (esperada !== partes.v1) {
  throw new Error("Firma no valida");
}

return [{ json: JSON.parse(crudo) }];

Com es calcula aquesta signatura i per què la marca de temps va a dins és a webhooks. I l'adreça que et dóna el node Webhook és la que es registra amb POST /webhooks.

Recórrer llistes llargues

Per llegir totes les factures d'un any no serveix una sola crida: l'API pagina amb cursor. I aquí n8n ho posa fàcil, perquè siguiente ja és la URL sencera de la pàgina que segueix, amb els teus filtres a dins: no cal recompondre cap consulta.

• Demana amb ?limite=200&orden=antiguo, que és l'ordre que no es mou mentre el recorres.
• Agafa siguiente de la resposta i fes-lo servir com a URL tal qual. No és l'id de l'últim element ni un cursor que s'hagi d'enganxar a mà a ?desde=: és l'adreça completa.
• Para quan siguiente vingui a null, no quan datos vingui buit.

Al paginat del mateix node HTTP Request això es configura amb el mode de «següent URL» i l'expressió {{ $response.body.siguiente }}, i la condició d'aturada és que aquest camp sigui nul.

El detall de la paginació, amb el bucle escrit en JavaScript i en PHP, és a errors i paginació.