Интеграция в существующую систему биллинга¶

В этой статье описаны типовые сценарии внедрения Flussonic Watcher с контролируемой продажей камер по подписке и учетом абонентов и их услуг в сторонней системе. Справочник API: Watcher Client API и Watcher Admin API.

Далее будут использоваться термины:

• оператор связи — клиент компании Эрливидео, владелец сервиса
• абонент — абонент у оператора связи, пользователь сервиса
• биллинг — система внешняя к Watcher, в ней ведется тарификация услуг оператора связи абонентам и взимание денег

Концепция использования биллинга подразумевает, что именно он является центральным местом хранения данных в системе, а не Flussonic Watcher. Такая практика является стандартной и позволяет централизованно управлять услугами в разных системах, связывая, например, умный дом и видеонаблюдение в едином проекте.

Механизм сопоставления тарифных планов биллинга и пресетов Watcher, а также логика, которая будет влиять на доступ, глубину архива и прочие настройки, находится на стороне биллинга.

Сервисная учетная запись и авторизация запросов¶

В API v2 запросы от биллинга авторизовались глобальным ключом домена, не привязанным к учетной записи. В API v3 такого ключа нет: каждый запрос выполняется от имени пользователя. Поэтому сначала создайте сервисную учетную запись — пользователя с уровнем доступа администратора (access_level: admin), от имени которого биллинг будет выполнять все запросы к Watcher.

Роли в этой схеме распределяются так:

• Абонент — владелец своей организации. Он видит видео, работает в мобильном приложении, добавляет камеры и других пользователей. Его external_id попадает в отчеты как идентификатор счета.
• Сервисная учетная запись — администратор Watcher. Она управляет камерами, тарифами и блокировками через Admin API (/watcher/admin-api/v3/...): запросы Admin API доступны администратору для любой организации домена и не требуют членства или прав в ней. Организации создаются через Client API — администратор проходит по доменным правам.

Не пытайтесь управлять камерами абонентов от имени администратора через Client API: его запросы проверяют права в конкретной организации, и администратор, не будучи ее владельцем или участником, получит ошибку 403. Для операций биллинга используйте Admin API.

Авторизоваться можно двумя способами:

• JWT-токен — выдается запросом POST /watcher/client-api/v3/login с Basic-авторизацией. Срок действия access_token — один час; новый токен выдается повторным запросом /login с заголовком Authorization: Bearer <refresh_token>.
• Персональный API-ключ — имеет неограниченный срок действия и не требует обновления; это рекомендуемый способ для серверной интеграции. Ключ выпускается один раз:

POST /watcher/client-api/v3/users/{user_id}/apikey
Authorization: Bearer <access_token>

Полученный ключ передавайте в заголовке Authorization: Bearer <ключ> каждого запроса.

Создание пресетов¶

Пресет — это предварительно заданный набор настроек архива и аналитики, которые можно применить на камере. Пресеты соответствуют тарифам в биллинге, поэтому их нужно настроить перед добавлением камер.

Как правило при интеграции с биллингом абоненты не должны менять задаваемые пресетом настройки на камере. Для выполнения этого требования достаточно сделать пресет ненастраиваемым ("is_adjustable": false). Тогда, даже если у абонента будут права владельца организации с возможностью редактирования настроек камер, он не сможет изменить заданные пресетом настройки. Они будут видны ему, но недоступны для редактирования.

Владельцы организаций не могут создавать, редактировать и удалять пресеты: такие права есть только у администратора Watcher. Если к организации привязано несколько пресетов, то владелец организации сможет поменять один пресет на другой в настройках камеры.

Помимо тарифных пресетов, заранее создайте технический пресет — пресет с нулевой глубиной архива и без аналитики. Он используется как тариф при приостановке услуг за неуплату.

Пресеты создаются из биллинга через Admin API:

POST /watcher/admin-api/v3/presets

Обязательный параметр title — название пресета. В поле billing_external_id можно сохранить идентификатор соответствующего тарифа во внешнем биллинге, чтобы не вести таблицу соответствия на стороне биллинга.

Также доступны запросы GET/PUT/DELETE для получения/изменения/удаления пресета с заданным идентификатором.

Чтобы тариф стал доступен организации абонента, привяжите пресет к организации:

PUT /watcher/client-api/v3/organizations/{organization_id}/presets
{"preset_id": 42}

Подключение абонента¶

Подключение абонента выполняется в два шага. Идентификаторы для каждого следующего шага возвращаются в ответе на предыдущий, поэтому шаги выполняются строго по порядку.

Шаг 1. Создать пользователя¶

Абонент создается через Admin API, без указания организации — своя организация появится на следующем шаге, а пока пользователь будет числиться в организации домена по умолчанию:

POST /watcher/admin-api/v3/users
{
  "name": "ivanov",
  "password": "секрет",
  "external_id": "billing-account-123"
}

Поля:

• name — логин пользователя (не отображаемое имя).
• password — пароль абонента; обычно генерируется биллингом и передается абоненту. Поле необязательное, однако без пароля абонент не сможет войти в сервис, пока пароль не будет установлен запросом обновления пользователя.
• external_id — идентификатор абонента в биллинге. Попадает в отчеты Watcher как идентификатор счета — заполняйте его при создании.
• email — необязательная почта для уведомлений.

