Tracker tariff
Which tariff a device is on, and the rules governing a change to another.
These operations read the tariffs a device may switch to, and perform the switch.
A change is heavily constrained, and tariff/tracker/list exists so a caller can find out what is actually permitted rather than guessing. A user may move a tracker from tariff t1 to tariff t2 only when all of the following hold:
The tracker belongs to the user and is not a clone.
The tracker's tariff was last changed more than
tariff.freeze.periodago, 30 days by default.t1.tariff_iddiffers fromt2.tariff_id, so the new tariff is genuinely a different one.t1.dealer_idandt2.dealer_idboth equal the user's effective dealer.t2.activeis 1, meaning the dealer has allowed users to switch to it themselves.t1.groupingequalst2.grouping, so the change stays inside one group of tariffs.t2.deviceistracker, so the new tariff is one for trackers.The new tariff is available to the user's legal type. See Tariff (plan).
The effective dealer is the user's own dealer when its dealer_id equals the configured defaultDealerId, or when its dogovor_type is paas. Otherwise it is that dealer's parent.
API actions
API base path: /tariff/tracker.
Operations that list no errors of their own return only the general error codes.
Required sub-user rights: admin (available only to master users).
Move a tracker from its current plan to the plan given by tariff_id.
The change is allowed only when all of the following hold: the tracker belongs to the user and is not a clone; the last change was more than the freeze period ago, 30 days by default; the new plan differs from the current one; both plans belong to the user's effective dealer; the new plan is active; both plans are in the same group; the new plan is for trackers; and the new plan is available to the user's legal type.
When the last change was too recent but the current plan has an early_change_price, the change proceeds and that price is charged. Without one it fails with error 240.
Master users only. A sub-user gets error 13, which the published error list does not mention.
Also accepts GET with the same parameters as query-string values.
Requires the admin right.
Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.
ID of the tracker, also known as the object ID. Must belong to the current account. A blocked tracker is accepted here, unlike most operations taking a tracker ID.
ID of the new plan.
Plan changed
true if request finished successfully.
trueBad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error 13: the caller is a sub-user. Error 219: the tracker is a clone. Error 221: the new plan's device limit is below the current number of devices. Error 238: the user may not switch this tracker to that plan. Error 240: the plan was last changed 30 days ago or less, and the current plan has no early change price.
Error 239: the new plan does not exist.
Error response object
POST /v2/tariff/tracker/change HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 30
{
"tracker_id": 1,
"tariff_id": 1
}{
"success": true
}Errors
These errors come in addition to the general error codes:
201 - Not found in the database - if user doesn't have trackers with given
tracker_id.219 - Not allowed for clones of the device.
237 - Invalid plan - if there are no plan with specified
tariff_idand belongs to user's effective dealer.221 - Device limit exceeded - when new plan limit for devices is less than the current count of devices in the account.
238 - Changing plan is not allowed - user can't switch tracker to that plan.
239 - New plan doesn't exist.
240 - Not allowed changing plan too frequently - plan last changed less or equal to 30 days (tariff.freeze.period config option).
Lists the plans a tracker can switch to, even when the plan was last changed less than tariff.freeze.period ago.
List the plans the given tracker can be switched to, together with the wait until the next free change.
The list is returned even when the last change was less than the freeze period ago; days_to_next_change is what tells you whether a change is free yet.
Also accepts GET with the same parameters as query-string values.
Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.
ID of the tracker, also known as the object ID. Must belong to the current account. A blocked tracker is accepted here, unlike most operations taking a tracker ID.
Plans available for the tracker
true if request finished successfully.
trueDays until the next free change, or 0 when a free change is available now.
Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.
Error response object
POST /v2/tariff/tracker/list HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16
{
"tracker_id": 1
}{
"success": true,
"list": [
{
"id": 1,
"name": "text",
"group_id": 1,
"active": true,
"type": "monthly",
"price": 1,
"early_change_price": 1,
"device_limit": 1,
"has_reports": true,
"paas_free": true,
"store_period": "text",
"auto_prolong": true,
"features": [
"api"
],
"map_filter": {
"exclusion": true,
"values": [
"text"
]
}
}
],
"days_to_next_change": 1
}Last updated
Was this helpful?