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 (Ошибки)

Любой ответ, считающийся ошибкой, имеет HTTP-код либо 4хх (клиентские ошибки), либо 500 (серверные ошибки).

На данный момент возможность “подавления” кода ошибки 4хх (suppress to 200) и возврат с кодом 200 отсутствует.

Тело ответа содержит как минимум объект с атрибутом message, в котором указан текст ошибки:

HTTP/1.1 404 Not found

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

В некоторых случаях в ответ может быть добавлен атрибут subcode, указывающий на номер ошибки по внутренней класификации. Данный номер служит целям текущей разработки и отладки, поэтому клиентское приложение не должно на него полагаться, а должно учитывать HTTP-код ответа.

Дополнительно, если это возможно, может быть указан атрибут documentation_url со ссылкой на раздел документации, описывающий проблему подробнее.

HTTP/1.1 400 Bad request

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

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

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"
}

Схема ответа-ошибки

message : number - Текст ошибки
errors : array optional - массив дополнительных данных (не обяз.)
documentation_url : string optional - ссылка на раздел документаци (не обяз.)
subcode : string optional - код ошибки по внутр. классификации (не обяз.)

Time stamps (обозначение времени)

Временные метки (timestamps) указываются в стандартном формате ISO-8601: YYYY-MM-DDTHH:mm:ss+-HH:hh

В настоящий момент по умолчанию используется часовая зона +03:00, но подразумевается, что временные метки всегда будут указываться в UTC (YYYY-MM-DDTHH:mm:ssZ).

Перевода и отображения времени в часовой зоне клиентского устройства - задача именно клиента.

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/

RequestsAuthorize and get the tokensRefresh Tokens

Body

{
  "grant_type": "password",
  "client_id": "client-key",
  "client_secret": "client-secret",
  "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.

Body

{
  "grant_type": "refresh_token",
  "refresh_token": "the-refresh-token-itself",
  "client_id": "'client-id",
  "client_secret": "client-secret",
  "scope": "teleport"
}

Schema

{
  "type": "object",
  "properties": {
    "grant_type": {
      "type": "string"
    },
    "refresh_token": {
      "type": "string"
    },
    "client_id": {
      "type": "string"
    },
    "client_secret": {
      "type": "string"
    },
    "scope": {
      "type": "string"
    }
  },
  "required": [
    "grant_type",
    "refresh_token",
    "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/`

Initial authorization

To authorize and get a fresh pair of tokens, client should make a request with grant_type=password, providing corresponding data in payload:

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

Get new pair of tokens

To get a new unexpired access token, client should make a request with grant_type=refresh_token, and provide corresponding data in payload with a valid refresh token, obtained earlier:

{
    "grant_type": "refresh_token",
    "refresh_token": "the-refresh-token-itself",
    "client_id": "'client-id",
    "client_secret": "client-secret",
    "scope": "teleport"
}

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 ¶

Торговый автомат (ТА) - одна из базовых сущностей при работе с Телеметроном.

Торговый автомат имеет:

Номер. Это строка состоящая из префикса “T” (англ заглавная t) и его id. Напр. “T1230”.
Наименование.
Планограмму (необяз).
Тип (необяз).
Место установки (необяз).

Attributes

id : number - id ТА. Номер ТА - префикс “Т”+id. Напр., T1234.
name : string - Наименование ТА
planogram_id : number - id планограммы
state : number - рабочее состояние ТА
service : object (no_recent_sales, low_change, need_loading) - сервисные флаги ТА (aka сервисное состояние)
type : VendingMachineType (id, label, name)*
Location : Location (id, name, address) - место установки ТА

Торговый автомат может быть одного из указанных типов.

#	метка	описание
1	coffee	кофейный
2	snack	снековый
3	combo	комбинированный
4	other	прочее
5	paired	спарка
6	can	баночный

Attributes

id : number - id типа
label : string - метка (на англ)
name : string - описание типа

Состояние ТА характеризуется двумя параметрами: это рабочее состояние, отражающее физическое состояние ТА и модема, и сервисное состояние - набор флагов, отражающих логическое состояние ТА.

Рабочее состояние задается числом в атрибуте state:

#	описание
null или 0	неизвестно - модем еще не присылал данные
1	работает
2	не работает
3	нет GSM-связи

Сервисное состояние задается значением true соответствующего свойства объекта в атрибуте service:

свойство	описание
low_change	Мало сдачи
need_loading	Требуется загрузка
no_recent_sales	Давно не было продаж

Эти два типа состояний не взаимоисключающие. Автомату может требоваться загрузка, но при этом он может продолжать работать.

Каждому ТА может соответствовать место установки. Эта дополнительная информация, относящаяся к ТА, может быть не указана.

Каждое место описывается названием и необязательным адресом.

Планограмма - сущность, объединяющая рецепты и продукты, а также доп. настроки, характеризующие тот ассортимент, что способен продавать ТА. Примерная аналогия - меню в ресторане.

Ингредиент – составная часть рецепта. Например, зерновой кофе, вода, размешиватель.

Рецепт – это то, что продается в автомате и состоит из ингредиентов. Напр., “эспрессо” - это рецепт, состоящий из воды, кофе, стаканчика и размешивателя.

В основном используются в кофейных автоматах.

Продукт – это то, что продается в автомате и не включает в себя ингредиенты. Например, шоколадный батончик.

Простыми словами

Автомат может продавать как шоколадные батончики (мы их называем продуктами), так и кофе-какао-чай (их мы тоже называем продуктами, однако, когда надо уточняем - это рецепт).

ТА продает только продукты. Набор и размещение этих продуктов и определяются планограммой.

Шоколадный батончик - продукт неделимый. Кофе-чай - это составной продукт, который состоит из смеси ингредиентов (иногда мы их называем компонентами).

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

В торговый автомат загружаются, а при продажах расходуются ингредиенты.

Чтобы не запутаться, все продукты помечаются флагом composite. Составные продукты (ака рецепты) типа кофе-чая - это composite = true, шок. батончики - composite = false.

И с другого угла: ингредиенты, которые относятся к простым продуктам типа шок. батончиков, имеют флаг is_product = true. Остальные ингредиенты, из которых можно составить рецепт - is_product = false.

Простыми словами вкратце

Рецепт Эспрессо = молотый кофе (ингредиент) + вода (ингредиент) + стакан (ингредиент) + размешиватель (ингредиент). Продукт Сникерс = сникерс (ингредиент, is_product=true). Планограмма = продукт Эспрессо + продукт Сникерс + … Загрузка ТА = ингред1 ХХ единиц + ингред2 XY единиц + ингред3 XZ единиц + …

Компания ¶

Реквизиты ¶

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

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": 123,
    "title": "Название компании или ИП",
    "title_short": "Краткое название",
    "addr_legal": "Юридический адрес",
    "addr_fact": "Фактический адрес",
    "inn": "ИНН",
    "kpp": "КПП",
    "provider": "od"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number"
      },
      "title": {
        "type": "string"
      },
      "title_short": {
        "type": "string"
      },
      "addr_legal": {
        "type": "string"
      },
      "addr_fact": {
        "type": "string"
      },
      "inn": {
        "type": "string"
      },
      "kpp": {
        "type": "string"
      },
      "provider": {
        "type": [
          "string",
          "null"
        ],
        "enum": [
          "od",
          "co",
          "ipro",
          null
        ],
        "description": "Облачная касса"
      }
    }
  }
}

Реквизиты
GET`/v2/requisites`

Получить список всех реквизитов компании с настройками ОККТ.

Список значений атрибута provider:
- od - Orange Data
- co - Чек онлайн
- ipro - Инитпро

Пользователь ¶

Текущий пользователь ¶

Возвращает информация о текущем залогиненном пользователе.

Содержит в т.ч. и текущий список ролей (только роли, RBAC level 1).

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

Responses200

Headers

Content-Type: application/json

Body

{
  "id": 496
  "company_id": 165
  "first_name": "Сидор"
  "last_name": "Сидоров"
  "position": "Ст. ннженер тех отдела по переоборудованию"
  "email": "s@example.com"
  "language_id": null
  "status": true
  "last_login": "2016-02-14T22:44:33"
  "phone": true
  "roles":
    [
      {
        "id": 3
        "name": "operator"
        "title": "Оператор"
      }
    ]
}

Полная информация
GET`/v2/me`

Attributes

