Constaia

Widget de subida

Referencia de @constaia/widget, el web component <constaia-upload> para capturar documentos en el navegador sin exponer tu clave. React, Vue y cualquier framework.

@constaia/widget es un web component, <constaia-upload>, que captura un documento en el navegador, comprueba la calidad de la foto y lo envía a tu backend. Tu backend llama a Constaia con la clave y devuelve el resultado, que el widget muestra como Válido, No válido o Revisar con sus motivos. Versión actual: 0.2.0.

  • Sin dependencias, unos 14,4 kB comprimido (gzip). Funciona en cualquier framework, con wrappers para React y Vue.
  • Arrastrar y soltar, selector de ficheros y cámara en el móvil. JPEG, PNG, WEBP, HEIC y PDF de hasta 20 MB.
  • Guía de encuadre para tarjetas (ID-1), comprobación de calidad en el cliente y captura de anverso y reverso.
  • Progreso de subida real, accesible (teclado, aria-live, veredictos con icono y texto) y en es, en, pt, fr.

El widget nunca lleva la clave

Si cualquier atributo contiene algo parecido a una clave (ck_live_… o ck_test_…), el componente se niega a funcionar, muestra un error y emite constaia:error con el código secret_key_rejected.

Instalación

npm install @constaia/widget
import "@constaia/widget"; // registra <constaia-upload>

Cómo funciona

  1. El usuario elige o fotografía el documento. Para DNI, NIE e ID europeos el widget pide anverso y reverso y los une en una sola imagen JPEG.
  2. El widget comprueba la calidad (resolución, desenfoque, brillo) y avisa antes de subir.
  3. Envía POST multipart/form-data a tu endpoint con dos campos: file y options.
  4. Tu backend llama a POST /v1/analyze decidiendo él expect y checks, y devuelve el análisis en JSON.
  5. El widget muestra el veredicto, los motivos y los avisos, y emite constaia:result.

Ejemplo mínimo

index.html
<script type="module" src="https://cdn.jsdelivr.net/npm/@constaia/widget@0.2"></script>

<constaia-upload endpoint="/api/constaia" document="es_dni" lang="es"></constaia-upload>

<script type="module">
  const el = document.querySelector("constaia-upload");
  el.addEventListener("constaia:result", (e) => {
    console.log(e.detail.id, e.detail.verdict?.status); // "valid" | "invalid" | "review"
  });
  el.addEventListener("constaia:error", (e) => console.warn(e.detail.code, e.detail.message));
</script>

Y el backend (Node, con el SDK de JavaScript):

server.ts
import express from "express";
import multer from "multer";
import { Constaia, ConstaiaError } from "@constaia/sdk";

const app = express();
const upload = multer({ storage: multer.memoryStorage(), limits: { fileSize: 20 * 1024 * 1024 } });
const constaia = new Constaia();

app.post("/api/constaia", upload.single("file"), async (req, res) => {
  if (!req.file) return res.status(400).json({ error: { message: "Falta el documento." } });
  try {
    const analysis = await constaia.analyze(req.file.buffer, {
      filename: req.file.originalname,
      expect: ["es_dni", "es_nie", "passport"], // lo decide el servidor, no el navegador
      checks: { notExpired: true },
      language: "es",
    });
    res.json(analysis);
  } catch (err) {
    const status = err instanceof ConstaiaError && err.status && err.status < 500 ? 422 : 502;
    res.status(status).json({ error: { message: "No hemos podido analizar el documento." } });
  }
});

app.listen(3000);

Guías completas por framework en Integraciones.

Contrato con tu backend

PeticiónPOST a endpoint, multipart/form-data, mismo origen con cookies (with-credentials para otro origen).
Campo fileEl documento. En tarjetas a dos caras, un JPEG con el anverso arriba y el reverso abajo.
Campo optionsJSON con expect y language tomados de los atributos. Es una pista: cualquiera puede editarla.
Respuesta correcta2xx con el objeto análisis tal cual (el widget usa verdict.status, verdict.reasons[].message, warnings y document.label).
Respuesta de errorCódigo no 2xx y { "error": { "message": "…" } }: el widget muestra ese mensaje.

No confíes en el navegador

