Saltar a contenido

API de gestión de usuarios

Un usuario tiene una cuenta en un dominio y puede pertenecer a varias organizaciones. Los permisos de dominio, organización y carpeta se asignan por separado. Todos los ejemplos usan autenticación API v3.

Crear un usuario en una organización

En Client API indique una organización cuyos usuarios pueda gestionar:

POST /watcher/client-api/v3/users
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "resident-example",
  "fullname": "Irina Smirnova",
  "password": "ExamplePassword",
  "email": "resident@example.com",
  "organization_id": 7,
  "access_level": "generic",
  "locale": "ru"
}

Guarde el id de la respuesta. name es el inicio de sesión, fullname el nombre mostrado y email la dirección de notificaciones. La contraseña se envía en password. Si se omite el inicio de sesión, Watcher lo genera; indíquelo explícitamente para integraciones.

Si falta organization_id en Client API, Watcher elige la primera organización con permiso explícito de gestión de usuarios o devuelve un error de validación. Indique la organización. El límite de usuarios se comprueba al crear.

Cree un usuario ordinario con access_level: "generic". Para asignar un administrador de dominio, envíe otra solicitud con el id guardado:

PUT /watcher/client-api/v3/users/15
Authorization: Bearer <token>
Content-Type: application/json

{"access_level":"domain_admin"}

Puede asignarlo un administrador de Watcher o un administrador actual del dominio de destino con acceso al usuario. Enviar domain_admin en POST /users no asigna por sí solo el rol. Compruebe access_level en la respuesta de PUT.

admin concede permisos de administrador de Watcher y solo puede asignarlo otro administrador de Watcher. generic significa usuario ordinario. Los permisos de organización y carpeta se asignan aparte.

Las integraciones de facturación con cuenta de sistema pueden usar POST /watcher/admin-api/v3/users. Si se omite la organización, Admin API añade el usuario a la organización predeterminada del dominio de destino. Con organization_id explícito, incluso Admin API comprueba permiso de gestión de sus usuarios. Consulte la secuencia de registro en integración con facturación.

Listar usuarios de una organización

GET /watcher/client-api/v3/organizations/7/users?limit=100
Authorization: Bearer <token>

Requiere gestionar los usuarios de la organización. Procese users y el cursor next; envíelo como cursor para continuar.

Las cuentas del dominio están disponibles mediante GET /watcher/client-api/v3/users dentro de los permisos del solicitante. Admin API proporciona la lista administrativa /watcher/admin-api/v3/users.

Añadir un usuario a una organización

Cree primero la cuenta y añádala por su ID:

PUT /watcher/client-api/v3/organizations/7/users/15
Authorization: Bearer <token>
Content-Type: application/json

{"can_edit_users": false, "can_edit_streams": false, "can_view_streams": false}

Si no existe pertenencia, PUT la crea. Los campos de permisos van directamente en el cuerpo. Campos principales:

  • can_edit_users — gestionar usuarios de la organización.
  • can_edit_streams — gestionar cámaras de la organización.
  • can_view_streams — acceder a todas sus cámaras.
  • can_view_stats — ver estadísticas.
  • can_view_persons_lists — ver listas de personas.
  • can_edit_persons_lists — modificar listas de personas.
  • nvrs — permisos de NVR: {"can_view":true,"can_edit":false}.

can_edit_streams también permite ver cámaras. Para cámaras seleccionadas, deje desactivada la visualización general y conceda permisos de carpeta. El ejemplo de cámaras compartidas muestra la creación del usuario, obtención de folder_id y concesión y revocación del acceso.

Consultar permisos de un usuario

GET /watcher/client-api/v3/organizations/7/users/15
Authorization: Bearer <token>

La respuesta describe el usuario y sus permisos efectivos, incluidos los del propietario: puede diferir del indicador enviado.

Modificar permisos de organización

Use el mismo PUT /organizations/7/users/15 con los campos necesarios. Los permisos de carpeta requieren otra solicitud:

PUT /watcher/client-api/v3/organizations/7/folders/12/users/15
Authorization: Bearer <token>
Content-Type: application/json

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

Modificar permisos de carpeta requiere gestión de cámaras. También se aplican a subcarpetas. can_view permite vídeo en directo y can_view_dvr archivo; dvr_depth_limit limita la profundidad de acceso en segundos, y 0 elimina ese límite. can_use_ptz permite control PTZ.

Modificar datos de la cuenta

Los datos generales cambian mediante PUT /watcher/client-api/v3/users/{user_id} o su equivalente administrativo. Envíe disabled: true para desactivar y disabled: false para activar. Use password para cambiar la contraseña; el administrador no necesita una solicitud específica. La desactivación elimina las sesiones; cambiar la contraseña desde otra cuenta también termina las sesiones del usuario de destino.

Un usuario con readonly: true no puede realizar solicitudes de modificación, independientemente de otros permisos.

Retirar un usuario de una organización

DELETE /watcher/client-api/v3/organizations/7/users/15
Authorization: Bearer <token>

Elimina pertenencia, permisos de organización y permisos de sus carpetas. La cuenta permanece. Retirar al propietario exige autoridad adicional: puede hacerlo el propio propietario o quien gestione organizaciones del dominio.

Para eliminar la cuenta por completo, un administrador usa DELETE /watcher/admin-api/v3/users/15. La eliminación correcta devuelve 204.