n8n: HTTP Request to call and Code to verify

The credential, set up once

n8n has no Cairos node, and it does not need one: the HTTP Request node calls any API. What is worth setting up properly from the start is the credential, so as not to repeat the key in every node or leave it written into the flow.

You create a Header Auth credential with these two values:

Name:  Authorization
Value: Bearer cai_live_TU_CLAVE

From then on, each HTTP Request node uses that credential and never knows anything about the key again. When you rotate it, it changes in one place.

Calling Cairos

One HTTP Request node per operation. What you have to fill in is always the same:

And turn the node's own retry on only if you have set the idempotency key. A retry of a POST with no key is the quickest way to end up with two invoices.

The body, in JSON mode, with n8n's expressions to take the data from the previous node:

{
  "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
    }
  ]
}

The names go exactly as they are: fecha_emision, descripcion and tipo_iva. A field that does not exist is not ignored; it returns 422 and names it in error.detalles.campos, so that is the first place to look when the node goes red.

Receiving Cairos events, which is where n8n shines

This is where n8n beats the no-code alternatives: it has a code node where you can check a webhook's signature, which is the one thing that is not negotiable when you open a public endpoint.

The setup is three 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) }];

How that signature is worked out and why the timestamp goes inside it is in webhooks. And the address the Webhook node gives you is the one you register with POST /webhooks.

Working through long lists

To read all of a year's invoices one call is not enough: the API paginates with a cursor. And here n8n makes it easy, because siguiente is already the complete URL of the next page, with your filters inside it: there is no query to reassemble.

• Ask with ?limite=200&orden=antiguo, which is the order that does not shift while you are working through it.
• Take siguiente from the response and use it as the URL exactly as it comes. It is not the id of the last item, and it is not a cursor to be pasted by hand into ?desde=: it is the complete address.
• Stop when siguiente comes back as null, not when datos comes back empty.

In the HTTP Request node's own pagination that is configured with the “next URL” mode and the expression {{ $response.body.siguiente }}, and the stop condition is that field being null.

The detail on pagination, with the loop written in JavaScript and in PHP, is in errors and pagination.