Plantillas

Una plantilla (tpl_…) es una configuración de verificación guardada: qué documentos aceptas (expect), qué compruebas (checks), qué se guarda y durante cuánto tiempo, y cuándo tiene que mirar el resultado una persona. La creas una vez y la usas por su id con template en cualquier flujo, en lugar de repetir las mismas opciones en cada llamada. Guía paso a paso con ejemplos en cuatro lenguajes: Reutilizar la configuración con plantillas.

Todas las rutas usan una clave secreta (ck_test_… o ck_live_…) desde tu backend. Las plantillas son de la cuenta, no de un modo: la misma plantilla sirve con claves de test y de live. También se gestionan en el panel, en Plantillas.

El objeto templateCopy Anchor Link

{
  "id": "tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
  "object": "template",
  "name": "DNI vigente mayor de edad",
  "description": "DNI español en vigor de una persona de 18 años o más.",
  "expect": "es_dni",
  "checks": { "not_expired": true, "min_age_years": 18 },
  "extract": true,
  "storage": "review",
  "ttl_hours": null,
  "keep_results": true,
  "export": [],
  "processing": null,
  "language": null,
  "redact": false,
  "mask_fields": ["document_number"],
  "verdict_without_expect": true,
  "retention_days": 90,
  "review_retention_hours_after_decision": 0,
  "review_max_days": 7,
  "review": { "auto_approve_valid": true, "require_human_for": ["review", "invalid"] },
  "example": false,
  "created_at": "2026-09-30T09:12:44Z",
  "updated_at": "2026-09-30T09:12:44Z"
}

Opciones de análisisCopy Anchor Link

Tienen el mismo significado y la misma validación que en POST /v1/analyze. Un valor null en la respuesta significa que la plantilla no lo fija: se usa el de la petición o, si tampoco lo trae, el de la cuenta.

Al crear o cambiar una plantilla también se admite precise_bboxes (como en analyze), aunque no se devuelve en el objeto.

Retención y plazos de revisiónCopy Anchor Link

Los plazos se resuelven al crear cada análisis y se guardan con él: cambiar la plantilla después no altera los análisis ya hechos.

Política de revisión humana (review)Copy Anchor Link

Un análisis hecho con la plantilla queda pendiente (review.status: "pending", verdict.final_status: null) si su veredicto está en require_human_for, o si es valid y auto_approve_valid es false. Sin plantilla, solo los review. La cola se atiende en el panel o por API: ver Revisiones.

Otros camposCopy Anchor Link

Usar una plantillaCopy Anchor Link

Pasa el id de la plantilla con template. Primero se aplica la plantilla y encima las opciones de la petición, que mandan; checks se fusiona clave a clave (puedes añadir holder en cada petición y conservar el resto de checks de la plantilla).

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F "file=@dni.jpg" \
  -F 'options={"template":"tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2","checks":{"holder":{"full_name":"María García López"}},"metadata":{"user_id":"123"}}'

El análisis devuelve la plantilla usada en template_id (y en su alias template). Si la plantilla no existe en la cuenta (o se borró): 422 template_not_found, con param: "options.template" en analyze, classify, lotes y sesiones, y param: "template" en enlaces y expedientes.

Crear una plantillaCopy Anchor Link

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

Solo name es obligatorio. El resto de campos son los del objeto (sin id, object, example ni fechas). Los campos son estrictos: uno desconocido devuelve 422 invalid_parameter con su param.

curl https://api.constaia.com/v1/templates \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DNI vigente mayor de edad",
    "expect": ["es_dni", "es_nie"],
    "checks": { "not_expired": true, "min_age_years": 18 },
    "storage": "review",
    "review_max_days": 7,
    "mask_fields": ["document_number"],
    "review": { "require_human_for": ["review", "invalid"] }
  }'

Responde 201 con el objeto template. Si expect o un check no son válidos, 422 invalid_parameter con el param exacto (expect, checks.min_age_years, review.require_human_for…).

Listar plantillasCopy Anchor Link

GET /v1/templates?limit=20

Devuelve { "object": "list", "data": [...], "has_more": false, "url": "/v1/templates" }, de la más reciente a la más antigua. Ver Paginación.

Recuperar, cambiar y borrarCopy Anchor Link

curl https://api.constaia.com/v1/templates/tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

curl -X PATCH https://api.constaia.com/v1/templates/tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "checks": { "not_expired": true, "min_age_years": 16 }, "ttl_hours": null }'

curl -X DELETE https://api.constaia.com/v1/templates/tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

• PATCH es parcial: solo cambia los campos que mandas. Un campo de análisis a null lo quita de la plantilla (vuelve a mandar la petición o la cuenta). checks se sustituye entero, no se fusiona.
• review se sustituye entero: lo que no mandes dentro de review vuelve a su valor por defecto.
• Los cambios solo afectan a los análisis que se creen después.
• DELETE devuelve { "id": "tpl_…", "object": "template", "deleted": true }. Los análisis, enlaces y expedientes ya creados con ella no cambian; las peticiones nuevas que la usen reciben 422 template_not_found.

Una plantilla que no existe en la cuenta devuelve 404 resource_missing.

Plantillas de ejemploCopy Anchor Link

Cada cuenta empieza con cinco plantillas (example: true), con el nombre en el idioma de la cuenta: DNI vigente mayor de edad, certificado médico deportivo de menos de 6 meses, certificado de delitos sexuales sin antecedentes, justificante de transferencia y factura (con exportación a XLSX). Se crean al dar de alta la cuenta o, en cuentas anteriores, en la primera lectura de la lista. Puedes usarlas tal cual, cambiarlas o borrarlas.

SDKCopy Anchor Link

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

const constaia = new Constaia();

const tpl = await constaia.templates.create({
  name: "DNI vigente mayor de edad",
  expect: ["es_dni", "es_nie"],
  checks: { notExpired: true, minAgeYears: 18 },
  review: { requireHumanFor: ["review", "invalid"] },
  reviewMaxDays: 7,
});

for await (const t of constaia.templates.list()) console.log(t.id, t.name);
await constaia.templates.update(tpl.id, { maskFields: ["document_number"] });
await constaia.templates.delete(tpl.id);

ErroresCopy Anchor Link

Siguientes pasosCopy Anchor Link