Integración con un sistema externo de gestión¶

Un sistema externo puede crear organizaciones, usuarios y cámaras, cambiar parámetros y gestionar acceso. Relaciona los objetos y usuarios de la empresa con sus ID en Watcher; Watcher aplica configuración y permisos recibidos.

Elija escenario:

• Cámaras privadas del usuario — cree usuario y organización, asigne un preajuste disponible y conecte cámaras.
• Cámaras compartidas — ya existen organización y cámaras; siga el ejemplo de acceso limitado a una carpeta.

En este modelo:

• Administrador — opera Watcher y conecta el sistema externo.
• Usuario — empleado con acceso a cámaras de la instalación.
• Sistema de gestión — vincula objetos y usuarios con organizaciones, cámaras y preajustes.

Use API v3. Guarde los ID devueltos en el sistema externo. Los contratos completos están en Client API y Admin API.

Cuenta de servicio y autenticación¶

Cree una cuenta de servicio separada con access_level: "admin". Obtenga JWT mediante /login o clave personal según autenticación. Los ejemplos presuponen:

Authorization: Bearer <token>
Content-Type: application/json

La cuenta gestiona usuarios y cámaras mediante Admin API. Crea organizaciones mediante Client API con permiso de gestión de organizaciones del dominio. En este ejemplo el nuevo usuario es propietario; propiedad y rol de administrador del sistema tienen permisos distintos en Client API.

En dominios sin fecha de creación o anteriores al 16 de enero de 2026, 08:30:29.622 UTC, fuera del dominio principal se comprueba además el nombre al crear o modificar administrativamente organizaciones: se permite billing o sufijo _master. Prepare la cuenta teniéndolo en cuenta.

Carpetas y claves de activación requieren permisos en la organización correspondiente. Asígnelos según API de usuarios o ejecute como el usuario. El rol administrativo no sustituye esas comprobaciones.

Crear preajustes¶

Un preajuste define archivo y analítica. Créelo mediante Admin API:

POST /watcher/admin-api/v3/presets

{
  "title": "Archivo de 7 días",
  "is_adjustable": false,
  "dvr": {"expiration": 604800}
}

Guarde id. is_adjustable: false impide sobrescribir sus parámetros DVR y analítica por cámara. Para cambiarlos, modifique el preajuste o asigne otro.

Alta de un usuario¶

El ejemplo crea primero usuario y después organización. Ejecute en orden: cada ID se utiliza en la siguiente solicitud.

Paso 1. Crear el usuario¶

POST /watcher/admin-api/v3/users

{
  "name": "resident-example",
  "fullname": "Irina Smirnova",
  "password": "ExamplePassword",
  "email": "resident@example.com",
  "external_id": "account-123"
}

Guarde id. name es el acceso y email el correo. external_id vincula la cuenta al registro externo.

Sin organization_id, Admin API lo añade a la organización predeterminada del dominio objetivo. Una organización explícita exige permiso de gestión de sus usuarios, incluso al administrador Watcher.

Paso 2. Crear organización con el usuario propietario¶

POST /watcher/client-api/v3/organizations

{
  "title": "Calle Jardín, apartamento 12",
  "owner": {"id":15},
  "limits": {"streams":4,"users":10}
}

Sustituya 15 por el ID del usuario y guarde el ID de organización. Se crea también Cameras. El propietario administra la organización y accede a sus cámaras sin permisos de carpeta aparte.

Si procede, retírelo de la predeterminada mediante DELETE /watcher/client-api/v3/organizations/{default_organization_id}/users/{user_id}. Confirme que permanece en su organización.

Vincule el preajuste: sustituya 7 por organización y 42 por preajuste.

PUT /watcher/client-api/v3/organizations/7/presets

{"preset_id":42}

Con varios preajustes disponibles, quien gestiona cámaras puede elegir. Limite la lista a los permitidos. Crear o cambiar preajustes corresponde al administrador Watcher.

Cámaras con Agent¶

Obtenga clave mediante Client API como usuario que gestione cámaras de la organización para una cámara con Agent:

POST /watcher/client-api/v3/agent_activation_token

{"organization_id":7,"preset_id":42,"title":"Entrada"}

Use el token devuelto para activar Agent. El preajuste debe estar disponible. Sin preset_id, Watcher elige el predeterminado disponible o el primero; no tener ninguno produce error.

