Telemetron API

API Endpoint

https://api.telemetron.net

Overview

Current document describes an official Telemetron API, which is used mostly in mobile apps.

Current version of API is v2.

Authorization

API v2 uses OAuth2 protocol to authorize requests. Application must get access_token prior to making API calls, and pass it with each API request.

Thus, every request must contain valid access_token. For calls, using API v2, HTTP header Authorization with Bearer state must be used.

Authorization: Bearer ACCESS_TOKEN

Schema

All requests must be done via HTTPS. API entry point is

https://api.telemetron.net/v2

Any resource path given in examples is relative to this entry point:

/user/active -> https://api.telemetron.net/v2/user/active

All response data is sent in JSON by default, but different format of response can be requested, if such is supported by resource.

All request data must be in JSON.

All timestamps are ISO8601-compliant.

Parameters

Some resources can receive optional parameters. GET-requests must provide this parameters as a query string, if such parameters are not in resource path.

POST, PUT, DELETE-requests can pass parameters as a query string included in the URL, or as a valid JSON contained in the body of the request.

Errors (Errors)

Any response classified as an error has a 4xx (client error) or 500 (server error) HTTP-code.

At this moment the possibility of code error 4xx (suppress to 200) and return with code 200 is missing.

Body of the response contains at least one object with a message attribute, in which error text is specified:

HTTP/1.1 404 Not found

{ "message": "Vending machine not found" }

In some cases, subcode attribute might be added to the response, indicating the number of internal classification error. This number serves the purpose of current development and debugging, so the client application should not fully rely on it, but should take into account the HTTP response code.

Additionally, if possible, documentation_url attribute can be specified with reference to the documentation section describing the problem in more detail.

HTTP/1.1 400 Bad request

{
    "message": "Not allowed",
    "subcode": "E123",
    "documentation_url": "https://api.telemetron.ru/doc/error/chapter/..."
}

Some resources might also complement error response with errors array, which lists additional data indicating the source of the error. For example, when validating incoming data, some fields fail validation. The format of this additional data is described in the section of the relevant resource, if it supports additional data in error.

HTTP/1.1 400 Bad request

{
    "message": "Bad request",
    "errors": [
        {
            "field": "id",
            "reason": "missing"
        },
        {
            "field": "created_at",
            "reason": "invalid"
        }
    ],
    "documentation_url": "https://api.telemetron.ru/doc/creating_models"
}

Response-error scheme

message : number - Error text
errors : array optional - Array of additional data (optional)
documentation_url : string optional - reference to documentation section (optional)
subcode : string optional - error code according to internal classification (optional)

Time stamps (time specifications)

Timestamps (timestamps) are indicated in a standard format ISO-8601: YYYY-MM-DDTHH:mm:ss+-HH:hh

Currently, the default time zone is +03:00, but it is implied that time stamps will always be specified in UTC (YYYY-MM-DDTHH:mm:ssZ).

Time display and setting according to the time zone of the client device is the task of the client.

Authorization ¶

OAuth entry-point is:

https://api.telemetron.net/auth

To gain an access_token, client must make POST to provided URL and set parameters:

grant_type - Type of authentication. “password”, “auth_code” and “refresh_token” are supported.
client_id - Client ID
client_secret - Client secret
scope - Authorization scope. Optional, defaults to teleport.
username - User name to authenticate (when using password grant type).
password - User password to authenticate (when using password grant type).

Teleport mobile app should use “password” grant type and “teleport” scope.

These parameters can be either in query string OR as a body of request in JSON format.

If JSON is provided, Content-Type: application/json header must be set.

Access token ¶

POST https://api.telemetron.net//auth/

Requestsexample 1

Body

{
  "grant_type": "password",
  "client_id": "devclient-key",
  "client_secret": "KHGdkgfKSGufgvduykdgvc",
  "scope": "teleport",
  "username": "me@example.com",
  "password": "123456"
}

Schema

{
  "type": "object",
  "properties": {
    "grant_type": {
      "type": "string",
      "description": "Access token grant type"
    },
    "client_id": {
      "type": "string",
      "description": "Client ID"
    },
    "client_secret": {
      "type": "string",
      "description": "Client secret"
    },
    "scope": {
      "type": "string",
      "description": "Desired scope for access token"
    },
    "username": {
      "type": "string",
      "description": "User to authenticate"
    },
    "password": {
      "type": "string",
      "description": "User's password"
    }
  },
  "required": [
    "grant_type",
    "client_id",
    "client_secret"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Responses200400

Headers

Content-Type: application/json

Body

{
    token_type: "Bearer",
    expires_in: 86400,
    access_token: "ltdfQ.UPD8g-wYflaxOLd4.AH6ZqYAYXj",
    refresh_token: "def502001afef98...12252c90038a67cf"
}

This response has no content.

Get new access token
POST`/auth/`

Logout ¶

In general, application or client logout is not required. Applications should only delete active access token from their storage and not use it in futher work.

Anyway, there is a way to force access_token to expire prematurely. In this case, API server also have an ability to stat such logout and make some additional work or calculations. So, logging out is more preffered than doing nothing or waiting access_token to expire in its natural way.

https://api.telemetron.net/logout

GET https://api.telemetron.net//logout

Responses200

Headers

Content-Type: application/json

Body

{
  "bye": "bye"
}

Logout and expire token
GET`/logout`

Definitions ¶

Vending Machine (VendingMachine)

Vending machine (VM) - is one of key concepts when working with Telemetron.

A vending machine has:

Number. It is a string which consists of a prefix “T” (capital English t) and its id. For instance, “T1230”.
Name.
Planogram (optional).
Type (optional).
Location site (optional).

Attributes

id : number - VM id. VM Number - prefix “Т”+id. For instance, T1234.
name : string - VM name
planogram_id : number - planogram id
state : number - VM operating state
service : object (no_recent_sales, low_change, need_loading) - service flags of VM (aka service state)
type : VendingMachineType (id, label, name)*
Location : Location (id, name, address) - VM location site

VM Types

A vending machine can be just one of these types.

#	label	description
1	coffee	coffee
2	snack	snacks
3	combo	combined
4	other	other
5	paired	paired
6	can	can

Attributes

id : number - type id
label : string - label (in English)
name : string - type description

VM states

VM state is described with two parameters: its operating state, which reflects the physical state of a VM and modem, and service state - a set of flags, reflecting logical state of a VM.

Operating state is specified by a number in state attribute:

#	description
null or 0	unknown - modem has not sent data yet
1	operating
2	out of service
3	no GSM connection

Service state is set to the true value of the corresponding object property in service attribute:

property	description
low_change	Low change
need_loading	Product refill needed
no_recent_sales	No recent sales

These two state types are not conflicting. A vending machine might need product loading, and at the same time it continues operating.

Location (Location)

Each VM may correspond to the location site. This additional VM-related information might not be indicated.

Each location is described with a name and an optional address.

Planogram (Planogram)

Planogram - is a concept combining recipes and products, as well as additional settings that characterize the range that a VM can sell. An approximate analogy - a restaurant menu.

Ingredient – is an integral part of the recipe. For example, coffee beans, water, stirrer.

Recipe – is what is sold in a VM and consists of ingredients. For example, “espresso” - is a recipe, consisting of water, coffee, a cup and a stirrer.

Mainly used in coffee machines.

Product – is what is sold in a vending machine and does not include ingredients. For example, a chocolate bar.

Simply put

Vending machine can sell both chocolate bars (we call them products), and coffee-cocoa-tea (we also call them products, however, when needed, we clarify - that this is a recipe).

VM sells only products. The set and placement of these products are determined by the planogram.

Chocolate bar is an indivisible product. Coffee & tea are composite products, which consist of ingredients mix (sometimes we call them components).

However, it cannot be said that VMs can be loaded with forty chocolate bars or hundreds teas. Ingredients are loaded into a vending machine. And the current VM load also applies to ingredients. In case of chocolate bars, in order not to complicate work with the data, we define that it, as product, consists of one ingredient with the same name.

A vending machine is refilled with ingredients, and during sales spends ingredients.

In order not to get confused, all products are flagged composite. Composite products (aka recipes) such as coffee and tea - it is composite = true, chocolate bars - composite = false.

And from a different angle: ingredients, that are simple products like chocolate bars have flag is_product = true. Other ingredients, of which a recipe can be made - is_product = false.

Briefly and simply

Recipe Espresso = ground coffee (ingredient) + water (ingredient) + cup (ingredient) + stirrer (ingredient). Product Snickers = Snickers (ingredient, is_product=true). Planogram = product Espresso + product Snickers + … VM Refill = ingred1 ХХ units + ingred2 XY units + ingred3 XZ units + …

User ¶

Active user ¶

Returns information about the current logged in user.

Contains a current list of roles in particular (only roles, RBAC level 1).

GET https://api.telemetron.net//v2/me

Responses200

Headers

Content-Type: application/json

Body

{
  "id": 496
  "company_id": 165
  "first_name": "Sidor"
  "last_name": "Sidorov"
  "position": "Senior engineer of technical refurbishment department"
  "email": "s@example.com"
  "language_id": null
  "status": true
  "last_login": "2016-02-14T22:44:33"
  "phone": true
  "roles":
    [
      {
        "id": 3
        "name": "operator"
        "title": "Operator"
      }
    ]
}

Full information
GET`/v2/me`

Attributes

id : number - ingredient id
company_id : number - company id
email : string - Contact email address, same to login
phone : boolean - whether a user has left his phone number
first_name : string - Name
last_name : string - Surname
position : string - Position. As a rule, rarely indicated.
lang : string - User’s language (ISO-639-1)
status : boolean - Active user (true) or banned (false)
roles : Array of Roles - array of user roles
- id : number - role id
- name : string role label (always in English),
- title : string - short role description (l10n)

Modems ¶

Full list of modems ¶

Get the list of all modems, available to the current user.

GET https://api.telemetron.net//v2/modems

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": 1,
    "imei": "0000000000000000",
    "hw_version": null,
    "boot_version": null,
    "firmware": "3.32",
    "phone": "79999999999"
  },
  {
    "id": 2,
    "imei": "0000000000000001",
    "hw_version": "2.4",
    "boot_version": "4.4.12",
    "firmware": "3.32",
    "phone": "79999999998"
  },
]