id : number - id ингредиента
company_id : number - id компании
email : string - Контактный адрес email, он же - логин
phone : boolean - указан ли у пользователя номер телефона для связи
first_name : string - Имя
last_name : string - Фамилия
position : string - Должность. Как правило, указана редко.
lang : string - Обозначение языка пользователя (ISO-639-1)
status : boolean - Активный юзер (true) или забанен (false)
roles : Array of Roles - массив ролей пользователя
- id : number - id роли
- name : string метка роли (всегда англ),
- title : string - краткое описание роли (l10n)

Модемы ¶

Полный список модемов ¶

Получить список всех модемов, доступных текущему пользователю.

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

Responses200

Headers

Content-Type: application/json

Body

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

Полный список
GET`/v2/modems`

Attributes

Array of
- id : number - Modem ID
- imei: string - IMEI
- iccid: string - ICCID
- hw_version : string - Аппаратная версия
- boot_version : string - Версия загрузчика
- firmware : string - Версия прошивки
- phone : string - Номер телефона

Модем ¶

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

Responses200

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "imei": "IMEI",
  "iccid": "ICCID",
  "hw_version": "Аппаратная версия",
  "boot_version": "Версия загрузчика",
  "firmware": "Версия прошивки",
  "phone": "Номер телефона"
}

Schema

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

Подробная информация о модеме
GET`/v2/modems/{id}`

URI Parameters

HideShow

id: number (required) Example: 123
Modem ID

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

RequestsТолько название

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."
      ]
    ]
}

Изменение модема
PUT`/v2/modems/{id}`

Обновление данных конкретного модема.

Доступные поля:

phone : string - Номер телефона

URI Parameters

HideShow

id: number (required) Example: 123
Modem ID

POST https://api.telemetron.net/v2/modems/123/set

RequestsТолько название

Body

{
  "cashless_mode": 1,
  "cashless_address": 1,
  "cashless_credit": "100.50,6,1"
}

Responses200

Headers

Content-Type: application/json

Body

{
    "res" => true
}

Отправка команд модему
POST`/v2/modems/{id}/set`

Доступные поля:

cashless_mode : int, optional - вкл/выкл кешлесса (0|1)
cashless_address : int, optional - адрес на шине (1|2)
cashless_credit : string, optional - начислить кредит (credit [, amount] [,autoapprove])

URI Parameters

HideShow

id: number (required) Example: 123
Modem ID

Торговые автоматы ¶

VendingMachineType

id : number - id типа
label : string - метка (на англ)
name : string - описание типа

id	метка	описание
1	coffee	кофейный
2	snack	снековый
3	combo	комбинированный
4	other	прочее
5	paired	спарка
6	can	баночный

VendingMachineState

#	описание
null или 0	неизвестно - модем еще не присылал данные
1	работает
2	не работает
3	нет GSM-связи

VendingMachineService

свойство	описание
low_change	Мало сдачи
need_loading	Требуется загрузка
no_recent_sales	Давно не было продаж
no_bills_in	Давно не вносились купюры
no_coins_in	Давно не вносились монеты

Location

id : number - id места установки
name : string - название места
address : string - адрес

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

Получить список всех ТА, доступных текущему пользователю.

Для администраторов и старших операторов список ТА не ограничивается, но для операторов список ограничен теми ТА, которые входят в назначенные оператору группы. Может так получиться, что у пользователя не будет ни одного доступного ТА.

GET https://api.telemetron.net/v2/vending_machines?local=1

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": 929,
    "name": "Старый ламповый автомат",
    "planogram_id": 289,
    "state": 1,
    "service": {
      "low_change": true,
      "no_recent_sales": true
    },
    "location": {
      "id": 692,
      "group_id": null,
      "name": "Svenskan Södermann",
      "address": "Садовая, 49"
    },
    "type": null,
    "imei": 999999999123456,
    "is_crt_active": false,
    "inventory_number": null,
    "mm_id": null,
    "last_event_dates": {
      "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"
    }
  },
  {
    "id": 928,
    "name": "Двухдверный с синей обклейкой",
    "planogram_id": 289,
    "state": 3,
    "service": null,
    "location": {
      "id": 691,
      "group_id": null,
      "name": "Ресторан У Бертолуччо",
      "address": "Автобусное ш., 7"
    },
    "type": {
      "id": 1,
      "label": "coffee",
      "name": "кофейный"
    },
    "imei": 999999999123459,
    "is_crt_active": false,
    "inventory_number": null,
    "track_bus_vends": false,
    "mm_id": 100,
    "tz_id : 109",
    "tz : America/Grenada",
    "last_event_dates": {
      "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"
    }
  },
]

Полный список
GET`/v2/vending_machines{?local}`

Attributes

Array of
- id : number - id ТА
- serial_number: string - Серийный номер ТА
- name : string - Наименование ТА
- planogram_id : number - id планограммы
- state : number - рабочее состояние ТА
- service : object (no_recent_sales, low_change, need_loading) - сервисные флаги ТА (aka сервисное состояние)
- type : VendingMachineType (id, label, name) - тип ТА
- location : Location (id, name, address) - место установки ТА
- imei : string - IMEI установленного в торговом аппарате модема Телеметрон
- is_crt_active : bool - Флаг передачи данных в облачную ККТ для регистрации фискального чека
- inventory_number: string - Инвентарный номер
- track_bus_vends: bool - Флаг сбора статистики продаж с платежной шины (вместо EVA-DTS)
- mm_id: number | null - Модель торгового автомата (ID из справочника vm_models)
- tz_id : 109 (number, nullable) - ID часового пояса
- tz : America/Grenada (string, nullable) - Название часового пояса
- last_event_dates : object (last_sale, last_service, last_collection, last_loading, last_report, last_acquired_report) - временные метки событий ТА;

URI Parameters

HideShow

local: bool (optional) Example: 1
временные метки с учетом локального времени ТА

Торговый автомат ¶

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

Responses200

Headers

Content-Type: application/json

Body

{
  "id": 123,
  "serial_number": "AAA0000",
  "name": "Тестовый ТА",
  "planogram_id": 123,
  "state": 1,
  "service": {
    "low_change": true,
    "need_loading": true,
    "no_recent_sales": true
  },
  "location": {
    "id": 123,
    "name": "ТЦ Кофейник",
    "address": "дорога на Турухтанные острова, 12"
  },
  "type": {
    "id": 123,
    "label": "coffee",
    "name": "кофейный"
  },
  "modem": {
    "id": 123,
    "imei": "999999999123456",
    "bus": "exe",
    "sw_version": "4.4.42",
    "hw_version": "2.4"
  },
  "is_crt_active": true,
  "inventory_number": "B42",
  "mm_id": 100,
  "money": {
    "change": 10000,
    "revenue": 500000
  },
  "tz_id": 109,
  "tz": "America/Grenada"
}

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": "Адрес места установки"
        }
      }
    },
    "type": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "id типа ТА"
        },
        "label": {
          "type": "string",
          "description": "Тип ТА (метка на англ)"
        },
        "name": {
          "type": "string",
          "description": "Описание"
        }
      },
      "description": "тип ТА"
    },
    "modem": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "id модема"
        },
        "imei": {
          "type": "string",
          "description": "IMEI"
        },
        "bus": {
          "type": "string",
          "description": "Тип платежной шины (EXE, MDB, null)"
        },
        "sw_version": {
          "type": "string",
          "description": "Версия прошивки"
        },
        "hw_version": {
          "type": "string",
          "description": "Аппаратная версия"
        }
      },
      "description": "установленный модем Телеметрон"
    },
    "is_crt_active": {
      "type": "boolean"
    },
    "inventory_number": {
      "type": "string"
    },
    "mm_id": {
      "type": [
        "number",
        "null"
      ],
      "description": "Модель торгового автомата"
    },
    "money": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "change": {
          "type": "number",
          "description": "Сдача в копейках."
        },
        "revenue": {
          "type": "number",
          "description": "Выручка в копейках"
        }
      }
    },
    "tz_id": {
      "type": [
        "number",
        "null"
      ],
      "description": "ID часового пояса"
    },
    "tz": {
      "type": [
        "string",
        "null"
      ],
      "description": "Название часового пояса"
    }
  }
}

Подробная информация о ТА
GET`/v2/vending_machines/{id}`

Attributes

