n8n

n8n se ejecuta en tu servidor (o en n8n Cloud), así que la clave queda guardada como credencial y nunca llega a quien sube el documento. Esta guía usa el nodo genérico HTTP Request.

RequisitosCopy Anchor Link

• n8n 1.x (self-hosted o Cloud).
• Una clave de test ck_test_… del panel.
• Un nodo anterior que aporte el documento como dato binario: Form Trigger con un campo de fichero, un adjunto de Gmail u Outlook, Read/Write Files from Disk, Google Drive…

1. CredencialCopy Anchor Link

En Credentials → New → Header Auth:

Llámala, por ejemplo, Constaia (test). Cuando pases a producción, crea otra con la clave ck_live_….

2. Nodo HTTP RequestCopy Anchor Link

Parámetros del cuerpo:

{
  "expect": "es_dni",
  "checks": { "not_expired": true, "holder": { "full_name": "{{ $json.full_name }}" } },
  "storage": "none",
  "language": "es"
}

Las opciones van en snake_case, como en la API. Si el nombre del titular viene de un paso anterior, usa una expresión como la de arriba; si no, quita holder.

Si el documento está en una URL en lugar de en un binario, cambia Body Content Type a JSON y envía:

{ "file_url": "https://…/dni.jpg", "expect": "es_dni", "checks": { "not_expired": true }, "storage": "none" }

3. Enrutar según el veredictoCopy Anchor Link

Añade un nodo Switch con la regla {{ $json.verdict.status }} y tres salidas:

Para errores de la API (clave incorrecta, formato no admitido, créditos agotados), activa Settings → On Error → Continue (using error output) en el nodo HTTP Request y trata esa salida aparte.

4. Recibir webhooks (opcional)Copy Anchor Link

Para análisis con "async": true, crea un flujo con un nodo Webhook (método POST, opción Raw Body activada) y registra su URL de producción en el panel de Constaia. Verifica la firma en un nodo Code antes de seguir:

const crypto = require("crypto"); // requiere NODE_FUNCTION_ALLOW_BUILTIN=crypto
const { headers } = $input.first().json;
const body = (await this.helpers.getBinaryDataBuffer(0, "data")).toString("utf8");
const secret = Buffer.from($env.CONSTAIA_WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64");

const signed = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${body}`;
const expected = crypto.createHmac("sha256", secret).update(signed).digest("base64");
const fresh = Math.abs(Date.now() / 1000 - Number(headers["webhook-timestamp"])) <= 300;
const valid = headers["webhook-signature"].split(" ").some((s) => s === `v1,${expected}`);
if (!fresh || !valid) throw new Error("Firma de Constaia no válida");

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

Según tu instalación, puede que tengas que permitir el acceso a variables de entorno desde los nodos (N8N_BLOCK_ENV_ACCESS_IN_NODE=false). Detalles de la firma en Webhooks.

Probar en modo testCopy Anchor Link

Con la credencial ck_test_…, pasa al nodo HTTP Request un binario llamado dni_valid.jpg (valid), dni_expired.jpg (invalid, motivo expired) o blurry.jpg (review). El nombre del fichero binario es lo que decide el resultado, así que comprueba que el nodo anterior lo conserva.

Siguiente pasoCopy Anchor Link

• Webhooks para flujos asíncronos y lotes.
• Tipos de documento para cambiar expect por certificados médicos, justificantes de pago y más.