Full list
GET`/v2/modems`

Attributes

Array of
- id : number - Modem ID
- imei: string - IMEI
- hw_version : string - Hardware version
- boot_version : string - Boot version
- firmware : string - Firmware version
- phone : string - Phone number

Modem ¶

GET https://api.telemetron.net//v2/modems/123

Responses200

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "imei": "IMEI",
  "hw_version": "Hardware version",
  "boot_version": "Boot version",
  "firmware": "Firmware version",
  "phone": "Phone number"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "imei": {
      "type": "string"
    },
    "hw_version": {
      "type": "string"
    },
    "boot_version": {
      "type": "string"
    },
    "firmware": {
      "type": "string"
    },
    "phone": {
      "type": "string"
    }
  }
}

Detailed information about modem
GET`/v2/modems/{id}`

URI Parameters

HideShow

id: number (required) Example: 123
Modem ID

PUT https://api.telemetron.net//v2/modems/123

RequestsName only

Body

{
  "phone": "79999999997"
}

Responses200422

Headers

Content-Type: application/json

Body

{
    "res" => true
}

Headers

Content-Type: application/json

Body

{
    "message" => "The given data was invalid.",
    "errors" => [
      "phone" => [
        "The phone may not be greater than 10 characters."
      ]
    ]
}

Change settings
PUT`/v2/modems/{id}`

Update settings of specified modem.

Available fields:

phone : string - Phone number, if using GSM network with SIM.

URI Parameters

HideShow

id: number (required) Example: 123
Modem ID

Vending machines ¶

VendingMachineType

id : number - id of type
label : string - label (in English)
name : string - description of type

id	label	description
1	coffee	coffee
2	snack	snack
3	combo	combined
4	other	other
5	paired	paired
6	can	can

VendingMachineState

#	description
null or 0	unknown - modem has not sent data yet
1	operating
2	out of service
3	no GSM connection

VendingMachineService

property	description
low_change	Low change
need_loading	Product refill needed
no_recent_sales	No recent sales
no_bills_in	No bills in
no_coins_in	No coins in

Location

id : number - id of location site
name : string - name of location
address : string - address

Полный список ТА ¶

Get the list of all VMs, available for a current user.

For administrators and senior operators the list of VMs is not limited, but for the operators the list is limited to those VMs, that belong to the groups assigned to the operator. It may happen that the user will not have a single TA available.

GET https://api.telemetron.net//v2/vending_machines

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": 929,
    "name": "Old lamp machine",
    "planogram_id": 289,
    "state": 1,
    "service": {
      "low_change": true,
      "no_recent_sales": true
    },
    "location": {
      "id": 692,
      "group_id": null,
      "name": "Svenskan Södermann",
      "address": "Sadovaya, 49"
    },
    "type": null,
    "imei": 999999999123456,
    "is_crt_active": false,
    "inventory_number": null
  },
  {
    "id": 928,
    "name": "Two-door with blue sticker",
    "planogram_id": 289,
    "state": 3,
    "service": null,
    "location": {
      "id": 691,
      "group_id": null,
      "name": "Restaurant At Bertolucco’s",
      "address": "Avtobusnoje motorway, 7"
    },
    "type": {
      "id": 1,
      "label": "coffee",
      "name": "coffee"
    },
    "imei": 999999999123459,
    "is_crt_active": false,
    "inventory_number": null
  },
]

Full list
GET`/v2/vending_machines`

Attributes

Array of
- id : number - VM id
- serial_number: string - Serial number of VM
- name : string - VM name
- planogram_id : number - planogram id
- state : number - VM operating state
- service : object (no_recent_sales, low_change, need_loading) - service flags of VM (aka service state)
- type : VendingMachineType (id, label, name) - VM type
- location : Location (id, name, address) - location of VM
- imei : string - IMEI of Telemetron modem installed in a VM
- is_crt_active : bool - Flag of data transmission into cloud cash register equipment
- inventory_number: string - Inventory number

Vending machine ¶

GET https://api.telemetron.net//v2/vending_machines/123

Responses200

Headers

Content-Type: application/json

Body

{
  "id": 123,
  "serial_number": "AAA0000",
  "name": "Test VM",
  "planogram_id": 123,
  "state": 1,
  "service": {
    "low_change": true,
    "need_loading": true,
    "no_recent_sales": true
  },
  "location": {
    "id": 123,
    "name": "Shopping Center Koffejnik",
    "address": "Turuhtannye ostrova road, 12"
  },
  "type": {
    "id": 123,
    "label": "coffee",
    "name": "coffee"
  },
  "modem": {
    "id": 123,
    "imei": "999999999123456",
    "bus": "exe",
    "sw_version": "4.4.42",
    "hw_version": "2.4"
  },
  "is_crt_active": true,
  "inventory_number": "B42"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "serial_number": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "planogram_id": {
      "type": "number"
    },
    "state": {
      "type": "number"
    },
    "service": {
      "type": "object",
      "properties": {
        "low_change": {
          "type": "boolean"
        },
        "need_loading": {
          "type": "boolean"
        },
        "no_recent_sales": {
          "type": "boolean"
        }
      }
    },
    "location": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "name": {
          "type": "string"
        },
        "address": {
          "type": "string",
          "description": "Address of location site"
        }
      }
    },
    "type": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "id of VM type"
        },
        "label": {
          "type": "string",
          "description": "VM type (label in English)"
        },
        "name": {
          "type": "string",
          "description": "Description"
        }
      },
      "description": "VM type"
    },
    "modem": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "modem id"
        },
        "imei": {
          "type": "string",
          "description": "IMEI"
        },
        "bus": {
          "type": "string",
          "description": "Type of payment bus (EXE, MDB, null)"
        },
        "sw_version": {
          "type": "string",
          "description": "Firmware version"
        },
        "hw_version": {
          "type": "string",
          "description": "Hardware version"
        }
      },
      "description": "installed Telemetron modem"
    },
    "is_crt_active": {
      "type": "boolean"
    },
    "inventory_number": {
      "type": "string"
    }
  }
}

