Device API предназначено для прямой интеграции Server-Server или Application-Server, с доступом к данным на уровне устройства и торговой точки, к которой прикреплено это устройство.
API поддерживает JRPC 2.0-протокол вызова методов.
Для работы необходимо знать ключ <AccessKey&> «устройства» с которым можно обращаться по URL: https://api.giftoman.ru/s/<accesskey>
Протокол обмена данными
Запрос представляет собой JSON-сериализованный объект отправляемый с помощью POST-метода в виде RAW_POST_DATA
{
"jsonrpc": "2.0",
"id": "[Свободно-генерируемый идентификатор запроса]",
"method": "[Название вызываемого метода]",
"params": "[объект или массив аргументов вызываемого метода]"
}
Ответ так же является JSON-сериализованным объектом
{
"jsonrpc": "2.0",
"id": "[Идентификатор запроса на который дан ответ]",
"result": "[Любой тип данных - объект, массив, значение]"
}
или отрицательный
{
"jsonrpc": "2.0",
"id": "[Идентификатор запроса на который дан ответ]",
"error": {
"code": "[Код ошибки]",
"message": "Неправильная операция"
}
}
Список ошибок
| Код ошибки | Пояснение |
|---|---|
| -32000 | Неизвестный идентификатор сотрудника |
| -32500 | Ошибка клиента |
| -32600 | Неправильный формат запроса |
| -32601 | Неправильная операция |
| -32602 | Неправильные параметры операции |
| -32605 | Операция не удалась |
| -32606 | Слишком частое выполнение операции |
| -32610 | Ошибка БД |
| -32700 | Неправильный формат сообщения |
| -32800 | Неизвестный терминал |
| -32801 | Терминал заблокирован |
| -32802 | Невалидный секретный ключ |
| -32803 | Терминал с таким идентификатором уже существует |
| -33000 | Неизвестный пользователь |
| -33001 | Владелец POS не найден |
| -33100 | Отказ в авторизации |
Регистрация продажи/возврата
Запрос позволяет как оформить продажу, так и возврат
purchaseRegister( token, amount, cart [, poskey ] );
Параметры.
| name | type | description |
|---|---|---|
| token | string(32) | Локальный идентификатор покупателя, если таковой отсутствует передавать ‘guest’ |
| amount | decimal(10,4) | Если >0, то сумма чека, если <0, то сумма возврата |
| cart | object | Объект расширяемых (опциональных) параметров чека: — discount (decimal(10,4)) : Скидка по чеку — ts ( ISO 8601 : YYYY-MM-DDThh:mm:ss±hh:mm) : Точное время чека. Необходимо обязательно передавать метку времени с корректным смещением ±hh от UTC, соответствующим временному поясу торговой точки. — cashier (string(200)) : Имя продавца — extId (string(40)): Идентификатор чека в ТС — positions (array) : [ Товарные позиции в чеке { — name (string(200)) : Название товара — count (decimal(10,4)) : Кол-во товара — total (decimal(10,4)) : Общая сумма по позиции — seller (string(200)) : Продавец для конкретной позиции — category (string(200)) : Название категории товара (Можно передать несколько категорий в строке, разделяя ‘&&’) — extId (string(40)) : Внешний идентификатор товара (Артикул) },.. ] — attributes (array) : [ Массив свободных атрибутов чека (карты лояльности, платёжные системы и т.п.) { — name (string(10)) : Название атрибута (английские мнемоники), — value (decimal(10,4)) : Значение атрибута },.. ] |
| poskey (опциональный) | string(130) | Ключ маппинга к устройству или торговой точке. Общий формат: @store_ext_id/cashbox_ext_id— store_ext_id — Внешний идентификатор торговой точки, передаваемый в методе setCashbox() в аргументе метода extid — Пример: @111/123 |
Пример
{
"jsonrpc": "2.0",
"id": "7241520367540836",
"method": "purchaseRegister",
"params": {
"token": "guest@giftoman.ru",
"amount": 100,
"cart": {
"discount": 0,
"ts": "2018-03-14T16:39:51.000Z",
"cashier": "Марина Ивановна",
"extId": "bb802ad3-d268-4946-b80c-b963aaf66b21",
"positions": [
{
"name": "Пирожок с повидлом",
"count": 10,
"total": 100,
"seller": "Марина Ивановна",
"category": "Вкусное"
}
]
}
}
}
Успешный ответ
{
"jsonrpc": "2.0",
"id": "3061520885622532",
"result": {
"amount": Зарегистрированная сумма /* Decmial(10,4) */,
"id": Идентификатор чека /* Unsigned Int64 */,
"ts": Время регистрации /* Y-m-d H:i:sT.000Z ISO 8601 формат */
}
}
Пакетная регистрация продаж/возвратов
Запрос позволяет за раз загрузить пакет чеков (максимум = 100)
purchaseRegisterBatch( receipts );
Параметры.
| name | type | description |
|---|---|---|
| receipts | Array of Objects | Объект массива: — amount (decimal(10,4)) : Итоговая сумма по чеку (скидки вычтены) — discount (decimal(10,4)) : Итоговая скидка по чеку — ts ( ISO 8601: YYYY-MM-DDThh:mm:ss±hh:mm) : Точное время чека. Необходимо обязательно передавать метку времени с корректным смещением ±hh от UTC, соответствующим временному поясу торговой точки. — cashier (string(200)) : Имя продавца — extId (string(40)): Идентификатор чека в ТС — positions (array) : [ Товарные позиции в чеке { — name (string(200)) : Название товара — count (decimal(10,4)) : Кол-во товара — total (decimal(10,4)) : Общая сумма по позиции — seller (string(200)) : Продавец для конкретной позиции — category (string(200)) : Название категории товара (Можно передать несколько категорий в строке, разделяя ‘&&’) — extId (string(40)) : Внешний идентификатор товара (Артикул) },.. ] — attributes (array) : [ Массив свободных атрибутов чека (карты лояльности, платёжные системы и т.п.) { — name (string(10)) : Название атрибута (английские мнемоники), — value (decimal(10,4)) : Значение атрибута },.. ] — poskey (string(130) Ключ маппинга к устройству или торговой точке. — Общий формат: @store_ext_id/cashbox_ext_id— store_ext_id — Внешний идентификатор торговой точки, передаваемый в методе setCashbox() в аргументе метода extid — Пример: @111/123 |
| agent | name: agent STRING, //наименование ПОversion : agent Version, //версия ПО |
Пример
{
"jsonrpc": "2.0",
"id": "7241520367540836",
"method": "purchaseRegisterBatch",
"params": {
"receipts": [
{
"amount": 100,
"discount": 0,
"ts": "2018-03-14T16:39:51.000Z",
"cashier": "Марина Ивановна",
"extId": "bb802ad3-d268-4946-b80c-b963aaf66b21",
"positions": [
{
"name": "Пирожок с повидлом",
"count": 10,
"total": 100,
"seller": "Марина Ивановна",
"category": "Вкусное",
"extId": "10002346"
}
]
},
{
"amount": 250,
"discount": 0,
"ts": "2018-03-14T16:55:01.000Z",
"cashier": "Илона Давыдовна",
"extId": "34c39902-5554-4be3-a3b2-042c3e2a6262",
"positions": [
{
"name": "Пирожок с повидлом",
"count": 15,
"total": 150,
"seller": "Илона Давыдовна",
"category": "Вкусное",
"extId": "1066"
}
],
"poskey": "@111/123"
}
],
"agent": {
"name": "Centrum",
"version": "10.2.60.0"
}
}
}
Успешный ответ
{
"jsonrpc": "2.0",
"id": "3061520885622532",
"result": {
"count" : Кол-во зарегистрированных чеков /* Unsigned INT */
}
}
Ошибка обработки чека
{
"jsonrpc": "2.0",
"id": "3061520885622532",
"error": {
"message": "Текст ошибки",
"code" : "Код ошибки",
"receipt": {
"amount":100,
"discount":0,
"ts": "2018-03-14T16:39:51.000Z",
"cashier": "Марина Ивановна",
"extId": "bb802ad3-d268-4946-b80c-b963aaf66b21",
"positions": [
{
"name": "Пирожок с повидлом",
"count" : 10,
"total" : 100,
"seller": "Марина Ивановна",
"category": "Вкусное"
}
]
}
}
}
Установка планового значения
С помощью этого запроса можно как установить, так и удалить плановое значение на нужный период.
Планы устанавливаются на ту Торговую точку, где зарегистрировано данное устройство.
planSet( metric, plan, year [, month, day, day_corr_plan ] );
Параметры.
| name | type | description |
|---|---|---|
| metric | string(40) | Мнемоника, либо прямой идентификатор правила: — income : Выручка — average : Средний чек — count : Кол-во продаж — category : Выручка по СТМ — complexity : Комлексность чека по кол-ву товаров — p/ <идентификатор показателя> — прямой идентификатор показателя |
| plan | DECIMAL(13,4) | Если >=0, то установка планового значения = plan, если <0, то удаление |
| year | int | Год |
| month (необязательный) | int | Месяц, если не указан или = -1, то выставляется план на год |
| day (необязательный) | int | День, если не указан или = -1, то выставляется план на месяц, иначе — на день |
| day_corr_plan (необязательный) | DECIMAL(13,4) | Коррекционное значение плана на день (если указан день) |
Параметры ответа
result: { "addressId" : ИД торговой точки, "metric": Идентификатор показателя, "plan": Установленный план, "year": Год, "month" : Месяц, "day": День}
Публикация плана
После установки всех плановых значений на период необходимо вызвать метод публикации плана для актуализации значений
planPublish( auto );
Параметры.
| name | type | description |
|---|---|---|
| auto | boolean | — true — Использовать сервисную аналитику распределения по периодам. — false — Не использовать аналитику (равномерное распределение по нижним периодам) |
Параметры ответа
result: { "addressId" : ИД торговой точки, "auto": Автоматическое распределение}
Получение отчётов по Торговой точке
Для получения планов по Торговой точке используется команда reports(id [,params])
reports(id [, params ] );
Параметры.
| name | type | description |
|---|---|---|
| id | string(20) | — ‘metrics’ — Получение общего отчёта «Показатели» — ‘bysellers’ — Получение отчёта «Продавцы» — ‘bytradepoints’ — Получение отчёта «Рейтинг торговых точек» |
| params | object | { «filter»: { } , «range» : [ { «type»: <id периода>, «from»: «Y-m-d H:i», «to»:»Y-m-d H:i»},.. ] |
Пример запроса metrics
{
"id":"1251506945251332",
"method":"reports",
"params":{
"id":"metrics",
"params": { "range" : [{"type":"month","from":"2018-04-01", "to":"2018-04-31 23:59"},{"type":"day","from":"2018-04-17","to":"2018-04-17 23:59:59"}]}
},
"jsonrpc":"2.0"
}
Пример ответа
{
"jsonrpc": "2.0",
"id": "1251506945251332",
"result": {
"data": {
"month": { // Отчёт по запросу params.range.type == 'month'
"metrics": { // Список метрик
"id": "3656",//string
"store_ext_id": "0",//string
"name": "Тюмень, 50 лет ВЛКСМ, 63 Шаурма",//string
"metrics": [
{
"id": "1437627895975735595", // Уникальный идентификатор метрики : string
"name": "Выручка", //Название правила : string
"order": 0, // Порядок сортировки, рекомендуемой настройками аккаунта : short
"type": 1, // Клиенсткий тип данных 1 = Числовой, 2 = денежный, 3 = процентный : short
"fact": 401628, // Фактическое значение : double
"plan": 19999.9980, // Плановое значение на конец дня : double
"planhour": 0, //План на текущий час : double
"predict": 0, // Прогноз на конец дя double
"qty": 2287.0000 //Кол-во продаж : float
},
{
"id": "1437627895975735596",
"name": "Средний чек",
"order": 1,
"type": 2,
"fact": 175.61,
"plan": 0,
"planhour": 0,
"predict": 0,
"qty": 2287.0000
},
{
"id": "1437627895975735664",
"name": "Наполняемость",
"order": 2,
"type": 3,
"fact": 2,
"plan": 0,
"planhour": 0,
"predict": 0,
"qty": 2269.0000
}
]
}
},
"day": { // Отчёт по запросу params.range.type == 'day'
"metrics": {
"id": "3656",
"store_ext_id": "0",
"name": "Тюмень, 50 лет ВЛКСМ, 63 Шаурма",
"metrics": [
{
"id": "1437627895975735595",
"name": "Выручка",
"order": 0,
"type": 7,
"fact": 24672,
"plan": 19999.9980,
"planhour": 0,
"predict": 0,
"ratio": 1.2336,
"qty": 141.0000
},
{
"id": "1437627895975735596",
"name": "Средний чек",
"order": 1,
"type": 2,
"fact": 174.98,
"plan": 0,
"planhour": 0,
"predict": 0,
"ratio": 1,
"qty": 141.0000
},
{
"id": "1437627895975735664",
"name": "Наполняемость",
"order": 2,
"type": 3,
"fact": 2.32,
"plan": 0,
"planhour": 0,
"predict": 0,
"ratio": 1,
"qty": 140.0000
}
]
}
}
}
}
}
Пример запроса bysellers
{
"id":"1251506945251332",
"method":"reports",
"params":{
"id":"bysellers",
"params": { "range" : [{"type":"month","from":"2018-04-01", "to":"2018-04-31 23:59"},{"type":"day","from":"2018-04-17","to":"2018-04-17 23:59:59"}]}
},
"jsonrpc":"2.0"
}
Пример ответа
{
"jsonrpc": "2.0",
"id": "1251506945251332",
"result": {
"data": {
"month": {
"bysellers": {
"common": [ // Суммарные (общие) показатели
{
"id": "1437627895975735595", // Идентификатор показателя : string
"idx": "1", // Связующий идентификатор показателя общей статистики и по продавцу : string
"order": 1, // Рекомендуемая аккаунтом сортировка : short
"label": "Выручка", // Название показателя : string
"type": 2, // Клиенсткий тип данных 1 = Числовой, 2 = денежный, 3 = процентный : short
"fact": 1509878, // Общее фактическое значение : double
"plan": 1269999.847, // Общее плановое значение : double
"qty": 8604, // Кол-во продаж
},
{
"idx": "2",
"order": 2,
"label": "Средний чек",
"type": 2,
"id": "1437627895975735596",
"fact": 175.48617001395,
"plan": 0,
"qty": 8604
},
{
"idx": "3",
"order": 3,
"label": "Наполняемость",
"type": 1,
"id": "1437627895975735664",
"fact": 1.948460758605,
"plan": 0,
"qty": 8542
}
],
"sellers": [ // Показатели по продавцам
{
"name": "Конищева Мария Андреевна",
"id": "1514522702289725696",
"metrics": [
{
"idx": "1",
"order": 1,
"label": "Выручка",
"type": 2,
"fact": 435286,
"plan": 0,
"qty": 3893
},
{
"idx": "2",
"order": 2,
"label": "Средний чек",
"type": 2,
"fact": 180.6921384807,
"plan": 0,
"qty": 2409
},
{
"idx": "3",
"order": 3,
"label": "Наполняемость",
"type": 1,
"fact": 2.03098048983,
"plan": 0,
"qty": 2409
}
]
},
{
"name": "Поступинских Анна Владимировна",
"id": "1517977472394792448",
"metrics": [
{
"idx": "1",
"order": 1,
"label": "Выручка",
"fact": 320182,
"plan": 0,
"qty": 2785
},
{
"idx": "2",
"order": 2,
"label": "Средний чек",
"fact": 171.95656831364,
"plan": 0,
"qty": 1862
},
{
"idx": "3",
"order": 3,
"label": "Наполняемость",
"fact": 1.841699194415,
"plan": 0,
"qty": 1862
}
]
}
]
}
},
"day": {
"bysellers": {
"common": [
{
"idx": "1",
"order": 1,
"label": "Выручка",
"id": "1437627895975735595",
"fact": 24672,
"plan": 19999.998,
"qty": 141
},
{
"idx": "2",
"order": 2,
"label": "Средний чек",
"id": "1437627895975735596",
"fact": 174.9786,
"plan": 0,
"qty": 141
},
{
"idx": "3",
"order": 3,
"label": "Наполняемость",
"id": "1437627895975735664",
"fact": 2.3224,
"plan": 0,
"qty": 140
}
],
"sellers": [
{
"name": "Конищева Мария Андреевна",
"id": "1514522702289725696",
"metrics": [
{
"idx": "1",
"order": 1,
"label": "Выручка",
"fact": 24704,
"plan": 0,
"qty": 255
},
{
"idx": "2",
"order": 2,
"label": "Средний чек",
"fact": 176.4569,
"plan": 0,
"qty": 140
},
{
"idx": "3",
"order": 3,
"label": "Наполняемость",
"fact": 2.3224,
"plan": 0,
"qty": 140
}
]
}
]
}
}
}
}
}
Сигнал открытия/закрытия торговой точки
Данный метод позволяет сформировать запрос о времени открытии и закрытии торговой точки
regısterEvent (name,ts [,params])
Параметры.
| name | type | description |
|---|---|---|
| name | string(32) |
‘shift/start’ начало смены ‘shift/stop’ конец смены |
| ts | decimal(10,4) |
‘shift/start’, ‘Y-m-d H:i:s’ /*Локальное время начала смены*/ ‘shift/stop, ‘Y-m-d H:i:s’ /*Локальное время конца*/ |
| params | decimal(10,4) |
в params можно передавать массив метаданных: — seller : string ФИО — localtimezone: offset +/- hours |
Пример запроса regısterEvent
Успешный ответ