Constaia

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:

VeredictoSignificado
VálidoEs del tipo esperado y ninguna comprobación ha fallado ni genera dudas.
No válidoAlgún motivo tiene severidad error: otro tipo de documento, caducado, titular distinto, letra del NIF incorrecta…
RevisarAlgú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

Terminal
curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F file=@dni_valid.jpg \
  -F 'options={"expect":"es_dni"}'
Respuesta (extracto)
{
  "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. Sin expect se calcula contra el tipo detectado (verdict.basis: "detected"); es null si el documento no se reconoce.
  • fields: datos extraídos, cada uno con value, confidence, validated y source (página y rectángulo de origen). También puedes pasar tu propio JSON Schema en extract.
  • 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 (sovereign o standard), 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 con temporary (con ttl_hours) o persistent.
  • Con keep_results: false tampoco 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

En esta página