Skip to content

Integration with existing billing system

This article describes common scenarios of integration between Flussonic Watcher and third party system allowing managed camera sales and accounting for subscribers and their services. API for integration is fully available here.

Explanation of terms:

  • Provider is a client of Flussonic, the owner of the service
  • Subscriber is a Provider's subscriber, the user of the service
  • Billing is a third party system not related to Watcher; it allows managing plans (billing plans, subscriptions) of Provider's services to subscribers as well as payment collection

The concept of billing implies that the billing service is the master system storing and managing subscribers data, and not Flussonic Watcher. Such a best practice allows you to centrally manage services in different systems, linking, for example, smart home and video surveillance in a single project.

Before you add any cameras for you subscribers, make sure to create the corresponding structure of organizations and presets in Watcher, assign permissions to subscriber. You can do it in Watcher web UI and/or by corresponding API requests for organizations, users, folders management. The mechanism for matching billing plans and Watcher presets, as well as the logic that will affect access, archive depth and other settings, is on the billing side in any case.

The integration scenario is different for cameras with or without the Agent. Both are described below.

You will also find below example requests to suspend Watcher services for a subscriber.

Creating presets

A preset is a predefined set of archive and analytics settings to populate to the camera. Presets correspond to your billing plans, so you should create and configure presets before adding cameras.

The subscribers usually shall not be allowed to change the camera settings populated from the preset. Just make the preset non-configurable to fulfill this requirement.

With non-configurable presets, the subscribers will not be able to change the preset-defined parameters even if they have the Organization Owner permissions allowing them to edit the camera settings. The settings will be visible but not editable.

Non-adjustable preset on the camera

Organization Owners cannot create, edit or delete presets: only Watcher Administrators have such permissions. However, if several presets are linked to an Organization, then the Organization Owner will be able to switch presets in the camera settings.

Use the following API request to create a preset from the billing system:

POST http(s)://YOUR_WATCHER_URL/vsaas/api/v2/presets

title is a required parameter for the preset name.

Request example to create a non-adjustable preset (is_adjustable=false) defining the archive depth of 2 days:

curl -v POST http://127.0.0.1/vsaas/api/v2/presets \
-d '{"title":"non-adjustable preset","is_adjustable":false, "organization_id":"1", "dvr_depth": 2}' \
-H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a368d' \
-H "Content-Type: application/json"

The response will contain all the parameters of the created preset, including id for further use in the camera management requests.

{
    "is_default": false,
    "is_deleted": false,
    "title": "non-adjustable preset",
    "dvr_space": null,
    "id": 1,
    "is_adjustable": false,
    "dvr_depth": 2,
    "vision_areas": null,
    "precise_thumbnails_days": 0,
    "vision_enabled": null,
    "vision_alg": null,
    "vision_gpu": null,
    "domain_id": 1,
    "dvr_lock_days": null,
    "vision_params": {}
}

You can also use requests like GET/PUT/DELETE http(s)://YOUR_WATCHER_URL/vsaas/api/v2/presets/{preset_id} to get/change/delete the preset with the specified ID.

Cameras with Agent

When you use cameras with Agent, the scenario is as follows:

  1. A modified firmware with Flussonic Agent is uploaded on a batch of cameras (Flussonic specialists can do that). This firmware contains information about which Flussonic Watcher this camera should be linked to.
  2. The Provider enters camera info into the billing inventarization system while the camera is on stock.
  3. When selling the camera to the subscriber, the Provider's employee links the camera serial number in billing with the subscriber’s ID.
  4. As soon as the camera connects to some network, it receives authorization data from the activation server. This data is not related to the subscriber’s authorization; this is the camera authorization.
  5. The activated camera immediately starts trying to connect to Flussonic Watcher.

  6. The activation server sends data about the camera to the billing.

    Note

    The activation server can send data about the camera directly to Watcher, if information about its owner is already known when activating the camera with the Agent (for example, when IRIS camera is activated from the mobile app). It depends on the Agent type and on requirements to integration. Please contact Flussonic Watcher technical support to configure the activation server.

  7. Billing receives information about the newly created camera, adds information about the preset (billing plan) and the organization to it.

  8. Billing sends information about newly created camera to Watcher. This and the previous steps are to be implemented at billing side.
  9. Now the camera can connect to Watcher and start streaming.

