Hono

Valida documentos con Hono 4 y el SDK de Constaia en Node.js, Bun o Deno, con la misma app, límite de cuerpo y webhook verificado.

Vas a escribir una única app de Hono 4 con dos rutas y a ejecutarla en Node.js, Bun o Deno sin cambiar el código:

POST /api/verify-dni: recibe un fichero, lo analiza con Constaia y devuelve el veredicto.
POST /webhooks/constaia: verifica la firma sobre el cuerpo crudo y descarta duplicados.

Hono trabaja con Request/Response estándar y el SDK usa fetch y WebCrypto, así que encajan sin adaptadores. La clave vive solo en el servidor.

Instalación

npm i hono @hono/node-server @constaia/sdk
npm i -D typescript tsx

Variables de entorno

.env

CONSTAIA_API_KEY=ck_test_...
CONSTAIA_WEBHOOK_SECRET=whsec_...

La clave se crea en el panel → API keys. El secreto del webhook se muestra una sola vez al crear el endpoint (Webhooks). Cada runtime lee el entorno a su manera, por eso la app recibe la configuración como parámetro.

Utilidades compartidas

Recortan la respuesta que ve el navegador, traducen los errores del SDK a Response y procesan los eventos del webhook.

src/constaia.ts

import {
  AuthenticationError,
  ConstaiaError,
  InsufficientCreditsError,
  InvalidRequestError,
  PermissionError,
  RateLimitError,
  type Analysis,
  type WebhookEvent,
} from "@constaia/sdk";

// Lo que devuelves al navegador (y lo que pinta el widget): sin los campos extraídos.
export function publicResult(analysis: Analysis) {
  const { id, object, status, document, verdict, warnings } = analysis;
  return { id, object, status, document, verdict, warnings };
}

const httpError = (status: number, code: string, message: string, retryAfter?: number) =>
  Response.json(
    { error: { code, message } },
    { status, headers: retryAfter ? { "Retry-After": String(retryAfter) } : undefined },
  );

export function errorResponse(error: unknown): Response {
  if (error instanceof InvalidRequestError) {
    // Fichero ilegible, formato no admitido, demasiadas páginas…: el usuario puede corregirlo.
    return httpError(error.status === 413 ? 413 : 422, error.code ?? "invalid_request", error.message);
  }
  if (error instanceof RateLimitError) {
    const wait = Math.ceil(error.retryAfter ?? 1);
    return httpError(429, "rate_limited", "Demasiadas peticiones. Inténtalo en unos segundos.", wait);
  }
  if (error instanceof InsufficientCreditsError) {
    console.error("[constaia] Sin créditos. Recarga en https://app.constaia.com", error.requestId);
    return httpError(503, "unavailable", "La validación no está disponible ahora mismo.");
  }
  if (error instanceof AuthenticationError || error instanceof PermissionError) {
    console.error("[constaia] Revisa CONSTAIA_API_KEY", error.code, error.requestId);
    return httpError(500, "misconfigured", "Error de configuración del servidor.");
  }
  if (error instanceof ConstaiaError) {
    // APIError (5xx), APIConnectionError, APITimeoutError
    console.error("[constaia]", error.name, error.code, error.requestId);
    return httpError(502, "upstream_error", "No se ha podido analizar el documento. Inténtalo de nuevo.");
  }
  console.error(error);
  return httpError(500, "internal_error", "Error interno.");
}

// Deduplicación por webhook-id. En producción, una tabla con clave única.
const processed = new Set<string>();
export const alreadyProcessed = (webhookId: string) => processed.has(webhookId);
export const markProcessed = (webhookId: string) => void processed.add(webhookId);

export async function handleEvent(event: WebhookEvent) {
  switch (event.type) {
    case "analysis.completed":
      // event.data es el análisis completo (con fields). Guárdalo por event.data.id.
      console.log("analysis.completed", event.data.id, event.data.verdict?.status);
      break;
    case "analysis.review_required":
      console.log("A revisión manual", event.data.id);
      break;
    case "analysis.failed":
      console.warn("analysis.failed", event.data.id, event.data.error?.code);
      break;
    case "credits.low":
      console.warn("Quedan pocos créditos: recarga en https://app.constaia.com");
      break;
  }
}