id : number - id ТА
serial_number: string - Серийный номер ТА
name : string - Наименование ТА
planogram_id : number - id планограммы
state : number - рабочее состояние ТА
service : array (no_recent_sales, low_change, need_loading) - сервисные флаги ТА (aka сервисное состояние)
type : VendingMachineType (id, label, name) - тип ТА
location : Location (id, name, address) - место установки ТА
modem : Modem (id, imei, bus, sw_version, hw_version) - установленный на ТА модем
is_crt_active : bool - Включить передачу данных в облачную ККТ для регистрации фискального чека
inventory_number: string - Инвентарный номер
track_bus_vends: bool - Включить сбор статистики продаж с платежной шины (вместо EVA-DTS)
requisite_id: number - id реквизитов
min_price: number - минимальная допустимая цена чека
max_price: number - максимальная допустимая цена чека
mm_id: number | null - модель торгового автомата (ID из справочника vm_models)
money: object | null - Наличные деньги в автомате
- change: number | null - Сдача в копейках.
- revenue: number | null - Выручка в копейках
tz_id : number | null - ID часового пояса
tz : string | null - Название часового пояса

URI Parameters

HideShow

id: number (required) Example: 123
VM ID

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

Requestsexample 1

Body

{
  "name": "Настольный кофейник",
  "serial_number": "234441X8347CF",
  "planogram_id": 1,
  "location_id": 42,
  "mm_id": 1,
  "imei": "123456789012345",
  "tz": "Europe/Moscow"
}

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 may not be greater than 255 characters."
      ]
    ]
}

Создание ТА
POST`/v2/vending_machines{?force}`

При создании нового ТА необходимо указать его модель из справочника (/v2/vm_models). Если требуемой модели нет в списке, то как решение можно использовать mm_id = 52 (“модель не указана” или “нет в списке”).

Модем можно указать по ID (modem_id) или по IMEI (imei).

Если указан параметр force, модем будет отвязан от старого ТА и привязан к этому.

name : string, required - Наименование ТА
mm_id, required : number` - Модель торгового автомата (ID из справочника vm_models)
serial_number : string - Серийный номер ТА
planogram_id : number, optional - Планограмма, если задана
location_id : number, optional - Место установки, если задано
modem_id : number, optional - ID модема
imei : string, optional - IMEI модема
is_crt_active : bool, optional - Флаг передачи данных в облачную ККТ
inventory_number: string, optional - Инвентарный номер
track_bus_vends: bool - Включить сбор статистики продаж с платежной шины (вместо EVA-DTS)
tz_id: number, optional - ID часового пояса (из справочника часовых зон)
tz: string, optional - название часового пояса
min_price: number, optional - минимальная допустимая цена чека
max_price: number, optional - максимальная допустимая цена чека

URI Parameters

HideShow

force: bool (optional) Example: 1
Принудительная привязка модема к ТА

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

RequestsТолько названиеГруппа полей

Body

{
  "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": "Новое название ТА",
  "mm_id": 1,
  "serial_number": "Новый серийный номер ТА",
  "modem_id": 42,
  "tz_id": 109
}

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."
      ]
    ]
}

Изменение ТА
PUT`/v2/vending_machines/{id}{?force}`

Обновление данных конкретного ТА.

Доступные поля:

name : string - Наименование ТА
mm_id, required : number` - Модель торгового автомата (ID из справочника vm_models)
serial_number : string - Серийный номер ТА
planogram_id : number, optional - Планограмма
location_id : number, optional - место установки
modem_id : number, optional - ID модема
imei : string, optional - IMEI модема
is_crt_active : bool, optional - Флаг передачи данных в облачную ККТ
inventory_number: string, optional - Инвентарный номер
track_bus_vends: bool, optional - true - Платежная шина | false - EVA-DTS
requisite_id: number, optional - id реквизитов
tz_id: number, optional - ID часового пояса (из справочника часовых зон)
tz: string, optional - название часового пояса
min_price: number, optional - минимальная допустимая цена чека
max_price: number, optional - максимальная допустимая цена чека

Если задан атрибут planogram_id, к указанному ТА будет привязана новая планограмма.

Если у ТА ранее была назначена другая планограмма и была указана какая-либо загрузка, то все продукты на спиралях, которых нет в новой планограмме, будут автоматически выгружены с записью в историю изменений (такая же логика, которая работает в Личном кабинете при изменении планограммы торгового автомата в настройках).

Модем можно указать по ID (modem_id) или по IMEI (imei).

Если указан параметр force, модем будет отвязан от старого ТА и привязан к этому.

URI Parameters

HideShow

id: number (required) Example: 123
id ТА
force: bool (optional) Example: 1
Принудительная привязка модема к ТА

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&local=1

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
  }
]

События
GET`/v2/vending_machines/{vm_id}/events{?since,until,local}`

Список событий ТА.

Максимально доступный период - 7 дней. Максимально доступная глубина выборки - 14 дней.

Доступные поля:

date : string - Дата
code: string - Код события (см. спровочник)
payload : array - Метаданные по событию

URI Parameters

HideShow

vm_id: number (required) Example: 123
VM ID
since: string (optional) Example: 2018-01-01T00:00:00+03:00
Начало периода (включительно)
until: string (optional) Example: 2018-01-02T00:00:00+03:00
Конец периода (включительно)
local: boolean (optional) Example: 1
Период с учетом часовой зоны ТА (т.е. использовать локальное время автомата)

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&local=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
    }
  ]

Отчеты
GET`/v2/vending_machines/{vm_id}/reports{?since,until,cp1251,base64,port,local}`

Выгрузка отчетов EVA-DTS.

Максимально доступный период - 14 дней. Максимально доступная глубина выборки - 14 дней.

Доступные поля:

date : string - Дата
data: string - Тело отчета
evadts_port : string - Порт

URI Parameters

HideShow

vm_id: number (required) Example: 123
VM ID
since: string (optional) Example: 2018-01-01T00:00:00+03:00
Начало периода (включительно)
until: string (optional) Example: 2018-01-02T00:00:00+03:00
Конец периода (включительно)
port: number (optional) Example: 1
Необязательный параметр, указывающий номер порта (2-DEX)
cp1251: number (optional) Example: 1
Необязательный флаг, тело отчета data будет в кодировке Windows-1251
base64: number (optional) Example: 1
Необязательный флаг, тело отчета data будет запаковано в BASE64
local: boolean (optional) Example: 1
Период с учетом часовой зоны ТА (т.е. использовать локальное время автомата)

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

Responses200

Headers

Content-Type: application/json

Body

{
  "status": "ok"
}

Перезагрузка модема
POST`/v2/vending_machines/{id}/reset`

Отправляет команду на перезагрузку модема

URI Parameters

HideShow

id: number (required) Example: 123
VM ID

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

Responses200422

Headers

Content-Type: application/json

Body

{
  "status": "ok"
}

Headers

Content-Type: application/json

Body

{
    "status" => "error",
    "data" => [
      "vm_id" => 13979,
      "modem_id" => 25164,
      "modem_time" => "2023-07-28 12:32:57"
    ]
}

Выдача напитка
POST`/v2/vending_machines/{vm_id}/dispense`

Выдать напиток на автоматах Jofemar G23 с модемом Vendista.

Доступные поля:

number : required, number - Номер продукта
cup : required, number - Выдача стакана (0/1)
sugar : required, number - Сахар (0…4)
discount : number - Размер скидки продукта

URI Parameters

HideShow

vm_id: number (required) Example: 123
VM ID

POST https://api.telemetron.net/v2/vending_machines/123/vendista-credit

Responses200422

Headers

Content-Type: application/json

Body

{
  "status": "ok"
}

Headers

Content-Type: application/json

Body

{
    "status": "error",
    "message": "The given data was invalid.",
}

Начислить кредит
POST`/v2/vending_machines/{vm_id}/vendista-credit`

Начислить кредит на автоматах с модемом Vendista.

Доступные поля:

amount : required, number - Сумма начисления в копейках

URI Parameters

HideShow

vm_id: number (required) Example: 123
VM ID

Текущая загрузка ТА ¶

Текущий уровень загрузки торгового автомата ингредиентами.

Для ингредиентов, которые обозначают продукт (напр., шоколадный батончик, бутылка воды), указывается дополнительное поле layout_number. В этом поле указан номер спирали/товарной позиции в автомате, к которому число загрузки и относится.

Т.е. если в автомате шок. батончик расположен на нескольких спиралях, то в ответе придет несколько записей для одного и того же component_id с разным значением загрузки для каждой из спиралей (planogram.layout).

Для ингредиентов, которые составляют рецепт (напр., сливки, сахар), номер спирали бессмысленен, поэтому значение поля layout_number не указывается.

Ситуация, когда тек. уровень какого-либо компонента в ТА больше значения максимальной загрузки, указанного в настройках связанной планограммы - нормальная.

Макс. загрузка в настройках ТМ - это не безусловный порог максимума, а, скорее, как некий базис для расчетов.

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,  /* такой же продукт, что и выше, но на другой спирали! */
    value: 0,
    layout_number: 'A2'
  },
]

