Описание протокола работы терминального ПО

Регистрация терминала
Запрос к API для регистрации терминала имеет следующий формат
https://<адрес сервера>/gen_key?terminalId=xxx&terminalHash=xxx&closeCycle=xxx

Запросы необходимо отправлять по протоколу HTTPS. Параметры разделяются амперсандами (&). Некоторые параметры являются обязательными, другие – нет. Ниже представлен список параметров.

terminalId– ID терминала, который вы хотите зарегистрировать,
terminalHash– идентификатор оборудования,
closeCycle – указывает, закрывать ли смену. Допустимые значения – true или false. Этот параметр является необязятельным, значение по умолчанию false.

Для аутентификации каждый запрос должен содержать заголовок Authorization следующего вида – Authorization: Basic <login>:<password> в кодировке base64.

login – идентификтор пользователя следующего формата <username>@<dealerId>, где
username– имя пользователя,
dealerId – ID агента,
password – пароль пользователя.

Ответ возвращается в формате JSON. Ниже приведен пример ответа при неудачной попытке регистрации терминала
{
"error":{
"errorCode" : 103,
"errorMessage" : "Регистрация терминала запрещена"
}
}

errorCode – код ошибки,
errorMessage– текст ошибки.

Если терминал успешно зарегистрирован, в ответе возвращается сертификат, который в последствии будет использоваться для клиентской SSL аутентификации.
{
"local" : "-----BEGIN "CERTIFICATE-----\nMIICwIBMM<.................>gLV930zwCKjhS9XDpqm7w==\n----- END CERTIFICATE-----",

"private_key" : "-----BEGIN PRIVATE KEY-----\nMIICdgIBADANBgkCqhhS9KjhS9qhk<.................>F5xeCKjhS9XA==\n----- END PRIVATE KEY-----"
}

local– клиентский сертификат в PEM формате,
private_key– приватный ключ.

Для всех остальных запросов требуется HTTP Basic- и клиентская SSL аутентификация. Для этого каждый запрос должен содержать HTTP заголовок Authorization и клиентский SSL сертификат, полученный при регистрации.
Авторизация пользователя
Формат запроса
https://<адрес сервера>/login

Аутентификация: HTTP Basic + SSL client.

Ответ в случае успешной авторизации
{
"dealerId" : 3002,
"login" : admin,
"lastCycleNumber" : 1,
"dealerInfo" : {
"inn" : "656464684984984",
"phone" : "9508718681",
"email" : "rrt@rer.ru",
"address" : "ул. Убей-коня, д. 12, кв 674",
"name" : "qweqweqwe"
},
"maxCheckNumber" : 148,
"roles" : [PERM_USER_CREATE, ..., PERM_TERMINAL_SETUP]
}

dealerId– ID агента,
login– имя пользователя,
roles– список ролей и разрешений пользователя,
lastCycleNumber– номер последеней закрытой смены,
maxCheckNumber– последний номер чека,
dealerInfo– информация обагенте,
inn– ИННагента,
phone– телефонагента,
email– почтаагента,
address– адресагента,
name– имяагента.

При неудачной попытке авторизации возвращается стандартный ответ (код и текст ошибки).

Запрос списка провайдеров, доступных для проведения
Формат запроса
https://<адрес сервера>/get_provider_ids

Аутентификация: HTTP Basic + SSL client.

В случае успешного выполнения запроса возвращается список идентификаторов провайдеров в JSON формате.

[1,3,15,...,16,19]

Запрос списка провайдеров
Формат запроса
https://<адрес сервера>/get_providers?lastObjVersion=xxx&lastId=xxx&count=xxx
lastObjVersion– версияпоследнего загруженного провайдера,
lastId– ID последнего загруженного провайдера,
count – максимальное количество записей в ответе.

Аутентификация: HTTP Basic + SSL client.

Пример ответа