La app

src/app.ts

import { Hono } from "hono";
import { bodyLimit } from "hono/body-limit";
import { Constaia, WebhookVerificationError } from "@constaia/sdk";
import { alreadyProcessed, errorResponse, handleEvent, markProcessed, publicResult } from "./constaia.ts";

export function createApp(config: { apiKey: string; webhookSecret: string }) {
  const constaia = new Constaia({ apiKey: config.apiKey });
  const app = new Hono();

  // Aquí va tu middleware de autenticación y de rate limit: cada llamada gasta créditos.
  app.post(
    "/api/verify-dni",
    bodyLimit({
      maxSize: 21 * 1024 * 1024,
      onError: (c) => c.json({ error: { code: "file_too_large", message: "Máximo 20 MB." } }, 413),
    }),
    async (c) => {
      const body = await c.req.parseBody();
      const file = body.file;
      if (!(file instanceof File) || file.size === 0) {
        return c.json({ error: { code: "missing_file", message: "Falta el fichero." } }, 400);
      }
      // Mejor aún: el nombre del usuario autenticado, no el del formulario.
      const fullName = typeof body.full_name === "string" ? body.full_name.trim() : "";

      try {
        const analysis = await constaia.analyze(file, {
          expect: "es_dni",
          checks: { notExpired: true, ...(fullName ? { holder: { fullName } } : {}) },
          storage: "none",
          language: "es",
        });
        // Guarda analysis.id y analysis.verdict en tu base de datos.
        return c.json(publicResult(analysis), analysis.status === "completed" ? 200 : 202);
      } catch (error) {
        return errorResponse(error);
      }
    },
  );

  app.post("/webhooks/constaia", async (c) => {
    const rawBody = await c.req.text();
    let event;
    try {
      event = await constaia.webhooks.verify(rawBody, c.req.raw.headers, config.webhookSecret);
    } catch (error) {
      if (error instanceof WebhookVerificationError) return c.text("Invalid signature", 400);
      throw error;
    }

    const webhookId = c.req.header("webhook-id")!;
    if (!alreadyProcessed(webhookId)) {
      await handleEvent(event);
      markProcessed(webhookId);
    }
    return c.body(null, 200);
  });

  return app;
}

File conserva el nombre original, así que no hace falta pasar filename. En modo test ese nombre decide la respuesta.
c.req.text() devuelve el cuerpo exacto. No leas antes c.req.json(): el cuerpo solo se puede consumir una vez y reserializarlo rompe la firma.
El servidor fija expect y checks. El widget envía options con una pista de expect que esta ruta ignora a propósito.

Arrancar en cada runtime

src/node.ts

import { serve } from "@hono/node-server";
import { createApp } from "./app.ts";

const app = createApp({
  apiKey: process.env.CONSTAIA_API_KEY!,
  webhookSecret: process.env.CONSTAIA_WEBHOOK_SECRET!,
});

serve({ fetch: app.fetch, port: 3000 });

npx tsx --env-file=.env src/node.ts

Qué recibe el navegador

{
  "id": "an_01J…",
  "object": "analysis",
  "status": "completed",
  "document": { "type": "es_dni", "label": "DNI (España)", "confidence": 0.97, "side": "both", "country": "ESP" },
  "verdict": {
    "expected": ["es_dni"],
    "match": true,
    "status": "valid",
    "reasons": [
      { "code": "type_match", "severity": "info", "message": "El documento es DNI (España)." },
      { "code": "not_expired", "severity": "info", "message": "Vigente hasta el 12/03/2031." },
      { "code": "holder", "severity": "info", "message": "Los datos del titular coinciden (full_name)." }
    ]
  },
  "warnings": []
}

Errores