Текущая загрузка ТА
GET`/v2/vending_machines/{id}/loading`

Attributes

Array of
- component_id : number - id компонента
- value : number - текущий уровень загрузки компонента (в его ед. изм.)
- layout_number : string - номер спирали/торговой линии для продукта

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": "Комментарий к загрузке"
}

Responses201400

Headers

Content-Type: application/json

Body

{
  "digest" : <digest of operation>
}

Headers

Content-Type: application/json

Body

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

Body

{
  "data": [],
  "note": "Комментарий к загрузке"
}

Responses400

Headers

Content-Type: application/json

Body

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

Body

{
  "data": [
    {
      "component_id": 123,
      "add": 0
    }
  ],
  "note": "Комментарий к загрузке"
}

Responses400

Headers

Content-Type: application/json

Body

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

Сделать загрузку ТА
POST`/v2/vending_machines/{id}/loading`

Request body

data: Array of
- component_id : number - id компонента
- layout_number : string - номер спирали, если указывается загрузка продукта. Для ингредиента параметр должен быть null или отсутсвовать.
- add : number - изменение загрузки компонента в его ед. изм. Т.е. это дельта загрузки. Если положительная - компонент загрузили, если отрицательная, компонент выгрузили.
note: string - комментарий к загрузке
created_at: timestamp - время загрузки (если не указано, в личном кабинете оно будет равно времени непосредственной записи в БД)

URI Parameters

HideShow

id: number (required) Example: 123
VM ID

Инвентаризация ¶

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": "Комментарий для инвентаризации"
}

Responses201400

Headers

Content-Type: application/json

Body

{
  "res" : true,
  "digest" : <digest of operation>
}

Headers

Content-Type: application/json

Body

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

Body

{
  "data": [],
  "note": "Комментарий для инвентаризации"
}

Responses422400

Headers

Content-Type: application/json

Body

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

Headers

Content-Type: application/json

Body

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

Body

{
  "data": [
    {
      "component_id": 123
    }
  ],
  "note": "Комментарий для инвентаризации"
}

Responses422

Headers

Content-Type: application/json

Body

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

Инвентаризация
POST`/v2/vending_machines/{id}/inventory`

Указать текущий уровень загрузки торгового автомата ингредиентами.

Т.е. если в автомате шок. батончик расположен на нескольких спиралях, то в запросе нужно указать несколько записей для одного и того же component_id с разным значением загрузки для каждой из спиралей (layout_number).

Для ингредиентов, которые составляют рецепт (напр., сливки, сахар), номер спирали не имеет смысла, поэтому значение layout_number не указывается (сервер игнорирует это поле).

Про ингредиенты, которые в запросе не указаны, мы считаем, что значение их загрузки соответствует данным из ЛК. Т.е. их отсутствие в запросе не означает “в автомате соотв. ингредиент отсутствует”.

Успешный запрос может получить в ответ 200 или 201!

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

Но если между указанными данными и данными на сервере есть разница, то фиксируется изменение текущей загрузки автомата, а сервер возвращает успешный ответ со статусом 201.

data: Array of
- component_id : number - id компонента
- layout_number : string - номер спирали, если производится инвентаризация продукта. Для ингредиента параметр должен быть null или отсутствовать.
- loaded : number - количество фактической загрузки компонента в его ед. изм.
note: string - комментарий к инвентаризации
created_at: timestamp - время инвентаризации (если не указано, в личном кабинете оно будет равно времени непосредственной записи в БД)

URI Parameters

HideShow

id: number (required) Example: 123
VM ID

Список загрузок ингредиентов по автомату ¶

GET https://api.telemetron.net/v2/vending_machines/123/loading_tx?since=2018-01-01 00:00:00+03&until=2018-01-07 00:00:00+03&local=1

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": 1,
    "vm_id": 9759,
    "created_at": "2020-08-26 13:47:24",
    "user_id": 12884,
    "data": [
      {
        "component": "Амаретто Капучино",
        "delta": 2,
        "orig": 2
      },
      {
        "component": "Амаретто Капучино со сливками",
        "delta": 3,
        "orig": 3,
        "underflow": true
      }
    ]
  }
]

Список загрузок ингредиентов
GET`/v2/vending_machines/{id}/loading_tx{?since,until,local}`

Выдает список загрузок ингредиентов оператором на конкретный автомат за выбранный период времени.

data : array
- component: “Название компонента текстом” (string)
- delta: -2000 (number)
- orig: 1000 (number) - сколько было до загрузки
- underflow: true (boolean) - результат загрузки не совпадает с данными в базе

URI Parameters

HideShow

id: number (required) Example: 123
VM ID
since: string (optional) Example: 2018-01-01 00:00:00+03
Начало периода (включительно)
until: string (optional) Example: 2018-01-07 00:00:00+03
Конец периода (включительно)
local: boolean (optional) Example: 1
Период с учетом часовой зоны ТА (т.е. использовать локальное время автомата)

Запрос данных с автомата ¶

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
}

Запросить данные
POST`/v2/vending_machines/{vm_id}/request`

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

На данный момент доступно два типа: это отчет и конфиг.

“Отчет” означает, что при следующем пинге модем должен будет снять и прислать EVADTS-отчет с торгового автомата. На основе этого отчета позже обновится текущая информация торгового автомата: кол-во/сумма продаж, загрузка, …

Attributes

report : boolean - запросить снятие отчета с модема
config : boolean - запросить конфигурационные параметры модема

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

Ответ должен содержать id запроса. Также может быть указан атрибут progress: true, означающий, что в наст. момент у торгового автомата уже есть запрос заданного типа.

В точки зрения сервера запрос к торговому автомату - это один объект, объединяющий в себе булевы атрибуты, которые и описывают текущие “требования” запроса. Т.е. в один момент времени может быть актуальным как “запрос отчета”, так и “запрос конфига” - в этом случае request_id будет один и тот же.

Это может проявиться как

POST {"report": true } -> 200 {"request_id": 17543}
POST {"config": true } -> 200 {"request_id": 17543} /* тот же request_id */

Запрос для автомата, у которого нет привязанного модема, не имеет смысла и вернет ошибку.

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"
}

Прогресс запроса данных
GET`/v2/vending_machines/{vm_id}/request/{id}`

По имеющемуся request_id можно проверить состояние запроса на получение данных с торгового автомата.

Если по заданному идентификатору находится запрос на получение данных (ответ 200), то это означает, что данный запрос все еще в стадии исполнения, и никаких новых данных от ТА пока не получено.

Если по указанному request_id нет никаких записей (ответ 404), значит такой запрос данных ТА уже завершился, и требуемые данные можно получить соответствующим вызовом API (напр., /vending_machines/:id/reports/last для EVA-DTS отчетов)

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&local=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. Отчет
GET`/v2/vending_machines/{vm_id}/reports/{id}{?cp1251,base64,port,local}`

Получение EVA-DTS отчета по его номеру.

Если используется 2-DEX, в ответе в атрибуте evadts_port будет указан номер порта, с которого был снят отчет. Если 2-DEX не используется, evadts_port равен 1 или null.

Чтобы получить самый последний валидный отчет, вместо ID отчета можно указать last_valid: /vending_machines/{vm_id}/reports/last_valid

Чтобы получить последний отчет независимо от валидации, вместо ID отчета можно указать last: /vending_machines/{vm_id}/reports/last

Отчеты, снятые более 14 дней назад, в поиске не учитываются.

URI Parameters

HideShow

vm_id: number (required) Example: 123
VM ID
id: number, string (required) Example: 827323
ID отчета, или last
port: number (optional) Example: 1
Необязательный параметр, указывающий номер порта (2-DEX)
cp1251: number (optional) Example: 1
Необязательный флаг, тело отчета data будет в кодировке Windows-1251
base64: number (optional) Example: 1
Необязательный флаг, тело отчета data будет запаковано в BASE64
local: boolean (optional) Example: 1
Период с учетом часовой зоны ТА (т.е. использовать локальное время автомата)

GET https://api.telemetron.net/v2/vending_machines/123/reports/last_errors?local=1

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "code": "D54",
    "evadts_port": 1,
    "modem_time": "2020-01-01T07:00:00.000000Z",
    "created_at": "2020-01-01T07:00:00.000000Z",
    "value": "54"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "code": {
        "type": "string"
      },
      "evadts_port": {
        "type": "number"
      },
      "modem_time": {
        "type": "string"
      },
      "created_at": {
        "type": "string"
      },
      "value": {
        "type": "string"
      }
    }
  }
}

EVA-DTS. Ошибки
GET`/v2/vending_machines/{vm_id}/reports/last_errors{?local}`