The subscriber does not have to change any settings of routers, cameras and other network devices when the process is arranged the above way. The camera appears in the subscriber’s account automatically as soon as it is connected to the network as soon as the API is implemented in billing for receiving data about newly created cameras and sending this data to Watcher. Such a data proxying scheme is needed to add information about the owner of the camera and the services that are available on this camera.

The activation server maintained by Flussonic sends a request with a CSV or a list of JSON objects to the configured URL. Please contact Flussonic Watcher technical support to make the server send requests to the billing URL.

Send all data received from the activation server to Flussonic Watcher unchanged unless you decide to change them for some reason. For example, you may receive the can_ptz=1 flag and set it to 0 to forbid the subscriber from controlling PTZ in Watcher.

The fields (in CSV or JSON) sent from the activation server to the billing:

  • agent_model (string): camera model
  • agent_serial (string): camera serial number
  • agent_id (string): unique ID of the Agent on camera
  • agent_key (string): special field for the camera authorization by Watcher
  • stream_url (string): main RTSP URL of the stream
  • substream_url (string): second RTSP URL of the stream
  • thumbnails (string): thumbnails URL
  • onvif_url (string): URL for camera response via ONVIF
  • onvif_profile (string): service field
  • can_ptz (0 or 1): enable or disable PTZ
  • abonent_sign (integer): encrypted information about the organization and the user who owns the camera. It is present only for the corresponding type of Agent, when the subscriber manually adds a camera to the organization via Watcher mobile app or web UI. If this field is filled, you do not have to add info about the camera owner.

Warning

Having received the data, the billing system must return a "200" response to the activation server. Otherwise, the activation server will retry sending data until this acknowledgment is received.

The information received from the activation server should be "merged" with the camera data already existing in the billing or other accounting system by parameter agent_serial (camera serial number). You should understand that agent_id can change, e.g. if the camera is handed to another subscriber. The serial number of the camera does not change.

Note

Thus, if there is an inventory system in billing, in which the camera is linked to a subscriber before the first activation, then a new record will not appear; instead, you must fill in the missing fields in the existing line in the database. If there is no such inventory system, then you need to create new entries for cameras in the billing when you receive an activation message.

The billing should add additional camera attributes, such as linking to an organization or details on services within the plan.

When the additional fields (preset_id, enabled, organization_id) are added, send the information about the camera (CSV or JSON) to Watcher using one of the following requests:

POST http(s)://YOUR_WATCHER_URL/vsaas/api/v2/cameras/import to add several cameras

POST http(s)://YOUR_WATCHER_URL/vsaas/api/v2/cameras to add one camera

Example request for several cameras is shown below. Please note that the X-Vsaas-Api-Key should be changed to the one shown in your Watcher settings.

curl -v POST http://localhost:80/vsaas/api/v2/cameras/import \
  -d \
  '[{
  "name":"cam1","stream_url":"fake://clock",
  "enabled":true,"dvr_depth":3,"agent_id":"123098456","agent_serial":"mJ0ODnktZFc",
  "agent_key":"salt:secretkey","preset_id":"1","organization_id":"1"
  }]' \
  -H "X-Vsaas-Api-Key: 7ab056b1-5bb1-4501-b528-d69538392842" \
  -H "Content-Type: application/json"
....
{
  "deleted": 0, 
  "updated": 0, 
  "errors": {}, 
  "created": 1
}

If you do not specify the preset ID and organization ID in the request, the camera will be added to the default organization with the default preset.

Cameras without Agent

The scenario for cameras without Agent (e.g. RTSP, ONVIF) would usually be as follows:

  1. A camera is connected to the internal Provider’s network.
  2. The subscriber asks Provider to grant access to the camera.
  3. The Provider sends request to billing to add the camera for the subscriber or give permissions to use the camera.

  4. If it is a new personal camera (e.g. for subscriber’s smart home):

    • It is assumed that the user and organization for the subscriber have already been created in Watcher. If they are not, you or the billing system need to create them in the Watcher web UI or by sending the appropriate API requests from billing.

    • Billing fills in the necessary camera attributes in accordance with the billing plan.

    • Billing sends a request to Watcher to add a camera to the subscriber (see example below).

  5. If the subscriber wants to connect to a shared camera, for example, to an intercom or to the Safe City system:

    • It is assumed that the corresponding camera and organization have already been created in Watcher. If they are not, you or the billing system need to create them in the Watcher web UI or by sending the appropriate API requests from billing.

    • Billing fills in the necessary attributes of the user (subscriber) by adding to the organization to which the required camera is added.

    • Billing sends a request to Watcher to create or update the subscriber (see example below).