Después, GET /watcher/client-api/v3/agent_activation_token/{token} como creador de la clave devuelve stream_name. Guárdelo. También puede leer cámaras mediante GET /watcher/admin-api/v3/streams?organization_id=7.

El usuario puede activar desde la interfaz. Si prepara claves un administrador, la cuenta de servicio necesita permisos organizativos. No entregue credenciales administrativas al instalador o usuario.

Cámara sin Agent¶

El administrador conoce previamente la fuente. Cree la cámara en la organización del usuario y asigne preajuste.

Para cámaras compartidas use acceso a carpeta seleccionada. El siguiente ejemplo crea una cámara privada en la organización preparada.

Añadir cámara¶

Obtenga carpetas con GET /watcher/client-api/v3/organizations/7/folders?limit=100 y guarde el ID elegido. Para cámara privada puede usar raíz Cameras. Sustituya 7, 42 y 12 por organización, preajuste y carpeta. Si hay next, continúe con cursor. Se requieren los permisos descritos antes.

PUT /watcher/admin-api/v3/streams/new-camera

{
  "title": "Entrada",
  "organization_id":7,
  "preset_id":42,
  "folder_id":12,
  "inputs":[{"url":"rtsp://camera.example.com/main"}]
}

La carpeta debe pertenecer a la organización y el preajuste estar disponible. Watcher genera el nombre desde el título; no usará new-camera de la URL. Guarde el name real para solicitudes posteriores.

PUT con nombre inexistente crea. Repetir el mismo nombre arbitrario puede duplicar cámaras. Ante error de red compruebe primero si el objeto existe.

La importación masiva usa Client API con permisos organizativos y solo devuelve contadores. Si necesita cada nombre inmediatamente, cree individualmente.

Añadir usuario¶

La cuenta principal se crea en el primer paso. Añada usuarios con POST /watcher/client-api/v3/users y organization_id si puede gestionarlos. Pertenecer no da vídeo: conceda carpetas o visualización general explícitamente.

El backend HTTP verifica contraseñas externas, pero no sustituye organizaciones ni permisos.

Cambiar preajuste¶

Asigne otro disponible. Sustituya nombres por cámaras existentes de respuestas Watcher y 43 por un preajuste disponible para ellas:

PUT /watcher/admin-api/v3/streams/entrance-example

{"preset_id":43}

Para varias:

POST /watcher/admin-api/v3/streams/multiedit

{"streams":[{"name":"entrance-example","preset_id":43},{"name":"parking-example","preset_id":43}]}

multiedit admite DVR y otros campos del esquema; consulte Admin API actual. Si falta una cámara, rechaza con 404. Aplicación correcta devuelve 204. Relea parámetros y compruebe grabación real.

Suspender acceso¶

Desactive la cuenta:

PUT /watcher/admin-api/v3/users/15

{"disabled":true}

Watcher elimina sesiones activas. Para restaurar, envíe disabled: false; el usuario vuelve a entrar.

Para detener solo una cámara privada, use PUT /watcher/admin-api/v3/streams/{name} con {"disabled":true}. Afecta a todos sus consumidores. En cámaras compartidas retire permisos individuales y conserve acceso de otros.

Desactivar una cuenta no elimina tokens de cámara compartida emitidos aparte. Revóquelos independientemente si procede.

Revocar acceso y eliminar¶

El ejemplo independiente retira 15 de la organización compartida 8. Para organización privada, use su ID y revise consecuencias de retirar al propietario en API de usuarios.

DELETE /watcher/client-api/v3/organizations/8/users/15

Se eliminan pertenencia y permisos de organización y carpetas. Para borrar la cuenta, el administrador usa DELETE /watcher/admin-api/v3/users/15.

Cambie contraseña actualizando usuario:

PUT /watcher/admin-api/v3/users/15

{"password":"NewExamplePassword"}

Cambiar desde otra cuenta elimina sesiones. Eliminar organización es una operación en cascada separada; revise contenido y consecuencias en API de organizaciones.

Estado de cámaras¶

Lea GET /watcher/admin-api/v3/streams?organization_id=7 o GET /watcher/admin-api/v3/streams/{name}. Recorra todas las páginas con next/cursor.

stats incluye estado actual, status y alive cuando están disponibles. disabled es desactivación administrativa, no indicador de red. La ausencia de estadísticas tampoco equivale a bloqueo.