Эндпоинт возвращает уведомления об ошибках и событиях торгового автомата.
Данные для отображения берутся из отчетов, получаемых с автомата или с монетоприемника (в зависимости от того, к чему подключен модем).
Наибольшая детализация достигается при подключении модема непосредственно к автомату.

Отчеты, снятые более 14 дней назад, в поиске не учитываются.

URI Parameters

HideShow

vm_id: number (required) Example: 123
VM ID
local: boolean (optional) Example: 1
Период с учетом часовой зоны ТА (т.е. использовать локальное время автомата)

GET https://api.telemetron.net/v2/vending_machines/123/timestamp?local=1

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",
}

Время событий
GET`/v2/vending_machines/{id}/timestamp{?local}`

Данный ресурс предоставляет список актуальных временных меток для разного рода событий ТА, которые могут быть использованы для расчета актуальности данных, кеша, необходимости делать какой-либо запрос и т.д.

Временные метки (timestamps) указываются в стандартном формате ISO-8601 (YYYY-MM-DDTHH:mm:ss+-HH:hh). В настоящий момент не поддерживается (по умолчанию часовая зона +3), но подразумевается, что временные метки будут указываться в UTC (YYYY-MM-DDTHH:mm:ss+00:00).

При разборе данных всегда следует учитывать часовую зону и не отбрасывать ее при парсинге.

Если какая-либо метка времени не известна, либо событие еще не происходило, значение соответствуюзего параметра будет null.

Attributes

last_sale : string - время последней продажи;
last_service : string - время последнего обслуживания ТА;
last_collection : string - время последней инкассации ТА;
last_loading : string - время последней загрузки ингредиентов;
last_report : string - время последнего валидного отчета, принятого от ТА;
last_acquired_report : string - время последнего отчета, независимо от того, прошел отчет валидацию или нет;

URI Parameters

HideShow

id: number (required) Example: 123
VM ID
local: boolean (optional) Example: 1
Период с учетом часовой зоны ТА (т.е. использовать локальное время автомата)

Справочник событий ¶

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."
  }
]

Справочник событий
GET`/v2/event_codes`

Attributes

code : string - уникальный идентификатор события
name : string - название
desc : string - комментарий

Справочник ошибок ¶

GET https://api.telemetron.net/v2/reports/errors/D54

Responses200

Headers

Content-Type: application/json

Body

{
    "code": "D54",
    "vendor_code": "54",
    "name": "Ошибка 54",
    "note": "Не заданы параметры перекрестной электропроводки кнопки выбора. Есть кнопка выбора с незаданными параметрами перекрестной электропроводки кнопки выбора",
    "comment": "null",
    "severity": 3
{

Справочник ошибок
GET`/v2/reports/errors/{code}`

Attributes

code : string - код ошибки
vendor_code : string - код ошибки по классификации производителя
name : string - название ошибки
note : string - описание ошибки
comment : string - комментарии к ошибке
severity : number - важность произошедшего

URI Parameters

HideShow

code: string (required) Example: D54
Текстовый код ошибки

Справочник моделей ТА ¶

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"
  }
]

Справочник моделей ТА
GET`/v2/vm_models`

Attributes

id : number - id модели
name : string - полное наименование модели

Справочник часовых зон ¶

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

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "tz_id": 109,
    "tz": "America/Grenada",
    "utc_offset": "-04:00"
  },
  {
    "tz_id": 220,
    "tz": "Asia/Baku",
    "utc_offset": "+04:00"
  }
]

Справочник часовых зон
GET`/v2/timezones`

Attributes

tz_id : number - id часовой зоны
tz : string - название часовой зоны
utc_offset : string - смещение от UTC

Статистика продаж ¶

В зависимости от модели и версии собственного ПО, а также установленного оборудования, автомат может регистрировать продажи различного уровня детализации.

Поэтому возможна ситуация, когда за один и тот же период времени статистики продаж с детализацией продуктов нет, но общая статистика ненулевая.

Диапазон времени по умолчанию - текущие сутки.
Максимальная длина диапазона выборки - 31 день.

Доступна статистика не старше двух месяцев.

Общая статистика ¶

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&local=1

Responses200

Headers

Content-Type: application/json

Body

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

Общая статистика
GET`/v2/stats/vends/summary{?since,until,local}`

Общая статистика продаж (кол-во продаж, сумма) за выбранный период, не включающая детализацию данных по продуктам и групировку по торговым автоматам.

Максимальная длина диапазона выборки - 7 дней.

URI Parameters

HideShow

since: string (optional) Example: 2018-01-01 00:00:00+03
Начало периода (включительно)
until: string (optional) Example: 2018-01-07 00:00:00+03
Конец периода (включительно)
local: boolean (optional) Example: 1
Выдача с учетом часовой зоны ТА

Общая статистика ¶

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

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "quantity": 255,
    "amount": 869500
  }
]

Общая статистика
GET`/v2/stats/vends/payments/summary{?since,until,local}`

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

Максимальная длина диапазона выборки - 7 дней.

URI Parameters

HideShow

since: string (optional) Example: 2018-01-01 00:00:00+03
Начало периода (включительно)
until: string (optional) Example: 2018-01-07 00:00:00+03
Конец периода (включительно)
local: boolean (optional) Example: 1
Выдача с учетом часовой зоны ТА

Общая статистика ТА ¶

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&local=1

Responses200

Headers

Content-Type: application/json

Body

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

Общая статистика ТА
GET`/v2/vending_machines/{id}/stats/vends/summary{?since,until,local}`

Общая статистика продаж (кол-во продаж, сумма) за выбранный период по одному ТА, не включающая детализацию данных по продуктам и группировку по торговым автоматам.

URI Parameters

HideShow

id: number (required) Example: 123
VM ID
since: string (optional) Example: 2018-01-01 00:00:00+03
Начало периода (включительно)
until: string (optional) Example: 2018-02-01 00:00:00+03
Конец периода (включительно)
local: boolean (optional) Example: 1
Выдача с учетом часовой зоны ТА

Продажи по продуктам ¶

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&local=1

Responses200

Headers

Content-Type: application/json

Body

[
  {
      "time": "2018-01-10T12:59:16+03:00",
      "layout_number": "2",
      "name": "Американо 8",
      "vend_type": 3,
      "price": 35,
      "number": 2,
      "value": 70,
      "discount": 20
      "payment_type" : 1
  },
  {
      "time": "2018-01-11T14:45:00+03:00",
      "layout_number": "3",
      "name": "Кофе с молоком",
      "vend_type": 3,
      "price": 35,
      "number": 1,
      "value": 35,
      "discount": 20,
      "payment_type" : 1
  }
]

Продажи по продуктам
GET`/v2/vending_machines/{id}/stats/vends/products{?type,since,until,local}`

Статистика продаж за период с детализацией по продуктам.

URI Parameters

HideShow

id: number (required) Example: 123
VM ID
type: enum(paid, free, test) (optional) Example: paid
Тип выдачи
since: string (optional) Example: 2018-01-01T00:00:00+03:00
Начало периода (включительно)
until: string (optional) Example: 2018-02-01T00:00:00+03:00
Конец периода (включительно)
local: boolean (optional) Example: 1
Выдача с учетом часовой зоны ТА

Продажи по продуктам и оплатам ¶

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&local=1

Responses200

Headers

Content-Type: application/json

Body

[
  {
      "time": "2018-01-10T12:59:16+03:00",
      "layout_number": "2",
      "name": "Американо 8",
      "payment_type": 1,
      "price": 35,
      "number": 2,
      "value": 70,
      "discount": 20,
      "vend_type": 3,
  },
  {
      "time": "2018-01-10T12:59:16+03:00",
      "layout_number": "3",
      "name": "Кофе с молоком 8+4.93",
      "payment_type": 1,
      "price": 35,
      "number": 1,
      "value": 35,
      "discount": 20,
      "vend_type": 3,
  }
]

Продажи по продуктам и оплатам
GET`/v2/vending_machines/{id}/stats/vends/payments{?type,since,until,local}`

Статистика продаж за период с детализацией по продуктам и типу оплаты (наличные, безналичные, жетоны).

URI Parameters

HideShow

id: number (required) Example: 123
VM ID
type: enum(cash, cashless, token) (optional) Example: paid
Тип оплаты
since: string (optional) Example: 2018-01-01T00:00:00+03:00
Начало периода (включительно)
until: string (optional) Example: 2018-02-01T00:00:00+03:00
Конец периода (включительно)
local: boolean (optional) Example: 1
Выдача с учетом часовой зоны ТА

