Widget de subida

@constaia/widget es un componente web (<constaia-upload>) que muestra una zona para arrastrar o elegir un documento, hacer una foto con el móvil, comprobar la calidad de la imagen antes de subirla y enseñar el veredicto. Funciona en HTML plano y trae envoltorios para React y Vue.

Cómo funciona (patrón seguro)Copy Anchor Link

Tu clave ck_live_… o ck_test_… nunca debe llegar al navegador: cualquiera podría leerla y gastar tus créditos. Por eso el widget no llama a Constaia directamente:

Si pones una clave secreta en cualquier atributo, el widget se bloquea, emite constaia:error con el código secret_key_rejected y muestra un error en la consola.

InstalaciónCopy Anchor Link

npm i @constaia/widget

Al importar el paquete se registra el elemento <constaia-upload>:

import "@constaia/widget";

Sin herramientas de build, cárgalo desde un CDN como módulo:

<script type="module" src="https://cdn.jsdelivr.net/npm/@constaia/widget/dist/cdn/constaia-widget.min.js"></script>

HTML planoCopy Anchor Link

<constaia-upload endpoint="/api/constaia" expect="es_dni,es_nie" lang="es"></constaia-upload>

<script type="module">
  import "https://cdn.jsdelivr.net/npm/@constaia/widget/dist/cdn/constaia-widget.min.js";

  const upload = document.querySelector("constaia-upload");

  upload.addEventListener("constaia:result", (event) => {
    const analysis = event.detail; // lo que devolvió tu endpoint
    if (analysis.verdict?.status === "valid") {
      document.querySelector("#continue").disabled = false;
    }
  });

  upload.addEventListener("constaia:error", (event) => {
    console.warn(event.detail.code, event.detail.message);
  });
</script>

AtributosCopy Anchor Link

Cámara en el móvilCopy Anchor Link

En pantallas táctiles, el widget muestra un botón Hacer foto que abre directamente la cámara trasera (capture="environment"), además del selector de ficheros normal. Controla ese botón con el atributo camera. Con documentos de dos caras guía al usuario para fotografiar anverso y reverso y los une en una sola imagen JPEG antes de enviarla.

Antes de subir, comprueba en el propio navegador la resolución, el desenfoque y la exposición. Si la foto es mala, propone repetirla (o subirla igualmente). Así se evitan análisis que acabarían en review por blurry o glare.

EventosCopy Anchor Link

Todos burbujean y atraviesan el shadow DOM (bubbles y composed).

Si tu endpoint responde con un error en el formato { "error": { "code": "…", "message": "…" } }, el widget muestra ese message al usuario.

Métodos y propiedadesCopy Anchor Link

ReactCopy Anchor Link

"use client";

import { ConstaiaUpload } from "@constaia/widget/react";

export function DniUpload({ onVerified }: { onVerified: (analysisId: string) => void }) {
  return (
    <ConstaiaUpload
      endpoint="/api/constaia"
      expect={["es_dni", "es_nie"]}
      lang="es"
      onResult={(analysis) => {
        if (analysis.verdict?.status === "valid") onVerified(analysis.id);
      }}
      onError={(error) => console.warn(error.code, error.message)}
    />
  );
}

También hay un hook, useConstaiaUpload, que expone status, progress, result, error, submit y reset para montar tu propia interfaz alrededor del componente.

VueCopy Anchor Link

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

function onResult(analysis: { id: string; verdict?: { status: string } | null }) {
  if (analysis.verdict?.status === "valid") {
    // continúa el formulario
  }
}
</script>

<template>
  <ConstaiaUpload endpoint="/api/constaia" expect="es_dni" lang="es" @result="onResult" @error="(e) => console.warn(e)" />
</template>

Si prefieres usar la etiqueta <constaia-upload> directamente en tus plantillas, instala el plugin ConstaiaPlugin y dile al compilador de Vue que es un elemento personalizado: compilerOptions: { isCustomElement: (tag) => tag.startsWith("constaia-") }.

Tu endpoint de servidorCopy Anchor Link

El endpoint recibe file y options, llama a Constaia y devuelve JSON. Devuelve solo lo que el widget necesita pintar (verdict, warnings, document): los campos extraídos, mejor guárdalos en tu servidor.

import { Constaia, ConstaiaError } from "@constaia/sdk";
import { getSession } from "@/lib/auth"; // tu autenticación

const constaia = new Constaia(); // CONSTAIA_API_KEY solo en el servidor
const LANGUAGES = ["es", "en", "pt", "fr"] as const;

export async function POST(request: Request) {
  const session = await getSession();
  if (!session) {
    return Response.json({ error: { code: "unauthorized", message: "Inicia sesión." } }, { status: 401 });
  }

  const form = await request.formData();
  const file = form.get("file");
  if (!(file instanceof File)) {
    return Response.json({ error: { code: "missing_file", message: "Falta el documento." } }, { status: 400 });
  }

  // Del navegador solo aceptamos el idioma; expect y checks los decide el servidor.
  const sent = JSON.parse(String(form.get("options") ?? "{}"));
  const language = LANGUAGES.includes(sent.language) ? sent.language : "es";

  try {
    const analysis = await constaia.analyze(file, {
      expect: ["es_dni", "es_nie"],
      checks: { notExpired: true, holder: { fullName: session.user.name } },
      language,
      metadata: { user_id: session.user.id },
    });

    await saveVerification(session.user.id, analysis); // tu base de datos

    return Response.json({
      id: analysis.id,
      object: analysis.object,
      status: analysis.status,
      document: analysis.document,
      verdict: analysis.verdict,
      warnings: analysis.warnings,
    });
  } catch (err) {
    if (err instanceof ConstaiaError && err.status && err.status < 500) {
      return Response.json({ error: { code: err.code ?? err.type, message: err.message } }, { status: 400 });
    }
    return Response.json({ error: { code: "upstream_error", message: "Inténtalo de nuevo." } }, { status: 502 });
  }
}

AccesibilidadCopy Anchor Link

• La zona de subida es un botón accesible por teclado: se activa con Intro o Espacio.
• Los cambios de estado (subiendo, analizando, resultado) se anuncian a lectores de pantalla mediante una región aria-live.
• La barra de progreso usa role="progressbar" con su valor actual.
• Al cambiar de paso, el foco pasa al siguiente control útil (repetir foto, enviar, analizar otro documento).
• El veredicto se muestra siempre con icono y texto, nunca solo con color.
• Textos en español, inglés, portugués y francés; puedes sustituir cualquiera con la propiedad messages.

EstilosCopy Anchor Link

El componente usa shadow DOM. Puedes ajustar su aspecto con ::part():

constaia-upload::part(container) { border-radius: 12px; }
constaia-upload::part(button-primary) { background: #0b1220; }
constaia-upload::part(result) { font-size: 0.95rem; }

Partes disponibles: container, dropzone, frame, button, button-primary, camera-button, progress, progress-bar, result, verdict.