Интеграция Lumika с биллингом¶

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

Биллинг хранит соответствие своих абонентов и услуг объектам Lumika. Lumika применяет настройки и возвращает фактическое потребление. Запросы направляйте на адрес своего домена, например https://operator.vsaas.io. В примерах используются два пространства API:

• Client API — /watcher/client-api/v3: организации, привязка тарифов, отчёт и управление токенами.
• Admin API — /watcher/admin-api/v3: создание и изменение обычных пользователей, чтение и настройка камер, список тарифов.

Наличие admin-api в пути не требует выдавать биллингу права администратора. Отдельный машинный токен допускается к перечисленным ниже операциям по своим разрешениям и только в своём домене. Полные контракты: Client API и Admin API.

Выберите задачу:

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

Модель данных¶

Сначала термины. Домен — ваш изолированный экземпляр Lumika: адрес <ваш-домен>.vsaas.io, ваши организации, пользователи, камеры и тарифы. Внутри домена живут четыре объекта:

• Организация — лицевой счёт абонента. В неё входят пользователи и камеры абонента.
• Пользователь — учётная запись, под которой абонент или его сотрудник входит в интерфейс.
• Камера — единица услуги, по камерам ведётся учёт потребления. В API камера называется стримом (stream) — отсюда методы /streams и поле stream_name в отчёте.
• Пресет — тарифный план: набор настроек камеры, которые определяют себестоимость услуги (глубина хранения архива, тип хранения, видеоаналитика).

Учётный период — непрерывный отрезок времени, в течение которого конкретная камера была на конкретном тарифе. Из таких периодов состоит отчёт о потреблении.

Связка с вашим биллингом устроена так:

Рекомендуемая модель: один абонент — одна организация. Несколько объектов одного абонента (дом, офис, склад) размещайте в одной организации, раскладывая камеры по папкам. Один пользователь может владеть несколькими организациями — тогда в отчёте они придут отдельными account_id с одинаковым external_account_id.

Доступ к API¶

Для серверной интеграции используйте отдельный API-токен домена. Создаёт его администратор домена, а биллинг хранит полученный ключ в своей серверной конфигурации. Пароль администратора и его персональный ключ биллингу не нужны.

Подготовьте разрешения¶

Для полного сценария этой страницы нужны следующие разрешения. Если биллинг выполняет только часть операций, выдайте соответствующую часть списка.

Флаг операции и область должны находиться в одном элементе permissions. Например, write у config/users не разрешает менять организацию. Наличие read не заменяет list.

Токен с этими областями не предоставляет прямого просмотра видео, кадров камер и архива. Он также не разрешает вход под пользователем или создание других токенов. При этом управление пользователями, владельцами организаций и доступом монтажников позволяет интеграции выдавать доступ пользовательским учётным записям. Храните такой токен на сервере биллинга; монтажник работает под собственным логином.

Выпустите и проверьте токен¶

Выберите один способ выпуска: через интерфейс или через API. Имя billing должно быть свободно в домене. Если такой токен уже существует, проверьте его доступ и используйте управление токеном; повторный выпуск с тем же именем не нужен.

Выпуск через интерфейс¶

Войдите на адрес своего домена как администратор домена. Откройте Настройки → API-токены.

1. Нажмите Выпустить токен и введите billing в поле Имя.

2. Для полного маршрута этой статьи включите Изменение у Пользователей, Организаций и Участников организаций, а у Пресетов и Камер — Чтение и Изменение. Это семь галочек для пяти областей из таблицы выше. Для части операций выберите только необходимые разрешения.

   

3. Нажмите Выпустить. В открывшемся окне скопируйте значение поля Ключ кнопкой копирования и сохраните его на сервере биллинга. Ключ показывается только в этом окне; после закрытия его нельзя повторно открыть в списке.

   

4. Нажмите Готово. Проверьте, что в списке появилась строка billing и в столбце Доступ перечислены выбранные разрешения.

   

Завершите настройку проверочным запросом списка тарифов. Токен уже выпущен: повторять запрос создания из API-варианта не нужно.

Выпуск через API¶

1. Администратор домена получает пользовательскую сессию через POST /watcher/client-api/v3/login с Authorization: Basic base64(login:password). Из ответа возьмите access_token. Эту сессию используйте только для управления токеном.