Чеки из облачной ККТ ¶

GET https://api.telemetron.net/v2/stats/crt?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": 123,
        "created_at": "2019-12-20 09:54:57+00",
        "input": {
            "place": "ТЦ",
            "digest": "9dc54a44a8c3787231312b03a3c0d1db",
            "address": "Мира пр 24б",
            "payments": [
                {
                    "type": 2,
                    "amount": 45
                }
            ],
            "terminal": "000111",
            "positions": [
                {
                    "qty": 1,
                    "vat": 4,
                    "name": "Ореховый Мока",
                    "price": 45
                }
            ]
        },
        "output": {
            "fp": "2046793736",
            "date": "20191217T155100",
            "device_rn": "0000000000028583",
            "fs_number": "9999078900006831",
            "document_type": 1,
            "document_number": 82,
            "total_payment_amount": "45.00"
        },
        "aux": [
            "vm_inventory_number": "ABC-0123",
            "product_inventory_number": "ABC-0123"
        ]
    }
]

Чеки из облачной ККТ
GET`/v2/stats/crt{?vm_id,since,until}`

Статистика по чекам, полученным из облачной ККТ.

Если since и until не указаны, то по умолчанию берётся текущий календарный день.
Если vm_id не указан, то статистика выводится по всем доступным автоматам.

Атрибут	Описание	Возможные значения
`id`	Уникальный идентификатор чека в системе Телеметрон.
`vm_id`	Торговый автомат.
`created_at`	Дата создания чека в системе Телеметрон.
Атрибуты чека `input`
`input.digest`	Уникальный идентификатор чека в облачной кассе.
`input.place`	Место расчётов.	Значение задается в настройках места установки ТА. Это конкретная точка, на которой установлен автомат, например, "Холл на 1 этаже".
`input.address`	Адрес расчётов.	Значение задается в настройках места установки ТА.
`input.terminal`	Серийный номер ТА.	Значение берется из настроек ТА.
Список платежей `input.payments`
`input.payments.*.type`	Тип оплаты	Cумма по чеку наличными Cумма по чеку электронными
`input.payments.*.amount`	Сумма платежа
Список позиций `input.positions`
`input.positions.*.qty`	Кол-во
`input.positions.*.vat`	Ставка НДС	Значение берется из планограммы. Cтавка НДС 20% Cтавка НДС 10% Cтавка НДС 0% НДС не облагается Cтавка НДС расч. 20/120 Cтавка НДС расч. 10/110
`input.positions.*.name`	Наименование	Значение берется из планограммы.
`input.positions.*.price`	Цена
Фискальные данные чека `output`
`output.fp`	Фискальный признак документа.	Возвращает облачная касса.
`output.date`	Дата и время формирования документа.	Возвращает облачная касса.
`output.device_rn`	Регистрационный номер устройства.	Возвращает облачная касса.
`output.fs_number`	Номер фискального накопителя, в котором сформирован документ.	Возвращает облачная касса.
`output.document_type`	Тип чека	Возвращает облачная касса. Приход Возврат прихода Расход Возврат расхода
`output.document_number`	Номер фискального документа.	Возвращает облачная касса.
`output.total_payment_amount`	Итог чека.	Возвращает облачная касса.
Дополнительная мета-информация `aux`
`aux.inventory_number`	Инвентарный номер ТА.	Значение берется из настроек ТА.
`aux.product_inventory_number`	Инвентарный номер продукта.	Значение берется из настроек продукта.

URI Parameters

HideShow

vm_id: number (optional) Example: 123
VM ID
since: string (optional) Example: 2018-01-01T00:00:00+03:00
Начало периода (включительно)
until: string (optional) Example: 2018-02-01T00:00:00+03:00
Конец периода (включительно)

Чеки коррекции из облачной ККТ ¶

GET https://api.telemetron.net/v2/stats/crt/correction?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": 123,
    "created_at": "2019-12-20 09:54:57+00",
    "input": {
      "type": "1",
      "vats": [
        {
          "type": 1,
          "amount": "4.17"
        },
        {
          "type": 2,
          "amount": "0"
        },
        {
          "type": 3,
          "amount": "0"
        },
        {
          "type": 4,
          "amount": "0"
        }
      ],
      "place": "ТЦ",
      "digest": "9dc54a44a8c3787231312b03a3c0d1db",
      "reason": {
        "doc_date": "2019-07-23",
        "doc_name": "КАССОВЫЙ ЧЕК №1",
        "doc_number": "1"
      },
      "address": "Мира пр 24б",
      "payments": [
        {
          "type": 1,
          "amount": "25"
        },
        {
          "type": 2,
          "amount": "0"
        }
      ],
      "terminal": "I12345679",
      "correction_type": "0"
    },
    "output": {
      "fp": "2046793736",
      "inn": "7805629524",
      "date": "20190723T123600",
      "device_rn": "0000000000028583",
      "fs_number": "9999078900006831",
      "document_type": 1,
      "document_number": 4,
      "total_payment_amount": "0.00"
    },
    "aux": []
  }
]

Чеки коррекции из облачной ККТ
GET`/v2/stats/crt/correction{?vm_id,since,until}`

Статистика по чекам коррекции, полученным из облачной ККТ.

Статистика по чекам, полученным из облачной ККТ.

URI Parameters

HideShow

vm_id: number (optional) Example: 123
VM ID
since: string (optional) Example: 2018-01-01T00:00:00+03:00
Начало периода (включительно)
until: string (optional) Example: 2018-02-01T00:00:00+03:00
Конец периода (включительно)

Планограммы ¶

Планограмма - набор продуктов и рецептов, связанных с торговым автоматом. Как правило, планограмма содержит только составные продукты (рецепты), если она относится к кофейным автоматам. Либо содержит только простые продукты, если она относится к снековым автоматам.

Однако, возможна ситуация, когда ТМ может содержать как продукты, так и рецепты (автомат - комбо или спарка).

Дополнительно ТМ содержит такие данные, как вместимость и уровень критической загрузки компонентов, а также номера товарных позиций, т.н. layout продуктов на автомате (т.е. какие продукты соответствуют каким номерам спиралей или кнопок).

CapacityItem Вместимость и критический порог загрузки.

Для любого ингредиента вместимость может быть не указана вообще.

component_id : number - id ингредиента
capacity : number - макс. вместимость ингредиента (в ед. изм. ингредиента)
critical : number - критический порог загрузки ингредиента (может быть не указана)

ProductsArray Список продуктов, составляющих планограмму.

Array of
- id : number - id продукта
- components : array - список составляющих компонентов
  - id : number - id компонента
  - volume : number - объем/количество компонента в его ед. изм.

ProductLayout Соответствие продуктов товарным позициям (номера кнопок, спиралей).

Array of
- product_id : number - id продукта
- number : string - обозначение спирали или номера кнопки
- price: number - цена продукта в планограмме

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

Получить список всех планограмм из личного кабинета компании.

По умолчанию возвращается просто список с названиями. Но с параметром full в ответ будет добавлена подробная информация о составе планограммы. Это полезно при первоначальной синхронизации/составлении справочников данных, чтобы не дергать в цикле ресурс /planograms/{id}.

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": "Универсальная 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": "Планограмма для новых автоматов",
    "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": "Непустая беззагрузочная"
  }
]

Полный список
GET`/v2/planograms{?full}`

Attributes

Array of
- id : number - id планограммы
- name : string - Наименование планограммы

URI Parameters

HideShow

full: string (optional) Example: 1
добавлять ли в ответ подробную информацию о составе планограммы (layout, capacity, products).

Планограмма ¶

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

Responses200

Headers

Content-Type: application/json

Body

{
  "id": 1267
  "name": "Универсальная 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",
      price: 20
    },
    {
      product_id: 900,
      number: "AA",
      price: 25
    },
    {
      product_id: 900,
      number: "AB",
      price: 0
    },
    {
      product_id: 900,
      number: "AC",
      price: 15
    }
  ]
}

Подробная информация о планограмме
GET`/v2/planograms/{id}`

Включается также информация о “емкости” ингредиентов (макс. вместимость и критический порог загрузки), а также список всех продуктов/рецептов, составляющих планограмму.

Attributes

id : number - id планограммы
name : string - название
capacity : array of CapacityItem - Вместимость ингредиентов
products : ProductsArray - Состав (рецепты) продуктов
layout : ProductLayout - Список товарных позиций

URI Parameters

HideShow

id: number (required) Example: 123
VM ID

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

RequestsСозданиеСоздание и привязка к ТА

Body

