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):
storage | Qué 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. |
none | No 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. |
temporary | Se guarda cifrado y se borra automáticamente pasadas ttl_hours horas (de 1 a 720; 24 por defecto). |
persistent | Se 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
invalidy tu plantilla pide que los inválidos también los revise una persona. - El veredicto es
validy tu plantilla pide revisar también los válidos (no los aprueba sola). - No hay veredicto (documento no reconocido sin
expect, overdict_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_documentsoside_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:
| Ajuste | Valores | Por defecto | Qué hace |
|---|---|---|---|
review_retention_hours_after_decision | 0–720 horas | 24 | Tras 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_days | 1–90 días | 30 | Si 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}devuelve404 resource_missingy el análisis no aparece al listar. - Constaia solo conserva los metadatos de facturación: páginas, créditos y tipo de documento.
{
"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": { "mode": "review", "kept": true, "reason": "pending_review", "expires_at": "2026-10-29T10:00:02Z", "file_deleted_at": null }"storage": { "mode": "review", "kept": false, "reason": null, "expires_at": null, "file_deleted_at": "2026-09-29T10:00:02Z" }"storage": { "mode": "none", "kept": false, "reason": null, "expires_at": null, "file_deleted_at": "2026-09-29T10:00:02Z" }"storage": { "mode": "temporary", "kept": true, "reason": null, "expires_at": "2026-10-02T10:00:02Z", "file_deleted_at": null }| Campo | Descripción |
|---|---|
mode | El modo aplicado (none, review, temporary o persistent): el que pediste, el de la plantilla o el predeterminado de la cuenta. |
kept | true si el original sigue guardado ahora mismo. |
reason | pending_review si se guarda porque espera revisión humana (modo review, sin decidir). null en los demás casos. |
expires_at | Cuá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_at | Cuá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
curl -X DELETE https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
-H "Authorization: Bearer $CONSTAIA_API_KEY"{ "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
exportsson enlaces firmados que caducan a las 24 horas. Pasado ese tiempo devuelven404. 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.
| Perfil | Proveedores de IA que puede usar |
|---|---|
sovereign | Solo 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. |
standard | Los 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:
"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
Privacidad avanzada
Copia pixelada, campos enmascarados, borrado por metadatos y retención.
Residencia de datos
Dónde se procesan y guardan los documentos.
Analizar sin guardar
storage none y keep_results false en la práctica.
Revisión humana desde tu backend
Lista pendientes, descarga el original y decide por API.
Seguridad
Claves, webhooks y buenas prácticas.
Exportaciones
Enlaces firmados que caducan a las 24 h.
Paginación
Cómo recorrer listas de la API de Constaia con paginación por cursor (limit y starting_after) y filtros por estado, tipo y metadata, con ejemplos.
Privacidad avanzada
Copia pixelada del documento con redact, campos enmascarados con mask_fields, borrado y exportación por metadatos (derechos de supresión y de acceso) y retención de resultados por plantilla o cuenta.