n8n
Valida documentos desde n8n con el nodo HTTP Request (multipart o JSON), enruta por veredicto y recibe webhooks de Constaia verificando la firma.
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 nodos estándar: HTTP Request para llamar a la API, Switch o IF para enrutar según el veredicto y Webhook + Code para recibir eventos.
Próximamente
El nodo oficial de Constaia para n8n está en desarrollo. Hasta entonces, el nodo HTTP Request cubre toda la API.
Requisitos
- n8n 1.x (self-hosted o Cloud).
- Una clave de test
ck_test_…del panel. Consulta Autenticación. - Un nodo anterior que aporte el documento como dato binario (Form Trigger con un campo de fichero, adjunto de
Gmail u Outlook, Google Drive, Read/Write Files from Disk…) o una URL
https://descargable del fichero.
Analizar un documento
Crea la credencial
En Credentials → Add credential → Header Auth:
| Campo | Valor |
|---|---|
| Name | Authorization |
| Value | Bearer ck_test_… |
Llámala, por ejemplo, Constaia (test). Para producción crea otra con la clave ck_live_… y cambia la
credencial del nodo cuando el flujo esté probado.
Configura el nodo HTTP Request
| Campo | Valor |
|---|---|
| Method | POST |
| URL | https://api.constaia.com/v1/analyze |
| Authentication | Generic Credential Type |
| Generic Auth Type | Header Auth → Constaia (test) |
| Send Body | activado |
| Body Content Type | Form-Data |
En Body Parameters añade dos parámetros:
| Parameter Type | Name | Valor |
|---|---|---|
n8n Binary File | file | Input Data Field Name: data (la propiedad binaria que trae el nodo anterior) |
Form Data | options | el JSON de opciones, como texto |
Un valor típico para options:
{
"expect": ["es_dni", "es_nie", "passport"],
"checks": { "min_age_years": 18 },
"language": "es",
"metadata": { "source": "n8n" }
}Puedes usar expresiones dentro del JSON, por ejemplo para comprobar el titular con datos del formulario:
"holder": { "full_name": "{{ $json.nombre }}" } dentro de checks. Todas las opciones están en
POST /v1/analyze y los checks en Checks.
Enruta según el veredicto
Añade un nodo Switch (modo Rules) con el valor {{ $json.verdict.status }} y tres reglas
String → is equal to: valid, invalid y review. Si solo necesitas dos salidas, un nodo IF con la misma
expresión y la condición is equal to valid es suficiente.
| Salida | Qué hacer |
|---|---|
| Válido | Continuar: guardar los datos de {{ $json.fields }}, aprobar la solicitud… |
| No válido | Rechazar y enviar al usuario {{ $json.verdict.reasons }} (el message ya viene en el idioma de language). |
| Revisar | Crear una tarea para una persona (Slack, email, tu CRM). Ver Revisión humana. |
Cada campo extraído es un objeto: el valor está en {{ $json.fields.document_number.value }} y la confianza en
{{ $json.fields.document_number.confidence }}. El significado de cada estado está en
Veredictos.
Controla los errores
Si la API responde con un error (401, 402, 413, 422, 429…), el nodo falla. En Settings → On Error elige
Continue (using error output) para llevar esos casos a una rama propia. El cuerpo del error sigue el formato
{ "error": { "type", "code", "message", "param", "request_id" } }; guarda request_id si necesitas soporte.
Los códigos están en Errores.
Ten en cuenta también la respuesta 202: si el análisis no termina en 30 s (PDFs largos), la API devuelve el
análisis con status: "queued" o "processing" y verdict todavía vacío. Añade una condición sobre
{{ $json.status }} igual a completed antes del Switch, o usa async: true y recibe el resultado por webhook
(más abajo).
Alternativa: cuerpo JSON con file_url
Si el documento ya está en una URL https:// pública o firmada (por ejemplo, un enlace temporal de tu almacenamiento),
no hace falta descargarlo en n8n. En el nodo HTTP Request usa Body Content Type JSON, Specify Body
Using JSON y:
{
"file_url": "{{ $json.document_url }}",
"filename": "{{ $json.document_name }}",
"options": {
"expect": "payment_receipt",
"checks": { "expected_amount": 45, "expected_reference": "INSCRIPCION 123" }
}
}Constaia descarga el fichero con un límite de 20 MB y 15 s; solo acepta https y rechaza IPs privadas. También
puedes enviar el fichero en base64 con file_base64 + filename en lugar de file_url.
Probar en modo test
Con una clave ck_test_… la respuesta depende del nombre del fichero, no de su contenido, y no se consumen
créditos. El fichero tiene que ser un JPEG, PNG, WEBP, HEIC o PDF real.
- Con multipart, renombra el binario antes del nodo HTTP Request (por ejemplo, sube un fichero llamado
dni_valid.jpg,dni_expired.jpgoblurry.jpg). - Con JSON, pasa
"filename": "dni_valid.jpg": sustituye al nombre que Constaia deduce de la URL.
| Fichero | Con expect: "es_dni" |
|---|---|
dni_valid.jpg | Válido |
dni_expired.jpg | No válido motivo not_expired con severidad error |
blurry.jpg | Revisar motivo low_quality con severidad warning |
Así pruebas las tres ramas del Switch. Todos los escenarios están en Modo test.
Recibir eventos por webhook
Para análisis asíncronos (async: true), lotes o avisos de saldo, Constaia llama a una URL tuya.
Crea el nodo Webhook
| Campo | Valor |
|---|---|
| HTTP Method | POST |
| Path | por ejemplo constaia |
| Respond | Immediately |
| Options → Raw Body | activado |
Raw Body es imprescindible: la firma se calcula sobre el cuerpo exacto, byte a byte, y el nodo lo deja como
dato binario (propiedad data; compruébalo en la salida del nodo). Responder de inmediato devuelve un 2xx rápido;
Constaia da por fallida la entrega si no recibe un 2xx en 15 s.
Registra el endpoint
Copia la Production URL del nodo (activa el flujo) y regístrala en el panel o por API. El endpoint recibe solo eventos del modo de la clave con que lo creas.
curl https://api.constaia.com/v1/webhook-endpoints \
-H "Authorization: Bearer $CONSTAIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://n8n.example.com/webhook/constaia","events":["analysis.completed","analysis.failed","analysis.review_required"]}'La respuesta incluye secret: "whsec_…" solo esta vez. Guárdalo.
Verifica la firma en un nodo Code
Añade un nodo Code (JavaScript, Run Once for All Items) justo después del Webhook:
const crypto = require("crypto");
const secret = $env.CONSTAIA_WEBHOOK_SECRET; // whsec_…
const headers = $input.first().json.headers;
const raw = await this.helpers.getBinaryDataBuffer(0, "data");
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"];
if (!id || !timestamp || !signatures) throw new Error("Faltan cabeceras de firma");
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) throw new Error("Timestamp fuera de tolerancia");
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = crypto
.createHmac("sha256", key)
.update(Buffer.concat([Buffer.from(`${id}.${timestamp}.`), raw]))
.digest();
const valid = signatures.split(" ").some((entry) => {
const [version, signature] = entry.split(",");
if (version !== "v1" || !signature) return false;
const received = Buffer.from(signature, "base64");
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
if (!valid) throw new Error("Firma no válida");
const event = JSON.parse(raw.toString("utf8"));
return [{ json: { webhook_id: id, ...event } }];Si la firma no es válida, el nodo lanza un error y la ejecución se detiene: nada de lo que viene después se procesa.
A continuación, un Switch sobre {{ $json.type }} separa analysis.completed, analysis.review_required,
analysis.failed y batch.completed; el análisis está en {{ $json.data }}.
Descarta duplicados
Constaia reintenta las entregas fallidas durante unos 3 días, siempre con el mismo webhook-id. Guarda los
webhook_id procesados (en tu base de datos o con el nodo Remove Duplicates en modo Remove Items Processed
in Previous Executions, si tu versión lo incluye) y descarta los repetidos.
Requisitos del nodo Code
En n8n self-hosted, require("crypto") necesita la variable de entorno NODE_FUNCTION_ALLOW_BUILTIN=crypto y
$env necesita que el acceso a variables de entorno no esté bloqueado (N8N_BLOCK_ENV_ACCESS_IN_NODE=false).
Si tu instancia no permite ninguna de las dos cosas, no verifiques la firma en n8n: usa solo data.id del evento
y vuelve a leer el análisis con un HTTP Request a GET https://api.constaia.com/v1/analyses/{{ $json.data.id }}
con tu credencial. Esa respuesta viene de la API con tu clave y es la fuente de verdad.
El formato completo de los eventos, la política de reintentos y el algoritmo de firma están en Webhooks.
Seguridad
- No pegues nunca una clave
ck_live_…en un campo de texto, en el JSON del cuerpo ni en una nota del flujo: usa siempre la credencial Header Auth. Al exportar o compartir un workflow, las credenciales no viajan con él. - Usa claves de test mientras construyes el flujo y una credencial distinta para live.
- Si recibes documentos desde un Form Trigger público, decide
expectychecksen el flujo, no a partir de lo que envía el usuario. - Por defecto (
storage: "review") Constaia solo guarda el fichero, cifrado, si hay que revisarlo, y lo borra al decidir; constorage: "none"no lo guarda nunca. Revisa también qué guarda n8n: el historial de ejecuciones conserva los binarios y los datos extraídos. Ajusta la retención de ejecuciones si procesas documentos de identidad. Más en Almacenamiento y privacidad.
Límites
- 20 MB por fichero; PDFs de hasta 30 páginas en síncrono y hasta 200 con
async: true. - 2 peticiones por segundo por clave en el plan gratuito (10 en el de pago). Si procesas muchos elementos, activa Options → Batching en
el nodo HTTP Request (por ejemplo, 5 elementos cada 1000 ms). Ante un 429, respeta la cabecera
Retry-After. Detalles en Límites de uso. - Para decenas de documentos de golpe, POST /v1/batches evita el goteo de peticiones.
Siguientes pasos
Flutter
Valida documentos desde una app Flutter con image_picker enviando la foto a tu backend, que llama a Constaia; incluye un servidor Dart con shelf.
Make
Valida documentos en Make con el módulo HTTP en multipart/form-data, enruta por veredicto con un Router y recibe eventos de Constaia con un webhook.