Detailed information about VM
GET`/v2/vending_machines/{id}`

Attributes

id : number - VM id
serial_number: string - Serial number of VM
name : string - VM name
planogram_id : number - planogram id
state : number - VM operating state
service : array (no_recent_sales, low_change, need_loading) - service flags of VM (aka service state)
type : VendingMachineType (id, label, name) - VM type
location : Location (id, name, address) - location of VM
modem : Modem (id, imei, bus, sw_version, hw_version) - Telemetron modem installed in a VM
is_crt_active : bool - Flag of data transmission into cloud cash register equipment
inventory_number: string - Inventory number

URI Parameters

HideShow

id: number (required) Example: 123
VM ID
force: bool (optional) Example: 1
Forced modem assignment to a VM

POST https://api.telemetron.net//v2/vending_machines

VM setup
POST`/v2/vending_machines`

When setting up a new VM, it is necessary to specify its model from the directory (/v2/vm_models). If the required model is not in the list, then mm_id = 52 can be used (“model not specified” or “not in the list”).

A modem can be specified by ID (modem_id) or by IMEI (imei).

If force parameter is specified, a modem will be unassigned from an old VM and assigned to this one.

Attributes for setting up a VM

name : string, required - VM name

PUT https://api.telemetron.net//v2/vending_machines/123?force=1

RequestsName onlyGroup of fields

Body

{
  "name": "New VM name"
}

Responses200422

Headers

Content-Type: application/json

Body

{
    "res" => true
}

Headers

Content-Type: application/json

Body

{
    "message" => "The given data was invalid.",
    "errors" => [
      "name" => [
        "The name may not be greater than 255 characters."
      ]
    ]
}

Body

{
  "name": "New VM name",
  "mm_id": 1,
  "serial_number": "New serial number of a VM",
  "modem_id": 42
}

Responses200422

Headers

Content-Type: application/json

Body

{
    "res" => true
}

Headers

Content-Type: application/json

Body

{
    "message" => "The given data was invalid.",
    "errors" => [
      "name" => [
        "The name may not be greater than 255 characters."
      ]
    ]
}

Change of VM
PUT`/v2/vending_machines/{id}{?force}`

Data update of a certain VM.

Available fields:

name : string - VM name
mm_id, required : number` - Model of VM (ID from vm_models directory)
serial_number : string - Serial number of VM
planogram_id : number, optional - Planogram
location_id : number, optional - location site
modem_id : number, optional - Modem ID
imei : number, optional - IMEI of a modem
is_crt_active : bool, optional - Flag of data transmission into cloud cash register equipment
inventory_number: string, optional - Inventory number

If planogram_id attribute is set, a new planogram will be assigned to the specified VM.

If another planogram was previously assigned to a VM and any load was indicated, then all products on vending machine spirals, that are not present in the new planogram, will be automatically unloaded with a record in the history of changes (same logic that works in the Dashboard when the planogram of a VM is changed in the settings).

A modem can be specified by ID (modem_id) or by IMEI (imei).

If force parameter is specified, the modem will be unassigned from an old VM and assigned to this one.

URI Parameters

HideShow

id: number (required) Example: 123
VM id
force: bool (optional) Example: 1
Forced modem assignment to a VM

GET https://api.telemetron.net//v2/vending_machines/123/events?since=2018-01-01T00:00:00+03:00&until=2018-01-02T00:00:00+03:00

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "date": "2018-10-09T00:59:48+03:00",
    "code": "TEVA",
    "payload": null
  },
  {
    "date": "2018-10-09T01:59:48+03:00",
    "code": "TEVA",
    "payload": null
  }
]

Events
GET`/v2/vending_machines/{vm_id}/events{?since,until}`

List of VM events.

Maximum available period is 7 days. Maximum available sampling depth is 14 days.

Available fields:

date : string - Date
code: string - Event code (see directory)
payload : array - Event metadata

URI Parameters

HideShow

vm_id: number (required) Example: 123
VM ID
since: string (optional) Example: 2018-01-01T00:00:00+03:00
Start of period (included)
until: string (optional) Example: 2018-01-02T00:00:00+03:00
End of period (included)

GET https://api.telemetron.net//v2/vending_machines/123/reports?since=2018-01-01T00:00:00+03:00&until=2018-01-02T00:00:00+03:00&cp1251=1&base64=1&port=1

Responses200

Headers

Content-Type: application/json

Body

[
    {
      "date": "2016-09-27T00:01:38+03:00",
      "data": "DXS*NRI C2    *VA*V1/1*1\r\ ... E*1*1\r\n",
      "evadts_port": 1
    }
  ]

Reports
GET`/v2/vending_machines/{vm_id}/reports{?since,until,cp1251,base64,port}`

EVA-DTS reports unloading.

Maximum available period is 14 days. Maximum available sampling depth is 14 days.

Available fields:

date : string - Date
data: string - Body of the report
evadts_port : string - Port

URI Parameters

HideShow

vm_id: number (required) Example: 123
VM ID
since: string (optional) Example: 2018-01-01T00:00:00+03:00
Start of period (included)
until: string (optional) Example: 2018-01-02T00:00:00+03:00
End of period (included)
port: number (optional) Example: 1
Optional parameter indicating number of the port (2-DEX)
cp1251: number (optional) Example: 1
Optional flag, body of the report data will be in Windows-1251 encoding
base64: number (optional) Example: 1
Optional flag, body of the report data will be packed in BASE64

Current load level of a VM ¶

Current level of vending machine ingredients’ load.

For ingredients that denote product (e.g., chocolate bar, water bottle), an additional field layout_number is specified. This field contains the number of the spiral/product item in the VM, to which the loading number belongs.

So, if a chocolate bar in a VM is located on several spirals, then the response will contain several records for the same component_id with a different load value for each of the spirals (planogram.layout).

For ingredients that make up recipe (for example, cream, sugar), spiral number is meaningless, so the value of layout_number field is not specified.

The situation when the current level of any component in VM is bigger than maximum load value, specified in the settings of the associated planogram, is normal.

Maximum load in the settings of VM is not the absolute maximum threshold, but rather a basis for calculations.

GET https://api.telemetron.net//v2/vending_machines/123/loading

Responses200

Headers

Content-Type: application/json

Body

[
  {
    component_id: 1,
    value: 0
  },
  {
    component_id: 2,
    value: 180
  },
  {
    component_id: 100,
    value: 10,
    layout_number: 'A1'
  },
  {
    component_id: 100,  /* same product, as above, but on a different spiral! */
    value: 0,
    layout_number: 'A2'
  },
]

Current loading of a VM
GET`/v2/vending_machines/{id}/loading`

Attributes

Array of
- component_id : number - component id
- value : number - current level of component load (in its unit of measurement)
- layout_number : string - number of spiral/product line for a product

URI Parameters

HideShow

id: number (required) Example: 123
VM ID

POST https://api.telemetron.net//v2/vending_machines/123/loading

Requestsexample 1example 2example 3

Body

{
  "data": [
    {
      component_id: 1,
      add: 10
    },
    {
      component_id: 2,
      add: 18
    },
    {
      component_id: 100,
      add: 18000
    },
    {
      component_id: 101,
      add: -2000
    },
  ],
  "note": "Comment to refill"
}

Responses201400

Headers

Content-Type: application/json

Body

{
  "digest" : <digest of operation>
}

Headers

Content-Type: application/json

Body

{
  "message": "Duplicate",
  "subcode": "L102"
}

Body

{
  "data": [],
  "note": "Comment to refill"
}

Responses400

Headers

Content-Type: application/json

Body

{
  "message": "Not enough data",
  "subcode": "L103"
}

Body

{
  "data": [
    {
      "component_id": 123,
      "add": 0
    }
  ],
  "note": "Comment to refill"
}

Responses400

Headers

Content-Type: application/json

Body

{
  "message": "Not enough data (no load)",
  "subcode": "L104"
}

Do VM refill
POST`/v2/vending_machines/{id}/loading`

Request body

data: Array of
- component_id : number - component id
- layout_number : string - number of spiral, if refill of product is specified. For ingredient the parameter should be equal to null or should not be present.
- add : number - change of component load in its unit of measurement. If positive, the component has been refilled, if negative, the component has been unloaded.
note: string - comment to refill
created_at: timestamp - time of refill (if not specified, it will be equal to the time of record in the database)

URI Parameters

HideShow

id: number (required) Example: 123
VM ID

Inventory control ¶

POST https://api.telemetron.net//v2/vending_machines/123/inventory

Requestsexample 1example 2example 3

Body

{
  "data": [
    {
      "component_id": 1,
      "loaded": 10
    },
    {
      "component_id": 2,
      "loaded": 18
    },
    {
      "component_id": 100,
      "loaded": 18000
    },
    {
      "component_id": 101,
      "loaded": -2000
    },
  ],
  "note": "Comment for inventory control"
}

Responses201400

Headers

Content-Type: application/json

Body

{
  "digest" : <digest of operation>
}

Headers

Content-Type: application/json

Body

{
  "message": "Duplicate",
  "subcode": "L102"
}

Body

{
  "data": [],
  "note": "Comment for inventory control"
}

Responses400

Headers

Content-Type: application/json

Body

{
  "message": "Not enough data",
  "subcode": "L103"
}

Body

{
  "data": [
    {
      "component_id": 123
    }
  ],
  "note": "Comment for inventory control"
}

Responses422

Headers

Content-Type: application/json

Body

{
  "message": "The given data was invalid.",
  "errors": {
    "data.0.loaded": [
      "The data.0.loaded field is required."
    ]
  }
}

Inventory control
POST`/v2/vending_machines/{id}/inventory`

Indicate the current level of vending machine ingredients load.

For ingredients that denote a product (for example, a chocolate bar, a bottle of water), an additional field layout_number is specified. This field contains the number of a spiral/number of the product item in a VM, with which refill number is associated.

So, if a chocolate bar is located on several spirals of a VM, then in the query it is needed to write several records for the same component_id with a different load value for each of the spirals (planogram.layout).

For ingredients that make up a recipe (for example, cream, sugar), the number of spiral is meaningless, so the value of layout_number field is not specified.

For ingredients which have not been indicated in a query, we take it that a load value is equal to Dashboard data.

Attributes for setting up a VM

data: Array of
- component_id : number - component id
- layout_number : string - number of spiral, if inventory control of a product is held. For an ingredient the parameter should be equal to null or should not be present.
- loaded : number - loaded amount of a component in its units of measurement
note: string - comment to inventory control
created_at: timestamp - time of inventory control (if not indicated, in the Dashboard it will be equal to the time of record in the database)

URI Parameters

HideShow

id: number (required) Example: 123
VM ID

Information request from VM ¶

POST https://api.telemetron.net//v2/vending_machines/123/request

Requestsexample 1

Body

{
  "report": true
}

Responses200

Headers

Content-Type: application/json

Body

{
  "request_id": 17543,
  "progress": true
}

Request data
POST`/v2/vending_machines/{vm_id}/request`

To request any data from a vending machine, in the request you should specify an attribute with any value, which will indicate the type of the relevant data.

Currently there are two types of relevant data available: a report and a config file.

“Report” means that during the next ping, the modem will have to remove and send the EVADTS-report from a vending machine. Based on this report, the current information of the vending machine will be updated later: number/amount of sales, load, …

Attributes

report : boolean - request modem reporting
config : boolean - request configuration parameters of the modem

Since the process of requesting and receiving a response at the moment is hardly controllable and can take a long time, the biggest part of the logic should be implemented by the client application.

The response must contain a request id. Attribute progress: true can also be specified, which indicates that right now a vending machine already has a request of the specified type.

From the viewpoint of server, a request to a vending machine is one object that combines boolean attributes, which describe current “requirements” of the request. So, at the same moment of time, “report request” and “config request” can both be relevant - and in this case, request_id will be the same.

This may show up as

POST {"report": true } -> 200 {"request_id": 17543}
POST {"config": true } -> 200 {"request_id": 17543} /* same request_id */

A request for a vending machine that does not have an associated modem is meaningless and will return an error.

URI Parameters

HideShow

vm_id: number (required) Example: 123
VM ID

GET https://api.telemetron.net//v2/vending_machines/123/request/17543

Responses200404

Headers

Content-Type: application/json

Body

{
  "progress": true
}

Headers

Content-Type: application/json

Body

{
  "message": "Not found"
}

Data request progress
GET`/v2/vending_machines/{vm_id}/request/{id}`

Using the existing request_id it is possible to check the status of the request for receiving data from a vending machine.

If a specified identifier finds a request to receive data (response 200), this means, that this request is still being executed, and no new data has been received from a VM yet.

If by the specified request_id there are no records (response 404), then this VM data request has already been completed, and the required data can be obtained by a corresponding API call (for example, /vending_machines/:id/reports/last for EVA-DTS reports)

URI Parameters

HideShow

vm_id: number (required) Example: 123
VM ID
id: number (required) Example: 17543
Request ID

GET https://api.telemetron.net//v2/vending_machines/123/reports/827323?cp1251=1&base64=1&port=1

Responses200404

Headers

Content-Type: application/json

Body

{
    "date": "2016-09-27T00:01:38+03:00",
    "data": "DXS*NRI C2    *VA*V1/1*1\r\ ... E*1*1\r\n",
    "evadts_port": 1
}

Headers

Content-Type: application/json

Body

{
  "message": "Not found"
}

EVA-DTS. Report
GET`/v2/vending_machines/{vm_id}/reports/{id}{?cp1251,base64,port}`

Obtaining EVA-DTS report by its number.

If 2-DEX is used, the response in evadts_port attribute will indicate a port number, from which the report has been received. If 2-DEX is not used, evadts_port equals 1 or null.

To obtain latest valid report, instead of ID report last_valid can be specified: /vending_machines/{vm_id}/reports/last_valid

To obtain latest report regardless of validation, instead of ID report it is possible to specify last: /vending_machines/{vm_id}/reports/last

Reports, obtained more than 14 days ago, are not found in search.

URI Parameters

HideShow

vm_id: number (required) Example: 123
VM ID
id: number, string (required) Example: 827323
report ID, or last
port: number (optional) Example: 1
Optional parameter, indicating port number (2-DEX)
cp1251: number (optional) Example: 1
Optional flag, body of report data will be coded at Windows-1251
base64: number (optional) Example: 1
Optional flag, body of report data will be packed in BASE64

GET https://api.telemetron.net//v2/vending_machines/123/timestamp

Responses200

Headers

Content-Type: application/json

Body

{
  last_sale: "2015-12-22T12:09:20+03:00",
  last_service: "2015-09-01T11:15:53+03:00",
  last_collection: "2015-09-01T11:15:16+03:00",
  last_loading: "2016-03-18T21:38:18+03:00",
  last_report: "2015-12-22T12:09:20+03:00",
  last_acquired_report: "2016-01-02T09:12:44+03:00",
}

Event time
GET`/v2/vending_machines/{id}/timestamp`

This resource provides a list of relevant timestamps for various VM events, that can be used for calculating data relevance, cache, need in requests and so on.

Timestamps are designated in a special format ISO-8601 (YYYY-MM-DDTHH:mm:ss+-HH:hh). At this moment it is not supported (time zone +3 by default), but implied, that timestamps are designated in UTC (YYYY-MM-DDTHH:mm:ss+00:00).

During data processing it is necessary to fetch the timezone and check it in parsing process.

If any timestamp is not known, or an event has not yet occurred, the value of this parameter will be null.

Attributes

last_sale : string - time of last sale;
last_service : string - time of last VM service;
last_collection : string - time of last VM cash collection;
last_loading : string - time of recent ingredient refill;
last_report : string - time of recent valid report received from a VM;
last_acquired_report : string - time of last report, independently of whether the report has been validated or not;

URI Parameters

HideShow

id: number (required) Example: 123
VM ID

Event directory ¶

GET https://api.telemetron.net//v2/event_codes

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "code": "EA",
    "name": "Coin Mechanism",
    "desc": "COIN MECHANISM: General non-specific Coin Mechanism fault."
  },
  {
    "code": "EA1A",
    "name": "Cassette Removed",
    "desc": "COIN MECHANISM: The coin storage cassette has been removed unexpectedly."
  }
]

Event directory
GET`/v2/event_codes`

Attributes

code : string - unique event identifier
name : string - name
desc : string - comment

Event directory ¶

GET https://api.telemetron.net//v2/vm_models

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": 1,
    "name": "Bianchi BVM 676"
  },
  {
    "id": 2,
    "name": "Necta Kikko Max"
  }
]

Directory of VM models
GET`/v2/vm_models`

Attributes

id : number - model id
name : string - full model name

Sales statistics ¶

Depending on a model and version of its software, as well as equipment installed, VM can register sales with different levels of detail.

Therefore, it is possible that during the same time period sales statistics and product details are absent, but the total statistics is non-zero.

The default time range is current day.
Maximum length of sample range is 31 days.

::: info Available statistics does not exceed two months. :::

Total statistics ¶

GET https://api.telemetron.net//v2/stats/vends/summary?since=2018-01-01 00:00:00+03&until=2018-01-07 00:00:00+03

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "number": 255,
    "value": 869500
  }
]

Total statistics
GET`/v2/stats/vends/summary{?since,until}`

Total sales statistics (number of sales, sum) for the particular period; detailed data on products and grouping by vending machines are excluded.

Maximum length of sample range is 7 days.

URI Parameters

HideShow

since: string (optional) Example: 2018-01-01 00:00:00+03
Start of period (included)
until: string (optional) Example: 2018-01-07 00:00:00+03
End of period (included)

Total VM statistics ¶

GET https://api.telemetron.net//v2/vending_machines/123/stats/vends/summary?since=2018-01-01 00:00:00+03&until=2018-02-01 00:00:00+03

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "number": 255,
    "value": 869500
  }
]

Total VM statistics
GET`/v2/vending_machines/{id}/stats/vends/summary{?since,until}`

Total sales statistics (number of sales, sum) for the particular period in VM, detailed data on products and grouping by vending machines is excluded.

URI Parameters

HideShow

id: number (required) Example: 123
VM ID
since: string (optional) Example: 2018-01-01 00:00:00+03
Start of period (included)
until: string (optional) Example: 2018-02-01 00:00:00+03
End of period (included)

Sales by products ¶

GET https://api.telemetron.net//v2/vending_machines/123/stats/vends/products?type=paid&since=2018-01-01T00:00:00+03:00&until=2018-02-01T00:00:00+03:00

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "time": "2018-01-10T12:59:16+03:00",
    "layout_number": "2",
    "name": "Americano 8",
    "vend_type": 3,
    "price": 35,
    "number": 2,
    "value": 70
  },
  {
    "time": "2018-01-11T14:45:00+03:00",
    "layout_number": "3",
    "name": "Coffee with milk",
    "vend_type": 3,
    "price": 35,
    "number": 1,
    "value": 35
  }
]

Sales by products
GET`/v2/vending_machines/{id}/stats/vends/products{?type,since,until}`

Sales statistics for a period with detailed product description.

URI Parameters

HideShow

id: number (required) Example: 123
VM ID
type: enum(paid, free, test) (optional) Example: paid
Type of vend
since: string (optional) Example: 2018-01-01T00:00:00+03:00
Start of period (included)
until: string (optional) Example: 2018-02-01T00:00:00+03:00
End of period (included)

Sales by products and payments ¶

GET https://api.telemetron.net//v2/vending_machines/123/stats/vends/payments?type=paid&since=2018-01-01T00:00:00+03:00&until=2018-02-01T00:00:00+03:00

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "time": "2018-01-10T12:59:16+03:00",
    "layout_number": "2",
    "name": "Americano 8",
    "payment_type": 1,
    "price": 35,
    "number": 2,
    "value": 70
  },
  {
    "time": "2018-01-10T12:59:16+03:00",
    "layout_number": "3",
    "name": "Coffee with milk 8+4.93",
    "payment_type": 1,
    "price": 35,
    "number": 1,
    "value": 35
  }
]

Sales by products and payments
GET`/v2/vending_machines/{id}/stats/vends/payments{?type,since,until}`

Sales statistics for a period with details on product and payment types (cash, cashless, tokens).

URI Parameters

HideShow

id: number (required) Example: 123
VM ID
type: enum(cash, cashless, token) (optional) Example: paid
Type of payment
since: string (optional) Example: 2018-01-01T00:00:00+03:00
Start of period (included)
until: string (optional) Example: 2018-02-01T00:00:00+03:00
End of period (included)

Receipts from cloud cash register equipment ¶

GET https://api.telemetron.net//v2/stats/fiscal?vm_id=123?since=2018-01-01T00:00:00+03:00&until=2018-02-01T00:00:00+03:00

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": 1000042,
    "vm_id": 12345,
    "fiscal": {
      "fp": "123456789",
      "id": "fc8950b5a4c3cb1456ad203a2dca9395",
      "change": 0,
      "ofdinn": "1234567890",
      "content": {
        "type": 1,
        "positions": [
          {
            "tax": 6,
            "text": "Crisps \"Russian potato\"",
            "price": 130,
            "quantity": 1,
            "paymentMethodType": 4,
            "paymentSubjectType": 1
          }
        ],
        "checkClose": {
          "payments": [
            {
              "type": 1,
              "amount": 130
            }
          ],
          "taxationSystem": 0
        },
        "automatNumber": "T12345",
        "customerContact": "example@example.com",
        "settlementPlace": "SPb, Nameless Str., 123",
        "settlementAddress": "VM at the entrance"
      },
      "ofdName": "ООО \"Yarus\" (\"OFD-YA\")",
      "deviceRN": "0000000000028583",
      "deviceSN": "0372340028000334",
      "fsNumber": "9999078900006831",
      "companyINN": "7805629524",
      "fnsWebsite": "www.nalog.ru",
      "ofdWebsite": "www.ofd-ya.ru",
      "companyName": "LLC DELORIAN",
      "processedAt": "2018-08-22T18:07:00",
      "shiftNumber": 1,
      "documentIndex": 80,
      "documentNumber": 82
    },
    "fiscal_at": "2018-08-22 18:07:33+03",
    "created_at": "2018-08-22 18:03:40+03",
    "aux": {
      "vm_inventory_number": "ABC-0123",
      "product_inventory_number": "ABC-0123"
    }
  }
]

Receipts from cloud cash register equipment
GET`/v2/stats/fiscal{?vm_id}{?since,until}`

Statistics on receipts from cloud cash register equipment.

Directory of values for some receipt attributes

content.type - Type of payment method

Income
Income refund
Expenditure
Expenditure refund

content.positions.*.quantity - Quantity

content.positions.*.tax - VAT rate

VAT rate 18%
VAT rate 10%
Calculated VAT rate 18/118
Calculated VAT rate 10/110
VAT rate 0%,
No VAT

content.positions.*.paymentMethodType - Type of payment method (always equals 4 - full payment)

content.positions.*.paymentSubjectType - Type of payment subject (always equals 1 - product)

content.checkClose - Receipt close, list of payments by payment type

content.checkClose.taxationSystem - Taxation system

General tax system
Simplified income, Simplified tax system income
Simplified income less expenditure
Unified tax on imputed income
Unified agricultural tax
Patent tax system, Patent

content.checkClose.payments.*.type - Payment type

Sum of receipt cash
Sum of online receipt

URI Parameters

HideShow

vm_id: number (optional) Example: 123
VM ID
since: string (optional) Example: 2018-01-01T00:00:00+03:00
Start of period (included)
until: string (optional) Example: 2018-02-01T00:00:00+03:00
End of period (included)

Planograms ¶

A planogram is a set of products and recipes related to a vending machine. As a rule, a planogram contains only composite products (recipes), if it relates to coffee machines. Or, it contains only simple products, if it relates to snack machines.

However, it is possible that a VM may contain both products and recipes (VM - combined or coupled).

Additionally, a VM contains such data as capacity and components load par level, as well as product items, the so-called layout of products in a VM (i.e. which products correspond to which numbers of spirals and buttons).

CapacityItem Capacity and load par level.

For any ingredient capacity may not be specified at all.

component_id : number - ingredient id
capacity : number - max. capacity of ingredient (in the units of measurement of an ingredient)
critical : number - ingredient load par level (may not be specified)

ProductsArray List of products, making up a planogram.

Array of
- id : number - product id
- components : array - list of components
  - id : number - component id
  - volume : number - volume/number of a component in its units of measurement

ProductLayout Conformity of products to product items (numbers of buttons, spirals).

Array of
- product_id : number - product id
- number : string - name of spiral or button number

Full list ¶

Get the list of all planograms from company’s personal Dashboard.

By default, just a list with names is shown. With a full parameter, detailed info on the content of a planogram will be added in a response. It is useful during initial synchronization/compilation of directories, so as not to drag resource / planograms/{id} in the loop.

GET https://api.telemetron.net//v2/planograms?full=1

Requests?full=1

Body

?full=1

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": 1267
    "name": "Universal’naya 42",
    "capacity": [
        {
           "component_id": 1,
           "capacity": 19000,
           "critical": null
        },
        {
          "component_id": 2,
          "capacity": 3000,
          "critical": 90
        },
        {
          "component_id": 3,
          "capacity": 500,
          "critical": 50
        }
      ],
      "products": [
        {
          id: 1,
          components: [
            {
              id: 1,
              volume: 125
            },
            {
              id: 2,
              volume: 6
            },
            {
              id: 3,
              volume: 1
            },
            {
              id: 4,
              volume: 5
            },
            {
              id: 5,
              volume: 1
             }
          ]
        },
        {
          id: 900,
          components: [
            {
              id: 100,
              volume: 1
            }
          ]
        }
      ],
      "layout": [
        {
          product_id: 1,
          number: "1"
        },
        {
          product_id: 900,
          number: "AA"
        },
        {
          product_id: 900,
          number: "AB"
        },
        {
          product_id: 900,
          number: "AC"
        }
      ]
  },
  {
    "id": 1265
    "name": "Planogram for new VMs",
    "capacity": [
        {
           "component_id": 21,
           "capacity": 10,
           "critical": null
        },
        {
          "component_id": 22,
          "capacity": 30,
          "critical": 2
        },
        {
          "component_id": 23,
          "capacity": 100,
          "critical": 50
        }
      ],
    "products": [
        {
          id: 21,
          components: [
            {
              id: 101,
              volume: 1
            }
          ]
        },
        {
          id: 22,
          components: [
            {
              id: 100,
              volume: 1
            }
          ]
        },
        {
          id: 23,
          components: [
            {
              id: 103,
              volume: 1
            }
          ]
        }
      ],
    "layout": [
        {
          product_id: 21,
          number: "A1"
        },
        {
          product_id: 21,
          number: "A2"
        },
        {
          product_id: 22,
          number: "B1"
        },
        {
          product_id: 23,
          number: "C1"
        }
      ]
  },
  {
    "id": 1513
    "name": "Unempty bootless"
  }
]

Full list
GET`/v2/planograms{?full}`

Attributes

Array of
- id : number - planogram id
- name : string - name of planogram

URI Parameters

HideShow

full: boolean (optional) Example: 1
whether detailed info on planogram content (layout, capacity, products) should be added in the response.

A planogram ¶

GET https://api.telemetron.net//v2/planograms/123

Responses200

Headers

Content-Type: application/json

Body

{
  "id": 1267
  "name": "Universal’naya 42"
  "capacity": [
    {
       "component_id": 1,
       "capacity": 19000,
       "critical": null
    },
    {
      "component_id": 2,
      "capacity": 3000,
      "critical": 90
    },
    {
      "component_id": 3,
      "capacity": 500,
      "critical": 50
    }
  ],
  "products": [
    {
      id: 1,
      components: [
        {
          id: 1,
          volume: 125
        },
        {
          id: 2,
          volume: 6
        },
        {
          id: 3,
          volume: 1
        },
        {
          id: 4,
          volume: 5
        },
        {
          id: 5,
          volume: 1
         }
      ]
    },
    {
      id: 900,
      components: [
        {
          id: 100,
          volume: 1
        }
      ]
    }
  ],
  "layout": [
    {
      product_id: 1,
      number: "1"
    },
    {
      product_id: 900,
      number: "AA"
    },
    {
      product_id: 900,
      number: "AB"
    },
    {
      product_id: 900,
      number: "AC"
    }
  ]
}

Detailed information about planogram
GET`/v2/planograms/{id}`

Information of the “capacity” of ingredients (max. capacity and load par level) is also included, as well as the list of all products/recipes making up a planogram.

Attributes

id : number - Planogram id
name : string - Name
capacity : array of CapacityItem - Capacity of ingredients
products : ProductsArray - Product Array (recipes)
layout : ProductLayout - Product Layout

URI Parameters

HideShow

id: number (required) Example: 123
VM ID

POST https://api.telemetron.net//v2/planograms

RequestsSet upSet up and assignment to a VM

Body

{
  "name": "New planogram",
  "mode": "snack",
  "products": [
    {
      "id": 2230,
      "number": 2,
      "capacity": 14
    },
    {
      "id": 2218,
      "number": 3,
      "capacity": 88
    },
    {
      "id": 2243,
      "number": "4A",
      "capacity": 11
    }
  ]
}

Responses201422

Headers

Content-Type: application/json

Body

{
  "res": true,
  "resource": {
    "id": 42
  }
}

Headers

Content-Type: application/json

Body

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name has already been taken."
    ]
  }
}

Body

{
  "name": "New planogram for a VM",
  "mode": "snack",
  "assign": 10042,
  "products": [
    {
      "id": 2230,
      "number": 2,
      "capacity": 14
    },
    {
      "id": 2218,
      "number": 3,
      "capacity": 88
    }
  ]
}

Responses201422

Headers

Content-Type: application/json

Body

{
  "res": true,
  "resource": {
    "id": 42
  }
}

Headers

Content-Type: application/json

Body

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name has already been taken."
    ]
  }
}

New planogram
POST`/v2/planograms`

Currently, only one planogram set up mode is supported - snack. In this mode, name and list of products are set up.

Attributes

name: string, required - Name
mode: enum[snack, basic], required - Mode of planogram set up
assign: number, optional - Number of VM
products: array of
- id: number, required - Product ID
- number: string, required - Number of button, spiral, cell or shelf, where a product is located
- capacity: number, required - Ingredient capacity
- critical: number, optional - Par level

If assign attribute is set up, a new planogram will be assigned to the specified VM.

If a planogram was previously assigned to a VM and any load was specified, then all products on spirals, that are not in the new planogram, will be automatically unloaded with a record in the history of changes (same logic that works in the personal Dashboard when a VM planogram is changed).

DELETE https://api.telemetron.net//v2/planograms/123

Responses200

Headers

Content-Type: application/json

Body

{
  "res": true
}

Planogram removal
DELETE`/v2/planograms/{id}`

If a planogram is assigned to one or several vending machines, then for each machine the unloading of current load level will be carried out with a record in the history of unloading.

URI Parameters

HideShow

id: number (required) Example: 123
Planogram ID

Products ¶

Basically, this resource is needed when synchronizing data once before the app starts or when cache expires.

Calculations are based on app cache, so there is no need in resource /products/{id}.

GET https://api.telemetron.net//v2/products

Responses200

Headers

Content-Type: application/json

Body

[
  {
    id: 1932,
    composite: true,
    name: "Creamy nut mocha",
    components: [
      {
        volume: 114,
        id: 1547
      },
      {
        volume: 1,
        id: 1548
      },
      {
        volume: 1,
        id: 1549
      },
      {
        volume: 7,
        id: 1550
      },
      {
        volume: 17,
        id: 1554
      },
      {
        volume: 5,
        id: 1555
      }
    ],
    inventory_number: "B1-2018"
  },
  {
    id: 1933,
    composite: true,
    name: "Empty cup",
    components: [
      {
      volume: 1,
        id: 1548
      }
    ],
    inventory_number: "B2-2018"
  },
  {
    id: 22816,
    composite: false,
    name: "Bounty snack",
    components: [
      {
      volume: 1,
        id: 20839
      }
    ],
    inventory_number: "B3-2018"
  },
  {
    id: 22817,
    composite: false,
    name: "KitKat snack",
    components: [
      {
      volume: 1,
        id: 20840
      }
    ],
    inventory_number: "B4-2018"
  }
]

Full list
GET`/v2/products`

Directory of all products from company’s Dashboard.

Attributes

Array of
- id : number - product id
- name : string - name
- composite : boolean - whether a product is composite (i.e. recipe) or not
- components : Components - list of ingredients making up a product
- inventory_number : string - inventory number

Components

Array of
- id : number - ingredient id
- volume: number - volume/number of ingredient in its units of measurement

PUT https://api.telemetron.net//v2/products/123

RequestsBasic attributesNew product ingredients

Body

{
  "name": "Coffee 2.0",
  "note": "New description to Coffee 2.0"
}

Responses200422

Headers

Content-Type: application/json

Body

{
    "res" => true
}

Headers

Content-Type: application/json

Body

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name has already been taken."
    ]
  }
}

Body

{
  "name": "Vanilla cappuccino with cream (version N)",
  "components": [
    {
      "id": 51661,
      "volume": 6
    },
    {
      "name": "Water",
      "volume": 5,
      "unit": 3
    }
  ]
}

Responses200422

Headers

Content-Type: application/json

Body

{
    "res" => true
}

Headers

Content-Type: application/json

Body

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name has already been taken."
    ]
  }
}

Change of product (recipe)
PUT`/v2/products/{id}`

Update of specific product or recipe data. Mainly used to change product name in a printed receipt when the cash register equipment is connected.

Synchronization of Dashboard names and the printed receipt takes 2-7 minutes.

Important to note that a name change will not affect current sales statistics, but will only affect new sales.

Attributes for product change

name : string - Product name
note : string - Description

Change in recipe ingredients

In components array new recipe ingredients are specified. Ingredients are set up the same way, as when creating a recipe:

Option 1 (most preferable): id + volume
Option 2: name + unit + volume

If an ingredient is found by an id or a name, a new number of volume would be set up for it.
If an ingredient is not found, it will be created “right away” and added into a recipe.

To remove an ingredient from the recipe, it’s enough to exclude it from a new property of ingredients.

Ingredients excluded from the recipe will be automatically unloaded with a record in the history of changes, provided that they are no longer part of other recipes of one or more VMs.

Attributes for recipe change

name: string, optional - Recipe name
note: string, optional - Description
components: array - List of ingredients for recipe
- id: number, optional - ingredient ID
- name: string, optional - Name of ingredient
- volume: number, reuired - Ingredient volume
- unit: enum(1, 2, 3), optional - Unit of measurement
inventory_number: string, optional - Inventory number

URI Parameters

HideShow

id: number (required) Example: 123
Product ID

POST https://api.telemetron.net//v2/products

RequestsProduct set upRecipe set up

Body

{
  "composite": false,
  "name": "Snickers 75g"
}

Responses201422

Headers

Content-Type: application/json

Body

{
  "res": true,
  "resource": {
    "id": 42
  }
}

Headers

Content-Type: application/json

Body

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name has already been taken."
    ]
  }
}

Body

{
  "name": "Americano 100 ml",
  "composite": true,
  "components": [
    {
      "name": "Water",
      "volume": 100,
      "unit": 2
    },
    {
      "id": 14,
      "volume": 3
    }
  ]
}

Responses201422

Headers

Content-Type: application/json

Body

{
  "res": true,
  "resource": {
    "id": 42
  }
}

Headers

Content-Type: application/json

Body

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name has already been taken."
    ]
  }
}

New product
POST`/v2/products`

This resource is responsible for products set up, when composite = false. Or recipes, when composite = true.

Attributes for setting up a product

composite: boolean, required - false
name: string, required - Product name
note: string, optional - Description
inventory_number: string, optional - Inventory number

Attributes for setting up a recipe

composite: boolean, required - true
name: string, required - Recipe name
note: string, optional - Description
components: array - List of ingredients for recipe
- id: number, optional - ingredient ID
- name: string, optional - Name of ingredient
- volume: number, required - Volume of ingredient
- unit: enum(1, 2, 3), optional - Unit of measurement
inventory_number: string, optional - Inventory number

To create a recipe, it’s necessary to specify the list of ingredients in components.
Each ingredient can be set up two ways:

Set up an ingredient by id and volume.
Set up an ingredient by name, volume and unit. In this case it will be created, if not found by name + unit.

Both ways can be combined in one request.

DELETE https://api.telemetron.net//v2/products/123

Responses200

Headers

Content-Type: application/json

Body

{
  "res": true
}

Removal of product (recipe)
DELETE`/v2/products/{id}`

All ingredients excluded from the recipe will be automatically unloaded with a record in the history of changes, provided that they are no longer part of other recipes of one or more VMs.

URI Parameters

HideShow

id: number (required) Example: 123
Product ID

Recipe properties ¶

This resource allows to edit recipe ingredients. To add ingredients, change their number, remove ingredients from recipe.

GET https://api.telemetron.net//v2/products/123/components

Responses200

Headers

Content-Type: application/json

Body

{
  "id": 42,
  "volume": 100
},
{
  "id": 43,
  "volume": 15
}

Ingredients
GET`/v2/products/{id}/components`

List of ingredients in recipe.

Attributes

Array of
- id : number - ingredient id
- volume : number - volume

URI Parameters

HideShow

id: number (required) Example: 123
Product ID

POST https://api.telemetron.net//v2/products/123/components

Requestsexample 1

Body

{
  "id": 42,
  "volume": 100
},
{
  "id": 43,
  "volume": 15
}

Responses201422

Headers

Content-Type: application/json

Body

{
  "res": true,
  "resource": {
    "id": 42
  }
}

Headers

Content-Type: application/json

Body

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The id has already been taken."
    ]
  }
}

New ingredient
POST`/v2/products/{id}/components`

Adds an ingredient to a recipe.

Attributes

id: number, required - ingredient ID
volume: number, required - ingredient volume

URI Parameters

HideShow

id: number (required) Example: 123
Product ID

PUT https://api.telemetron.net//v2/products/123/components/42

Requestsexample 1

Body

{
  "volume": 100
}

Responses200

Headers

Content-Type: application/json

Body

{
  "res": true
}

Change of ingredient
PUT`/v2/products/{id}/components/{component_id}`

Changes the volume of a specific ingredient in a recipe.

Attributes

volume: number, required - Ingredient volume

URI Parameters

HideShow

id: number (required) Example: 123
Product ID
component_id: number (required) Example: 42
Component ID

DELETE https://api.telemetron.net//v2/products/123/components/42

Responses200

Headers

Content-Type: application/json

Body

{
  "res": true
}

Ingredient removal
DELETE`/v2/products/{id}/components/{component_id}`

Removes a specific ingredient from the recipe.

All ingredients excluded from the recipe will be automatically unloaded with a record in the history of changes, provided that they are no longer part of other recipes of one or more VMs.

URI Parameters

HideShow

id: number (required) Example: 123
Product ID
component_id: number (required) Example: 42
Component ID

Components / ingredients ¶

Full list of ingredients ¶

Basically, this resource is needed when synchronizing data once before the app starts or when cache expires.

Calculations are based on app cache, so there is no need in resource /components/{id}.

GET https://api.telemetron.net//v2/components

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": 18900
    "name": "Cherry yogurt"
    "is_product": true
    "units": "pcs"
  },
  {
    "id": 18985
    "name": "Water"
    "is_product": false
    "units": "ml"
  },
  {
    "id": 18986
    "name": "Coffee beans"
    "is_product": false
    "units": "g"
  }
]

Full list
GET`/v2/components`

Directory of all ingredients from company’s Dashboard.

Attributes

Array of
- id : number - ingredient id
- name : string - name
- is_product : boolean - indicates whether an ingredient is a one-name product
- units : enum('ml', 'pcs', 'g') - units of measurement

POST https://api.telemetron.net//v2/components

Requestsexample 1

Body

{
  "name": "Cup",
  "unit": 1
}

Responses201422

Headers

Content-Type: application/json

Body

{
  "res": true,
  "resource": {
    "id": 42
  }
}

Headers

Content-Type: application/json

Body

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name has already been taken."
    ]
  }
}

New ingredient
POST`/v2/components`

Attributes

name: string, required - Name
unit: enum(1, 2, 3), required - Unit of measurement

Location sites ¶

Full list ¶

Location site is a specific point where a vending machine is installed, for instance, “Hall on the first floor” at “Taezhnaya, 41”.

Only one VM can be installed at one site (coupled VM is considered one VM).

GET https://api.telemetron.net//v2/locations

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": 1,
    "name": "Business center Candy",
    "address": "Bolshaya Posadskaya, 1",
    "note": "on the table"
  },
  {
    "id": 2,
    "name": "McBryde's Pub",
    "address": "Taezhnaya, 41",
    "note": "right to the left window"
  },
  {
    "id": 3,
    "name": "Musta Kissa ravintola",
    "address": "Bolshaya Posadskaya, 15",
    "note": "on the stairs"
  }
]

Full list
GET`/v2/locations`

List of all available locations for installation.

Attributes

Array of
- id : number - ID
- name : string - Name of location
- address : string - Address
- note: string - Comment

PUT https://api.telemetron.net//v2/locations/1

RequestsName only

Body

{
  "name": "Business Center Sapphire",
  "address": "Taezhnaya, 42",
}

Responses200422

Body

{
    "res" => true
}

Headers

Content-Type: application/json

Body

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name has already been taken."
    ]
  }
}

Data change
PUT`/v2/locations/{id}`

Available fields:

name : string - Name of location
address : string - Address
note: string - Comment

URI Parameters

HideShow

id: number (required) Example: 1
ID of location site

POST https://api.telemetron.net//v2/locations

Requestsexample 1

Body

{
  "name": "Business Center Candy",
  "address": "Bolshaya Posadskaya, 1"
}

Responses201422

Headers

Content-Type: application/json

Body

{
  "res": true,
  "resource": {
    "id": 42
  }
}

Headers

Content-Type: application/json

Body

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name has already been taken."
    ]
  }
}

New location site
POST`/v2/locations`

Attributes

name: string, required - Name
address: string, required - Address
note: string, optional - Comment

DELETE https://api.telemetron.net//v2/locations/1?force=1

Responses200

Headers

Content-Type: application/json

Body

{
  "res": true
}

Location removal
DELETE`/v2/locations/{id}{?force}`

It is possible to remove a location site if it is not assigned to any vending machine. However, if no statistics is associated with the location site, it is possible to use force parameter to bypass this rule.

URI Parameters

HideShow

id: number (required) Example: 1
ID
force: bool (optional) Example: 1
Forced removal

Generated by aglio on 06 Jun 2024

API Endpoint

Overview ¶

Authorization ¶

Schema ¶

Parameters ¶

Errors (Errors) ¶

Time stamps (time specifications) ¶

Authorization ¶

Access token ¶

Body

Schema

Headers

Body

Get new access tokenPOST/auth/

Logout ¶

Headers

Body

Logout and expire tokenGET/logout

Definitions ¶

Vending Machine (VendingMachine) ¶

VM Types ¶

VM states ¶

Location (Location) ¶

Planogram (Planogram) ¶

User ¶

Active user ¶

Headers

Body

Full informationGET/v2/me

Attributes ¶

Modems ¶

Full list of modems ¶

Headers

Body

Full listGET/v2/modems

Attributes ¶

Modem ¶

Headers

Body

Schema

Detailed information about modemGET/v2/modems/{id}

Body

Headers

Body

Headers

Body

Change settingsPUT/v2/modems/{id}

Vending machines ¶

Полный список ТА ¶

Headers

Body

Full listGET/v2/vending_machines

Attributes ¶

Vending machine ¶

Headers

Body

Schema

Detailed information about VMGET/v2/vending_machines/{id}

Attributes ¶

VM setupPOST/v2/vending_machines

Attributes for setting up a VM ¶

Body

Headers

Body

Headers

Body

Body

Headers

Body

Headers

Body

Change of VMPUT/v2/vending_machines/{id}{?force}

Headers

Body

EventsGET/v2/vending_machines/{vm_id}/events{?since,until}

Headers

Body

ReportsGET/v2/vending_machines/{vm_id}/reports{?since,until,cp1251,base64,port}

Current load level of a VM ¶

Headers

Overview

Authorization

Schema

Parameters

Errors (Errors)

Time stamps (time specifications)

Get new access token
POST`/auth/`

Logout and expire token
GET`/logout`

Vending Machine (VendingMachine)

VM Types

VM states

Location (Location)

Planogram (Planogram)

Full information
GET`/v2/me`

Attributes

Full list
GET`/v2/modems`

Attributes

Detailed information about modem
GET`/v2/modems/{id}`

Change settings
PUT`/v2/modems/{id}`

Full list
GET`/v2/vending_machines`

Attributes

Detailed information about VM
GET`/v2/vending_machines/{id}`

Attributes

VM setup
POST`/v2/vending_machines`

Attributes for setting up a VM

Change of VM
PUT`/v2/vending_machines/{id}{?force}`

Events
GET`/v2/vending_machines/{vm_id}/events{?since,until}`

Reports
GET`/v2/vending_machines/{vm_id}/reports{?since,until,cp1251,base64,port}`

Current loading of a VM
GET`/v2/vending_machines/{id}/loading`

Attributes

Do VM refill
POST`/v2/vending_machines/{id}/loading`

Request body

Inventory control
POST`/v2/vending_machines/{id}/inventory`

Attributes for setting up a VM

Request data
POST`/v2/vending_machines/{vm_id}/request`

Data request progress
GET`/v2/vending_machines/{vm_id}/request/{id}`

EVA-DTS. Report
GET`/v2/vending_machines/{vm_id}/reports/{id}{?cp1251,base64,port}`

Event time
GET`/v2/vending_machines/{id}/timestamp`

Event directory
GET`/v2/event_codes`

Attributes

Directory of VM models
GET`/v2/vm_models`

Attributes

Total statistics
GET`/v2/stats/vends/summary{?since,until}`

Total VM statistics
GET`/v2/vending_machines/{id}/stats/vends/summary{?since,until}`