Tipos de documento

Cada documento que analizas se clasifica en un tipo. El identificador del tipo (es_dni, payment_receipt, invoice…) es lo que envías en expect y lo que recibes en document.type. Cada tipo define:

• una plantilla de campos: lo que devuelve extract: true en fields;
• unos validadores deterministas que se ejecutan siempre que el documento lo permite: letra del NIF/NIE, dígitos de control de la MRZ, IBAN, cuadre de totales, formato del CSV;
• los checks que tienen sentido para él: caducidad en un DNI, antigüedad en un certificado, importe en un justificante.

La fuente de verdad es GET /v1/document-types: público, sin clave y siempre al día. Para ver cada tipo con más detalle, abre el catálogo completo.

CategoríasCopy Anchor Link

CatálogoCopy Anchor Link

Aceptar varios tipos con expectCopy Anchor Link

Muchas veces te vale más de un documento: "DNI, NIE o pasaporte". Pasa una lista en expect (hasta 20 tipos). El veredicto es valid si el documento es cualquiera de ellos y cumple los checks.

{
  "expect": ["es_dni", "es_nie", "passport", "eu_id_card"],
  "checks": { "min_age_years": 18, "holder": { "full_name": "María García López" } }
}

• El tipo detectado llega en document.type y verdict.expected repite tu lista.
• Si se reconoce un tipo del catálogo que no está en la lista, el veredicto es invalid con el motivo type_mismatch.
• Si el documento no se puede identificar (generic) o la confianza de la clasificación es menor de 0,5, el motivo es type_unknown y el veredicto review.

Cada check se aplica solo si el tipo detectado tiene el campo correspondiente: min_age_years en un DNI, max_age_days en un certificado, expected_amount en un justificante. Si mezclas tipos, elige checks que tengan sentido para todos o ramifica según document.type. Qué checks admite cada tipo lo dice su lista checks en GET /v1/document-types/{type}.

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

const constaia = new Constaia();

const analysis = await constaia.analyze(await fromPath("./nie.jpg"), {
  expect: ["es_dni", "es_nie", "passport"],
  checks: { minAgeYears: 18, holder: { fullName: "Anna Kowalska" } },
});

switch (analysis.document?.type) {
  case "es_dni":
    console.log(analysis.fields.document_number?.value);
    break;
  case "es_nie":
    console.log(analysis.fields.nie_number?.value);
    break;
  case "passport":
    console.log(analysis.fields.document_number?.value, analysis.fields.nationality?.value);
    break;
}
console.log(analysis.verdict?.status);

En modo test, un fichero llamado nie.jpg devuelve un NIE válido de ANNA KOWALSKA.

generic con tu propio esquemaCopy Anchor Link

Si tu documento no está en el catálogo (una autorización de tu club, un formulario interno, un certificado poco habitual), analízalo con generic y describe los campos con un JSON Schema en extract:

{
  "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" },
      "signed": { "type": "boolean", "description": "Si el documento está firmado" }
    }
  },
  "checks": { "require_fields": ["club_name", "member_name"] }
}

Los campos vuelven en fields con valor, confianza y posición, igual que en los tipos del catálogo. generic no tiene validadores deterministas ni caducidad: los checks útiles son require_fields y max_age_days. La calidad del resultado depende de lo claras que sean las description de tu esquema. Más detalles en POST /v1/analyze.

También puedes pasar un esquema propio con un tipo del catálogo para quedarte solo con algunos campos: parte del schema que devuelve GET /v1/document-types/{type}.

Tipos nuevos en tu códigoCopy Anchor Link

El catálogo crece. Programa tu integración para que no falle si recibe en document.type un tipo que no conoce: trátalo como "otro documento" y mándalo a revisión. Si validas tu configuración al arrancar, hazlo contra GET /v1/document-types y no contra una lista fija.

Siguientes pasosCopy Anchor Link