2. Отправьте запрос создания от имени администратора. Имя billing должно быть свободно в домене:

   POST /watcher/client-api/v3/api_tokens
   Authorization: Bearer <access_token администратора>
   Content-Type: application/json
   
   {
     "name": "billing",
     "permissions": [
       {"scopes": ["config/users"], "write": true},
       {"scopes": ["config/organizations"], "write": true},
       {"scopes": ["config/presets"], "list": true, "write": true},
       {"scopes": ["config/streams"], "read": true, "list": true, "write": true},
       {"scopes": ["config/organization-users"], "write": true}
     ]
   }
   

3. Сохраните key из успешного ответа в конфигурации биллинга. Далее все примеры, кроме управления самим токеном, выполняются с заголовком Authorization: Bearer <key> на адресе этого же домена.

4. Проверьте токен чтением тарифов. В Bash задайте адрес домена и ключ, затем выполните:

   export LUMIKA_URL='https://operator.vsaas.io'
   read -r -s -p 'API token: ' LUMIKA_TOKEN
   echo
   export LUMIKA_TOKEN
   curl --fail-with-body -sS \
     -H "Authorization: Bearer $LUMIKA_TOKEN" \
     "$LUMIKA_URL/watcher/admin-api/v3/presets"
   

   Ожидается 200 и объект с массивом presets. Пустой массив означает, что запрос выполнен, но тарифов нет; согласуйте их с поддержкой до подключения абонентов. 401 означает проблему аутентификации, 403 — недостаточные разрешения или недоступную этому токену операцию. Проверьте адрес домена, область и флаг операции.

Машинному токену недоступны списки пользователей и организаций, получение пользовательских ключей и удаление пользователей или камер. Храните выданные id и name в биллинге. Для административной сверки используйте отдельную сессию администратора домена, без передачи её биллингу.

Изменение разрешений, перевыпуск и отзыв¶

Управление через интерфейс¶

Администратор домена открывает Настройки → API-токены и находит строку billing.

• Перевыпуск — нажмите Перевыпустить ключ (значок круговых стрелок). Прочитайте предупреждение и нажмите Перевыпустить. Скопируйте новый ключ из открывшегося окна и замените его в конфигурации биллинга. Прежний ключ сразу перестаёт работать; заранее согласуйте переключение.

  

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

  

Разрешения существующего токена меняются через API; отдельной формы их редактирования здесь нет.

Управление через API¶

Эти запросы выполняет администратор домена со своей сессией:

• Посмотреть токены интеграций — GET /watcher/client-api/v3/api_tokens.
• Изменить разрешения — PUT /watcher/client-api/v3/api_tokens/billing с name: "billing" и полным новым массивом permissions. Он заменяет прежние разрешения; ключ сохраняется.
• Перевыпустить ключ — POST /watcher/client-api/v3/api_tokens/billing/rotate. Сохраните key из ответа и обновите конфигурацию биллинга. Старый ключ сразу перестаёт аутентифицировать запросы, поэтому согласуйте переключение заранее.
• Отозвать токен — DELETE /watcher/client-api/v3/api_tokens/billing. После 204 прежний ключ не работает. Проверить отзыв можно повторным запросом списка тарифов: ожидается отказ аутентификации.

Имя токена при обновлении сохраняется. При 409 с причиной ambiguous_name остановите изменение и обратитесь к администратору: в домене есть одноимённые токены. Ключи подключения NVR и ссылки просмотра камер управляются своими механизмами и не являются токенами этой интеграции.

Тарифные планы (пресеты)¶

Состав тарифов подготовьте с поддержкой до запуска биллинга. Пресет определяет глубину архива, облачное или локальное хранение и аналитику. Привязку billing_external_id заполните в интерфейсе Lumika: Пресеты камеры → тариф → Внешний ID биллинга.

Машинный токен читает тарифы запросом GET /watcher/admin-api/v3/presets. Для каждого элемента сохраните id, title, billing_external_id и параметры услуги. При наличии next передайте его в cursor следующего запроса. Изменение полей самого пресета этим токеном не разрешено.

Привязка тарифов к организациям выполняется отдельно:

• Добавить тариф организации — PUT /watcher/client-api/v3/organizations/{id}/presets с телом {"preset_id": 7}. Запрос добавляет тариф, а не заменяет весь набор.
• Отозвать тариф — DELETE /watcher/client-api/v3/organizations/{id}/presets/{preset_id}.
• Тариф по умолчанию — пресет с is_default: true доступен организациям автоматически.

