Integración solo frontend

Con esta integración el fichero no pasa por tu servidor: el navegador lo sube directamente a Constaia. Tu backend solo hace dos llamadas pequeñas con la clave secreta: crear la sesión (qué se pide y qué se comprueba) y leer el resultado al final.

Úsala cuando no quieras montar y proteger una ruta de subida (tamaño de ficheros, límites, antivirus…), en webs estáticas con un backend mínimo o en apps de escritorio y móviles que cargan tu web. Si prefieres que el fichero pase por tu servidor, usa el widget con endpoint; si ni siquiera quieres construir la pantalla de subida, usa un enlace de verificación.

Tu servidor (ck_)                 Navegador (pk_)                     Constaia
─────────────────                 ───────────────                     ────────
1. POST /v1/sessions ───────────────────────────────────────────────▶ sess_… + client_secret (15 min)
2.   └─ client_secret ──────────▶ página
3.                                POST /v1/analyze (pk_ + client_secret) ▶ análisis con las opciones de la sesión
4. GET /v1/sessions/{id} → GET /v1/analyses/{id}  (o webhook) ──────▶ veredicto: decides tú, en el servidor

Referencia de todos los campos y errores: Sesiones y claves publicables.

Paso 1: crea una clave publicableCopy Anchor Link

En el panel, Desarrolladores → Claves de API → Crear clave, elige el tipo Publicable y añade los dominios desde los que se va a usar:

Empieza con una clave pk_test_… y localhost para desarrollar gratis. La clave publicable puede ir en el código de tu web: solo sirve para subir documentos a sesiones que crea tu servidor, y solo desde esos dominios.

Paso 2: crea la sesión en tu backendCopy Anchor Link

Tu backend decide qué documentos se piden y qué se comprueba, normalmente con una plantilla y datos del usuario autenticado (el titular esperado, su id en metadata). Crea la sesión al pintar la página: caduca a los 15 minutos.

curl https://api.constaia.com/v1/sessions \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
    "reference": "user_42",
    "metadata": { "user_id": "42" },
    "documents": [
      { "key": "id_card", "label": "DNI o NIE", "expect": ["es_dni", "es_nie"], "checks": { "holder": { "full_name": "María García López" } } }
    ]
  }'

Nunca devuelvas a la página la clave secreta ni el objeto sesión entero: solo client_secret.

Paso 3: sube desde la páginaCopy Anchor Link

El navegador sube el fichero a POST https://api.constaia.com/v1/analyze con la clave publicable, el client_secret y la document_key. Las opciones de análisis salen de la sesión: desde el navegador solo se acepta el idioma.

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

<constaia-upload
  publishable-key="pk_test_…"
  session-token="{{ clientSecret }}"
  document-key="id_card"
  document="es_dni"
  lang="es"
></constaia-upload>

<script type="module">
  document.querySelector("constaia-upload").addEventListener("constaia:result", () => {
    // Solo interfaz: el veredicto que cuenta lo lee tu servidor
    fetch("/api/constaia-done", { method: "POST" });
  });
</script>

Paso 4: lee el resultado en tu servidorCopy Anchor Link

Lo que ve el navegador sirve para la interfaz. La decisión (dar de alta, aprobar la inscripción) la toma tu backend con el análisis que lee con su clave secreta:

const session = await constaia.sessions.get(user.constaiaSessionId);
const doc = session.documents.find((d) => d.key === "id_card");
if (!doc?.analysis_id) return res.status(409).json({ error: "Falta el documento" });

const analysis = await constaia.analyses.get(doc.analysis_id);
const status = analysis.verdict?.final_status ?? analysis.verdict?.status;

También puedes esperar al webhook analysis.completed (y analysis.reviewed si hay revisión humana): el análisis lleva session_id, document_key y tu metadata, así que lo cruzas con el usuario sin guardar nada más. Si el veredicto es review, trátalo como en Revisión humana.

Probar en localCopy Anchor Link

1. Crea una clave ck_test_… para el backend y una pk_test_… con el dominio localhost:3000 (el de tu servidor de desarrollo).
2. Sube los ficheros de prueba (dni_valid.jpg, dni_expired.jpg…): en test no se gastan créditos y el resultado depende del nombre del fichero.
3. Prueba los errores: vuelve a subir el mismo documento (409 document_already_submitted), espera 15 minutos (401 session_expired) o abre la página desde otro puerto (403 origin_not_allowed).

Errores que verá la personaCopy Anchor Link

Estos errores traen un message pensado para enseñárselo a la persona (en su idioma); el widget ya los muestra.

Lista de comprobaciónCopy Anchor Link

• La clave secreta solo está en el servidor; la página solo ve pk_… y client_secret.
• expect, checks y el titular esperado se fijan en la sesión o la plantilla, nunca en el navegador.
• Guardas el session_id (o pones el id del usuario en metadata) para cruzar el resultado.
• La decisión final se toma en el servidor con GET /v1/analyses/{id} o el webhook.
• Los dominios de la clave pk_live_… son solo los de producción.

Siguientes pasosCopy Anchor Link