Error del SDK	Cuándo	Qué devuelve tu ruta
`InvalidRequestError`	Fichero vacío, ilegible, formato no admitido, más de 20 MB, demasiadas páginas u opciones mal formadas (400/409/413/415/422)	422 (o 413) con el mensaje, para que el usuario suba otro fichero
`RateLimitError`	Superas las peticiones por segundo de tu clave (429). El SDK ya reintenta dos veces respetando `Retry-After`	429 con `Retry-After`
`InsufficientCreditsError`	No quedan créditos (402)	503 al usuario y una alerta para ti: recarga en el panel
`AuthenticationError`, `PermissionError`	Clave ausente, revocada o incorrecta (401/403)	500: es un fallo de configuración tuyo, no del usuario
`APIError`, `APIConnectionError`, `APITimeoutError`	Error 5xx de Constaia o de red, tras agotar los reintentos	502 y un mensaje de reintentar

Todas extienden ConstaiaError y exponen status, code y requestId. Registra siempre el requestId: es lo que te pedirá soporte. Detalle de cada código en Errores.

Probar en modo test

curl -F "file=@dni_valid.jpg" -F "full_name=María García López" http://localhost:3000/api/verify-dni

Fichero	`full_name`	Resultado
`dni_valid.jpg`	`María García López`	`valid`
`dni_valid.jpg`	`Juan Pérez`	`invalid`: motivo `holder` con severidad `error`
`dni_expired.jpg`	(vacío)	`invalid`: `not_expired` con el mensaje "Caducado el 15/06/2020."
`blurry.jpg`	(vacío)	`review`: motivo `low_quality` y `warnings: ["blurry", "low_quality"]`
`factura.jpg`	(vacío)	`invalid`: `type_mismatch`, no es un DNI

En modo test la respuesta depende del nombre del fichero, que debe ser un JPEG, PNG, WEBP, HEIC o PDF real (vale cualquier imagen renombrada). No gasta créditos y livemode es false. Todos los nombres en Modo test.

Hono permite probar el webhook sin servidor con app.request:

test/webhook.test.ts

import { signWebhook } from "@constaia/sdk";
import { createApp } from "../src/app.ts";

const secret = process.env.CONSTAIA_WEBHOOK_SECRET!;
const app = createApp({ apiKey: "ck_test_...", webhookSecret: secret });

const body = JSON.stringify({
  type: "analysis.completed",
  created_at: new Date().toISOString(),
  data: { id: "an_test", object: "analysis", status: "completed", verdict: { status: "valid", reasons: [] } },
});
const headers = await signWebhook(body, secret);

const res = await app.request("/webhooks/constaia", {
  method: "POST",
  headers: { ...headers, "content-type": "application/json" },
  body,
});
console.log(res.status); // 200

Checklist de producción

Autenticación y rate limit por usuario en /api/verify-dni.
Límite de cuerpo de al menos 20 MB en la app (bodyLimit), en el runtime (Bun: maxRequestBodySize) y en el proxy.
Timeouts de 60 s o más en proxy y runtime (Bun: idleTimeout); un análisis síncrono puede tardar hasta 30 s.
PDF de más de 30 páginas o volumen alto: async: true y resultado por webhook.
Clave ck_live_ solo en el entorno del servidor.
Alerta ante InsufficientCreditsError y el evento credits.low.

Instalación

Variables de entorno

Utilidades compartidas

La app

Arrancar en cada runtime

Qué recibe el navegador

Errores

Probar en modo test

Checklist de producción

Siguientes pasos

Widget de subida

Webhooks

Errores

Bun

En esta página

Hono

InstalaciónCopy Anchor Link

Variables de entornoCopy Anchor Link

Utilidades compartidasCopy Anchor Link

La appCopy Anchor Link

Arrancar en cada runtimeCopy Anchor Link

Qué recibe el navegadorCopy Anchor Link

ErroresCopy Anchor Link

Probar en modo testCopy Anchor Link

Checklist de producciónCopy Anchor Link

Siguientes pasosCopy Anchor Link

Widget de subida

Webhooks

Errores

Bun

En esta página

Instalación

Variables de entorno

Utilidades compartidas

La app

Arrancar en cada runtime

Qué recibe el navegador

Errores

Probar en modo test

Checklist de producción

Siguientes pasos