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 enes,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/widgetimport "@constaia/widget"; // registra <constaia-upload>Cómo funciona
- 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.
- El widget comprueba la calidad (resolución, desenfoque, brillo) y avisa antes de subir.
- Envía
POST multipart/form-dataa tuendpointcon dos campos:fileyoptions. - Tu backend llama a
POST /v1/analyzedecidiendo élexpectychecks, y devuelve el análisis en JSON. - El widget muestra el veredicto, los motivos y los avisos, y emite
constaia:result.
Ejemplo mínimo
<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):
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ón | POST a endpoint, multipart/form-data, mismo origen con cookies (with-credentials para otro origen). |
Campo file | El documento. En tarjetas a dos caras, un JPEG con el anverso arriba y el reverso abajo. |
Campo options | JSON con expect y language tomados de los atributos. Es una pista: cualquiera puede editarla. |
| Respuesta correcta | 2xx con el objeto análisis tal cual (el widget usa verdict.status, verdict.reasons[].message, warnings y document.label). |
| Respuesta de error | Có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/analyzeconAuthorization: Bearer <publishable-key>y los camposfile,client_secret,document_key(si lo indicas) yoptionscon el idioma.expectydocumentsolo 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-credentialsse ignora ypublishable-keytiene prioridad sobreendpoint.- 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
| Atributo | Por defecto | Descripció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. |
sides | automático | 2 pide anverso y reverso (automático para es_dni, es_nie, eu_id_card); 1 fuerza un solo fichero. |
frame | automático | card muestra el marco ID-1 (85,6 × 54 mm); none lo oculta. |
accept | JPEG, PNG, WEBP, HEIC, PDF | Tipos aceptados (MIME, image/* o extensiones). |
max-size-mb | 20 | Tamaño máximo. |
auto-submit | true | false espera a que el usuario (o submit()) confirme tras la comprobación de calidad. |
with-credentials | desactivado | Envía cookies a un endpoint de otro origen. |
lang | lang de la página o es | es, en, pt, fr. También se envía como options.language. |
theme | light | dark o auto (sigue prefers-color-scheme). |
camera | auto | Botó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.
| Evento | detail | |
|---|---|---|
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:result | el análisis | La 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
"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
<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:
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
SDK de Python
Referencia del SDK oficial constaia para Python 3.9+: clientes síncrono y asíncrono, entradas, opciones, paginación, errores, concurrencia y webhooks.
Servidor MCP para agentes de IA
Conecta Constaia a Claude Desktop, Claude Code, Cursor, VS Code o Windsurf con @constaia/mcp para validar y extraer datos de documentos desde un agente.