Из ответа сохраните id пользователя.

Шаг 2. Создать организацию с абонентом-владельцем¶

Каждому абоненту соответствует своя организация. Владелец назначается сразу при создании:

POST /watcher/client-api/v3/organizations
{
  "title": "Иванов И.И., ул. Ленина 1",
  "owner": {"id": 15}
}

В поле owner.id передайте идентификатор пользователя из шага 1. Из ответа сохраните id организации; соответствие между организацией и абонентом храните на стороне биллинга. Вместе с организацией автоматически создается папка Cameras.

Как владелец организации абонент видит живое видео и архив всех ее камер, работает в мобильном приложении, добавляет камеры и других пользователей (например, членов семьи) и сам выдает им права на папки. Выдавать абоненту какие-либо права отдельными запросами не требуется.

При необходимости удалите абонента из организации по умолчанию, в которой он был создан на шаге 1:

DELETE /watcher/client-api/v3/organizations/{default_organization_id}/users/{user_id}

Камеры с агентом¶

Камеры с Flussonic Agent не создаются запросом добавления камеры: камера появляется в Watcher автоматически после активации агента по ключу активации.

Ключ активации создается запросом POST /watcher/client-api/v3/agent_activation_token от имени пользователя с правом управления камерами в организации. Администратору, не являющемуся владельцем организации, этот запрос недоступен, поэтому сценарий зависит от того, кто активирует камеру:

• Основной сценарий: камеру активирует абонент. Владелец организации добавляет камеру из мобильного приложения или веб-интерфейса Watcher — создание ключа активации встроено в интерфейс, участие биллинга не требуется. Так же действует монтажник, работающий под учетной записью абонента.

• Подготовка ключей оператором заранее (например, прошивка партии камер). В этом случае создайте организацию сначала с сервисной учетной записью в роли владельца (запрос из шага 2 без поля owner), создайте ключи активации, а затем передайте владение абоненту:

  POST /watcher/client-api/v3/agent_activation_token { "organization_id": 7, "preset_id": 42, "title": "Подъезд 1" }

  Поля preset_id (тариф; по умолчанию — пресет организации) и title (имя камеры; по умолчанию генерируется) необязательные. Из ответа сохраните token — это ключ активации; поле stream_name на этом этапе пустое. После активации агента имя камеры возвращается запросом GET /watcher/client-api/v3/agent_activation_token/{token} в поле stream_name.

  Передача владения абоненту после подготовки ключей:

  PUT /watcher/client-api/v3/organizations/{organization_id} {"owner": {"id": 15}}

В обоих сценариях биллинг обнаруживает появившиеся камеры абонента списком по организации:

GET /watcher/admin-api/v3/streams?organization_id={organization_id}

Из ответа сохраните поле name каждой камеры — дальнейшее управление (смена тарифа, отключение, чтение статуса) выполняется по нему, как для обычных камер.

Камера без агента¶

Сценарий интеграции для камер без агента (например, RTSP, ONVIF) обычно следующий:

1. Камера подключается к внутренней сети оператора связи
2. Абонент оставляет оператору связи запрос на подключение к камере.
3. Запрос на добавление камеры абоненту или выдачу абоненту прав на камеру поступает от оператора связи в биллинг.

4. Если подключается новая личная камера абонента, например, в систему умного дома:

   • Предполагается, что в Watcher уже создан пользователь и организация для абонента. Если их нет, создайте их по цепочке из раздела Подключение абонента.

   • Биллинг заполняет необходимые атрибуты камеры в соответствии с тарифом.

   • Биллинг отправляет в Watcher запрос на добавление камеры абоненту (см. пример ниже).

5. Если абонент хочет подключиться к общей камере, например, к домофону или к системе "Безопасный город":

   • Общие камеры размещаются в отдельной организации оператора, владельцем которой является сервисная учетная запись, — тогда она вправе управлять пользователями и папками этой организации через Client API.

   • Биллинг добавляет абонента в организацию с общими камерами запросом PUT /watcher/client-api/v3/organizations/{organization_id}/users/{user_id} — если абонент еще не состоит в организации, запрос добавит его как участника.

   • Биллинг выдает абоненту права на папку с камерой:

     PUT /watcher/client-api/v3/organizations/{organization_id}/folders/{folder_id}/users/{user_id} { "can_view": true, "can_view_dvr": true, "dvr_depth_limit": 0, "can_use_ptz": false }

     Флаги: can_view — живое видео, can_view_dvr — архив, dvr_depth_limit — ограничение глубины архива в секундах (0 — без ограничения), can_use_ptz — управление поворотными камерами. Права применяются рекурсивно ко вложенным папкам. Идентификаторы папок возвращает запрос GET /watcher/client-api/v3/organizations/{organization_id}/folders.

Добавление камеры¶

Камера создается и обновляется одним и тем же запросом Admin API (отдельного POST-запроса на создание в v3 нет — если камера не найдена, она будет создана):

