Constaia

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

Terminal
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:

Terminal
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.pdf

La 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

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 (los campos están recortados; size_bytes y fechas dependen de tu fichero y del momento):

200 OK
{
  "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

Terminal
curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F file=@dni_expired.jpg \
  -F 'options={"expect":"es_dni"}'
verdict
{
  "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

Terminal
curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F file=@blurry.jpg \
  -F 'options={"expect":"es_dni"}'
verdict y warnings
{
  "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:

Terminal
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 y verdict
{
  "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

Terminal
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:

Terminal
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}}'
verdict
{
  "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).

analyze.sh
#!/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

En esta página