POST /v1/analyze

POST https://api.constaia.com/v1/analyze recibe un documento, lo clasifica, extrae sus campos y, si le dices qué esperas con expect, lo valida y devuelve un veredicto valid, invalid o review. Es el endpoint principal de la API.

Si solo necesitas saber qué documento es (por ejemplo, para enrutarlo), usa POST /v1/classify, que cuesta 0,2 créditos. Para muchos documentos a la vez, POST /v1/batches. Si dudas, mira Qué endpoint usar.

Enviar el documentoCopy Anchor Link

Hay dos formas de enviar la petición. Cualquier otro Content-Type devuelve 415 unsupported_content_type.

1. multipart/form-dataCopy Anchor Link

curl 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}}'

Atajo para pruebas rápidas: si no envías options, puedes pasar expect como campo del formulario, repetible para varios tipos:

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F file=@nie.jpg -F expect=es_dni -F expect=es_nie -F expect=passport

Si envías options, el campo expect suelto se ignora.

2. application/jsonCopy Anchor Link

Con una URL pública o con el fichero en base64:

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/uploads/justificante.pdf",
    "options": {
      "expect": "payment_receipt",
      "checks": { "expected_amount": 45, "expected_reference": "INSCRIPCION 123" }
    }
  }'

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"file_base64\": \"$(base64 < dni_valid.jpg | tr -d '\n')\",
    \"filename\": \"dni_valid.jpg\",
    \"expect\": \"es_dni\",
    \"language\": \"en\"
  }"

Usa una de las dos formas para las opciones: si el cuerpo trae options, las claves de la raíz (salvo file_url, file_base64 y filename) no se leen.

Ficheros admitidosCopy Anchor Link

• Formatos: JPEG, PNG, WEBP, HEIC y PDF. El tipo se detecta por el contenido (magic bytes), no por la extensión.
• Tamaño: hasta 20 MB (413 file_too_large).
• Páginas: un PDF admite hasta 30 páginas en modo síncrono y hasta 200 con async: true o dentro de un lote. Por encima, 422 too_many_pages.
• Un DNI con anverso y reverso puede ir en un solo fichero (una imagen con las dos caras o un PDF de dos páginas).
• En modo test el nombre del fichero decide la respuesta simulada, así que cuida filename.

OpcionesCopy Anchor Link

Las opciones son estrictas: una clave desconocida devuelve 422 invalid_parameter con param: "options.<clave>".

Perfil de procesamientoCopy Anchor Link

processing elige qué proveedores de IA pueden tocar el documento en esta petición:

• sovereign: solo proveedores con sede y operación en la UE (un modelo europeo o alojado por Constaia, OCR de Mistral en París y los lectores locales de MRZ y PDF417).
• standard: además puede usar Claude en AWS Bedrock (Fráncfort, eu-central-1) o Gemini en Google Vertex AI (región UE). Los datos se procesan en regiones de la UE, pero AWS y Google son empresas con sede en EE. UU. (exposición a la CLOUD Act).
• Si no la envías, se usa el perfil de tu cuenta. Si el perfil pedido no está disponible, la API responde 422 processing_unavailable con param: "options.processing".

La respuesta dice siempre qué se usó en el objeto processing. Detalles en Residencia de datos.

ChecksCopy Anchor Link

checks también es estricto. Cada check solo se aplica si el tipo detectado tiene el campo correspondiente (por ejemplo, generic no tiene fecha de caducidad). Qué checks admite cada tipo lo indica GET /v1/document-types/{type} en su lista checks. Explicación detallada en Checks.

{
  "expect": ["es_dni", "es_nie", "passport"],
  "checks": {
    "min_age_years": 18,
    "holder": { "full_name": "María García López", "birth_date": "1990-05-14" }
  },
  "storage": "none",
  "metadata": { "registration_id": "123" },
  "language": "es"
}

Extraer campos con tu propio esquemaCopy Anchor Link

Pasa un JSON Schema en extract y los campos de fields serán los de tu esquema. Útil con generic o cuando solo quieres unos pocos campos. Las description de cada propiedad guían la extracción.

{
  "expect": "generic",
  "extract": {
    "type": "object",
    "properties": {
      "club_name": { "type": "string", "description": "Nombre del club que emite el documento" },
      "member_name": { "type": "string", "description": "Nombre completo del socio" },
      "season": { "type": "string", "description": "Temporada, p. ej. 2026-2027" }
    }
  },
  "checks": { "require_fields": ["club_name", "member_name"] }
}

Síncrono o asíncronoCopy Anchor Link

• Por defecto la petición espera el resultado hasta 30 segundos y responde 200 con status: "completed" (o "failed").
• Si el análisis tarda más de 30 s, la API responde 202 con el análisis en queued o processing. El trabajo sigue y el resultado llega por el webhook analysis.completed; también puedes consultar GET /v1/analyses/{id}.
• Con async: true la respuesta es 202 inmediata con status: "queued". Permite PDF de hasta 200 páginas.

Tu código debe tratar siempre el 202: comprueba status antes de leer verdict o fields.

Respuesta: el objeto analysisCopy Anchor Link