PUT /watcher/admin-api/v3/streams/{name}
{
  "title": "Подъезд 1",
  "preset_id": 42,
  "organization_id": 7,
  "folder_id": 15,
  "inputs": [{"url": "rtsp://..."}]
}

В запросе на добавление камеры обязательно должны быть указаны следующие параметры:

• preset_id (целое число) — идентификатор пресета Watcher, соответствующего тарифу в биллинге.
• organization_id (целое число) — идентификатор организации. Организация должна быть уже создана в Watcher, вместе с пользователем.

Если не указать в запросе идентификатор пресета и организации, то камера будет добавлена в организацию по умолчанию с пресетом по умолчанию.

Запрос массового импорта POST /watcher/client-api/v3/streams/import (см. Импорт камер по API) в этой схеме не используется: он относится к Client API и требует прав на управление камерами в организациях, которых у сервисной учетной записи нет. Добавляйте камеры по одной запросом PUT /watcher/admin-api/v3/streams/{name} — его ответ содержит присвоенное камере имя.

Добавление пользователя¶

Пользователь создается запросом POST /watcher/admin-api/v3/users — см. Подключение абонента.

Альтернатива добавлению пользователей - внешний авторизационный бекенд.

Смена тарифа¶

Тариф камеры меняется сменой пресета:

PUT /watcher/admin-api/v3/streams/{name}
{"preset_id": 43}

Для массовой смены тарифа (например, при изменении условий тарифного плана для всех камер сразу) используйте запрос:

POST /watcher/admin-api/v3/streams/multiedit
{
  "streams": [
    {"name": "cam-001", "preset_id": 43},
    {"name": "cam-002", "preset_id": 43}
  ]
}

Особенности multiedit:

• Изменить можно только поля preset_id и dvr.
• Успешный ответ — 204 без тела.
• Если хотя бы одна камера из списка не найдена, вернется 404 и изменения не применятся ни к одной камере.

Приостановка услуг¶

В случае, если абонент по какой-то причине не должен больше пользоваться услугами (например, отключил услугу или не внес оплату вовремя), биллинг должен отправить в Watcher соответствующий запрос.

Самый простой вариант — отключить пользователя:

PUT /watcher/admin-api/v3/users/{user_id}
{"disabled": true}

Все активные сессии абонента (веб и мобильное приложение) при этом завершаются немедленно. Для возобновления услуги отправьте тот же запрос с {"disabled": false}.

Варианты ограничения без отключения пользователя:

• Отключить камеру абонента, которой не пользуется никто, кроме него:

PUT /watcher/admin-api/v3/streams/{name}
{"disabled": true}

• Перевести камеры на технический пресет через multiedit — видео останется доступным, а платные услуги (архив, аналитика) отключатся.

Отзыв доступа и удаление¶

• Исключить пользователя из организации с общими камерами (удаляются и права в организации, и права на папки):

DELETE /watcher/client-api/v3/organizations/{organization_id}/users/{user_id}

• Удалить пользователя полностью (удаляются сессии и все связи):

DELETE /watcher/admin-api/v3/users/{user_id}

• Сменить пароль абонента (отдельного запроса нет — используется обновление пользователя; все сессии абонента завершаются):

PUT /watcher/admin-api/v3/users/{user_id}
{"password": "новый-пароль"}

Статус камер¶

Состояние камер читается запросами GET /watcher/admin-api/v3/streams (список; параметр organization_id ограничивает выборку организацией абонента) и GET /watcher/admin-api/v3/streams/{name} (одна камера). Полей online/offline в ответе нет; используйте:

• stats.alive (bool) — камера отдает поток; становится false при задержке потока больше 12 секунд.
• stats.status — running, waiting или error.
• stats.last_online_at — время, когда камера была в сети в последний раз; поле присутствует только у камер, которые сейчас не в сети.

Поле disabled в конфигурации камеры показывает, что камера выключена административно (см. Приостановка услуг) — это не то же самое, что потеря связи.

Типичные ошибки¶

• Ошибка 403 в Client API у администратора. Запросы Client API проверяют права в конкретной организации, и права администратора их не заменяют. Это касается создания пользователя с organization_id, выдачи прав на папки и создания ключей активации. Операции с камерами и пользователями выполняйте через Admin API; операции, доступные только владельцу организации, — от имени владельца (см. Сервисная учетная запись).
• Право на редактирование камер включает просмотр видео. Пользователь с правом can_edit_streams автоматически получает и can_view_streams — доступ к живому видео и архиву всех камер организации. Настроить учетную запись, которая управляет камерами, но не имеет доступа к видео, невозможно.
• Ответ не повторяет отправленные значения. В ответе на PUT /organizations/{id}/users/{id} флаг can_view_streams: true возвращается всегда, когда у пользователя есть право редактирования камер или владение организацией, независимо от отправленных значений. Не проверяйте успешность запроса сравнением отправленных и полученных флагов.
• В поле name пользователя передается логин. Почта для уведомлений указывается в поле email.

Соответствие запросов v2 и v3¶

Прочие отличия v3:

• Списки возвращаются с курсорной пагинацией: поля estimated_count, next, prev.
• Ресурс cameras переименован в streams.