{
"id": 50002698,
"name": "тестовый провайдер 777",
"address": "4",
"aliases": "провайдер 777",
"blocked": false,
"checkName": "Платежи по свободным реквизитам",
"description": "7",
"groupId": 19,
"groupName": "Бюджетные платежи",
"imageFileName": null,
"imageHash": null,
"inn": "2",
"legalName": "1",
"noBonus": false,
"noFiscalDoc": false,
"phones": "5",
"printTwoSplittedDoc": false,
"region": "3",
"services": "",
"site": "6",
"splitByCommission": false
"objVersion": 9161,
"barcode": {
"itm": [
{
"inter": [
{
"f": 88,
"s": 55
}
],
"pos": {
"f": 15,
"s": 22
}
}
]
},
"parameters": [
{
"barcodeFinish": null,
"barcodeStart": null,
"checkLabel": "Расчетный счет",
"id": 8715,
"items": [],
"keyboardLanguage": null,
"keyboardLayout": null,
"keyboardType": "number",
"kind": 0,
"label": "Введите расчетный счет",
"mask": "09999999999999999999",
"name": "account",
"pos": 0,
"printInCheck": true,
"providerId": 50002698,
"regExp": "^\\d{1,20}$",
"useInOnlineCheck": false,
"value": null,
"values": {
}
},
{
"barcodeFinish": null,
"barcodeStart": null,
"checkLabel": "Назначение платежа",
"id": 8727,
"keyboardLanguage": null,
"keyboardLayout": null,
"keyboardType": "full",
"kind": 2,
"label": "Назначение платежа",
"mask": null,
"name": "reason",
"pos": 12,
"printInCheck": true,
"providerId": 50002698,
"regExp": "^[A-Za-zА-Яа-яёЁ\\- \\d ]{1,100}$",
"useInOnlineCheck": false,
"value": null,
"values": {},
"items": [
{
"barcodeFinish": null,
"barcodeStart": null,
"checkLabel": "param1",
"id": null,
"items": [],
"keyboardLanguage": null,
"keyboardLayout": null,
"keyboardType": null,
"kind": null,
"label": "param1",
"mask": "8-(000)-000-00-00",
"name": "param1",
"pos": 0,
"printInCheck": true,
"providerId": 50002698,
"regExp": "^\\d{10}$",
"useInOnlineCheck": false,
"value": null,
"values": {
"param3333": "33333"
}
},
{...}
]
},
{
"barcodeFinish": null,
"barcodeStart": null,
"checkLabel": "Дополнительная информация",
"id": 8729,
"items": [],
"keyboardLanguage": null,
"keyboardLayout": null,
"keyboardType": null,
"kind": 1,
"label": "Дополнительная информация",
"mask": null,
"name": "extra",
"pos": 14,
"printInCheck": true,
"providerId": 50002698,
"regExp": null,
"useInOnlineCheck": false,
"value": null,
"values": {
"значение1": "11",
"значение2": "22"
}
},
{...}
]
}

Список полей провайдера:
id – ID провайдера,groupId – ID группы провайдера,groupName – название группы провайдера,
name – название провайдера,aliases – дополнительное название провайдера (используется для поиска),services – текстовое поле со списком услог для дополнительной информации,region – регион,legalName – юридическое лицо,checkName – название на чеке,description – описание,inn – ИНН,address – адрес,site – сайт,imageFileName – имя файла с логотипом,imageHash – хэш файла с логотипом,phones – телефоны,noFiscalDoc – не печатать фискальный чек,noBonus – без бонуса,splitByCommission – для совместимости со старыми терминалами; не используется,printTwoSplittedDoc – для совместимости со старыми терминалами; не используется,
fixedSumm – фиксированная сумма платежа по провайдеру,blocked – провайдер заблокирован,objVersion – версия изменений настроек провайдера,
barcode – настройки разбора штрихкода для определения провайдера,
itm – список диапазонов значений,
pos – позиция кода провайдера в штрихкоде (s – первая цифра кода провайдера,f – последняя цифра кода провайдера),
inter – список диапазонов значений кода провайдера (s – первое значение,f – последнее значение в диапазоне),
parameters – список параметров провайдера,