Compruebe guardado y vídeo por separado. Una respuesta correcta de configuración no confirma que la cámara sea accesible.

Cámaras compartidas: usuario limitado¶

El ejemplo concede a un usuario nuevo una carpeta y subcarpetas de cámaras compartidas. Organización y cámaras ya existen. La cuenta de servicio sigue siendo propietaria; no asigne propiedad al usuario.

La cuenta debe gestionar usuarios y cámaras de esa organización concreta. admin no sustituye esos permisos. Use su JWT o clave personal según autenticación. Todos los siguientes requieren Authorization: Bearer <token> y Content-Type: application/json.

7 es organización compartida existente, 12 carpeta y 15 usuario nuevo. Sustituya por ID de su instalación. Busque organización con GET /watcher/client-api/v3/organizations?limit=100, según API de organizaciones.

Paso 1. Crear usuario ordinario en la organización¶

POST /watcher/client-api/v3/users

{
  "name": "shared-camera-viewer",
  "password": "ExampleViewerPassword",
  "organization_id": 7,
  "access_level": "generic",
  "user_permissions": {
    "can_edit_users": false,
    "can_edit_streams": false,
    "can_view_streams": false
  }
}

Guarde id como user_id. Crea inmediatamente pertenencia. No necesita otra organización ni hacerlo propietario. can_view_streams: true mostraría todas las cámaras; can_edit_streams: true también daría gestión y vídeo.

Paso 2. Obtener ID de carpeta¶

GET /watcher/client-api/v3/organizations/7/folders?limit=100

Busque en folders, compruebe title y parent_id, guarde id como folder_id. Continúe con cursor=<next> si es necesario. La raíz Cameras incluye todas: para limitar, elija otra carpeta con las cámaras necesarias. Incluye sus subcarpetas.

Paso 3. Conceder visualización de la carpeta¶

PUT /watcher/client-api/v3/organizations/7/folders/12/users/15

{
  "can_view": true,
  "can_view_dvr": true,
  "dvr_depth_limit": 0,
  "can_use_ptz": false,
  "can_use_actions": false
}

Permite directo y archivo disponible completo; prohíbe PTZ y acciones. Para solo directo, can_view_dvr: false. dvr_depth_limit: 0 elimina el límite de antigüedad accesible, sin cambiar retención.

Paso 4. Verificar¶

Relea permisos como cuenta de servicio:

GET /watcher/client-api/v3/organizations/7/users/15
GET /watcher/client-api/v3/organizations/7/folders/12/users/15

En la primera respuesta compruebe ausencia de gestión de usuarios/cámaras y visualización general. En la segunda, permisos de carpeta. Entre como usuario nuevo y pruebe cámara y archivo si se permite. Verifique que no accede fuera de carpeta ni modifica cámaras. Use su token: la cuenta de servicio ve más.

Se supone una cuenta nueva sin permisos anteriores. Una existente puede mantener acceso por otras carpetas o cámaras. Quitar uno no cancela otros.

Paso 5. Revocar¶

Para retirar permisos de carpeta manteniendo cuenta y pertenencia:

DELETE /watcher/client-api/v3/organizations/7/folders/12/users/15

Retira acceso a carpeta y subcarpetas. Para excluir completamente de la organización:

DELETE /watcher/client-api/v3/organizations/7/users/15

El segundo elimina pertenencia y permisos; conserva cuenta. Repita prueba como usuario. Revocar no termina inmediatamente sesiones multimedia abiertas. Consulte eliminación completa en API de usuarios.

Comprobar integración¶

• Permisos — pruebe la cuenta de servicio en la organización del usuario; rol de sistema no sustituye organización en Client API.
• Reenvíos — evite duplicados tras errores; guarde nombre y compare estado.
• Vídeo — can_edit_streams incluye visualización; can_view_streams abarca toda la organización. Para selección use carpetas.
• Suspensión — compruebe acceso desactivado y tokens compartidos anteriores por separado.
• Preajuste — relea y compruebe archivo tras cambios.
• Eliminación — distinga retirar de organización, borrar usuario y cascada de organización.

Equivalencia v2 y v3¶

La tabla de migración enumera rutas antiguas y cambios. Verifique también cuerpos y permisos. Todos los ejemplos operativos de esta página usan v3.