¶ TDTP (Telemetron Data Transfer Protocol, протокол Telemetron)
Передача данных телеметрии терминалов Vendista
¶ 1. Общее описание
¶ 1.1. Основная информация
TDTP (Telemetron Data Transfer Protocol, протокол Telemetron) - протокол передачи данных, построенный поверх протокола HTTP и служащий для приема данных телеметрии от исполнительных устройств. Все запросы выполняются методом POST на адрес API партнера с передачей параметров в формате application/x-www-form-urlencoded.
При запросе интеграции будет запущен сервис на сервере Vendista, отправляющий пакеты данных в формате данного протокола. При запросе интеграции необходимо сообщить: URL адрес api партнера, параметры для авторизации и подписи пакетов.
|
Параметр |
Тип |
Значение |
|
URL |
string |
Адрес API, на который будут направляться POST запросы с данными пакетов |
|
X-Key |
string |
Ключ авторизация для приема данных. |
|
IDENT |
string |
Строка, которая добавляется в начало каждой подписи s. |
|
Key |
string |
Закрытый ключ для генерации подписи s. |
¶ 1.2. Заголовки пакета
Любой пакет данных содержит следующие обязательные заголовки:
|
Заголовок |
Тип |
Значение |
|
Content-Type |
string |
application/x-www-form-urlencoded |
|
Content-Length |
integer |
Размер содержимого данных пакета в байтах |
|
X-Key |
string |
Ключ авторизация для приема данных. |
Интеграция Vendista использует аутентификацию по ключу, передаваемому в заголовке X-Key. Ключ используется один на всю интеграцию. Ключ генерируется самостоятельно и передается в Vendista при подключении интеграции.
¶ 1.3. Тело пакета
Каждый пакет содержит минимум три параметра:
|
Параметр |
Тип |
Значение |
|
imei |
string |
Идентификатор устройства. 15-значный IMEI терминала Vendista. |
|
time |
string |
Время формирования пакета. |
|
s |
string |
Подпись пакета. Указывается последним параметром пакета |
Кроме трех обязательных параметров, пакет может содержать три необязательных параметра, которые информируют о статусе устройства:
|
Параметр |
Тип |
Значение |
|
mdb |
string |
mdb=ok если с шиной MDB все нормально, mdb=error если есть ошибки:
|
|
bat |
integer |
bat=50 при ошибке питания. Значение не изменяется. При отсутствии ошибки питания, параметр не используется |
|
qlt |
integer |
текущий уровень связи (диапазон 0-32, где 32 - это наилучшее качество) |
Имеются также и другие параметры, которые относятся к различным типам пакетов. Подробнее о них в пт. 2. Пакеты.
¶ 1.4. Ответ на запрос
При отправке каждого пакета интеграция ожидает ответ от сервера партнера. При получении статуса ответа 200 и значение параметра status=ok в теле пакета, то такой пакет считается доставленным в системе Vendista. При получении статуса ответа отличного от 200 и отсутствия параметра status=ok, или вовсе отсутствие ответа от сервера, интеграция будет отправлять пакет повторно.
Заголовки:
|
Заголовок |
Тип |
Значение |
|
Status |
integer |
200 |
|
Content-Type |
string |
text/html |
Тело ответа:
|
Параметр |
Тип |
Значение |
|
time |
string |
Время формирования ответа. |
|
status |
string |
ok |
Пример положительного ответа:
HTTP/1.1 200 OK
Date: Thu, 1 Jan 2020 00:00:00 GMT
Server: nginx
Content-Type: text/html
time=2022-01-01 03:00:00&status=ok
¶ 2. Пакеты
¶ 2.1 Пинг
Пинг используется как индикатор того, что устройство находится на связи и работает исправно. Также пинг необходим для того, чтобы устройство периодически проверяло нет ли для него каких-либо запросов от сервера, например запрос отчета EvaDTS.
Пинг кроме обязательных параметров (imei, time) должен содержать параметр reason со значением ping.
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: <...>
X-Key: <...>
imei=111111111111111&time=2022-04-04 06:12:23&mdb=ok&reason=ping&qlt=31&s=009J7VD37120F5F438F4DA
¶ 2.2 Продажа
Пакет продажи имеет все те же параметры, что и пинг с добавлением параметра mdb_product[], который фиксирует факт продажи. Значение mdb_product[] передается в формате <num>, <price>, <time>, <name>, <payment>.
|
Параметр |
Тип |
Значение |
|
num |
string |
Номер ценовой линии проданного товара. Например, 12 |
|
price |
float/string |
Цена продажи. При бесплатной продаже принимает значение free. Например, 120.0, 4.45 или free |
|
time |
string |
Время продажи в ISO формате (или в коротком YYYY-MM-DD HH:mm:ss). Например, 2020-12-31 23:58:22 |
|
name |
string |
Название товара (опционально) |
|
payment |
string |
Способ оплаты: cash, cashless. |
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: <...>
X-Key: <...>
imei=111111111111111&time=2022-04-04 06:12:23&mdb=ok&reason=ping&mdb_product[]=3,60.00,2022-04-04 06:12:23,Item,cash&s=00I21M5D08D39ABBC549A0
Получение фискальных данных чека
После отправки пакета о продажи, интеграция будет ожидать фискальные данные для отображения QR-кода чека. Получение фискальных данных строится по следующему алгоритму:
- Интеграция отправляет пакет о продаже mdb_product[]
- Сервер партнера в ответ присылает идентификатор продажи в параметре vend_tx_id (vend_tx_id=BE0A99124AB76FF43A61D485C3EB9EB7).
- Интеграция запрашивает фискальные данные, добавляя этот же параметр и значение в пинг-пакет.
- Если всё готово, сервер партнера возвращает фискальные данные в параметре fiscal (fiscal=t%3D20190520T1356%26s%3D4.02%26fn%3D9999078900001341%26i%3D2853%26fp%3D599041704%26n%3D1).
Время опроса ~1 минута после продажи с периодичностью один раз в 5-10 сек.
Пример ответа на продажу:
HTTP/1.1 200 OK
Date: Thu, 1 Jan 2020 00:00:00 GMT
Server: nginx
Content-Type: text/html
time=2022-04-02 12:13:16&vend_tx_id=4EF41B38C1EF3F0C800F262577EF54FB&s=B211F0D0C8269B74993A12&status=ok
Пример запроса фискальных данных:
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: <...>
X-Key: <...>
imei=111111111111111&time=2022-04-02 12:13:13&mdb=ok&qlt=30&reason=ping&vend_tx_id=4EF41B38C1EF3F0C800F262577EF54FB&s=B2EIR602C47D39762A441B
Пример ответа с фискальными данными:
HTTP/1.1 200 OK
Date: Thu, 1 Jan 2020 00:00:00 GMT
Server: nginx
Content-Type: text/html
time=2022-04-02 12:13:22&fiscal=t%3D20220402T121300%26s%3D80.00%26 fn%3D9999078900001341%26i%3D2853%26fp%3D599041704%26n%3D1s=B2BA6B09A2A9EC3D17FC66&status=ok
¶ 2.3 События при обслуживании ТА
Обслуживание ТА — это намеренное действие оператора, которое он обозначает нажатием соответствующей кнопки на терминале. Данный пакет информирует о нажатии таких кнопок.
|
Параметр |
Тип |
Значение |
|
evadts |
string |
Пустая строка. Пакет о событиях при обслуживании не передает отчет evadts |
|
reason |
string |
button |
|
events |
string |
Событие, которое стало причиной отправки пакета. Обслуживание TSER Инкассация TIO Загрузка ингредиентов TLOA |
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: <...>
X-Key: <...>
imei=111111111111111& time=2022-04-02 12:13:22&evadts=&mdb=ok&qlt=10&reason=button&events=TSER&s=B2EIR602C47D39762A441B
¶ 2.4 Пакет EvaDTS отчет
Если в каком-либо ответе сервера содержится get=evadts или get=report, то интеграция отправит команду на снятие EvaDTS отчета терминалу. Когда отчет от терминала будет полностью получен, интеграция отправит пакет отчета в формате base64string.
|
Параметр |
Тип |
Значение |
|
evadts_base64 |
string |
Содержимое отчета в формате base64 |
|
reason |
string |
server-evadts |
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: <...>
X-Key: <...>
imei=111111111111111& time=2022-04-02 12:13:22&evadts_base64=<...>&qlt=15&reason=server-evadts&s=B2EIR602C47D39762A441B
¶ 2.5 Движение наличных в ТА
При поступлении денежных средств в монетоприемник или купюропримник отправляются данные о поступивших денежных средствах, а также общие данные о наличных в монетоприемнике и купюропримнике ТА.
|
Параметр |
Тип |
Значение |
|
evadts |
string |
Содержимое отчета |
|
reason |
string |
coin |
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: <...>
X-Key: <...>
imei=111111111111111& time=2022-04-02 12:13:22 &mdb=ok&qlt=31&reason=coin&evadts=DXS*DEL0000000*VA*V0/6*1
ST*001*0001
CA3*****21144700*1703600*8239100***11202000**
CA17*0*100*90***
CA17*1*200*0***
CA17*2*500*146***
CA17*3*1000*89***
CA17*4*1000*0***
G85*4A93
SE*1*0001
DXE*1*1&s=B2Q9Q1ECAFC18FE268B4A0
¶ 2.6 События ТА и терминала
Помимо событий обслуживания ТА существуют и другие события связанные с ТА и терминалом Vendista. Информирование о событии помещается в поле reason. Перечень событий, которые передаются по протоколу:
- Включение ТА (enable)
- Выключение ТА (disable)
- Подключение питания (poweron)
- Отключение питания/ошибка питания (poweroff)
- Перезагрузка терминала (reset)
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: <...>
X-Key: <...>
imei=111111111111111&time=2022-04-20 06:52:48&mdb=ok&qlt=29&reason=reset&s=B2N80XBBDA18F876CD3D61
¶ 2.7 Конфигурационный пакет
Если в каком-либо ответе сервера содержится get=config, то сервер Vendista отправит конфигурационный пакет. Помимо обязательных полей данный пакет содержит два дополнительных:
- Версия терминала (version)
- Номер телефона симкарты модема (simnumber)
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: <...>
X-Key: <...>
imei=111111111111111&time=2022-04-10 16:15:10&mdb=ok&qlt=10&version=83&simnumber=+71234567890