При is_adjustable: false параметры архива определяются пресетом. Чтобы изменить услугу, назначьте другой доступный пресет; проверяйте сохранённый тариф камеры и фактическую запись после изменения.

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

Выполняйте шаги с токеном биллинга в указанном порядке. Числа 314, 501 и 7 — примеры: заменяйте их идентификаторами из ответов. До создания камеры у её организации должен быть владелец с заполненным external_id.

1. Создайте организацию абонента. При работе токеном она может временно не иметь владельца:

   POST /watcher/client-api/v3/organizations
   
   {"title": "Абонент 1042", "limits": {"streams": 5, "users": 3}}
   

   Сохраните id организации — далее 314. Если ответ потерян, сначала попросите администратора сверить создание по списку организаций; повторный POST может создать дубль. У токена нет операции чтения списка организаций.

2. Создайте обычного пользователя в этой организации через Admin API:

   POST /watcher/admin-api/v3/users
   
   {
     "name": "subscriber-1042",
     "password": "ExamplePassword1042",
     "email": "subscriber-1042@example.com",
     "external_id": "1042",
     "organization_id": 314
   }
   

   Сохраните id пользователя — далее 501. name служит логином, email — адресом уведомлений. Для реального абонента задайте отдельный пароль. Токен создаёт и изменяет только обычных пользователей своего домена; административные учётные записи и пользователи с особыми правами ему недоступны.

3. Назначьте абонента владельцем:

   PUT /watcher/client-api/v3/organizations/314
   
   {"owner": {"id": 501}}
   

   Теперь абонент управляет своей организацией и может активировать камеры. Токен биллинга не становится участником организации и не требует постоянных пользовательских прав на её камеры.

4. Разрешите тариф абонента, если он не доступен по умолчанию:

   PUT /watcher/client-api/v3/organizations/314/presets
   
   {"preset_id": 7}
   

5. Добавьте камеру либо передайте абоненту данные для самостоятельной активации Агента. Проверьте вход под абонентом, доступ к своей камере и архиву по выбранному тарифу. Убедитесь, что камеры других абонентов ему недоступны. Сохраните соответствие абонент → user_id → organization_id → stream_name в биллинге.

Дополнительный пользователь не получает просмотр только от членства в организации. Его разрешения выдаёт владелец организации или интеграция с областью config/organization-users по отдельному маршруту. Через эту область доступны только can_edit_streams, can_view_streams и note; управление пользователями и другие организационные права ею не выдаются.

Камеры¶

Чтобы создать доступную из облака RTSP-камеру, используйте Admin API. Организация и выбранный пресет должны принадлежать домену, а пресет — быть доступен организации:

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

{
  "title": "Подъезд 1",
  "organization_id": 314,
  "preset_id": 7,
  "inputs": [{"url": "rtsp://camera.example.com/main"}]
}

Сохраните name из ответа. Система генерирует имя камеры; new-camera в пути не станет её именем. При потере ответа сначала сверьте список через GET /watcher/admin-api/v3/streams?organization_id=314, обрабатывая next → cursor. Повтор создания с произвольным именем может создать вторую камеру.

Проверьте сохранённые организацию и пресет запросом GET /watcher/admin-api/v3/streams/{stream_name}. Фактическое видео и архив проверяет абонент или монтажник под своей учётной записью: машинный токен конфигурации не предоставляет просмотр.

Агентские камеры¶

Камеры за NAT подключаются через Flussonic Agent. После назначения владельца абонент входит в приложение или веб-интерфейс Lumika и активирует устройство в своей организации. Монтажник может сделать это под собственной учётной записью после выдачи временного доступа.

Машинный токен не вызывает пользовательский маршрут создания ключа активации Агента. Он получает уже появившиеся камеры через GET /watcher/admin-api/v3/streams?organization_id=314 и управляет их тарифами. Чтобы различить организации при установке, монтажник должен выбрать организацию нужного абонента.

Экспорт агентов в ваш биллинг¶

Отдельная интеграция сервиса активации может присылать сведения об активированных устройствах на URL биллинга. Её подключение и авторизацию согласуйте с поддержкой отдельно: этот входящий экспорт не использует токен конфигурации Lumika.

При включённом экспорте на ваш URL приходит POST-запрос с записями об активированных агентах. Поля записи:

Получив запись, ответьте 200 — при любом другом ответе сервер активации будет повторять отправку (несколько попыток с нарастающим интервалом). Тело вашего ответа не разбирается.

Храните agent_serial для сопоставления с учётом устройств и agent_id для текущей активации. Поля owner и abonent_sign могут содержать сведения о привязке. После уведомления сверяйте камеру и её организацию через API Lumika; формат записи экспорта не является телом запроса создания камеры.

Если устройство ещё не привязано, завершите пользовательскую активацию из предыдущего раздела. Затем сохраните выданное имя камеры в биллинге. Повторное уведомление об одном устройстве не должно создавать вторую услугу.

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

Назначьте камере другой доступный пресет:

PUT /watcher/admin-api/v3/streams/{stream_name}

{"preset_id": 9}

Для нескольких камер используйте:

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

{"streams": [{"name": "camera-one", "preset_id": 9}, {"name": "camera-two", "preset_id": 9}]}

Подставьте сохранённые имена. Если одно не найдено, запрос отклоняется с 404; при успешном применении ответ — 204. Перечитайте камеры и проверьте новый пресет, затем запись под пользовательской учётной записью. Смена глубины архива не восстанавливает уже удалённые записи.

Удаление камеры¶

Токен config/streams не разрешает DELETE /streams/{name}. Если камера больше не нужна, её удаляет пользователь с соответствующими правами через интерфейс Lumika. Для временной приостановки используйте отключение, описанное ниже. Удаление и отключение имеют разные последствия для учёта потребления; сверяйте итог по отчёту.

Временный доступ монтажника¶

Монтажник — обычный пользователь домена со своим логином и паролем. Для выдачи доступа интеграции нужна область config/organization-users с write: true. Подготовьте учётную запись до назначения прав; если её создаёт биллинг, используйте POST /watcher/admin-api/v3/users как в шаге подключения абонента и сохраните её id. Назначать монтажника владельцем организации не требуется.

1. Выдайте пользователю 502 доступ к организации абонента 314:

   PUT /watcher/client-api/v3/organizations/314/users/502
   
   {"can_edit_streams": true, "note": "Монтаж на объекте"}
   

   Ожидается 200 и сведения о пользователе организации. Учётная запись и организация должны быть из домена токена. При добавлении участника учитывается лимит пользователей организации.

2. Передайте монтажнику адрес домена и данные его пользовательской учётной записи. В приложении или веб-интерфейсе он выбирает организацию абонента и подключает камеру. Проверьте, что камера появилась у нужного абонента.

3. После работ удалите доступ:

   DELETE /watcher/client-api/v3/organizations/314/users/502
   

   Ожидается 204. Удаляются членство и права в этой организации, включая папочные и прямые права на её камеры. Учётная запись и её доступ в других организациях сохраняются. Проверьте, что монтажник больше не открывает камеру и её настройки. Уже установленные медиасоединения могут завершиться позднее.

Право can_edit_streams включает просмотр всех камер организации и архива. Для просмотра без настройки передайте can_view_streams: true без права редактирования. Доступ не имеет автоматического срока окончания: отзыв должен выполнить биллинг или ответственный администратор.

Токен не может через этот маршрут управлять владельцем организации, системным администратором, владельцем домена или пользователем с доменными привилегиями. Иные поля, например can_edit_users, этим токеном запрещены. Ошибка 403 требует проверки разрешённых полей и типа целевого пользователя; 404 — идентификаторов и домена.

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

При любом изменении пользователя через PUT /watcher/admin-api/v3/users/{id} передавайте актуальное значение disabled. Если поле пропустить, оно принимает false и запрос может снять блокировку. Токен биллинга не читает карточку пользователя: состояние блокировки храните в биллинге либо предварительно уточняйте через администратора.

Для блокировки обычного абонента используйте Admin API:

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

{"disabled": true}

Активные пользовательские сессии удаляются; повторный вход и новые обращения к видео должны быть запрещены. Не считайте ответ API подтверждением немедленного завершения всех уже открытых медиасоединений. Организация, камеры и архив сохраняются. Для возобновления передайте {"disabled": false} и проверьте новый вход абонента.

Чтобы остановить одну камеру для всех её пользователей:

PUT /watcher/admin-api/v3/streams/{stream_name}

{"disabled": true}

После сохранения перечитайте камеру и проверьте остановку видео и записи. Для включения передайте disabled: false.

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