Adding a camera

POST http(s)://YOUR_WATCHER_URL/vsaas/api/v2/cameras/import to add several cameras.

POST http(s)://YOUR_WATCHER_URL/vsaas/api/v2/cameras to add one camera.

The following parameters are required in the request to add a camera:

  • preset_id (integer): Watcher preset identifier corresponding to the billing plan in billing.
  • stream_url (string): main RTSP URL of the stream.
  • organization_id (integer): organization identifier. The organization must have already been created in Watcher.

The simple example of a request to add one camera is shown below. You can try to copy this request and execute it on a server with Watcher installed. Please note that the X-Vsaas-Api-Key should be changed to the one shown in your Watcher settings.

curl -v -X POST http://127.0.0.1/vsaas/api/v2/cameras \
-H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a368d' \
-H 'content-type: application/json' \
-d '{
  "title": "myCamera",
  "stream_url": "fake://clock",
  "preset_id": "1",
  "organization_id": "1"}'

As a result of such a request, a virtual camera called "myCamera" broadcasting time ("stream_url": "fake://clock") will be added to the default organization ("organization_id": "1") with default preset ("preset_id": "1"). In response to the request, Watcher will send JSON with a list of all parameters of the added camera.

Adding a user

POST http(s)://YOUR_WATCHER_URL/vsaas/api/v2/users

Example:

Please note that the X-Vsaas-Api-Key should be changed to the one shown in your Watcher settings.

curl -v POST http://127.0.0.1/vsaas/api/v2/users \
-d '{"login":"user1", "organization_id":"1"}' \
-H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a368d' \
-H "Content-Type: application/json"

As a result of this query, the user named user1 will be added to the default organization ("organization_id":"1").

The unencrypted password can also be sent in this query (use "password" parameter). However, if the Provider does not store subscriber passwords as plain text and cannot transfer them in any way, you need to configure external authorization backend in order for the subscriber to be able to log into Watcher.

See below for an example of updating the user.

Disabling the camera to the subscriber from billing

If the subscriber, for some reason, should no longer use the camera (for example, turned off the service or did not pay on time), billing should send a corresponding request to Watcher.

The easiest way is disabling the user. You can use the following request PUT https://watcher_api_url/vsaas/api/v2/users/(int:user_id) with "enabled": false.

Example:

curl -v -X PUT http://127.0.0.1/vsaas/api/v2/users/5 \
-H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a3687' \
-H 'content-type: application/json' -d '{"enabled":false}'

There are also the following main options for limiting rights without disabling the user:

  1. The subscriber's personal camera, and the subscriber has no rights to edit cameras.

    Disable the camera by PUT https://watcher_api_url/vsaas/api/v2/cameras/(string:cam_name), with "enabled": false.

    Example:

    curl -v -X PUT -H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a3687' -H 'content-type: application/json' \ http://127.0.0.1/vsaas/api/v2/cameras/inst1cam-8e1a6e020e -d '{"enabled":false}'

    Note

    Please note that the name of the camera in the interface may not coincide with its name in the database.

  2. The subscriber's personal camera, and the subscriber has rights to edit cameras.

    Prevent the user from editing cameras by request PUT https://watcher_api_url/vsaas/api/v2/users/(int:user_id), with "readonly": true.

    curl -v -X PUT -H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a3687' -H 'content-type: application/json' \ http://127.0.0.1/vsaas/api/v2/users/5 -d '{"readonly": true}'

    Then disable cameras as shown above in option 1.

  3. The camera is publicly available, many subscribers use it (for example, a video intercom in an apartment building or a camera of the "Safe City" system)

    Please note that you cannot restrict access to a particular camera for a user, you can only block access to a folder. See this page for details.

    The request to delete permissions to access a folder is DELETE https://watcher_api_url/vsaas/api/v2/organizations/(int:organization_id)/folders/(int:folder_id)/users/(int:user_id)

    Example request to restrict access for user with ID=3 to the folder with ID=2 in the organization with ID=1:

    curl -v -X DELETE -H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a368d' -H 'content-type: application/json' \ http://127.0.0.1:80/vsaas/api/v2/organizations/1/folders/2/users/3