Expedientes

Un expediente (dos_…) agrupa los documentos de una misma persona o trámite (el DNI, el certificado médico y el justificante de pago de una inscripción, por ejemplo) y calcula un veredicto global: si está todo, si algo falla o si hay que revisarlo. Además comprueba que todos los documentos son del mismo titular y que sus fechas son coherentes.

Todas las rutas usan una clave secreta (ck_test_… o ck_live_…) desde tu backend y solo ven los expedientes del modo de la clave. En el panel están en Expedientes.

Crear un expedienteCopy Anchor Link

POST /v1/dossiers
Content-Type: application/json

Un expediente sin requisitos (ni plantilla) también vale: acepta cualquier documento, y el veredicto se calcula con todos los que añadas.

curl https://api.constaia.com/v1/dossiers \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "inscripcion-4821",
    "metadata": { "registration_id": "4821" },
    "requirements": [
      { "key": "id_card", "label": "DNI o NIE", "expect": ["es_dni", "es_nie"], "checks": { "not_expired": true } },
      { "key": "medical", "label": "Certificado médico", "expect": "medical_certificate_sport", "checks": { "max_age_days": 180 } }
    ]
  }'

Responde 201 con el objeto dossier, con verdict.status: "incomplete" hasta que lleguen los documentos. Una clave repetida devuelve 422 duplicate_document_key; un expect o un check no válidos, 422 invalid_parameter con param: "requirements.<i>.<campo>".

Añadir documentosCopy Anchor Link

POST /v1/dossiers/{id}/documents

Hay dos maneras:

Responde 200 con el expediente actualizado.

# Fichero, para un requisito concreto
curl https://api.constaia.com/v1/dossiers/dos_01J9Z8Q3K4M5N6P7Q8R9S0T1V2/documents \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F "file=@dni.jpg" \
  -F "requirement_key=id_card"

# Análisis que ya tenías
curl https://api.constaia.com/v1/dossiers/dos_01J9Z8Q3K4M5N6P7Q8R9S0T1V2/documents \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "analysis_id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3", "requirement_key": "medical" }'

A qué requisito va. Si mandas requirement_key, a ese (si no existe: 422 invalid_document_key). Si no:

• con un fichero y un solo requisito, a ese; con varios, se analiza aceptando la unión de sus expect (sin sus checks) y se asigna al primer requisito sin documento cuyo expect incluye el tipo detectado;
• con analysis_id, al requisito del análisis si vino de un enlace con la misma clave o, si no, igual que arriba según su tipo;
• si ningún requisito encaja, queda como documento suelto: no cubre ningún requisito, pero cuenta para las comprobaciones cruzadas.

Puedes añadir varios documentos al mismo requisito (una foto nueva tras un rechazo, por ejemplo). Cuenta el último; si el último falló, el último que se completó.

El objeto dossierCopy Anchor Link

{
  "id": "dos_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
  "object": "dossier",
  "livemode": false,
  "reference": "inscripcion-4821",
  "template": null,
  "verification_link_id": null,
  "metadata": { "registration_id": "4821" },
  "requirements": [
    { "key": "id_card", "label": "DNI o NIE", "expect": ["es_dni", "es_nie"], "checks": { "not_expired": true }, "status": "valid", "analysis_id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3" },
    { "key": "medical", "label": "Certificado médico", "expect": ["medical_certificate_sport"], "checks": { "max_age_days": 180 }, "status": "missing", "analysis_id": null }
  ],
  "documents": [
    { "analysis_id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3", "requirement_key": "id_card", "type": "es_dni", "file_name": "dni.jpg", "status": "completed", "verdict_status": "valid", "final_status": "valid", "created_at": "2026-09-30T10:02:11Z" }
  ],
  "verdict": {
    "status": "incomplete",
    "reasons": [
      { "code": "requirement_missing", "severity": "warning", "message": "Falta el documento «Certificado médico».", "requirement_key": "medical" }
    ],
    "checks": [
      { "code": "same_holder", "passed": null, "severity": "warning", "message": "No hay datos suficientes para comprobar que todos los documentos son de la misma persona.", "analyses": ["an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3"] },
      { "code": "dates_consistent", "passed": true, "severity": "info", "message": "Las fechas de los documentos son coherentes.", "analyses": ["an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3"] }
    ]
  },
  "holder": { "name": "MARÍA GARCÍA LÓPEZ", "document_number": "12345678Z", "birth_date": "1990-04-12" },
  "created_at": "2026-09-30T10:00:00Z",
  "updated_at": "2026-09-30T10:02:12Z"
}

Los mensajes de reasons y checks salen en el idioma de la cabecera Accept-Language (es, en, pt, fr).

Veredicto globalCopy Anchor Link

Cada requisito toma el estado de su análisis. Si una persona revisó el análisis, cuenta su decisión (final_status); si está pendiente de revisión, o no tiene veredicto, cuenta como review. El expediente:

Sin requisitos, cada documento añadido cuenta como un requisito (y sin ningún documento, incomplete con el motivo no_documents). Los motivos por requisito son requirement_missing, requirement_processing, requirement_failed, requirement_invalid y requirement_review.

El veredicto se recalcula solo cuando termina un análisis del expediente o cuando una persona decide su revisión (en el panel o con POST /v1/analyses/{id}/review). Los expedientes no tienen webhook propio: consulta GET /v1/dossiers/{id} al recibir el analysis.completed o analysis.reviewed del documento, o usa un enlace de verificación y su evento verification_link.completed.

Comprobaciones cruzadasCopy Anchor Link

Solo cuentan los análisis completados (el que cuenta para cada requisito y los documentos sueltos). Los valores enmascarados con mask_fields no se comparan.

Listar, recuperar y borrarCopy Anchor Link

curl -G https://api.constaia.com/v1/dossiers \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  --data-urlencode "verdict=review" \
  --data-urlencode "metadata[registration_id]=4821"

GET /v1/dossiers/{id} devuelve el objeto. DELETE /v1/dossiers/{id} devuelve { "id": "dos_…", "object": "dossier", "deleted": true } y no borra los análisis (para eso, ver borrado por metadatos). Un expediente de otro modo o que no existe devuelve 404 resource_missing.

SDKCopy Anchor Link

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

const constaia = new Constaia();

const dossier = await constaia.dossiers.create({
  reference: "inscripcion-4821",
  requirements: [
    { key: "id_card", expect: ["es_dni", "es_nie"] },
    { key: "medical", expect: "medical_certificate_sport", checks: { maxAgeDays: 180 } },
  ],
});

await constaia.dossiers.addDocument(dossier.id, await fromPath("dni.jpg"), { requirementKey: "id_card" });
const updated = await constaia.dossiers.addDocument(
  dossier.id,
  { analysisId: "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V3" },
  { requirementKey: "medical" },
);

console.log(updated.verdict.status); // complete_valid | incomplete | invalid | review

ErroresCopy Anchor Link

Siguientes pasosCopy Anchor Link