{
  "id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
  "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": "none", "file_deleted_at": "2026-09-29T10:00:02Z", "expires_at": null },
  "processing": {
    "profile": "sovereign",
    "region": "eu",
    "mode": "vlm",
    "providers": [{ "name": "mock", "region": "local", "role": "llm", "model": "mock-llm-1" }]
  },
  "usage": { "credits": 0, "pages": 1 },
  "metadata": {}
}

En el ejemplo, fields está recortado a un campo. Un DNI devuelve también first_name, last_name_1, last_name_2, sex, nationality, birth_date, expiry_date, issue_date, support_number, address, birth_place, parents y mrz, cada uno con la misma estructura.

El objeto processingCopy Anchor Link

Dice qué perfil se aplicó y qué proveedores tocaron el documento, para que puedas demostrarlo en una auditoría:

{
  "profile": "sovereign",
  "region": "eu",
  "mode": "vlm",
  "providers": [
    { "name": "tesseract", "region": "local", "role": "local", "model": "mrz" },
    { "name": "openai_compat", "region": "de-fra", "role": "llm", "model": "mistral-small-3.2" }
  ]
}

En modo test el único proveedor es mock. Mientras el análisis está en cola, processing puede ser null.

El objeto signatureCopy Anchor Link

Solo en PDF. Constaia verifica la firma PAdES del fichero original (integridad, cadena del certificado y cambios posteriores) sin coste adicional:

{
  "status": "valid",
  "reasons": ["signature_valid"],
  "signer": "SELLO ELECTRONICO DEL MINISTERIO DE JUSTICIA",
  "issuer": "AC Sector Público",
  "signed_at": "2026-09-28T09:14:03Z",
  "trusted": true,
  "trust_anchor": "AC RAIZ FNMT-RCM",
  "signatures": 1
}

status es valid, invalid, missing, modified o untrusted. Qué garantiza cada estado y cómo exigirlo con require_valid_signature: Firmas digitales en PDF.

Motivos (verdict.reasons[].code)Copy Anchor Link

El mismo código puede venir con severidad info (se cumple), warning (lleva a review) o error (lleva a invalid). Por ejemplo, un DNI caducado devuelve { "code": "not_expired", "severity": "error", "message": "Caducado el 15/06/2020." }.

El primer motivo siempre es sobre el tipo:

• type_match (info): el tipo detectado está en expect.
• type_mismatch (error, lleva a invalid): se reconoce un tipo del catálogo, pero no es ninguno de los esperados.
• type_unknown (warning, lleva a review): el documento no se ha podido identificar (tipo generic) o la confianza de la clasificación es menor de 0,5.

Lista completa de códigos: type_match, type_mismatch, type_unknown, not_expired, max_age_days, age, min_age_years, max_age_years, holder, required_field_missing, require_signature, require_stamp, expected_amount, expected_iban, expected_reference, not_fit_for_sport, has_records, low_quality, low_confidence, y el código de cualquier validador determinista que falle (normalmente con severidad error).

Además:

• Firma del PDF: signature_valid (info), signature_invalid (siempre error), signature_missing, document_modified_after_signing y untrusted_signer. Sin require_valid_signature estos tres últimos son warning (y signature_missing solo aparece en tipos que suelen ir firmados); con él, son error. Ver Firmas digitales en PDF.
• Metadatos del PDF: edited_suspected (warning): el PDF lo generó un editor conocido, su fecha de modificación es muy posterior a la de creación o cambió después de firmarse.
• Formulario I-9 (EE. UU.): i9_list (info) indica a qué lista (A, B o C) pertenece el documento. Ver Documentos de EE. UU..

Validadores (checks[].code)Copy Anchor Link

Avisos (warnings)Copy Anchor Link

Constaia no es un KYC biométrico y no compara caras.

Códigos de estado y erroresCopy Anchor Link

Formato y tratamiento de errores en Errores. Para reintentar sin cobros dobles, envía la cabecera Idempotency-Key (Idempotencia).

Ejemplos completosCopy Anchor Link

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Idempotency-Key: registration-123-dni" \
  -F file=@dni_valid.jpg \
  -F 'options={
    "expect": ["es_dni", "es_nie", "passport"],
    "checks": { "min_age_years": 18, "holder": { "full_name": "María García López" } },
    "metadata": { "registration_id": "123" }
  }'

JSON con file_url y file_base64Copy Anchor Link

import { readFile } from "node:fs/promises";
import { Constaia } from "@constaia/sdk";

const constaia = new Constaia();

const fromUrl = await constaia.analyze(
  { fileUrl: "https://example.com/uploads/justificante.pdf" },
  { expect: "payment_receipt", checks: { expectedAmount: 45, expectedReference: "INSCRIPCION 123" } },
);

const fromBase64 = await constaia.analyze(
  { base64: (await readFile("./invoice.pdf")).toString("base64"), filename: "invoice.pdf" },
  { expect: "invoice", export: ["xlsx"] },
);

console.log(fromUrl.verdict?.status, fromBase64.exports.xlsx);

Siguientes pasosCopy Anchor Link