Reutilizar la configuración con plantillas

Si validas el mismo tipo de documento desde varios sitios (el formulario de alta, un proceso por lotes, los enlaces que envía tu equipo), acabarás repitiendo las mismas opciones en cada llamada. Una plantilla las guarda en Constaia:

• el código solo pasa template: "tpl_…";
• cambias una regla (edad mínima, antigüedad del certificado, qué va a revisión) sin desplegar;
• el panel, la analítica y la cola de revisión pueden filtrar por plantilla.

En esta guía crearás una plantilla para el DNI de un formulario de inscripción y la usarás en cada flujo. Referencia completa de campos: Plantillas.

Paso 1: crea la plantillaCopy Anchor Link

Queremos un DNI, NIE o pasaporte en vigor, de una persona mayor de edad; que una persona confirme cada rechazo; guardar el original solo mientras espera revisión (como mucho 7 días); y no guardar nunca el número de documento completo.

curl https://api.constaia.com/v1/templates \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inscripción: documento de identidad",
    "description": "DNI, NIE o pasaporte en vigor de un mayor de edad.",
    "expect": ["es_dni", "es_nie", "passport"],
    "checks": { "not_expired": true, "min_age_years": 18 },
    "storage": "review",
    "review_max_days": 7,
    "review_retention_hours_after_decision": 0,
    "mask_fields": ["document_number", "mrz"],
    "retention_days": 365,
    "review": { "auto_approve_valid": true, "require_human_for": ["review", "invalid"] }
  }'

También puedes crearla en el panel, en Plantillas, y copiar su id. La cuenta ya trae cinco plantillas de ejemplo (DNI mayor de edad, certificado médico deportivo, certificado de delitos sexuales, justificante de transferencia y factura) que puedes usar como punto de partida.

Paso 2: analiza con la plantillaCopy Anchor Link

Pasa template y, si hace falta, las opciones propias de cada petición. Aquí añadimos el titular esperado, que depende del usuario: checks se fusiona con los de la plantilla clave a clave.

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

Las opciones de la petición mandan sobre la plantilla. Por ejemplo, "storage": "none" en una petición concreta no guarda el original aunque la plantilla diga review, y "checks": { "min_age_years": 16 } cambia solo la edad mínima. El análisis devuelve template_id para que sepas con qué configuración se juzgó.

Paso 3: úsala en los demás flujosCopy Anchor Link

La misma plantilla sirve en todos los puntos de entrada:

curl https://api.constaia.com/v1/batches \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F "files[]=@dni_1.jpg" -F "files[]=@dni_2.jpg" \
  -F 'options={"template":"tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2"}'

curl https://api.constaia.com/v1/verification-links \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template": "tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2", "reference": "inscripcion-4821", "notify_email": "maria@example.com" }'

curl https://api.constaia.com/v1/sessions \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template": "tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2", "reference": "user_42" }'

curl https://api.constaia.com/v1/dossiers \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template": "tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2", "reference": "inscripcion-4821" }'

En enlaces, sesiones y expedientes, si no mandas documents (o requirements), se pide un único documento (key: "document") con el expect de la plantilla. Si mandas varios, cada uno puede tener su propio expect y checks, que se aplican encima de la plantilla. Más en Enlaces de verificación, Sesiones y Expedientes.

Paso 4: ajusta sin desplegarCopy Anchor Link

Cambia la plantilla desde el panel o con PATCH. Solo afecta a los análisis que se creen después.

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

Para probar un cambio grande sin tocar la plantilla en uso, crea una segunda plantilla, envía una parte del tráfico a cada una y compara con GET /v1/analytics?group_by=template.

Veredicto sin expectCopy Anchor Link

Si la plantilla no fija expect (por ejemplo, «cualquier documento de identidad que suba el usuario»), el veredicto se calcula contra el tipo detectado (verdict.basis: "detected"). Si prefieres no tener veredicto en ese caso, pon verdict_without_expect: false en la plantilla. Ver Veredictos.

ProbarCopy Anchor Link

Con una clave ck_test_… las plantillas funcionan igual y no gastan créditos. Analiza dni_valid.jpg (válido), dni_expired.jpg (no válido, queda pendiente de revisión por require_human_for) y blurry.jpg (a revisar) de los ficheros de prueba y mira review.status y storage.kept en cada respuesta.

Siguientes pasosCopy Anchor Link