Tu backend debe fijar expect y checks (por ejemplo, el titular a partir del usuario autenticado). Protege la ruta con autenticación y límite de peticiones, porque cada llamada gasta créditos. Y no te fíes de un veredicto que llegue desde el navegador: guarda en el servidor el resultado que recibiste o vuelve a leerlo con GET /v1/analyses/{id}.

Modo solo frontend (clave publicable)

Si no quieres que el fichero pase por tu servidor, el widget puede subirlo directamente a Constaia. Tu backend crea una sesión con la clave secreta y pasa a la página solo su client_secret:

<constaia-upload
  publishable-key="pk_live_…"
  session-token="{{ client_secret }}"
  document-key="id_card"
  document="es_dni"
></constaia-upload>
  • El widget envía POST https://api.constaia.com/v1/analyze con Authorization: Bearer <publishable-key> y los campos file, client_secret, document_key (si lo indicas) y options con el idioma. expect y document solo configuran la interfaz: lo que se comprueba lo fija la sesión.
  • Un <constaia-upload> por documento de la sesión; cada documento se analiza una vez.
  • with-credentials se ignora y publishable-key tiene prioridad sobre endpoint.
  • Los errores de sesión (session_expired, session_invalid, document_already_submitted, invalid_document_key, origin_not_allowed, secret_key_in_browser) se muestran con un mensaje propio para la persona, sin el botón de reintentar.
  • Disponible en las versiones del widget posteriores a la 0.2.0 (React: publishableKey, sessionToken, documentKey; Vue: los mismos atributos).

Paso a paso, con la sesión en Node.js, PHP y Python: Integración solo frontend.

Atributos

