Versión: 1.1.0Fecha: 19 de mayo de 2026Clasificación: Interno — Integración Frontend / QAAudiencia: Equipo frontend, QA , arquitecturaRepositorio validado: datavault-backend (este repo)Documento de referencia: CRONOGRAMA_NEBULA_VAULT (S9 B9.3 — Swagger; B9.1 — Postman)
Nota para QA: Este documento describe lo que expone el backend FastAPI en este repositorio , validado contra app/api/ y app/main.py (mayo 2026). Las secciones de mapeo Angular provienen del front nebula-vault-nuevo y se marcan como referencia front cuando no se pueden verificar aquí.
Nebula Vault consume el backend FastAPI DataVault mediante rutas bajo el prefijo /api/*Swagger UI y ReDoc generados por FastAPI; no hay colección Postman versionada en este repositorio.
Recurso
Estado
Notas
Swagger / OpenAPI (FastAPI)
Disponible al levantar el backend
/docs, /redoc, /openapi.json
Colección Postman
No encontrada en repo
Pendiente cronograma S9 (B9.1)
Schemas Pydantic (contratos)
En código backend
app/schemas/
Inventario en código
~130+ handlers HTTP
app/api/ (validado mayo 2026)
Front Angular consumiendo API
Operativo en DEV
Servicios en libs/vault/.../data-access/ (repo front )
El cronograma menciona Gateway Nebula (/api/vault/**). El frontend actual llama directamente al API legacy con rutas /api/ingest, /api/repository, etc. Esta página documenta el contrato del backend desplegado hoy .
┌─────────────┐ ┌──────────────────┐ ┌─────────────────────────────┐
│ vault-shell │────▶│ API_VAULT │────▶│ DataVault FastAPI │
│ (Angular) │ │ /api/ingest, … │ │ Prefijo global: /api │
└─────────────┘ └──────────────────┘ └─────────────────────────────┘
│
│ Login / OAuth Simappe (Nebula)
▼
┌──────────────────┐
│ API_BASE_URL │ → /simappe-oauth2-server/api/v1/…
│ (Simappe) │
└──────────────────┘
Dos bases distintas:
Simappe (auth Nebula): API_BASE_URL — login, refresh OAuth, perfil de sesión Nebula, emisión del JWT que usa DataVault.DataVault (negocio Vault): API_VAULT + rutas relativas /api/... — ingestión, repositorio, preservación, etc.
Ambiente
API Vault (DataVault)
Swagger
Front shell
Local (nx serve)Proxy → https://api-datavault-legacy-dev.centricasoluciones.com
Solo si levantas backend local :8000
http://localhost:4300
DEV https://api-datavault-legacy-dev.centricasoluciones.com{API_VAULT}/docs si está expuestonebula-vault-dev.centricasoluciones.com
Simappe DEV —
—
https://api-dev.centricasoluciones.com
Docker local (este repo) http://localhost:8000http://localhost:8000/docs—
Gateway Nebula (planificado) https://{gateway}/api/vault/**/api/vault/docs (S9)Aún no usado por el front actual
Proxy local front (apps/vault-shell/proxy.conf.json):
Petición navegador: http://localhost:4300/api/...
Destino: https://api-datavault-legacy-dev.centricasoluciones.com/api/...
El backend actual (Fase 3 — Simappe ) no usa el header X-Tenant-ID. El tenant se resuelve desde el JWT de Simappe :
Claim JWT
Uso
company_idObligatorio en la mayoría de endpoints de negocio. Sin él → 403 "Se requiere seleccionar una compañía en la sesión actual"
customer_id, subsidiary_id, environmentContexto adicional de Simappe
Roles (ROLE_ADMIN, ROLE_USER, …)
Mapeados a roles DataVault (admin_empresa, archivista, auditor, consulta, superadmin)
Flujo interno (app/main.py, app/dependencies.py):
Authorization: Bearer {JWT Simappe}
→ get_current_user_session (verificación criptográfica)
→ require_company_selected (company_id presente)
→ get_tenant_db (SimappeAdmin resuelve BD física del tenant)
Header
Obligatorio
Descripción
AuthorizationSí (salvo health)
Bearer {access_token} — token emitido por Simappe , no login local DataVault
Content-TypeJSON (no en multipart)
application/json
X-Tenant-IDNo usar Obsoleto en este backend; el tenant viene del JWT
Flujo
Descripción
Módulos típicos
A — Rol JWT Roles Simappe → check_role_access / jerarquía en app/utils/security.py
Legal hold, retención, ingest (parcial)
B — RBAC por módulo check_module_permission / has_module_permissionIngest, preservación (preservation, preservation.repair)
C — Superadmin Rol superadmin en JWT
Cloud (todos los endpoints), override mark-optimal en preservación
Mapeo roles Simappe → DataVault (extracto de ROLE_MAPPING):
Rol JWT (ejemplos)
Rol DataVault
ROLE_ROOT, ROLE_SUPER_ADMIN, ROLE_DEVELOPERsuperadmin
ROLE_ADMIN, ROLE_CUSTOMER_ADMINadmin_empresa
ROLE_USERarchivista
ROLE_AUDITORauditor
ROLE_VIEWERconsulta
Solo dos rutas activas en app/api/auth.py:
Método
Ruta
Auth
Uso
GET
/api/auth/meBearer JWT Simappe
Usuario actual (claims decodificados)
GET
/api/auth/actuator/healthNo
Health para balanceadores
No expuestos en este backend (existían en legacy; schemas/servicios pueden quedar en código pero sin router):
POST /api/auth/loginPOST /api/auth/refreshPOST /api/auth/logoutPUT /api/auth/profilePUT /api/auth/change-passwordPOST /api/auth/registerPassword reset
Login y refresh: siempre vía Simappe (API_BASE_URL + /simappe-oauth2-server/api/v1/...).
Método
Ruta
Notas
GET
/Info API (message, version, status)
GET
/healthHealth global (status, environment)
Recurso
Ruta
Swagger UI
/docs
ReDoc
/redoc
Esquema OpenAPI JSON
/openapi.json
Ejemplo local: docker compose up (según docker-compose.dev.yml) → http://localhost:8000/docs.
En Swagger Authorize → Bearer {token Simappe}. No añadir X-Tenant-ID; asegurar que el token incluye company_id (selección de empresa en Nebula).
Estado: no hay *.postman_collection.json en este repo.Workaround: Import → Link → https://{host}/openapi.json.Variables de colección: baseUrl, access_token (JWT Simappe completo).Pre-request: no enviar X-Tenant-ID.
Leyenda Front: servicio Angular en nebula-vault-nuevo (referencia, no validado en este repo ).
Método
Ruta
Auth
Notas
GET
/No
Info API
GET
/healthNo
Health check
Método
Ruta
Front
Auth / permisos
GET
/statsDashboardServiceJWT + tenant DB
GET
/tasksParcial / futuro
JWT + tenant DB
Método
Ruta
Front
Notas QA
GET
/projectsIngestProjectService.listRequiere permiso módulo ingest
POST
/projectscreate
PUT
/projects/{project_id}update
DELETE
/projects/{project_id}delete
GET
/projects/{project_id}/subfoldersgetSubfolders
POST
/projects/{project_id}/subfolderscreateSubfolder
POST
/projects/{project_id}/subfolders/bulk—
POST
/uploaduploadIngest (multipart)
GET
/status/{upload_id}getStatus
GET
/list—
— GET /projects/{project_id}No existe Gap: front filtra listado
— GET /projects/{id}/filesFront puede llamarlo
No existe en backend
Método
Ruta
Front
GET
/configConfig servidor
GET
/listNavegación carpetas
GET
/searchBúsqueda global
GET
/downloadDescarga unitaria
POST
/download-multipleZIP múltiple
GET
/download-folderDescarga carpeta
GET
/zip/listContenido ZIP
GET
/zip/downloadDescarga ZIP
Método
Ruta
Permiso QA
GET
/statuspreservation o superadmin
GET
/filepreservation
GET
/criticalpreservation
GET
/optimalpreservation
GET
/attentionpreservation
GET
/reports/statisticspreservation
POST
/verify-filespreservation
POST
/verifypreservation
PUT
/file/mark-optimalSolo superadmin
GET
/file/diagnosepreservation.repair
POST
/file/repairpreservation.repair
Método
Ruta
Front
GET
``
Listado
GET
/activeActivos
POST
``
Crear
PATCH
/{message_id}Editar
DELETE
/{message_id}Eliminar
Método
Ruta
Front
GET/POST
/policiesRetentionPolicyService
GET/PUT/DELETE
/policies/{policy_id}CRUD políticas
GET/POST
/documentsDocumentRetentionService
GET/PUT/DELETE
/documents/{retention_id}CRUD documentos
POST
/documents/{retention_id}/suspendSuspender
POST
/documents/{retention_id}/resumeReanudar
GET
/documents/expiring-soonPróximos a vencer
GET
/statsEstadísticas
GET
/documents/from-serverSelector desde servidor
GET
/documents/availableDisponibles
POST
/documents/by-pathAlta por ruta
GET
/audit/server-filesAuditoría archivos servidor
GET
/detect-files-by-policy/{policy_id}Detección por política
Método
Ruta
Notas QA
GET/POST
``
Listar / crear casos
GET/PUT
/{legal_hold_id}Detalle sí existe
POST
/{legal_hold_id}/closeCerrar
POST
/{legal_hold_id}/reopenReabrir
POST
/{legal_hold_id}/documentsAsignar documento
DELETE
/{legal_hold_id}/documents/{document_id}Quitar documento
POST
/documents/by-pathAsignar por ruta
GET
/documents/from-serverDesde servidor
GET
/documents/availableDisponibles
GET
/documents/check/{document_id}Verificar
Contrato fechas: start_date, end_date → tipo date-time (ISO 8601), ver app/schemas/legal_hold.py.
Roles típicos: admin_empresa, superadmin (check_role_access).
Método
Ruta
Auth
GET
/statusSuperadmin
POST
/uploadSuperadmin
GET
/daemon/statusSuperadmin
GET
/daemon/status/allSuperadmin
POST
/daemon/startSuperadmin
POST
/daemon/stopSuperadmin
POST
/daemon/restartSuperadmin
GET
/daemon/statsSuperadmin
GET
/daemon/logsSuperadmin
Método
Ruta
Front
GET
``
Logs del tenant
GET
/globalLogs globales (admin)
GET
/exportExport CSV/Excel
Método
Ruta
Backend
Front
GET
``
Listado (unread_only, limit)
NotificationsService
GET
/unread-countContador
—
PUT
/{notification_id}/readMarcar leída
Sí
PUT
/read-allMarcar todas
Front usa mark-all-read ⚠️
POST
``
Crear
—
POST
/test-pushSolo development / debug
—
Gap confirmado: backend expone PUT /api/notifications/read-all; si el front llama mark-all-read, fallará hasta alinear rutas.
Método
Ruta
Backend en repo
GET
/api/reports/typesNo existe
POST
/api/reports/generateNo existe
El front puede usar lista local de tipos si recibe 404. QA: no probar estos endpoints contra este backend hasta implementación.
Prefijo
Endpoints principales
Notas
/api/admin/usersCRUD, GET /allowed-domains
Gestión usuarios
/api/admin/tenantsCRUD + GET /test, GET /simple (utilidad)
Gestión empresas
/api/admin/user-tenantsRouter vacío (deprecado) Ver comentario en admin_user_tenants.py
/api/module-permissionsCRUD + GET /user/{user_id} + carpetas
Permisos módulo
Método
Ruta
Uso
GET
/my-tenantsEmpresas del usuario
GET
``
Listado (admin)
POST
``
Crear tenant
GET/PUT
/{tenant_id}Detalle / actualizar
POST
/requestsSolicitud alta tenant
GET
/requestsListar solicitudes
PUT
/requests/{request_id}/approveAprobar
PUT
/requests/{request_id}/rejectRechazar
Método
Ruta
GET
/inspect/{document_id}
POST
/apply-legal-hold/{document_id}
POST
/remove-legal-hold/{document_id}
POST
/apply-retention/{document_id}
Usa BD compartida OAIS (get_oais_db) + tenant_key del JWT.
Método
Ruta
POST
/assign
GET
/assigned
DELETE
/unassign/{assignment_id}
Según cronograma S11 — B11.4 , no deben probarse en Vault. Siguen activos en Swagger de este backend:
Prefijo API
Dominio
/api/employeesEmpleados
/api/contractsContratos
/api/certificationsCertificaciones
/api/trainingsCapacitaciones
/api/absencesAusencias
/api/hr-documentsDocumentos RRHH
Referencia front — validar en repo nebula-vault-nuevo.
Módulo UI
Servicio Angular
basePath
Inicio
DashboardService/api/dashboard
Carga documentos
IngestProjectService/api/ingest
Bóveda digital
RepositoryService/api/repository
Preservación
PreservationService/api/preservation
Mensajes informativos
PreservationMessagesService/api/preservation-messages
Retención
RetentionPolicyService, DocumentRetentionService/api/document-retention
Custodia legal
LegalHoldService/api/legal-hold
Respaldo externo
CloudService/api/cloud
Auditoría
AuditService/api/audit
Reportes
ReportsService/api/reports (sin backend )
Notificaciones
NotificationsService/api/notifications
Perfil
ProfileService/api/auth (solo /me en backend)
Login Nebula
AuthServiceSimappe /simappe-oauth2-server/api/v1
#
Tema
Detalle
Acción QA
1
Auth legacy
Doc antiguo listaba /api/auth/login, refresh, etc.
Obtener JWT solo desde Simappe
2
X-Tenant-IDNo se usa; tenant = company_id en JWT
No enviar header; verificar empresa seleccionada en UI
3
Gateway vs legacy
Cronograma: /api/vault/**; hoy: /api/** directo
Probar URL real del despliegue DEV
4
Postman
No versionada
Import OpenAPI o esperar S9 B9.1
5
GET /ingest/projects/{id}No existe
Esperar listado o usar PUT con id conocido
6
GET /ingest/projects/{id}/filesNo existe
No reportar como bug de backend si front lo llama
7
/api/reports/*No implementado
404 esperado; front con fallback
8
Notificaciones
Backend: PUT .../read-all; front: mark-all-read
Probar read-all; escalar desalineación front
9
/api/admin/user-tenantsDeprecado (router vacío)
No incluir en casos de prueba
10
HR endpoints
Activos en API, fuera producto Vault
Excluir de regresión Vault
11
Cloud
Solo superadmin
Usar usuario con ROLE_SUPER_ADMIN / equivalente
Usuario Nebula con acceso a Simappe DEV.
Empresa seleccionada en la sesión (token con company_id).Rol adecuado al módulo bajo prueba (ver tablas de permisos).
Token copiado desde DevTools (Network) o login Simappe.
Escenario
Request
Resultado esperado
Sin token
GET /api/dashboard/stats401
Token sin company_id
GET /api/dashboard/stats403 (compañía no seleccionada)
Token válido + empresa
GET /api/auth/me200 + claims
Rol insuficiente Cloud
GET /api/cloud/status403 superadmin
Health
GET /health200 sin Authorization
# Sustituir TOKEN por JWT de Simappe (con company_id)
export TOKEN="eyJ..."
export API="https://api-datavault-legacy-dev.centricasoluciones.com"
curl -s "$API/api/auth/me" \
-H "Authorization: Bearer $TOKEN"
curl -s "$API/api/dashboard/stats" \
-H "Authorization: Bearer $TOKEN"
curl -s "$API/api/notifications/unread-count" \
-H "Authorization: Bearer $TOKEN"
# Marcar todas leídas (ruta real del backend)
curl -s -X PUT "$API/api/notifications/read-all" \
-H "Authorization: Bearer $TOKEN"
# En la raíz de datavault-backend
docker compose -f docker-compose.dev.yml up -d
# http://localhost:8000/docs → Authorize → Bearer {TOKEN}
/api/auth/me con token Simappe válido/api/dashboard/statspreservation)read-all company_id → 403 en rutas tenant
Recurso
Ubicación
Routers API
app/api/__init__.py
Registro de rutas
app/api/*.py
Schemas Pydantic
app/schemas/
Auth / roles Simappe
app/utils/security.py, app/dependencies.py
Permisos preservación
app/utils/preservation_permissions.py
Entrypoint FastAPI
app/main.py
Deploy DEV Centrica
deploy-centrica-dev.sh
Documentos externos (wiki / front) citados en cronograma: matriz roles, matriz OAIS, QA_MATRIZ_ROLES_VAULT_S8.md en repo front.
Versión
Fecha
Autor
Descripción
1.0.0
2026-05-19
Equipo Vault
Borrador inicial (inventario + mapeo front)
1.1.0
2026-05-19
Equipo Vault
Validación contra datavault-backend: auth Simappe, sin X-Tenant-ID, inventario corregido, gaps QA, endpoints cloud/retención/notificaciones