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_emision": "{{ $now.format('yyyy-MM-dd') }}",
  "lineas": [
    {
      "descripcion": "{{ $('Pedido').item.json.titulo }}",
      "cantidad": 1,
      "precio": 180.00,
      "tipo_iva": 21
    }
  ]
}

Los nombres van tal cual: fecha_emision, descripcion y tipo_iva. Un campo que no existe no se ignora, devuelve 422 y lo nombra en error.detalles.campos, así que ése es el primer sitio donde mirar cuando el nodo se pone rojo.

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;
// 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) }];

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. Y aquí n8n lo pone fácil, porque siguiente ya es la URL entera de la página que sigue, con tus filtros dentro: no hay que recomponer ninguna consulta.

• Pide con ?limite=200&orden=antiguo, que es el orden que no se mueve mientras recorres.
• Coge siguiente de la respuesta y úsalo como URL tal cual. No es el id del último elemento ni un cursor que haya que pegar a mano en ?desde=: es la dirección completa.
• Para cuando siguiente venga a null, no cuando datos venga vacío.

En el paginado del propio nodo HTTP Request eso se configura con el modo de «siguiente URL» y la expresión {{ $response.body.siguiente }}, y la condición de parada es que ese campo sea nulo.

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