Veredictos y motivos

El veredicto responde a una pregunta concreta: "¿es este documento un X válido según mis reglas?". Aparece en verdict cuando indicas qué esperas con expect. Sin expect, verdict es null y solo recibes la clasificación (document), los campos (fields), las comprobaciones deterministas (checks) y los avisos (warnings).

El objeto verdictCopy Anchor Link

"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." }
  ]
}

Cada motivo tiene esta forma:

Los tres estadosCopy Anchor Link

La regla es mecánica y siempre la misma:

si algún motivo tiene severity "error"   → invalid
si no, si alguno tiene severity "warning" → review
si no                                      → valid

error gana a warning: un DNI caducado y además borroso es invalid, no review.

review no es un fallo de la API. Significa que Constaia no tiene datos suficientes para decidir con seguridad y que debe mirarlo una persona o pedirse otra foto. Consulta la guía revisión humana.

Qué motivos aparecenCopy Anchor Link

1. Tipo: siempre hay exactamente uno entre type_match, type_mismatch o type_unknown.
2. Checks que pediste (y los que están activos por defecto, como not_expired en documentos con caducidad): uno o varios motivos por cada uno. Detalle en checks.
3. Reglas propias del tipo: not_fit_for_sport (certificado médico con "no apto"), has_records (certificados de antecedentes).
4. Comprobaciones deterministas que fallan: si un elemento de checks[] tiene passed: false, se añade un motivo con su mismo code y severidad error. Las que pasan solo aparecen en checks[], no en reasons.
5. Calidad y confianza: low_quality y low_confidence, con severidad warning.
6. PDF: el resultado de la firma electrónica (signature_valid, signature_invalid…) y edited_suspected si los metadatos apuntan a una edición. Ver firmas digitales en PDF.
7. Formulario I-9: i9_list (info) en los documentos de EE. UU. de las listas A, B o C.

Tabla de códigos de motivoCopy Anchor Link

Estos códigos son estables. Podemos añadir códigos nuevos sin previo aviso (ver versionado): trata cualquier código desconocido según su severity.

Mismo código, distinta severidadCopy Anchor Link

El code dice qué regla se evaluó; la severity dice cómo salió. Un DNI vigente y uno caducado producen el mismo código:

{ "code": "not_expired", "severity": "info", "message": "Vigente hasta el 12/03/2031." }

{ "code": "not_expired", "severity": "error", "message": "Caducado el 15/06/2020." }

Por eso tu código debe mirar siempre el par code + severity, nunca solo la presencia del código.

Avisos (warnings)Copy Anchor Link

warnings es una lista de señales sobre la imagen o el documento. No son prueba de fraude: son indicios para decidir si pedir otra foto o revisar a mano. Constaia no es un KYC biométrico y no compara caras.

Las señales de calidad (low_quality, blurry, cropped, glare, screen_photo_suspected, photocopy_suspected, edited_suspected, multiple_documents) se resumen en un único motivo low_quality con severidad warning, así que llevan el veredicto a review (si no hay un error). side_missing y language_mismatch aparecen en warnings pero no cambian el veredicto por sí solas.

"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"]

Si la imagen es tan mala que se rechaza antes del OCR, document es null, match es false, el único motivo es low_quality (warning) y el análisis no se cobra.

Qué hacer con cada veredictoCopy Anchor Link

Recuerda además que el análisis puede no haber terminado: con async: true, o si tarda más de 30 s, recibes 202 con status: "queued" o "processing" y el resultado llega por webhook.

import { Constaia, InvalidRequestError } from "@constaia/sdk";
import { fromPath } from "@constaia/sdk/node";

const constaia = new Constaia(); // lee CONSTAIA_API_KEY

type Decision =
  | { action: "accept"; documentNumber: string | undefined }
  | { action: "reject"; errors: string[] }
  | { action: "review"; warnings: string[] }
  | { action: "pending"; id: string };

export async function checkDni(path: string, fullName: string): Promise<Decision> {
  const analysis = await constaia.analyze(await fromPath(path), {
    expect: "es_dni",
    checks: { holder: { fullName } },
  });

  if (analysis.status !== "completed") {
    return { action: "pending", id: analysis.id }; // llegará por webhook
  }

  const reasons = analysis.verdict?.reasons ?? [];
  switch (analysis.verdict?.status) {
    case "valid":
      return { action: "accept", documentNumber: analysis.fields.document_number?.value as string | undefined };
    case "invalid":
      return {
        action: "reject",
        errors: reasons.filter((r) => r.severity === "error").map((r) => r.message),
      };
    default:
      return {
        action: "review",
        warnings: reasons.filter((r) => r.severity === "warning").map((r) => r.message),
      };
  }
}

try {
  console.log(await checkDni("./dni_valid.jpg", "María García López"));
} catch (err) {
  if (err instanceof InvalidRequestError) console.error(err.code, err.param, err.message);
  else throw err;
}

Varios tipos aceptadosCopy Anchor Link

Con expect como lista, match es true si el documento es cualquiera de ellos. Es lo habitual para "documento de identidad": DNI, NIE/TIE o pasaporte.

{ "file_url": "https://example.com/nie.jpg", "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." }
  ]
}

Los checks se evalúan contra el tipo detectado, así que mira document.type para saber de qué campo leer el número (document_number en DNI y pasaporte, nie_number en NIE). Puedes consultar los campos de cada tipo con GET /v1/document-types/{type} o en el catálogo.

Sin expect: verdict es nullCopy Anchor Link

Si no mandas expect, Constaia clasifica y extrae, pero no decide:

"document": { "type": "generic", "label": "Otro documento", "confidence": 0.64, "side": null, "country": null },
"verdict": null,
"checks": [],
"warnings": []

Úsalo cuando no sabes qué documento te van a subir y quieres enrutar por document.type, o cuando aplicas tus propias reglas sobre fields. Si solo necesitas saber el tipo, POST /v1/classify cuesta 0,2 créditos; su veredicto solo contiene type_match o type_mismatch.

Siguientes pasosCopy Anchor Link