Introducción
Constaia es una API europea que responde si un documento es el que esperas y si es válido, con motivos, campos extraídos y sin guardar documentos que no haga falta revisar.
Constaia es una API para validar, clasificar y extraer datos de documentos con IA. Está pensada para formularios de inscripción, altas de clientes, licencias, expedientes y cualquier flujo en el que alguien te sube un documento y tú tienes que decidir si sirve.
La pregunta que responde
La mayoría de las APIs de documentos te devuelven texto o campos. Constaia responde a otra pregunta:
¿Es este documento un X válido?
Tú dices qué esperas (expect: "es_dni") y qué reglas debe cumplir (checks: vigente, titular, antigüedad
máxima, firma, importe…). Constaia devuelve uno de tres veredictos:
| Veredicto | Significado |
|---|---|
| Válido | Es del tipo esperado y ninguna comprobación ha fallado ni genera dudas. |
| No válido | Algún motivo tiene severidad error: otro tipo de documento, caducado, titular distinto, letra del NIF incorrecta… |
| Revisar | Algún motivo tiene severidad warning: calidad baja, confianza baja, tipo no identificado. Conviene que lo mire una persona. |
Cada veredicto trae motivos (reasons) con un código estable para tu lógica y un mensaje traducido para
mostrar al usuario. Los detalles están en Veredictos y motivos.
Un ejemplo mínimo
curl https://api.constaia.com/v1/analyze \
-H "Authorization: Bearer $CONSTAIA_API_KEY" \
-F file=@dni_valid.jpg \
-F 'options={"expect":"es_dni"}'{
"id": "an_01J...",
"object": "analysis",
"status": "completed",
"document": { "type": "es_dni", "label": "DNI (España)", "confidence": 0.97, "side": "both", "country": "ESP" },
"verdict": {
"expected": ["es_dni"],
"match": true,
"status": "valid",
"reasons": [
{ "code": "type_match", "severity": "info", "message": "El documento es DNI (España)." },
{ "code": "not_expired", "severity": "info", "message": "Vigente hasta el 12/03/2031." }
]
},
"checks": [
{ "code": "nif_check_digit", "passed": true, "message": "La letra del documento 12345678Z es correcta." }
],
"warnings": []
}Con una clave de prueba (ck_test_...) puedes lanzar esta llamada ahora mismo sin gastar créditos: el
resultado depende del nombre del fichero. Lo tienes paso a paso en el inicio rápido.
Qué recibes en cada análisis
document: tipo detectado del catálogo, etiqueta legible, confianza, cara y país.verdict: estado (valid,invalid,review) y motivos. Sinexpectse calcula contra el tipo detectado (verdict.basis: "detected"); esnullsi el documento no se reconoce.fields: datos extraídos, cada uno convalue,confidence,validatedysource(página y rectángulo de origen). También puedes pasar tu propio JSON Schema enextract.checks: validaciones deterministas (letra del NIF, dígitos de control de la MRZ, identificadores nacionales, IBAN, totales de factura, código PDF417 de los permisos de EE. UU.…), que no dependen de la IA.warnings: señales de calidad o de posible manipulación (blurry,glare,screen_photo_suspected…). Son indicios, no prueba de fraude.signature: en los PDF, la verificación de su firma electrónica (íntegra, de confianza, modificada…). Ver Firmas digitales en PDF.exports: enlaces firmados a JSON, CSV, XLSX, XML, vCard o PDF si los pides.processing: perfil (sovereignostandard), región y proveedores que han tratado el documento.usage: páginas procesadas y créditos consumidos.
Todos los conceptos, resumidos, en Conceptos clave.
Europea y sin guardar lo que no hace falta
- El procesamiento se hace en la UE, con proveedores de IA en regiones europeas. Con
processing: "sovereign", solo proveedores con sede y operación en la UE. Consulta Almacenamiento y privacidad y Residencia de datos. - Por defecto (
storage: "review") solo guardamos, cifrados, los documentos que necesitan revisión humana, y los borramos al decidir. Puedes elegir no guardar nunca el fichero (none: en un análisis síncrono se procesa en memoria y no se escribe en ningún almacenamiento) o conservarlo contemporary(conttl_hours) opersistent. - Con
keep_results: falsetampoco se guardan los datos extraídos: los recibes una vez y ya. - Los ficheros que sí se guardan se cifran en la aplicación (AES-256-GCM, clave por cuenta) antes de llegar al almacenamiento de objetos en la UE (Cloudflare R2 con jurisdicción UE).
Qué no es Constaia
Constaia no es un KYC biométrico: no compara caras, no hace prueba de vida y no consulta registros oficiales.
Comprueba que el documento es del tipo que esperas, que sus datos son coherentes y que cumple tus reglas. Las
warnings de posible edición o foto de pantalla son señales para decidir si revisar, no una detección de fraude.
El código csv_format solo comprueba el formato del código seguro de verificación (CSV) de certificados
españoles. Constaia no consulta el servicio de verificación del organismo emisor; si lo necesitas, verifica el
CSV en la sede oficial.
Siguientes pasos
Inicio rápido
Tu primer análisis en 5 minutos con una clave de prueba.
Conceptos clave
Tipos, expect, veredictos, campos, checks, modos y créditos.
Qué usar
analyze, classify, lotes o widget: cuál encaja con tu caso.
Casos de uso
DNI en un formulario, certificados médicos, justificantes, facturas…
Integraciones
Node, Next.js, Laravel, Django, n8n y muchas más.
Referencia de la API
Todos los endpoints, parámetros y errores.
SDK de JavaScript
@constaia/sdk para Node, Bun, Deno y edge.
Servidor MCP
Usa Constaia desde Claude, Cursor o VS Code.