AtributoPor defectoDescripción
endpoint—URL de tu backend.
expect—Tipo(s) esperado(s), separados por comas: es_dni o es_dni,passport. Se envía en options.
document—Tipo para la interfaz (encuadre, dos caras). Si no hay expect, también se envía como expect.
sidesautomático2 pide anverso y reverso (automático para es_dni, es_nie, eu_id_card); 1 fuerza un solo fichero.
frameautomáticocard muestra el marco ID-1 (85,6 × 54 mm); none lo oculta.
acceptJPEG, PNG, WEBP, HEIC, PDFTipos aceptados (MIME, image/* o extensiones).
max-size-mb20Tamaño máximo.
auto-submittruefalse espera a que el usuario (o submit()) confirme tras la comprobación de calidad.
with-credentialsdesactivadoEnvía cookies a un endpoint de otro origen.
langlang de la página o eses, en, pt, fr. También se envía como options.language.
themelightdark o auto (sigue prefers-color-scheme).
cameraautoBotón "Hacer foto": auto (pantallas táctiles), always, never.
headers—Cabeceras extra en JSON, por ejemplo un token CSRF.
publishable-key—Clave publicable (pk_live_…/pk_test_…) para el modo solo frontend. Una clave ck_ se rechaza.
session-token—Con publishable-key: el client_secret de la sesión. Con upload-url: token Bearer para tu propio proxy.
document-key—Documento de la sesión que rellena este widget (documents[].key). Opcional si la sesión tiene uno.
upload-url—URL de tu propio proxy (con session-token, sin publishable-key), o para sustituir https://api.constaia.com/v1/analyze en el modo solo frontend.

Propiedades y métodos

Propiedades: las de los atributos en camelCase (maxSizeMb, autoSubmit…), más headers (objeto), messages (textos), y de solo lectura status, result y error.

Métodos: submit(), reset(), selectFile(file, side?) y open(camera?).

const el = document.querySelector("constaia-upload");
el.headers = { "X-CSRF-TOKEN": token };
el.reset();

Eventos

Todos son CustomEvent con bubbles y composed.

Eventodetail
constaia:file{ file, side }Cancelable: preventDefault() impide usar el fichero. side: front, back o single.
constaia:quality{ file, side, metrics, issues }Tras la comprobación de calidad. issues[].code: low_resolution, blurry, too_dark, too_bright.
constaia:progress{ loaded, total, percent }Progreso de la subida.
constaia:resultel análisisLa respuesta de tu backend, tal cual.
constaia:error{ code, message, status? }Error de validación, red, HTTP o configuración (file_too_large, unsupported_file_type, network_error, http_error, invalid_response, missing_endpoint, secret_key_rejected, combine_failed).
constaia:status{ status }idle, checking, quality, ready, uploading, analyzing, done, error.

Anverso y reverso

Para tarjetas a dos caras, el widget pide el anverso y luego el reverso, y los une en el cliente en un JPEG (anverso arriba, reverso abajo, calidad 0,9, máximo 2000 px de ancho), porque la API recibe un único file.

  • Si el anverso es un PDF, no pide reverso: envía el PDF tal cual (debería contener las dos caras).
  • Si el reverso es un PDF o el navegador no puede decodificar una imagen (por ejemplo, HEIC fuera de Safari), solo envía el anverso y avisa. La API puede devolver entonces el aviso side_missing.

Comprobación de calidad

Antes de subir una imagen, el widget la reduce a 1024 px y mide la resolución original (lado corto menor de 600 px → low_resolution), el desenfoque (varianza del laplaciano), el brillo y, en tarjetas, los reflejos. Si hay problemas, el usuario ve Subir de todos modos y Repetir. Los PDF se saltan este paso; la API hace sus propias comprobaciones.

Estilos

constaia-upload {
  --constaia-accent: #12b76a;
  --constaia-accent-fg: #0b1220;
  --constaia-bg: #fafaf7;
  --constaia-fg: #0b1220;
  --constaia-surface: #ffffff;
  --constaia-muted: #5b6474;
  --constaia-border: #d5d9df;
  --constaia-radius: 12px;
  --constaia-font: Inter, system-ui, sans-serif;
  --constaia-valid: #12b76a;
  --constaia-invalid: #e5484d;
  --constaia-review: #f5a524;
  --constaia-focus: #12b76a;
}
constaia-upload::part(dropzone) { border-style: solid; }

Partes: container, dropzone, frame, button, button-primary, camera-button, preview, thumbnail, quality, progress, progress-bar, result, verdict, reasons, warnings, note, error.

Textos

document.querySelector("constaia-upload").messages = {
  dropTitle: "Sube tu certificado médico",
  verdictValid: "Todo correcto",
};

Las claves son las de LOCALES.es, exportado por el paquete (dropTitle, dropHint, chooseFile, takePhoto, verdictValid, verdictInvalid, verdictReview, tryAgain…).

React

VerifyId.tsx
"use client";
import { ConstaiaUpload, useConstaiaUpload } from "@constaia/widget/react";

export function VerifyId() {
  return (
    <ConstaiaUpload
      endpoint="/api/constaia"
      document="es_dni"
      lang="es"
      onResult={(analysis) => console.log(analysis.verdict?.status)}
      onError={(error) => console.warn(error.code)}
    />
  );
}

export function VerifyWithHook() {
  const { ref, status, result, error, reset } = useConstaiaUpload({ endpoint: "/api/constaia", document: "es_dni" });
  return (
    <>
      <ConstaiaUpload ref={ref} />
      <p>{status} {result?.verdict?.status} {error?.message}</p>
      <button type="button" onClick={reset}>Otra vez</button>
    </>
  );
}

Props: los atributos en camelCase (endpoint, expect, document, sides, frame, accept, maxSizeMb, autoSubmit, withCredentials, lang, theme, camera, messages, headers) y los callbacks onFile, onQuality, onProgress, onResult, onError, onStatus. Funciona con React 18 y 19 y con renderizado en servidor (el elemento se registra solo en el navegador).

Vue

VerifyId.vue
<script setup lang="ts">
import { ConstaiaUpload } from "@constaia/widget/vue";

function onResult(analysis: { verdict?: { status: string } | null }) {
  console.log(analysis.verdict?.status);
}
</script>

<template>
  <ConstaiaUpload endpoint="/api/constaia" expect="medical_certificate_sport" lang="es" @result="onResult" />
</template>

Eventos: @file, @quality, @progress, @result, @error, @status. Para usar la etiqueta <constaia-upload> directamente, instala ConstaiaPlugin e indica al compilador que es un custom element:

vite.config.ts
vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith("constaia-") } } });

Svelte, Angular y otros

Importa @constaia/widget una vez (registra el elemento) y usa la etiqueta. Escucha los eventos con addEventListener, porque los nombres llevan dos puntos (constaia:result). En Angular añade CUSTOM_ELEMENTS_SCHEMA al componente. Ejemplos en Svelte y Angular.

Siguientes pasos

En esta página