Constaia
Integraciones

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:

CampoValor
NameAuthorization
ValueBearer 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

CampoValor
MethodPOST
URLhttps://api.constaia.com/v1/analyze
AuthenticationGeneric Credential Type
Generic Auth TypeHeader Auth → Constaia (test)
Send Bodyactivado
Body Content TypeForm-Data

En Body Parameters añade dos parámetros:

Parameter TypeNameValor
n8n Binary FilefileInput Data Field Name: data (la propiedad binaria que trae el nodo anterior)
Form Dataoptionsel JSON de opciones, como texto

Un valor típico para options:

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.

SalidaQué hacer
VálidoContinuar: guardar los datos de {{ $json.fields }}, aprobar la solicitud…
No válidoRechazar y enviar al usuario {{ $json.verdict.reasons }} (el message ya viene en el idioma de language).
RevisarCrear 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:

Body (JSON)
{
  "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.jpg o blurry.jpg).
  • Con JSON, pasa "filename": "dni_valid.jpg": sustituye al nombre que Constaia deduce de la URL.
FicheroCon expect: "es_dni"
dni_valid.jpgVálido
dni_expired.jpgNo válido motivo not_expired con severidad error
blurry.jpgRevisar 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

CampoValor
HTTP MethodPOST
Pathpor ejemplo constaia
RespondImmediately
Options → Raw Bodyactivado

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.

Terminal
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:

Code: verificar firma
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 expect y checks en 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; con storage: "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

En esta página