Список полей параметра провайдера:
id – ID параметра провайдера,providerId – ID провайдера,name – название,label – заголовок,pos – порядковый номер параметра,checkLabel – заголовок на чеке,regExp – регулярное выражение для проверки значения,mask – маска ввода,value – значение по умолчанию,keyboardType – тип клавиатуры (значения – number, full),keyboardLanguage – язык программной клавиатуры (значения – en, ru),keyboardLayout – раскладка программной клавиатуры (qwerty, abcd, dvorak),useInOnlineCheck – параметр используется в онлайн-проверке,kind – тип параметра (0 – обычный, 1 – список значений, 2 – комплексный),printInCheck – печатать на чеке,barcodeStart – позиция значения параметра в штрихкоде (первый символ),barcodeFinish – позиция значения параметра в штрихкоде (последний символ),items – список вложенных параметров в комплексном параметре,values – список допустимых значений параметра.

Запрос профиля комиссий провайдеров
Формат запроса
https://<адрес сервера>/get_profile

Аутентификация: HTTP Basic + SSL client.

Пример ответа
{
"dealerId": 3002,
"defaultCommissionProfileId": 3485,
"id": 4309,
"name": "тестовый профиль 777",
"items": [
{
"commissionChangeProfileId": 5587,
"commissionProfileId": 5587,
"exclude": false,
"id": 141261,
"profileId": 4309,
"providerGroupId": 0,
"providerId": 1
},
{
"commissionChangeProfileId": 5587,
"commissionProfileId": 5587,
"exclude": false,
"id": 141262,
"profileId": 4309,
"providerGroupId": 0,
"providerId": 50002698
}
]
}

Список полей профиля:
id – ID профиля комиссий провайдеров,
name – название,
dealerId – ID агента,
defaultCommissionProfileId – ID профиля комиссий по умолчанию,
items – список элементов,

Список полей элемента профиля:
id – ID элемента,
profileId – ID профиля комиссий провайдеров,
commissionChangeProfileId – ID профиля комиссий на сдачу,
commissionProfileId – ID профиля комиссий,
exclude – исключить элемент из профиля,
providerGroupId – ID группы провайдеров,
providerId – ID провайдера.

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

Запрос профиля отображения провайдеров
Формат запроса
https://<адрес сервера>/get_form_profiles

Аутентификация: HTTP Basic + SSL client.

Пример ответа
[
{
"id":4,
"dealerId":2001,
"name":"Тестовый профиль",
"imageFileName":null,
"imageHash":null,
"objVersion":1394011682792,
"items":[
{
"id":1626,
"profileId":4,
"title":"МТС Беларусь",
"providerGroupId":null,
"providerId":2566,
"subProfileId":null,
"sortOrder":0,
"viewStyle":0,
"imageFileName":"fi1626.png",
"imageHash":"350665e703360c6efb453b610e14a956"
},
{
"id":1638,
"profileId":4,
"title":"Профиль Курск ЖКХ",
"providerGroupId":null,
"providerId":null,
"subProfileId":85,
"sortOrder":10,
"viewStyle":0,
"imageFileName":null,
"imageHash":null
}
]
},
{...}
]

Список полей профиля:
id – ID профиля отображения ,
name – название,
dealerId – ID агента,
imageFileName – имя файла с логотипом,imageHash – хэш файла с логотипом,
objVersion – версия изменений профиля,
items – список элементов,

Список полей элемента профиля:
id – ID элемента,
profileId – ID профиля отображения провайдеров,
title – заголовок элемента,
imageFileName – имя файла с логотипом элемента,imageHash – хэш файла с логотипом элемента,
sortOrder – порядковый номер элемента,
subProfileId – ID вложенного профиля отображения провайдеров,
providerGroupId – ID группы провайдеров,
providerId – ID провайдера.

Запрос списка профилей комиссий агента
Формат запроса
https://<адрес сервера>/get_commissions?lastObjVersion=xxx&lastId=xxx&count=xxx
lastObjVersion– версияпоследнего загруженного профиля,
lastId– ID последнего загруженного профиля,
count – максимальное количество записей в ответе.

Аутентификация: HTTP Basic + SSL client.

