Constaia
Conceptos

Almacenamiento y privacidad

Qué guarda Constaia de tus documentos y cuánto tiempo, con los modos review, none, temporary y persistent, plazos de revisión, keep_results, borrado, cifrado y perfiles de proceso.

Por defecto solo guardamos, cifrados, los documentos que necesitan revisión humana, y los borramos al decidir. Todos los demás se procesan y se descartan. Puedes elegir no guardar nunca el fichero o, al contrario, conservarlo más tiempo, por petición o como predeterminado de la cuenta.

Modos de almacenamiento

Se eligen con la opción storage de POST /v1/analyze (y de las clasificaciones y los lotes):

storageQué pasa con el fichero
review (por defecto)Se guarda cifrado solo si el análisis necesita revisión humana. Se borra al decidir la revisión (tras un margen configurable) o, si nadie decide, al cabo de un plazo máximo. Si no hace falta revisarlo, se borra al terminar el análisis, igual que con none.
noneNo se guarda nunca. Análisis síncrono: el fichero se procesa en memoria y nunca se escribe en el almacenamiento. Asíncrono o en lote: se guarda cifrado solo hasta que el análisis termina y entonces se borra. La revisión humana solo verá los datos extraídos, no el documento.
temporarySe guarda cifrado y se borra automáticamente pasadas ttl_hours horas (de 1 a 720; 24 por defecto).
persistentSe guarda cifrado hasta que lo borras con DELETE /v1/analyses/{id}.

Si no mandas storage, se usa el predeterminado de tu cuenta, que es review salvo que lo hayas cambiado. Lo mismo con ttl_hours: el de la cuenta o, si no hay, 24. Los predeterminados se cambian en el panel (Ajustes de la cuenta).

Cuentas creadas antes de este cambio

Las cuentas que tenían none como predeterminado pasan a review, salvo que el propietario hubiera cambiado el almacenamiento por defecto a mano: en ese caso se respeta su elección. Si quieres que un flujo no guarde nunca el documento, envía storage: "none" explícitamente en esas peticiones.

storage afecta al fichero. Los resultados (tipo, veredicto, campos) se guardan para que puedas consultarlos con GET /v1/analyses/{id}, salvo que uses keep_results: false.

Cuándo se guarda el documento en modo review

El original se guarda, cifrado, cuando el análisis queda pendiente de revisión humana:

  • El veredicto es review (Constaia no ha podido decidir con seguridad).
  • El veredicto es invalid y tu plantilla pide que los inválidos también los revise una persona.
  • El veredicto es valid y tu plantilla pide revisar también los válidos (no los aprueba sola).
  • No hay veredicto (documento no reconocido sin expect, o verdict_without_expect: false), pero hay avisos de calidad que piden mirar el documento: low_quality, blurry, cropped, glare, screen_photo_suspected, photocopy_suspected, edited_suspected, multiple_documents o side_missing.

Un veredicto calculado sin expect contra el tipo detectado (verdict.basis: "detected") sigue las mismas reglas que cualquier otro veredicto. En cualquier otro caso el fichero se borra al terminar el análisis.

Plazos de conservación

Dos ajustes controlan cuánto tiempo se guarda un documento pendiente de revisión:

AjusteValoresPor defectoQué hace
review_retention_hours_after_decision0–720 horas24Tras decidir la revisión, el original se conserva estas horas (para consultar la decisión) y después se borra. Con 0 se borra al decidir.
review_max_days1–90 días30Si nadie decide, el original se borra a los N días de terminar el análisis.

Se configuran para toda la cuenta en el panel (Ajustes de la cuenta) y, si lo necesitas, en cada plantilla; lo que fije la plantilla manda sobre la cuenta.

Mientras el original está guardado, tu equipo puede verlo al revisar en el panel y tu backend puede descargarlo con la API: ver Revisión humana desde tu backend.

keep_results: false

Con keep_results: false los datos extraídos tampoco se guardan:

  • Recibes el resultado completo una sola vez, en la respuesta (o en el webhook si es asíncrono).
  • Después, GET /v1/analyses/{id} devuelve 404 resource_missing y el análisis no aparece al listar.
  • Constaia solo conserva los metadatos de facturación: páginas, créditos y tipo de documento.
Lo mínimo posible
{
  "file_url": "https://example.com/dni.jpg",
  "expect": "es_dni",
  "storage": "none",
  "keep_results": false
}

Guía práctica: analizar sin guardar.

El objeto storage de la respuesta

Cada análisis te dice qué ha pasado con el fichero:

storage: review, pendiente de revisión
"storage": { "mode": "review", "kept": true, "reason": "pending_review", "expires_at": "2026-10-29T10:00:02Z", "file_deleted_at": null }
storage: review, no hacía falta revisarlo
"storage": { "mode": "review", "kept": false, "reason": null, "expires_at": null, "file_deleted_at": "2026-09-29T10:00:02Z" }
storage: none, análisis síncrono
"storage": { "mode": "none", "kept": false, "reason": null, "expires_at": null, "file_deleted_at": "2026-09-29T10:00:02Z" }
storage: temporary, ttl_hours: 72
"storage": { "mode": "temporary", "kept": true, "reason": null, "expires_at": "2026-10-02T10:00:02Z", "file_deleted_at": null }
CampoDescripción
modeEl modo aplicado (none, review, temporary o persistent): el que pediste, el de la plantilla o el predeterminado de la cuenta.
kepttrue si el original sigue guardado ahora mismo.
reasonpending_review si se guarda porque espera revisión humana (modo review, sin decidir). null en los demás casos.
expires_atCuándo se borrará el original. null si no se guarda o con persistent. Al decidir una revisión pasa a la hora de la decisión más review_retention_hours_after_decision.
file_deleted_atCuándo se borró el fichero, o null si sigue guardado. En modo none coincide con el final del análisis.

Mientras kept es true, el campo file_url del análisis trae una URL firmada al original que caduca a los 15 minutos. Pide el análisis de nuevo con GET /v1/analyses/{id} para obtener una nueva, o descárgalo con GET /v1/analyses/{id}/file.

Borrar un análisis

Terminal
curl -X DELETE https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"
Respuesta
{ "id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2", "object": "analysis", "deleted": true }

Borra el fichero, los resultados y las exportaciones del análisis. Es irreversible: después, GET devuelve 404. Úsalo, por ejemplo, cuando un usuario ejerce su derecho de supresión.

Exportaciones y descargas

  • Las URL de exports son enlaces firmados que caducan a las 24 horas. Pasado ese tiempo devuelven 404. Ver exportaciones.
  • Todas las descargas pasan por https://api.constaia.com/v1/files/…. Nunca recibes una URL directa del almacenamiento de objetos.

Cifrado y dónde se guarda

  • Cifrado en la aplicación antes de escribir nada: AES-256-GCM con una clave distinta por cuenta, derivada de una clave maestra. El proveedor de almacenamiento solo ve datos cifrados.
  • Almacenamiento de objetos en la UE: en producción, Cloudflare R2 con jurisdicción UE (los datos se guardan en centros de datos de la UE), que además cifra en reposo. Solo accede el servidor de la API: ningún tráfico tuyo ni de tus usuarios va a URLs del almacenamiento; ficheros y exportaciones se sirven siempre a través de la API.
  • Claves de API: se guardan como hash (SHA-256) y solo se muestran una vez al crearlas.
  • Secretos de webhook: se guardan cifrados.
  • Tránsito: toda la API se sirve por HTTPS.

Dónde se procesan los documentos (regiones y proveedores de IA) está en residencia de datos.

Perfiles de proceso: sovereign y standard

Con la opción processing eliges qué proveedores de IA pueden tocar un documento, en cada petición. Si no la mandas, se usa el perfil predeterminado de tu cuenta (sovereign cuando hay un proveedor soberano disponible). El predeterminado de la cuenta todavía no se puede cambiar desde el panel: envía processing en cada petición o escríbenos a support@constaia.com.

PerfilProveedores de IA que puede usar
sovereignSolo proveedores con sede y operación en la UE: un modelo europeo (IONOS, Scaleway, OVHcloud) o alojado por Constaia, OCR de Mistral (París) y los lectores locales de MRZ y PDF417.
standardLos anteriores y, además, Claude en AWS Bedrock (Fráncfort, eu-central-1) o Gemini en Google Vertex AI (región UE).

Sobre el perfil standard

AWS y Google procesan los datos en regiones de la UE, pero son empresas con sede en Estados Unidos y por tanto están sujetas a legislación estadounidense como la CLOUD Act. Si eso es un problema para tu caso, usa sovereign.

Si el perfil pedido no está disponible, la API responde 422 processing_unavailable. La respuesta incluye qué perfil se aplicó y qué proveedores procesaron el documento:

Respuesta
"processing": {
  "profile": "sovereign",
  "region": "eu",
  "mode": "vlm",
  "providers": [
    { "name": "tesseract", "region": "local", "role": "local", "model": "mrz" },
    { "name": "openai_compat", "region": "de-fra", "role": "llm", "model": "mistral-small-3.2" }
  ]
}

Detalle de cada campo en POST /v1/analyze.

La lista completa de subencargados de cada perfil está en el DPA.

Registro de auditoría y DPA

  • Constaia mantiene un registro de auditoría de las acciones sensibles de la cuenta (quién, desde qué IP y qué acción).
  • El acuerdo de encargo de tratamiento (DPA) está en /es/legal/dpa.

Siguientes pasos

En esta página