{
  "name": "Новая планограмма",
  "mode": "snack",
  "products": [
    {
      "id": 2230,
      "number": 2,
      "capacity": 14,
      "price": 10
    },
    {
      "id": 2218,
      "number": 3,
      "capacity": 88,
      "price": 35
    },
    {
      "id": 2243,
      "number": "4A",
      "capacity": 11,
      "price": 21
    }
  ]
}

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": "Новая планограмма для ТА",
  "mode": "snack",
  "assign": 10042,
  "products": [
    {
      "id": 2230,
      "number": 2,
      "capacity": 14,
      "price": 21
    },
    {
      "id": 2218,
      "number": 3,
      "capacity": 88,
      "price": 24
    }
  ]
}

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."
    ]
  }
}

Новая планограмма
POST`/v2/planograms`

В данный момент поддерживается только один режим создния новой планограммы - snack. В этом режиме задается название и список продуктов.

Attributes

name: string, required - Название
mode: enum[snack, basic], required - Режим создания планограммы
assign: number, optional - Номер торгового автомата
products: array of
- id: number, required - ID продукта
- number: string, required - Номер кнопки, спирали, ячейки или полки, где расположен продукт
- capacity: number, required - Вместимость ингредиентов
- critical: number, optional - Критический порог
- price: number, optional - Цена, от 0 до 999999

Если задан атрибут assign, новая планограмма будет привязана к указанному ТА.

Если у ТА ранее была назначена планограмма и была указана какая-либо загрузка, то все продукты на спиралях, которых нет в новой планограмме, будут автоматически выгружены с записью в историю изменений (такая же логика, которая работает в Личном кабинете при изменении планограммы торгового автомата).

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

Responses200

Headers

Content-Type: application/json

Body

{
  "res": true
}

Удаление планограммы
DELETE`/v2/planograms/{id}`

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

URI Parameters

HideShow

id: number (required) Example: 123
ID планограммы

Продукты ¶

Данный ресурс предоставляет список продукции из личного кабинета. Продукция включает в себя как продукты, так и рецепты.

Продукт – это то, что продается в автомате и не включает в себя ингредиенты. Например, шоколадный батончик.

Рецепт - это то, что состоит из ингредиентов и готовится в самом торговом автомате, как, например, эспрессо или пицца.

НДС используется, когда данные о продажах продукции регистрируются при помощи ККТ.
Значение задается в процентах, например “20” или “12.5”.

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

Responses200

Headers

Content-Type: application/json

Body

[
  {
    id: 1932,
    composite: true,
    name: "Сливочный мокка ореховый",
    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",
    vat: 12.5
  },
  {
    id: 1933,
    composite: true,
    name: "Пустой стакан",
    components: [
      {
      volume: 1,
        id: 1548
      }
    ],
    inventory_number: "B2-2018",
    vat: 20
  },
  {
    id: 22816,
    composite: false,
    name: "Батончик Bounty",
    components: [
      {
      volume: 1,
        id: 20839
      }
    ],
    inventory_number: "B3-2018",
    vat: 20
  },
  {
    id: 22817,
    composite: false,
    name: "Батончик KitKat",
    components: [
      {
      volume: 1,
        id: 20840
      }
    ],
    inventory_number: "B4-2018",
    vat: 20
  }
]

Полный список
GET`/v2/products`

Справочник всех продуктов из личного кабинета компании.

Attributes

Array of
- id : number - id продукта
- name : string - название
- composite : boolean - продукт составной (т.е. рецепт) или нет
- components : Components - список составляющих продукт ингредиентов
- inventory_number : string - инвентарный номер
- vat : number - значение НДС в процентах (используется при регистрации фискальных чеков)

Components

Array of
- id : number - id ингредиента
- volume: number - объем/количество ингредиента в его единицах измерения

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

RequestsБазовые атрибутыНовый состав рецепта

Body

{
  "name": "Кофе 2.0",
  "note": "Новое описание к Кофе 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": "Ванильный капучино со сливками (версия N)",
  "components": [
    {
      "id": 51661,
      "volume": 6
    },
    {
      "name": "Вода",
      "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."
    ]
  }
}

Изменение продукта (рецепта)
PUT`/v2/products/{id}`

Обновление данных конкретного продукта или рецепта. Используется в основном для изменения названия продукта в печатаемом чеке при подключенной контрольно-кассовой техники (ККТ).

Синхронизация названий ЛК и печатаемом чеке происходит в течение 2-7 минут.

Важно иметь в виду, что изменение названия не затронет имеющуюся статистику продаж, а отразится только на новых продажах.

name : string - Название продукта
note : string - Описание
vat : number - Значение НДС в процентах (используется при регистрации фискальных чеков)

В массиве components указывается новый состав рецепта. Ингредиенты задаются так же, как и при создании рецепта:

Вариант 1 (предпочтительный): id + volume
Вариант 2: name + unit + volume

Если ингредиент найден по id или по name, для него будет установлено новое кол-во volume.
Если ингредиент не найден, но заданы все три поля name, unit и volume, он будет создан “на лету” и добавлен в рецепт.

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

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

name: string, optional - Название рецепта
note: string, optional - Описание
components: array - Список ингредиентов для рецепта
- id: number, optional - ID ингредиента
- name: string, optional - Название ингредиента
- volume: number, reuired - Кол-во ингредиента
- unit: enum(1, 2, 3), optional - Единица измерения
vat: number - НДС
inventory_number: string, optional - Инвентарный номер
vat : number, optional - Значение НДС в процентах

URI Parameters

HideShow

id: number (required) Example: 123
ID продукта

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

RequestsСоздание продуктаСоздание рецепта

Body

{
  "composite": false,
  "name": "Сникерс 75гр"
}

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": "Американо 100 мл",
  "composite": true,
  "components": [
    {
      "name": "Вода",
      "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."
    ]
  }
}

Новый продукт
POST`/v2/products`

Этот ресурс отвечает за создание продуктов, при composite = false. Или рецептов, при composite = true.

composite: boolean, required - false
name: string, required - Название продукта
note: string, optional - Описание
vat: number, optional - НДС
inventory_number: string, optional - Инвентарный номер
vat : number, optional - Значение НДС в процентах

composite: boolean, required - true
name: string, required - Название рецепта
note: string, optional - Описание
components: array - Список ингредиентов для рецепта
- id: number, optional - ID ингредиента
- name: string, optional - Название ингредиента
- volume: number, required - Кол-во ингредиента
- unit: enum(1, 2, 3), optional - Единица измерения
vat: number, optional - НДС
inventory_number: string, optional - Инвентарный номер
vat : number, optional - Значение НДС в процентах

Для создания рецепта необходимо указать список ингредиентов в components.
Каждый ингредиент можно задать двумя способами:

Задать ингредиент по id и volume.
Задать ингредиент по name, volume и unit. В этом случае он будет создан, если не найдется по name + unit.

Оба способа можно комбинировать в одном запросе.

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

Responses200

Headers

Content-Type: application/json

Body

{
  "res": true
}

Удаление продукта (рецепта)
DELETE`/v2/products/{id}`

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

URI Parameters

HideShow

id: number (required) Example: 123
ID продукта

Состав рецепта ¶

Этот ресурс позволяет редактировать состав рецепта. Добавляет ингредиенты, менять кол-во, удалять ингредиенты из рецепта.

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

Responses200

Headers

Content-Type: application/json

Body

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

Ингредиенты
GET`/v2/products/{id}/components`

Список ингредиентов в рецепте.

Attributes

Array of
- id : number - id ингредиента
- volume : number - кол-во

URI Parameters

HideShow

id: number (required) Example: 123
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."
    ]
  }
}

Новый ингредиент
POST`/v2/products/{id}/components`

Добавляет ингредиент в рецепт.

id: number, required - ID ингредиента
volume: number, required - Кол-во ингредиента

URI Parameters

HideShow

id: number (required) Example: 123
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
}

Изменение ингредиента
PUT`/v2/products/{id}/components/{component_id}`

Изменяет кол-во конкретного ингредиента в рецепте.

volume: number, required - Кол-во ингредиента

URI Parameters

HideShow

id: number (required) Example: 123
ID продукта
component_id: number (required) Example: 42
ID компонента

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

Responses200

Headers

Content-Type: application/json

Body

{
  "res": true
}

Удаление ингредиента
DELETE`/v2/products/{id}/components/{component_id}`

Исключает конкретный ингредиент из состава рецепта.

URI Parameters

HideShow

id: number (required) Example: 123
ID продукта
component_id: number (required) Example: 42
ID компонента

Компоненты / ингреды ¶

Полный список ингредиентов ¶

В основном этот ресурс нужен при синхронизации данных единожды перед началом работы приложения или когда кеш просрочен.