Пример ответа
[
{
"dividePrePay": false,
"id": 569,
"name": "Комиссия 0%",
"objVersion": 4246,
"prePay": 0,
"terminalUsingPay": false,
"truncCommission": 0,
"items": [
{
"conditions": [
{
"coinBillRaw": "0",
"summRangeTop": 100000
}
],
"daysMatrix": [],
"monthMatrix": [],
"name": "Новая группа"
}
]
},
{
"dividePrePay": false,
"id": 3484,
"name": "5% сотовые",
"objVersion": 7323,
"prePay": 0,
"terminalUsingPay": false,
"truncCommission": -1,
"items": [
{
"conditions": [
{
"percent": 5,
"summRangeBottom": 1,
"summRangeTop": 15000
}
],
"daysMatrix": [
[-1], [-1], [-1], [-1], [-1], [-1], [-1]
],
"monthMatrix": [
[-1],[-1], [-1], [-1], [-1], [-1], [-1], [-1], [-1], [-1], [-1], [-1]
],
"name": "Новая группа"
}
]
}
]
id – ID профиля комиссии,
name – названиепрофиля комиссии,
objVersion – версия изменений профиля комиссии,
prePay – предоплата,
terminalUsingPay – оплата за использование терминала,
truncCommission – округлять комиссию,
items – группы условий для разных временных интервалов,
name – название группы условий,
conditions – список условий,
percent – процент комиссии,
summRangeBottom – минимальная сумма,
summRangeTop – максимальная сумма,
daysMatrix,monthMatrix – настройки временных интервалов.

Запрос списка общих профилей комиссий
Формат запроса
https://<адрес сервера>/get_shared_commissions?lastObjVersion=xxx& lastId=xxx&count=xxx

lastObjVersion– версияпоследнего загруженного профиля,
lastId– ID последнего загруженного профиля,
count – максимальное количество записей в ответе.

Аутентификация: HTTP Basic + SSL client.

Ответ такой же как и в запросе профилей комиссий агента

Запрос списка DEF-кодов
Формат запроса
https://<адрес сервера>/get_def_codes?lastObjVersion=xxx&lastId=xxx&count=xxx

lastObjVersion– версияпоследнего загруженного DEF-кода,
lastId– ID последнего загруженного DEF-кода,
count – максимальное количество записей в ответе.

Аутентификация: HTTP Basic + SSL client.

Пример ответа
[
{
"id":13776,
"providerId":99,
"minPhone":"8432130000",
"maxPhone":"8432139999",
"regionId":0,
"objVersion":0
},
{...}
]

id – ID DEF-кода,
providerId – ID провайдера,
minPhone – первое значение в диапазоне,
maxPhone – последнее значение в диапазоне,
regionId – ID региона,objVersion – версия изменений DEF-кода.

Запрос списка регионов
Формат запроса
https://<адрес сервера>/get_regions?lastObjVersion=xxx&lastId=xxx&count=xxx

lastObjVersion– версияпоследнего загруженного региона,
lastId– ID последнего загруженного региона,
count – максимальное количество записей в ответе.

Аутентификация: HTTP Basic + SSL client.

Пример ответа
[
{
"id":1,
"objVersion":0,
"name":"Челябинская область"
},
{...}
]

id – ID региона,
objVersion – версия изменений региона,
name – название региона.

Запрос на закрытие смены
Формат запроса
https://<адрес сервера>/add_cycles

Аутентификация: HTTP Basic + SSL client.

Список смен отправляется POST запросом в формате JSON.

Пример запроса
[
{
"comission": 0.100,
"currencyCode": 643,
"cycleNumber": 2,
"docsCount": 1,
"endDate": "2014-02-18T10:40:28Z",
"firstDoc": 149,
"introduction": 0,
"lastDoc": 149,
"payout": 200,
"startDate": "2014-02-17T17:29:37Z",
"summ": 1
}
]

comission – общая сумма комиссий,
currencyCode – код валюты,
cycleNumber – номер смены,
docsCount – количество чеков,
firstDoc – номер первого чека,
lastDoc – номер последнего чека,
endDate – дата закрытия смены,
startDate – 2014-02-17T17 –29 –37Z,
introduction – кассовая операция внесение,
payout – кассовая операция выплата,
summ – общая сумма платежей.

Пример ответа
{
"encashment": [
{
"cycleNumber": 2,
"insert": true,
"success": 1
},
{
"cycleNumber": 2,
"error":
{
"errorCode" : 1,
"errorMessage" : "Неизвестная ошибка"
}
}
]
}

