Client plans management | GPS-Trace

Client plans management

Methods in this section are related to the Forguard solution.

The specificity of Forguard accounts lies in assigning a client plan upon creation, wherein partners determine the available account limits and control specific application features/modules when creating a client plan.

The client plan, in turn, is built upon partner plans offered by the GPS-Trace platform.

Client plans consist of two sections:

  • Quotas
  • Modules 

Quotas include limits on unit quantity per account, geofence quantity, and maximum data storage limit.

"quotas": {
  "unit": number,
  "geofence": number,
  "unit_storage": number
}

Modules are specific features or functionalities within the Forguard application that partners can choose to enable or disable in a client plan for a client account at their discretion.

Currently, the following modules are available:

  • service_mode - Activates Service Mode option in the app
  • tools-  Activates Toolbox and SetBox in the app
  • notifications - Activates basic notifications in the app, providing access to view and configure notifications (Simple and Customizable)
  • unit_event - Activates the Event option in the app
  • geofence - Activates Geofences tab in the application
  • timeline - Activates Timeline tab in the application
  • sharing - Activates the Sharing option in the app
  • command - Activates the Commands Panel in the app
  • google_maps - Allows the use of Google Maps in the app
  • statistics - Activates Statistics tab in the app
  • extended_notification - Activates sending methods such as by email, Webhook, and Telegram. Enables Own notifications working by parameters.
  • maintenance - Activates Maintenance tab with mileage and engine hours counters.

Partner uses a partner plan to create a client plan, adjusting the limits based on the partner plan.

For instance, if a partner plan has a 10 units limit per account, the partner can set a lower value but not exceed 10 units in the client plan.

Scheme for creating a Forguard account:
Forguard Account (1)

Create client plan

This API endpoint allows for the creation of a client plan, which is used in the process of creating Forguard accounts.

POST /partner/client-plans

The mandatory field for this request:

  • “managed_plan_id”: “string” - The identifier of the partner plan on which the client plan is based. The list of partner plans can be obtained using the GET method /billing/managed-plans.
  • “app_id”:”string” - The ID of the application to which this tariff belongs. For the current moment, it is only Forguard (Forguard app_id - b901da51-ce00-4af2-b978-8d0fca8ae1ea)
  • “name”:”string” - Client plane name
  • “quotas”:{} - This is an object containing information about the quotas associated with the creation of a client plan. It includes three fields:
    • "unit": number - Represents the limit for the number of units available in the client plan.
    • "geofence": number - Specifies the limit for the number of geofences allowed in the client plan.
    • "unit_storage": number - Indicates the limit for the unit storage capacity in the client plan.
      The count should range between 10240 and 204800, depending on the partner plan limit.
      Step: 10240. Each step represents 10 MB.
  • “modules”:[] - This is an array listing the modules that will be available (enabled) in the client plan. Currently, the following modules are available:
    • "service_mode" - Activates Service Mode option in the app
    • "tools"-  Activates Toolbox and SetBox in the app
    • "notifications" - Activates basic notifications in the app, providing access to view and configure notifications (Simple and Customizable)
    • "unit_event" - Activates the Event option in the app
    • "geofence" - Activates Geofences tab in the application
    • "timeline" - Activates Timeline tab in the application
    • "sharing" - Activates the Sharing option in the app
    • "command" - Activates the Commands Panel in the app
    • "google_maps" - Allows the use of Google Maps in the app
    • "statistics" - Activates Statistics tab in the app
    • "extended_notification" - Activates sending methods such as by email, Webhook, and Telegram. Enables Own notifications working by parameters.
    • "maintenance" - Activates Maintenance tab with mileage and engine hours counters.

Request body example:

curl -X 'POST' \
  'https://api.gps-trace.com/partner/client-plans \
  -H 'accept: application/json' \
  -H 'X-AccessToken: <your token>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Client Plan",
  "description": "Client plan description",
  "quotas": {
        "unit": 30,
        "geofence": 50,
        "unit_storage": 204800},
  "modules": [
        "command",
        "google_maps",
        "geofence",
        "statistics",
        "tools",
        "extended_notification",
        "unit_event",
        "sharing",
        "timeline",
        "notification",
        "maintenance",
        "service_mode"
  ],
  "managed_plan_id": "string",
  "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea"
}'

Modules 'account', 'unit', and 'fuel' are always enabled by default in Forguard accounts. They can only be seen in the response to the request.

201 Response example:

{
  "data": {
    "quotas": {
      "unit": 30,
      "geofence": 50,
      "unit_storage": 204800
    },
    "creator_id": number,
    "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
    "updated_at": number,
    "description": "Client plan description",
    "managed_plan_id": "string",
    "modules": [
      "notification",
      "command",
      "account",
      "geofence",
      "service_mode",
      "sharing",
      "unit_event",
      "timeline",
      "statistics",
      "extended_notification",
      "maintenance",
      "tools",
      "unit",
      "google_maps"
    ],
    "name": "Client Plan",
    "created_at": number,
    "id": "string"
  }
}

Get list of client plans

This API endpoint allows you to obtain a list of created client plans.

GET /partner/client-plans

200 Response example:

{
  "data": [
    {
      "id": "string",
      "quotas": {
        "unit": 20,
        "geofence": 0,
        "unit_storage": 10240
      },
      "name": "Test",
      "creator_id": number,
      "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
      "managed_plan_id": "string",
      "updated_at": number,
      "description": null,
      "created_at": number,
      "modules": [
        "service_mode",
        "account",
        "unit"
      ]
    },
    {
      "id": "string",
      "quotas": {
        "unit": 10,
        "unit_storage": 102400,
        "geofence": 50
      },
      "name": "Test2",
      "creator_id": number,
      "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
      "managed_plan_id": "string",
      "updated_at": number,
      "description": null,
      "created_at": number,
      "modules": [
        "tools",
        "unit_event",
        "command",
        "google_maps",
        "statistics",
        "unit",
        "maintenance",
        "service_mode",
        "notification",
        "account",
        "extended_notification"
        "sharing",
        "timeline",
        "fuel",
        "geofence"
      ]
    }
  ]
}

The response includes information about client plans available, with each plan represented by an object containing the following fields:

  • id: string - unique identifier for the client plan.
  • name: string - name of the client plan.
  • creator_id: number - ID of the partner account who created the client plan.
  • app_id: string - ID of the application associated with this client plan.
  • managed_plan_id: string - ID of the partner plan upon which this client plan is based.
  • updated_at: number - timestamp indicating when the client plan was updated.
  • description: string - description of the client plan.
  • created_at: number - timestamp indicating when the client plan was created.
  • quotas - this is an object containing information about the quotas associated with the creation of a client plan. It includes three fields:
    • unit: number - represents the limit for the number of units available in the client plan.
    • geofence: number - specifies the limit for the number of geofences allowed in the client plan.
    • unit_storage: number - indicates the limit for the unit storage capacity in the client plan. The count should range between 10240 and 204800, depending on the partner plan limit. Step: 10240. Each step represents 10 MB.
  • modules:[] - this is an array listing the modules that will be available (enabled) in the client plan. Currently, the following modules are available:
    • service_mode - activates service mode option in the app
    • tools -  activates Toolbox and SetBox in the app
    • notifications - activates basic notifications in the app, providing access to view and configure notifications (Simple and Customizable)
    • unit_event - activates the event option in the app
    • geofence - activates geofences tab in the application
    • timeline - activates timeline tab in the application
    • sharing - activates the sharing option in the app
    • command - activates the commands panel in the app
    • google_maps - allows the use of Google Maps in the app
    • statistics - activates statistics tab in the app
    • extended_notification - activates sending methods such as by email, Webhook, and Telegram. Enables Own notifications working by parameters.
    • maintenance - activates maintenance tab with mileage and engine hours counters.
  • creator_id: number - partner account ID

Get client plan by ID

This API endpoint allows you to get information about a specific client plan by its ID

GET /partner/client-plans/{id}

  • id: string - unique identifier for the client plan.

200 Response example:

{
  "data": [
    {
      "id": "string",
      "quotas": {
        "unit": 20,
        "geofence": 0,
        "unit_storage": 10240
      },
      "name": "Test",
      "creator_id": number,
      "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
      "managed_plan_id": "string",
      "updated_at": number,
      "description": null,
      "created_at": number,
      "modules": [
        "service_mode",
        "account",
        "unit"
      ]
    }
  ]
}

Delete client plan

This API endpoint allows you to delete client plan by its ID

DELETE /partner/client-plans/{id}

  • "id": ”string” - The unique identifier for the client plan.

Upon successful deletion, a response with status code 200 will be returned, along with the ID of the client plan that was removed.

200 Response example:

{
  "data":"string"
}

Get modules

This endpoint allows to retrieve information about the modules used in creating client plans.

GET /partner/client-plans/modules

Creating Forguard account requires assigning a client plan to it.
Client plans are made based on partner plans provided by the GPS-Trace platform.

Partner plans consist of two main parts: 

  • Limits - include unit max quantity per account, geofence quantity, and data storage limit.

Example of limits:

"limits": {
          "geofence": {
            "default": 35,
            "max": 70,
            "min": 0,
            "step": 1
          },
          "unit": {
            "default": 35,
            "max": 70,
            "min": 1,
            "step": 1
          },
          "unit_storage": {
            "default": 102400,
            "max": 204800,
            "min": 10240,
            "step": 10240
          }
        }

  • Modules - specific features or functionalities within the Forguard application that partners can choose to enable or disable in a client plan for a client account at their discretion 

Currently, the following modules are available:

  • service_mode - activates service mode option in the app
  • tools-  activates Toolbox and SetBox in the app
  • notifications - activates basic notifications in the app, providing access to view and configure notifications (Simple and Customizable)
  • unit_event - activates event option in the app
  • geofence - activates geofences tab in the application
  • timeline - activates timeline tab in the application
  • sharing - activates the sharing option in the app
  • command - activates commands panel in the app
  • google_maps - allows the use of Google Maps in the app
  • statistics - activates statistics tab in the app
  • extended_notification - activates sending methods such as by email, Webhook, and Telegram. Enables Own notifications working by parameters.
  • maintenance - activates maintenance tab with mileage and engine hours counters.

Client plans based on partner plans and include specific quotas and modules.
Quotas for geofences, units, and data storage volume are set during client plan creation, within the limits of the partner plan. Partners can activate or deactivate modules available in the partner plan. 

For instance, a partner might select a partner plan allowing 70 units, create a client plan based on it, set a 50-unit limit, and apply this plan to a Forguard account for the client to track up to 50 units.

Modules 'account', 'unit', and 'fuel' are always enabled by default in Forguard accounts. They can only be seen in the response to the request.

200 Response example:

{
  "data": [    
{
      "default_included": false,
      "name": "tools",
      "hidden": false,
      "required": false,
      "depended_on": [],
      "default_access": 15
    },
    {
      "default_included": false,
      "name": "service_mode",
      "hidden": false,
      "required": false,
      "depended_on": [],
      "default_access": 15
    },
  ...