Берется расчет на кеш приложения, поэтому в ресурсе /components/{id} нет большой нужды.

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

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": 18900
    "name": "Йогурт вишневый"
    "is_product": true
    "units": "шт"
  },
  {
    "id": 18985
    "name": "Вода"
    "is_product": false
    "units": "мл"
  },
  {
    "id": 18986
    "name": "Зерновой кофе"
    "is_product": false
    "units": "гр"
  }
]

Полный список
GET`/v2/components`

Справочник всех ингредиентов из личного кабинета компании.

Attributes

Array of
- id : number - id ингредиента
- name : string - название
- is_product : boolean - обозначает ли ингредиент одноименный продукт
- units : enum('мл', 'шт', 'гр') - единицы измерения

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

Requestsexample 1

Body

{
  "name": "Стаканчик",
  "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."
    ]
  }
}

Новый ингредиент
POST`/v2/components`

name: string, required - Название
unit: enum(1, 2, 3), required - Единица измерения

Места установки ¶

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

Место установки - это конкретная точка, на которой установлен автомат, например, “Холл на 1 этаже” по адресу “Таежная, 41”.

На одном месте установки может быть установлен только один автомат (спарка считается одним автоматом).

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

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": 1,
    "name": "БЦ Конфетка",
    "address": "Большая Посадская, 1",
    "note": "на столе"
  },
  {
    "id": 2,
    "name": "McBryde's Pub",
    "address": "Таежная, 41",
    "note": "справа от левого окна"
  },
  {
    "id": 3,
    "name": "Musta Kissa ravintola",
    "address": "Большая Посадская, 15",
    "note": "на лестнице"
  }
]

Полный список
GET`/v2/locations`

Список всех доступных мест установки.

Attributes

Array of
- id : number - ID
- name : string - Название места
- address : string - Адрес
- note: string - Комментарий

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

RequestsТолько название

Body

{
  "name": "БЦ Сапфир",
  "address": "Таежная, 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."
    ]
  }
}

Изменение данных
PUT`/v2/locations/{id}`

Доступные поля:

name : string - Название места
address : string - Адрес
note: string - Комментарий

URI Parameters

HideShow

id: number (required) Example: 1
ID места установки

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

Requestsexample 1

Body

{
  "name": "БЦ Конфетка",
  "address": "Большая Посадская, 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."
    ]
  }
}

Новое место установки
POST`/v2/locations`

name: string, required - Название
address: string, required - Адрес
note: string, optional - Комментарий

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

Responses200

Headers

Content-Type: application/json

Body

{
  "res": true
}

Удаление локации
DELETE`/v2/locations/{id}{?force}`

Удалить место установки возможно в том случае, если оно не назначено ни одному торговому автомату. Однако, если с местом установки не связана какая-либо статистика или она не ведется, можно использовать параметр force для обхода этого правила.

URI Parameters

HideShow

id: number (required) Example: 1
ID
force: bool (optional) Example: 1
Принудительное удаление

Отчеты ¶

Инкасации ¶

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

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "time": "2021-06-10T09:41:56+03:00",
    "vm_id": 123,
    "hands_add": 100,
    "change": 0,
    "summary_coins": 150,
    "summary_banknotes": 3000
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "time": {
        "type": "string"
      },
      "vm_id": {
        "type": "number"
      },
      "hands_add": {
        "type": "number",
        "description": "Сумма сдачи, которую оператор загрузил в монетоприемник с момента предыдущей инкассации (только та сдача, которая загружена в монетоприемник в режиме \"загрузка сдачи\")"
      },
      "change": {
        "type": "number",
        "description": "Сумма сдачи в автомате на момент инкассации."
      },
      "summary_coins": {
        "type": "number",
        "description": "Сумма проинкассированных монет."
      },
      "summary_banknotes": {
        "type": "number",
        "description": "Сумма проинкассированных купюр."
      }
    }
  }
}

Инкасации
GET`/v2/reports/collections{?since,until}`

В данном отчете отражена информация по всем инкассациям всех автоматов за указанный промежуток времени.

Подробное описание логики работы инкассаций см. в справочном центре

Array of
- time: string - Время инкассации. Напр. 2021-06-10T09:41:56+03:00
- vm_id: number - Номер автомата
- hands_add: number Сумма сдачи, которую оператор загрузил в монетоприемник с момента предыдущей инкассации (только та сдача, которая загружена в монетоприемник в режиме “загрузка сдачи”)
- change: number - Сумма сдачи в автомате на момент инкассации.
- summary_coins: number - Сумма проинкассированных монет.
- summary_banknotes: number - Сумма проинкассированных купюр.

URI Parameters

HideShow

since: string (optional) Example: 2018-01-01T00:00:00+03:00
Начало периода (включительно)
until: string (optional) Example: 2018-01-02T00:00:00+03:00
Конец периода (включительно)

Additional ¶

Dev links

API Blueprint tutorial: https://github.com/apiaryio/api-blueprint/blob/master/Tutorial.md

Examples: https://github.com/apiaryio/api-blueprint/tree/master/examples

http://blog.apiary.io/2013/02/20/New-API-Blueprint-Format-Basics/

https://help.apiary.io/api_101/api_blueprint_tutorial/

Generated by aglio on 19 Nov 2024

API Endpoint

Overview ¶

Authorization ¶

Schema ¶

Parameters ¶

Errors (Ошибки) ¶

Time stamps (обозначение времени) ¶

Authorization ¶

Access token ¶

Body

Schema

Headers

Body

Body

Schema

Headers

Body

Get new access tokenPOST/auth/

Initial authorization ¶

Get new pair of tokens ¶

Logout ¶

Headers

Body

Logout and expire tokenGET/logout

Definitions ¶

Торговый автомат (VendingMachine) ¶

Типы ТА ¶

Состояния ТА ¶

Место установки (Location) ¶

Планограмма (Planogram) ¶

Компания ¶

Реквизиты ¶

Headers

Body

Schema

РеквизитыGET/v2/requisites

Пользователь ¶

Текущий пользователь ¶

Headers

Body

Полная информацияGET/v2/me

Attributes ¶

Модемы ¶

Полный список модемов ¶

Headers

Body

Полный списокGET/v2/modems

Attributes ¶

Модем ¶

Headers

Body

Schema

Подробная информация о модемеGET/v2/modems/{id}

Body

Headers

Body

Headers

Body

Изменение модемаPUT/v2/modems/{id}

Body

Headers

Body

Отправка команд модемуPOST/v2/modems/{id}/set

Торговые автоматы ¶

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

Headers

Body

Полный списокGET/v2/vending_machines{?local}

Attributes ¶

Торговый автомат ¶

Headers

Body

Schema

Подробная информация о ТАGET/v2/vending_machines/{id}

Attributes ¶

Body

Headers

Body

Headers

Body

Overview

Authorization

Schema

Parameters

Errors (Ошибки)

Time stamps (обозначение времени)

Get new access token
POST`/auth/`

Initial authorization

Get new pair of tokens

Logout and expire token
GET`/logout`

Торговый автомат (VendingMachine)

Типы ТА

Состояния ТА

Место установки (Location)

Планограмма (Planogram)

Реквизиты
GET`/v2/requisites`

Полная информация
GET`/v2/me`

Attributes

Полный список
GET`/v2/modems`

Attributes

Подробная информация о модеме
GET`/v2/modems/{id}`

Изменение модема
PUT`/v2/modems/{id}`

Отправка команд модему
POST`/v2/modems/{id}/set`

Полный список
GET`/v2/vending_machines{?local}`

Attributes

Подробная информация о ТА
GET`/v2/vending_machines/{id}`

Attributes

Создание ТА
POST`/v2/vending_machines{?force}`

Атрибуты для создания ТА

Изменение ТА
PUT`/v2/vending_machines/{id}{?force}`

События
GET`/v2/vending_machines/{vm_id}/events{?since,until,local}`

Отчеты
GET`/v2/vending_machines/{vm_id}/reports{?since,until,cp1251,base64,port,local}`

Перезагрузка модема
POST`/v2/vending_machines/{id}/reset`

Выдача напитка
POST`/v2/vending_machines/{vm_id}/dispense`

Начислить кредит
POST`/v2/vending_machines/{vm_id}/vendista-credit`

Текущая загрузка ТА
GET`/v2/vending_machines/{id}/loading`

Attributes

Сделать загрузку ТА
POST`/v2/vending_machines/{id}/loading`

Request body

Инвентаризация
POST`/v2/vending_machines/{id}/inventory`

Атрибуты для инвентаризации