encashment – список смен,
cycleNumber – номер смены,
insert – смена закрыта (true – закрыта сейчас, false – была закрыта ранее),
success – запрос на закрытие смены успешно обработан,

error – ошибка обработки запроса на закрытие смены,
errorCode – код ошибки,
errorMessage– текст ошибки.

Отправка состояния и получение настроек терминала
Формат запроса
https://<адрес сервера>/ping

Аутентификация: HTTP Basic + SSL client.

Состояние терминала отправляется POST запросом в формате JSON.

Пример запроса

{
"cpuTemperature":39,
"docNumber":0,
"error":"",
"hddTemperature":0,
"lastActivity":"2014-02-25T10:02:19Z",
"trafficIn":0,
"trafficOut":0,
"version":"0.3.7b",
"buildDt":"2014-02-25T08:19:06Z",
"currentDt":"2014-02-25T10:28:03Z",
"docsForDay":28,
"errorDt":"2014-02-25T10:02:17Z",
"startDt":"2014-02-25T10:27:59Z"
"printerStatus":
{
"error":"",
"tapeAvailable":0,
"errorDt":"2014-02-25T10:02:17Z"
},
"cycle":
{
"summ":4.0,
"fromDoc":722,
"toDoc":0,
"number":29,
"comission":0,
"docsFoCycle":2,
"from":"2014-02-25T10:02:17Z",
"to":"2014-02-25T10:02:17Z"
},
"ectsStatus":
{
"cycleNumber":0,
"docNumber":0,
"grossEnd":0,
"grossStart":0,
"kpkNumber":0,
"kpkValue":0,
"summ0":0.0,
"summ1":0.0,
"docsCnt":0,
"endDt":"2014-02-25T10:02:17Z",
"startDt":"2014-02-25T10:02:17Z",
"bufferedZCnt":0
}
}

cpuTemperature – температура процессора,
docNumber – номер последнего чека,
error – текст последней ошибки,
hddTemperature – температура жесткого диска,
lastActivity – дата последнего платежа,
trafficIn – входящий трафик,
trafficOut – исходящий трафик,
version – версия терминала,
buildDt – дата сборки,
currentDt – текущая дата в UTC,
docsForDay – количество чеков за день,
errorDt – дата ошибки,startDt – дата,

printerStatus – статус принтера,
error – описание ошибки,
tapeAvailable – true, если бумага есть, иначе false,
errorDt – дата ошибки,
cycle – смена,
summ – общая сумма за смену,
fromDoc – номер первого чека,
toDoc – номер последнего чека,
number – номер смены,
comission – общая комиссия за смену,
docsFoCycle – количество чеков за смену,
from – дата начала смены,
to – дата закрытия смены,
ectsStatus – Статус ФРа,cycleNumber – Номер текущей смены,docNumber – номер последнего чека,grossEnd – Гросс итог на конец смены,grossStart – Гросс итог на начало смены,kpkNumber – Номер кпк последнего документа,kpkValue – Значение кпк последнего документа,summ0 – Итоговая сумма зачислений на счета клиентов за текущую смену,summ1 – Общая сумма комиссий затекущую смену,docsCnt – Количество документов за текущую смену,endDt – Дата закрытия смены,startDt – Дата открытия смены,bufferedZCnt – Количество сменных отчетов с гашением в буфере ФРа.

Пример ответа
{
"providerProfileId":6,
"providerFormProfileId":5,
"checkTemplateId":7,
"dataVersions":{
"commissions":{
"objVersion":1
},
"checkTemplate":{
"objVersion":1
},
"providers":{
"objVersion":1
},
"enabledProviders":{
"objVersion":1
},
"providerProfile":{
"objVersion":1
},
"defCodes":{
"objVersion":1,
"removeObjVersion":2
},
"providerFormProfile":{
"objVersion":1
},
"regions":{
"objVersion":1
}
}
}

providerProfileId – ID профиля комиссий провайдеров,
providerFormProfileId – ID профиля отображения провайдеров,
checkTemplateId – ID шаблона чека,
dataVersions – версии изменений параметров терминала,
commissions.objVersion – версия изменений профиля комиссий,
checkTemplate.objVersion – версия изменений шаблона чека,
providers.objVersion – версия изменений провайдеров,
enabledProviders.objVersion – версия изменений доступных провайдеров,
providerProfile.objVersion – версия изменений профиля комиссий провайдеров,
defCodes.objVersion – версия изменений DEF-кодов,
defCodes.removeObjVersion – версия удаленных DEF-кодов,
providerFormProfile.objVersion – версия изменений профиля отображения провайдеров,
regions.objVersion – версия удаленных регионов.

