Sesiones y claves publicables

Las sesiones (sess_…) permiten que el navegador suba los documentos directamente a Constaia, sin pasar el fichero por tu servidor y sin exponer tu clave secreta:

1. Tu backend crea una sesión con la clave secreta (ck_…) y decide qué se pide y qué se comprueba.
2. Tu página recibe solo el client_secret de la sesión.
3. El navegador sube el documento a POST /v1/analyze con una clave publicable (pk_…) y ese client_secret.

Guía completa con el widget, fetch y el SDK: Integración solo frontend.

Tu servidor (ck_)                 Navegador (pk_)                     Constaia
─────────────────                 ───────────────                     ────────
POST /v1/sessions ──────────────────────────────────────────────────▶ sess_… + client_secret (15 min)
  └─ client_secret ─────────────▶ <constaia-upload> / fetch
                                  POST /v1/analyze ───────────────────▶ análisis con las opciones de la sesión
GET /v1/sessions/{id} ──────────────────────────────────────────────▶ documents[].analysis_id
GET /v1/analyses/{id}  (o webhook analysis.completed) ─────────────▶ veredicto

Claves publicablesCopy Anchor Link

Una clave publicable (pk_live_… o pk_test_…) puede ir en el código de tu web: solo sirve para subir documentos a una sesión que ya creó tu servidor, y solo desde los dominios que autorices.

• Se crean en el panel: Desarrolladores → Claves de API, tipo Publicable. Como todas las claves, se muestran una sola vez.
• Dominios permitidos (1–20): app.tuweb.com (ese host exacto), *.tuweb.com (cualquier subdominio, pero no tuweb.com a secas: añádelo aparte) y, solo en claves de test, localhost:3000. El puerto forma parte del host. Los cambios de dominios se aplican al momento.
• La petición del navegador debe llevar la cabecera Origin de uno de esos dominios (los navegadores la ponen solos). Si no: 403 origin_not_allowed.
• Solo sirven para POST /v1/analyze con client_secret. Cualquier otra ruta responde 403 publishable_key_not_allowed.
• El modo va con la clave: una pk_test_… solo abre sesiones creadas con una ck_test_…, y una pk_live_…, las de ck_live_….

Crear una sesiónCopy Anchor Link

POST /v1/sessions
Authorization: Bearer ck_live_…
Content-Type: application/json

Las opciones de cada documento salen de la plantilla y, encima, del expect y los checks del documento (checks clave a clave). Aquí es donde pones lo que no puede decidir el navegador: por ejemplo el titular esperado (checks.holder) a partir del usuario autenticado.

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" } } }
    ]
  }'

{
  "id": "sess_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
  "object": "session",
  "client_secret": "sess_01J9Z8Q3K4M5N6P7Q8R9S0T1V2_secret_Xk2…",
  "status": "open",
  "livemode": true,
  "template": "tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
  "reference": "user_42",
  "metadata": { "user_id": "42" },
  "documents": [
    { "key": "id_card", "label": "DNI o NIE", "expect": ["es_dni", "es_nie"], "analysis_id": null, "status": "pending" }
  ],
  "expires_at": "2026-09-30T10:15:00Z",
  "created_at": "2026-09-30T10:00:00Z"
}

Subir desde el navegadorCopy Anchor Link

POST /v1/analyze
Authorization: Bearer pk_live_…
Content-Type: multipart/form-data

const form = new FormData();
form.append("file", input.files[0]);
form.append("client_secret", clientSecret);
form.append("document_key", "id_card");

const res = await fetch("https://api.constaia.com/v1/analyze", {
  method: "POST",
  headers: { Authorization: "Bearer pk_live_…" },
  body: form,
});
const analysis = await res.json();

Responde con el objeto analysis, igual que una llamada normal (200, o 202 si tarda más de 30 s), con session_id y document_key. Se cobra a tu cuenta como cualquier análisis.

• Cada documento se analiza una vez. Una segunda subida del mismo documento devuelve 409 document_already_submitted. Si la subida falla antes de crear el análisis (fichero no válido, sin créditos, límite de peticiones), el documento queda libre para volver a intentarlo.
• No hay resultados progresivos (stream) ni Idempotency-Key en este modo.
• El navegador no puede leer análisis ni sesiones: el resultado que ve sirve para la interfaz, no para decidir.

Recuperar una sesiónCopy Anchor Link

curl https://api.constaia.com/v1/sessions/sess_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

Devuelve la sesión sin client_secret. Cuando el usuario termina, tu backend lee aquí el analysis_id de cada documento y el análisis con GET /v1/analyses/{id} (o lo recibe por el webhook analysis.completed), y decide con ese veredicto. Solo ve sesiones del modo de la clave; si no existe, 404 resource_missing.

SDKCopy Anchor Link

import { Constaia } from "@constaia/sdk";

// Backend (clave secreta)
const constaia = new Constaia();
const session = await constaia.sessions.create({
  template: "tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
  reference: "user_42",
  documents: [{ key: "id_card", expect: ["es_dni", "es_nie"] }],
});
// → session.client_secret a la página

// Navegador (clave publicable): solo permite sessions.submit()
const browser = new Constaia({ apiKey: "pk_live_…" });
const analysis = await browser.sessions.submit(file, { clientSecret, documentKey: "id_card" });

ErroresCopy Anchor Link

Los mensajes de estos errores están pensados para enseñarse a la persona (en es, en, pt o fr). El resto de errores de la subida (saldo, límites, fichero no válido) son los de analyze.

Siguientes pasosCopy Anchor Link