n8n: HTTP Request para llamar y Code para verificar

La credencial, que se monta una vez

n8n no tiene nodo de Cairos, y no hace falta: el nodo HTTP Request llama a cualquier API. Lo que sí conviene montar bien desde el principio es la credencial, para no repetir la clave en cada nodo ni dejarla escrita en el flujo.

Se crea una credencial de tipo Header Auth con estos dos valores:

Name:  Authorization
Value: Bearer cai_live_TU_CLAVE

A partir de ahí, cada nodo HTTP Request usa esa credencial y no vuelve a saber nada de la clave. Cuando la rotes, se cambia en un sitio.

Llamar a Cairos

Un nodo HTTP Request por operación. Lo que hay que rellenar es siempre lo mismo:

Y activa el reintento del propio nodo sólo si has puesto la llave de idempotencia. Un reintento de un POST sin llave es la forma más rápida de acabar con dos facturas.

El cuerpo, en modo JSON, con las expresiones de n8n para tomar los datos del nodo anterior:

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

Recibir sucesos de Cairos, que es donde n8n brilla

Aquí es donde n8n gana a las alternativas sin código: tiene un nodo de código donde se puede comprobar la firma de un webhook, que es lo único que no es negociable al abrir un extremo público.

El montaje son tres nodos:

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;
const cabecera = entrada.headers["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) }];

Cómo se calcula esa firma y por qué la marca de tiempo va dentro está en webhooks. Y la dirección que te da el nodo Webhook es la que se registra con POST /webhooks.

Recorrer listas largas

Para leer todas las facturas de un año no vale una sola llamada: la API pagina con cursor. En n8n eso se monta con el paginado del propio nodo HTTP Request, o a mano con un bucle:

• Pide con ?limite=200.
• Guarda siguiente de la respuesta.
• Vuelve a pedir con ?desde= y ese valor.
• Para cuando siguiente venga a null, no cuando datos venga vacío.

El detalle de la paginación, con el bucle escrito en JavaScript y en PHP, está en errores y paginación.