Запрос списка счетов
Формат запроса
https://<адрес сервера>/get_accounts

Аутентификация: HTTP Basic + SSL client.

Пример ответа
{
"accounts": [
{
"nameByClient":"11111111111111",
"minLimitByClient":0.0000,
"noLimit":true,
"currencyId":643,
"overdraftExternal":0.0000,
"minLimit":0.0000,
"id":2791,
"balance":0.0000,
"overdraft":0.0000,
"blockedByClient":true,
"blocked":false,
"balanceExternal":0.0000,
"dateExternal":"1859-12-31T20:00:00Z",
"noLimitByClient":false
},
{…}
]
}

accounts – список счетов,
id – ID счета,
nameByClient – название счета,
minLimitByClient – минимальный лимит,
noLimitByClient – нет лимита,
blockedByClient – счет заблокирован,
minLimit – минимальный лимит,
noLimit – нет лимита,
blocked – счет заблокирован,
currencyId – код валюты,
balance – баланс,
overdraft – овердрафт,
overdraftExternal – овердрафт в платежной системе,
balanceExternal – баланс в платежной системе,
dateExternal – время последнего обновления баланса в платежной системе.

Запрос на проведение платежа
Формат запроса
https://<адрес сервера>/add_pay

Аутентификация: HTTP Basic + SSL client.

Список платежей отправляется POST запросом в формате JSON. Если платеж был уже добавлен на проведение, возвращается его статус.

Пример запроса
{
"pays": [
{
"checkNumber": 150,
"code": "1111111111",
"commission": 0.10,
"currencyId": 643,
"cycleNumber": 3,
"params": {
"phone": "1111111111"
},
"payDate": "2014-02-18T11:18:47Z",
"providerId": 1,
"summ": 1
}
]
}

pays – список платежей,
checkNumber – номер чека,
code – номер счета,
summ – внесенная сумма,
commission – комиссия,
currencyId – код валюты,
cycleNumber – номер смены,
params – параметры платежа,
payDate – дата платежа,
providerId – ID провайдера.

Пример ответа
{
"result": 0,
"resultDescription": null,
"statuses": [
{
"checkNumber": 150,
"description": null,
"payDate": "2014-02-18T11:18:47Z",
"result": 0,
"resultDescription": null,
"status": 0,
"transactionId": 525170148
},
{...}
]
}

result – результат выполнения операции,
resultDescription – текст ошибки выполнения операции,
statuses – список статусов платежей,
checkNumber – номер чека,
description – описание статуса платежа,
status – статус платежа,
transactionId – ID транзакции,
payDate – дата платежа,
result – результат обработки платежа,
resultDescription – текст ошибки обработки платежа.

Запрос статуса платежа
Формат запроса
https://<адрес сервера>/get_pay_status

Аутентификация: HTTP Basic + SSL client.

Пример запроса
{
"pays": [
{
"checkNumber": 150
},
{
"checkNumber": 150
}
]
}

pays – список платежей,
checkNumber – номер чека.

Пример ответа
{
"result": 0,
"resultDescription": null,
"statuses": [
{
"checkNumber": 150,
"description": "Неизвестный статус Ошибка данных запроса (202)",
"payDate": "2014-02-18T11:18:47Z",
"result": 0,
"resultDescription": null,
"status": 2,
"transactionId": 525170148
}
]
}

Статус платежа:
0 – новый платеж,
1 – проведен,
2 – ошибочный платеж.

Результат обработки запроса:
0 – нет ошибки,
104 – база данных временно недоступна,
125 – платеж не найден,
101 – неверный запрос,
103 – ошибка авторизации,
200 – неизвестная ошибка,
201 – неизвестная ошибка базы данных,
501 – неверный номер смены.

This article was helpful for 1 person. Is this article helpful for you?

Customer support service by UserEcho