Migración de una integración a API v3¶

Use API v3 para Watcher actual. Traslade autenticación, modelo de permisos y tratamiento de respuestas. Cambiar solo la URL base no basta: crear cámaras y asignar permisos tiene otra estructura.

Los contratos completos están en Client API y Admin API. Consulte un ejemplo de gestión del servicio en integración con facturación.

Client API y Admin API¶

Client API — /watcher/client-api/v3. Operaciones de usuario con organizaciones, carpetas y cámaras, y lectura de episodios. Comprueba permisos del solicitante sobre objetos concretos.
Admin API — /watcher/admin-api/v3. Operaciones administrativas, incluidos preajustes y configuración de cámaras. /login administrativo exige admin. Algunas lecturas admiten administrador de dominio, sin acceso a todas las operaciones.

Elija según acción y autoridad. Un administrador de Watcher puede recibir rechazo en Client API si se exigen permisos de organización separados.

Autenticación¶

Cree una cuenta independiente con permisos necesarios. Obtenga tokens mediante POST /watcher/client-api/v3/login con Basic o una clave personal mediante POST /watcher/client-api/v3/users/{user_id}/apikey.

Después utilice:

Authorization: Bearer <access_token_or_apikey>

access_token dura una hora. Renueve mediante el mismo /login, enviando refresh_token como Bearer. La clave personal no necesita renovación temporal; emitir otra reemplaza la anterior. Consulte autenticación API.

Los tokens con ámbitos se destinan a operaciones concretas que los admiten, por ejemplo autologin/generate; no son claves universales de usuario.

Cambios de comportamiento¶

Las cámaras usan streams. PUT /streams/{name} crea si falta o actualiza si existe. Para una cámara ordinaria, Watcher genera el nombre desde title. Guarde el name real de la respuesta. Repetir con un nombre arbitrario anterior puede crear otra cámara.
JSON usa envoltura streams. POST /streams/import acepta {"streams":[...]}, no un array superior. Devuelve created y updated, sin nombres.
El usuario se envía en name. Nombre mostrado: fullname; correo: email.
El bloqueo usa disabled. true desactiva y false activa.
La contraseña se cambia actualizando el usuario. Envíe password en PUT /users/{user_id}. Desactivar elimina sesiones; cambiar desde otra cuenta también elimina las del usuario objetivo.
Los permisos de organización tienen nombres propios. can_edit_streams y can_edit_users van directamente en PUT /organizations/{id}/users/{user_id}. Crea pertenencia si falta.
Las cámaras seleccionadas se autorizan por carpetas. Use PUT /organizations/{id}/folders/{folder_id}/users/{user_id} con can_view, can_view_dvr y can_use_ptz. Se heredan recursivamente. Pertenecer sin permisos no da vídeo.
Gestionar cámaras incluye visualización. No conceda can_edit_streams para solo algunas carpetas. can_view_streams organizativo permite todas las cámaras.
Los límites van en limits. limits.streams y limits.users. El propietario es owner: {"id":15}; si se omite, lo es el creador.
Las listas usan cursores. Procese el array y envíe next como cursor. Usuarios de dominio: users_list; de organización: users.
readonly prohíbe cambios. Rechaza modificaciones independientemente de otros permisos.

Correspondencia entre v2 y v3¶

La columna izquierda sirve para encontrar código antiguo. Ejecute la columna v3 y compruebe cuerpos con el esquema actual.

Solicitud o campo antiguo	Solicitud o campo v3
`X-Vsaas-Api-Key`, `X-Vsaas-Session`	`Authorization: Bearer <token>`; elija el tipo según lo anterior
`POST /vsaas/api/v2/auth/login`	`POST /watcher/client-api/v3/login`
`GET /vsaas/api/v2/profile`	`GET /watcher/client-api/v3/profile`
`POST /vsaas/api/v2/users/{id}/apikey`	`POST /watcher/client-api/v3/users/{user_id}/apikey`
`GET /vsaas/api/v2/cameras`	`GET /watcher/client-api/v3/streams`
`POST /vsaas/api/v2/cameras`	`PUT /watcher/client-api/v3/streams/{name}`; guarde el `name` devuelto
`PUT/DELETE /vsaas/api/v2/cameras/{name}`	`PUT/DELETE /watcher/client-api/v3/streams/{name}`
`POST /vsaas/api/v2/cameras/import`	`POST /watcher/client-api/v3/streams/import` con CSV/JSON actual
`GET/POST /vsaas/api/v2/users`	`GET/POST /watcher/client-api/v3/users`; administración mediante Admin API
`PUT/DELETE /vsaas/api/v2/users/{id}`	`PUT/DELETE /watcher/client-api/v3/users/{user_id}` según permisos o Admin API
`GET/POST /vsaas/api/v2/organizations`	`GET/POST /watcher/client-api/v3/organizations`
`PUT/DELETE /vsaas/api/v2/organizations/{id}`	`PUT/DELETE /watcher/client-api/v3/organizations/{id}`
`POST /vsaas/api/v2/organizations/{id}/users`	`PUT /watcher/client-api/v3/organizations/{id}/users/{user_id}`
`GET/POST /vsaas/api/v2/presets`	Lectura: Client API `/presets`; creación: `POST /watcher/admin-api/v3/presets`
`POST /vsaas/api/v2/agent-activation-tokens`	`POST /watcher/client-api/v3/agent_activation_token`
`GET /vsaas/api/v2/events`	`GET /watcher/client-api/v3/episodes`; adapte al modelo de episodios
`POST /vsaas/api/v2/auth/generate-autologin-token`	`POST /watcher/client-api/v3/autologin/generate` con `login`; sesión propia solo para sí, facturación con ámbito `autologin/generate`
`POST /vsaas/autologin`	Intercambio JSON mediante `POST /watcher/client-api/v3/autologin` o enlace web
`POST /vsaas/api/v2/my/subscriptions` con `notification_type: http`	Suscripciones v3 aceptan `push`; no hay equivalente directo de webhook HTTP en esta solicitud

La última fila distingue contratos históricos y actuales. Para obtener episodios mediante Client API v3, use recopilación.

Enviar eventos completos face o vehicle a Central usa PUT /central/api/v3/episodes/{episode_id} y autenticación Central. No se sustituye por POST /watcher/client-api/v3/episodes: ese POST crea generic y Client PUT solo modifica título y descripción. Consulte analítica externa.

Secuencia de migración¶

Enumere acciones y solicitudes actuales.
Elija Client o Admin API por acción. Cree una cuenta de servicio de prueba con permisos.
Traslade autenticación y pruebe renovación de sesión o sustitución de clave.
Adapte cuerpos y respuestas; guarde los ID de Watcher.
Pruebe altas, modificaciones y eliminaciones con datos ficticios en una instalación de prueba, incluidos reenvíos.
Pruebe organización ajena, falta de permisos de carpeta y cuenta desactivada.
Para eventos y órdenes externas, confirme entrega, duplicados y resultado antes de cambiar producción.