Отчёт о потреблении¶

Данные для выставления счетов абонентам отдаёт метод:

GET /watcher/client-api/v3/usage/cameras?from=2026-07-01&to=2026-07-31

Для этого запроса токену нужны config/streams и list: true. Метод возвращает данные только домена токена. Каждая запись ответа — учётный период: отрезок, в течение которого камера была на одном тарифе, обрезанный по границам запрошенного диапазона:

{
  "usage": [
    {
      "stream_name": "Подъезд.1-k3n8f2p1qa",
      "plan_id": "cloud-7d",
      "billing_plan_id": "plan-hd-7d",
      "account_id": 314,
      "external_account_id": "1042",
      "license_id": "12345",
      "from": "2026-07-01",
      "to": "2026-07-18"
    },
    {
      "stream_name": "Подъезд.1-k3n8f2p1qa",
      "plan_id": "cloud-30d",
      "billing_plan_id": "plan-hd-30d",
      "account_id": 314,
      "external_account_id": "1042",
      "license_id": "12345",
      "from": "2026-07-19",
      "to": "2026-07-31"
    }
  ]
}

В примере отчёт содержит два периода: до 18 июля камера учитывается по одному тарифу, с 19 июля — по другому. Для начисления используйте даты выгрузки, а не время запроса изменения пресета.

Правила учёта:

• Отчёт использует календарные даты по UTC. Периоды обновляются фоновым процессом. Запрос смены пресета не гарантирует немедленного открытия нового учётного периода или фиксации тарифа ровно в полночь; для начисления используйте возвращённые from и to.
• День создания и день удаления камеры входят в отчёт.
• Незакрытый период приходит с to, равным текущей дате.
• Поля без значения не приходят вовсе: если у владельца организации нет external_id, ключа external_account_id в записи просто не будет.

Без параметров from и to метод возвращает данные за вчерашний день (по UTC). Ответ пагинируется параметрами limit (по умолчанию 1000) и cursor по общим правилам REST API.

Рекомендуемая схема: раз в сутки забирайте данные за прошедший день — значения по умолчанию делают ровно это. Агрегируйте дни на своей стороне и сохраняйте результат обработки каждого диапазона, чтобы повторная выгрузка не привела к повторному начислению. Альтернатива — первого числа запрашивать целиком прошедший месяц.

Вход абонента¶

Абонент входит на адрес своего домена по name и паролю, заданным при подключении. В мобильном приложении также нужен Operator ID домена. Передавайте эти данные абоненту; ключ серверной интеграции ему не нужен.

Если абонент забыл пароль, сначала уточните его состояние блокировки. Для активного абонента задайте новый пароль через Admin API:

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

{"password": "NewExamplePassword1042", "disabled": false}

Для заблокированного абонента передайте disabled: true, чтобы сохранить блокировку. При смене пароля другой учётной записью прежние сессии пользователя удаляются. Проверьте новый вход только после разрешённого возобновления доступа.

Частые вопросы¶

Как восстановить потерянное соответствие объектов? Биллинг должен сохранять идентификаторы из ответов. Токен конфигурации не читает списки пользователей и организаций. Для сверки администратор домена использует интерфейс или собственную сессию API. Камеры можно сверить токеном через Admin API. Не повторяйте запросы создания вслепую после таймаута.

Может ли биллинг менять тарифы без пользовательского доступа к видео? Да. config/streams с write: true позволяет изменить пресет камеры. Сам токен не предоставляет просмотр. Управление владельцами и разрешениями пользователей — отдельные действия, которые могут выдать просмотр соответствующей учётной записи.

Почему создание монтажника работает, а изменение его учётной записи после выдачи прав запрещено? Область config/users предназначена для обычных абонентских учётных записей и не позволяет менять пользователей с особыми правами. Подготовьте учётную запись до назначения организационных прав. Для отзыва монтажа используйте удаление участника организации из соответствующего раздела.

Почему в отчёте нет внешнего идентификатора абонента или тарифа? Заполните external_id владельца и billing_external_id пресета до начала услуги. Уже открытый период не получает эти значения задним числом. Сверьте владельца, пресет и даты отчёта перед начислением.

Почему пользователь не может активировать Агент? Проверьте, что он владеет нужной организацией или имеет в ней право редактирования камер. Доступ только к просмотру не даёт права подключения. Завершите назначение владельца либо выдачу доступа монтажнику до активации.