Inicio rápido
Valida tu primer DNI con la API de Constaia en 5 minutos usando una clave de prueba gratuita, con curl, JavaScript, PHP o Python.
En cinco minutos vas a crear una cuenta, obtener una clave de prueba y lanzar análisis reales contra la API sin gastar créditos. Después verás cómo pasar a producción.
1. Primer análisis
Crea una cuenta
Regístrate en app.constaia.com/signup con tu email o con tu cuenta de Google o GitHub (en ese caso el email queda verificado al momento). El plan gratuito incluye 150 créditos al mes y no pide tarjeta. Los créditos se renuevan el día 1 (UTC). Más detalles en Precios.
¿Solo quieres ver qué devuelve? La demo de la web analiza un documento sin cuenta ni clave (5 al día, sin guardar el fichero).
Copia tu clave de prueba
En el panel, ve a API keys y copia la clave que empieza por ck_test_. Las
claves se muestran una sola vez: guárdala en tu gestor de secretos.
Las claves de prueba nunca gastan créditos y devuelven resultados deterministas según el nombre del fichero. Todo sobre este modo en Modo test.
Exporta la clave como variable de entorno
export CONSTAIA_API_KEY="ck_test_..."Los SDKs oficiales leen CONSTAIA_API_KEY automáticamente. La clave siempre se queda en tu servidor:
nunca la pongas en código de navegador ni en una app móvil.
Prepara un fichero de prueba
En modo test el resultado se elige por el nombre del fichero, pero el contenido tiene que ser un JPEG, PNG, WEBP, HEIC o PDF real (el tipo se detecta por los primeros bytes). Copia cualquier foto y cualquier PDF que tengas a mano con estos nombres:
cp ~/Pictures/cualquier-foto.jpg dni_valid.jpg
cp dni_valid.jpg dni_expired.jpg
cp dni_valid.jpg blurry.jpg
cp dni_valid.jpg nie.jpg
cp dni_valid.jpg passport.jpg
cp ~/Documents/cualquier-documento.pdf medical_certificate.pdfLa firma y los metadatos de un PDF se analizan de verdad también en modo test: si tu PDF lo generó Word, Canva u otro
editor, verás el aviso edited_suspected y un veredicto review. Si te pasa, usa cp dni_valid.jpg medical_certificate.jpg. Ver Modo test.
Analiza un DNI
curl https://api.constaia.com/v1/analyze \
-H "Authorization: Bearer $CONSTAIA_API_KEY" \
-F file=@dni_valid.jpg \
-F 'options={"expect":"es_dni"}'Respuesta (los campos están recortados; size_bytes y fechas dependen de tu fichero y del momento):
{
"id": "an_01J...",
"object": "analysis",
"status": "completed",
"livemode": false,
"created_at": "2026-09-29T10:00:00Z",
"completed_at": "2026-09-29T10:00:02Z",
"file": { "name": "dni_valid.jpg", "mime_type": "image/jpeg", "pages": 1, "size_bytes": 482133 },
"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." }
]
},
"fields": {
"document_number": {
"value": "12345678Z",
"confidence": 0.99,
"validated": true,
"source": { "page": 1, "bbox": [0.61, 0.12, 0.83, 0.16] }
}
},
"checks": [
{ "code": "nif_check_digit", "passed": true, "message": "La letra del documento 12345678Z es correcta." },
{ "code": "mrz_checksums", "passed": true, "message": "Los dígitos de control de la MRZ son correctos." },
{ "code": "mrz_matches_visual", "passed": true, "message": "La MRZ coincide con los datos impresos." }
],
"warnings": [],
"signature": null,
"exports": {},
"storage": { "mode": "review", "kept": false, "reason": null, "expires_at": null, "file_deleted_at": "2026-09-29T10:00:02Z" },
"processing": {
"profile": "sovereign",
"region": "eu",
"mode": "vlm",
"providers": [{ "name": "mock", "region": "local", "role": "llm", "model": "mock-llm-1" }]
},
"usage": { "credits": 0, "pages": 1 },
"metadata": {}
}Además de document_number, fields trae first_name (MARÍA), last_name_1 (GARCÍA), last_name_2
(LÓPEZ), sex, nationality, birth_date (1990-05-14), issue_date, expiry_date (2031-03-12),
support_number, address, birth_place, parents y mrz, todos con la misma estructura.
Fíjate en usage.credits: 0 (modo test) y en storage: con el modo por defecto (review) el fichero solo se guarda si
hace falta revisarlo; este DNI es válido, así que se ha borrado al terminar (kept: false). signature es
null porque no es un PDF, y processing dice qué proveedores lo han tratado (en modo test, el simulado mock).
2. Prueba otros resultados
Cambia solo el nombre del fichero para ver cada veredicto. Te mostramos verdict y warnings; el resto de la
respuesta tiene la misma forma.
DNI caducado: invalid
curl https://api.constaia.com/v1/analyze \
-H "Authorization: Bearer $CONSTAIA_API_KEY" \
-F file=@dni_expired.jpg \
-F 'options={"expect":"es_dni"}'{
"expected": ["es_dni"],
"match": true,
"status": "invalid",
"reasons": [
{ "code": "type_match", "severity": "info", "message": "El documento es DNI (España)." },
{ "code": "not_expired", "severity": "error", "message": "Caducado el 15/06/2020." }
]
}El código es el mismo (not_expired) que en el DNI válido; lo que cambia es la severidad. Un motivo con
severidad error convierte el veredicto en No válido.
Foto borrosa: review
curl https://api.constaia.com/v1/analyze \
-H "Authorization: Bearer $CONSTAIA_API_KEY" \
-F file=@blurry.jpg \
-F 'options={"expect":"es_dni"}'{
"verdict": {
"expected": ["es_dni"],
"match": true,
"status": "review",
"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." },
{ "code": "low_quality", "severity": "warning", "message": "La calidad de la imagen es insuficiente (blurry, low_quality)." }
]
},
"warnings": ["blurry", "low_quality"]
}Un motivo warning da Revisar: pide otra foto al usuario o pásalo a revisión manual.
Varios tipos aceptados: NIE
expect admite una lista. Útil cuando aceptas DNI, NIE o pasaporte en el mismo campo:
curl https://api.constaia.com/v1/analyze \
-H "Authorization: Bearer $CONSTAIA_API_KEY" \
-F file=@nie.jpg \
-F 'options={"expect":["es_dni","es_nie","passport"]}'{
"document": { "type": "es_nie", "label": "NIE / TIE (España)", "confidence": 0.97, "side": "both", "country": "ESP" },
"verdict": {
"expected": ["es_dni", "es_nie", "passport"],
"match": true,
"status": "valid",
"reasons": [
{ "code": "type_match", "severity": "info", "message": "El documento es NIE / TIE (España)." },
{ "code": "not_expired", "severity": "info", "message": "Vigente hasta el 30/11/2029." }
]
}
}El número está en fields.nie_number (X1234567L). Cada tipo tiene sus campos: consúltalos en el
catálogo o con GET /v1/document-types/es_nie.
Pasaporte
curl https://api.constaia.com/v1/analyze \
-H "Authorization: Bearer $CONSTAIA_API_KEY" \
-F file=@passport.jpg \
-F 'options={"expect":"passport"}'Devuelve valid con document.type: "passport", fields.document_number PAA123456, caducidad
2032-06-01 y los checks mrz_checksums y mrz_matches_visual superados.
Certificado médico con reglas
Los checks añaden reglas de negocio. Aquí exigimos que el certificado no tenga más de un año y que esté
firmado:
curl https://api.constaia.com/v1/analyze \
-H "Authorization: Bearer $CONSTAIA_API_KEY" \
-F file=@medical_certificate.pdf \
-F 'options={"expect":"medical_certificate_sport","checks":{"max_age_days":365,"require_signature":true}}'{
"expected": ["medical_certificate_sport"],
"match": true,
"status": "valid",
"reasons": [
{ "code": "type_match", "severity": "info", "message": "El documento es Certificado médico deportivo." },
{ "code": "max_age_days", "severity": "info", "message": "Emitido hace 28 días (máximo 365)." },
{ "code": "require_signature", "severity": "info", "message": "El documento está firmado." }
]
}El certificado de prueba está emitido el 2026-09-01, así que el número de días del mensaje depende de la
fecha en que lo ejecutes. Todas las reglas disponibles están en Checks.
3. Desde tu código
La misma llamada con los SDKs o HTTP directo. Maneja siempre los errores: la API devuelve
{ "error": { "type", "code", "message", "request_id" } } (ver Errores).
#!/usr/bin/env bash
set -euo pipefail
curl --fail-with-body -sS https://api.constaia.com/v1/analyze \
-H "Authorization: Bearer $CONSTAIA_API_KEY" \
-F file=@dni_valid.jpg \
-F 'options={"expect":"es_dni","checks":{"min_age_years":18}}'Un análisis síncrono espera hasta 30 segundos. Si no ha terminado, la API responde 202 con status: "queued"
o "processing" y el resultado llega por webhook (o consultando
GET /v1/analyses/{id}). Con documentos cortos en modo test verás siempre 200.
4. Pasar a producción
Verifica tu email
Las claves ck_live_ solo se pueden crear con el email verificado, y los créditos gratis en modo live también lo
exigen (si no, 402 email_not_verified). Si te registraste con Google o GitHub, ya lo está.
Crea una clave ck_live_
En el panel → API keys, crea una clave de producción. Se muestra una sola vez. Los análisis en vivo consumen créditos: primero los 150 gratuitos del mes y después los de los packs que compres. Consulta Créditos y facturación.
Ten en cuenta los límites del plan gratuito: 2 peticiones por segundo, 2 análisis síncronos simultáneos y 60 páginas
por minuto (10, 10 y 600 cuando compras un pack). Si los superas recibes 429 con Retry-After; los SDK ya reintentan.
Ver Límites de uso.
Cambia la variable de entorno
No hace falta tocar el código: sustituye el valor de CONSTAIA_API_KEY en tu entorno de producción por la
clave ck_live_. Los análisis de cada modo son independientes: al listar con una clave live solo ves análisis
live.
Configura los webhooks de producción
Los endpoints de webhook pertenecen al modo de la clave con que los creas. Crea de nuevo tus endpoints con la clave live; ver Webhooks.
live_mode_unavailable
Las claves live nunca reciben resultados simulados. Si el entorno no tiene proveedores de IA reales
disponibles, las llamadas live fallan con 503 live_mode_unavailable. Mientras tanto, sigue desarrollando
con tu clave ck_test_.
Siguientes pasos
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.
Conceptos clave
Tipos de documento, expect, veredictos, motivos, campos, checks, warnings, modos test y live, créditos, almacenamiento, webhooks e idempotencia en Constaia.