API e integraciones

Propósito

Orientar a integradores y administradores sobre cómo consumir la API de VStation y enlaces relacionados. No hay página /api-docs embebida (redirige al inicio).

Documentación de referencia

Recurso	Dónde encontrarlo
OpenAPI / portal central	optrax-docs → catálogo API → VStation (vstation/openapi/openapi.yaml sincronizado).
Colección Postman	Ajustes → General → descargar colección Postman (archivo vstation-api-postman.json).
Autenticación	JWT de auth-gateway; las peticiones API usan Authorization: Bearer o cookies según endpoint.

Autenticación típica

1. Obtén token vía flujo de login del gateway (mismo usuario que la UI o cliente de servicio configurado).
2. Llama endpoints REST documentados (cámaras, grabaciones, LiveKit token, etc.).
3. Algunas URLs de playback aceptan access_token en query cuando el reproductor lo añade automáticamente.

Secretos

No publiques tokens, claves MinIO ni URLs RTSP con credenciales en tickets o capturas.

Integración con Core Optrax

Desde la UI (Ajustes → Integración Optrax) el administrador sincroniza cámaras y grupos. A nivel API, el servidor usa OPTRAX_API_URL y token configurados en el entorno.

Embed de video

Ruta /embed/camera/{id} para mostrar vivo en aplicaciones autorizadas (por ejemplo CAD). Requiere configuración de Nginx, tokens y políticas del despliegue; no es un flujo de usuario final habitual.

Eventos en tiempo real

Clientes autorizados pueden suscribirse a GET /api/events/stream (SSE). La vista ampliada de cámara muestra eventos entrantes en el panel lateral cuando la analítica los envía.

Casos especiales

• La colección Postman puede estar desactualizada respecto a OpenAPI; ante duda, usa el YAML del portal.
• Healthcheck público (/api/health) suele usarse solo para monitoreo de infraestructura.

Errores comunes

Problema	Qué hacer
401 en API	Renueva token o revisa permisos en gateway.
Playback 403	Incluye token válido en URL o cabecera según documentación.
Embed no carga	Revisa CORS, Nginx y permisos de la cámara.

[SCREENSHOT REQUIRED: Settings General tab showing Postman download link without exposing credentials]