Skip to content

DEVICE API

Общие положения

Для взаимодействия с Device API требуется ключ доступа (auth_key) типа терминала: "ККМ-сервис 2.0" или "Промежуточный сервер".

Получить auth_key можно 2 способами: - через ЛК HEADO - через метод setCashbox в составе Management API.

Обращение к Device API выполняется через URI:

Уровень доступа к данным, ограничен на уровне устройства и торговой точки, которому принадлежит

Регистрация продаж/возвратов

purchaseRegisterBatch;

purchaseRegisterBatch(receipts)

POST Web-адрес запроса:

- https://api.heado.ru/device/<Auth_Key>
- https://gamma.heado.ru/device/<Auth_Key> (для ключей домена gamma)

Метод предназначен для пакетной загрузки чеков продажи или возврата.

Максимальный размер пакета - 100 чеков.

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

При ошибке возвращает код и описание ошибки

Attention

Для регистрации чеков возврата параметр **amount и значения *value** атрибутов чека передавать с отрицательным значением.*

Параметры запроса:

NAME TYPE DESCRIPTION
receipts Array of Objects Объект массива:
- amount (decimal(12,4)) : Итоговая сумма по чеку (скидки вычтены). Если >0, то продажа, если <0, то возврат
- discount (decimal(12,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(12,4)) : Количество товара
-- total (decimal(12,4)) : Общая сумма по позиции с учетом скидок
-- seller (string(200)) : ФИО продавца для конкретной позиции (необходим для мотивации продавцов из разнных отделов).
-- category (string(2000)) : Иерархическая структура категорий/подкатегорий товара и дополнительные метки. Структура передается последовательно, начиная с первого уровня с использованием разделителя '&&'. Общая длина строки 2000 символов (длина каждой категории/метки не более 120 символов)
-- extId (string(40)) : Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв
},..
]
- attributes (array) : [ Массив свободных атрибутов чека (карты лояльности, платёжные системы и т.п.) для дополнительной аналитики.{
-- name (string(20)) : Название атрибута (английские мнемоники),
-- value (decimal(12,4)) : Значение атрибута (<0 при возврате)
},..
]
- poskey Ключ маппинга к устройству и торговой точки (опционально, при его отсутствии чек будет зарегистрирован по ключу авторизации)
-- Общий формат: @store_ext_id/pos_ext_id
--- store_ext_id (string(40)) - Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
--- pos_ext_id (string(64))- «Внешний идентификатор устройства» (кассы/сервера) из торговой системы предприятия, состоящий из латинских букв или цифр
-- Пример: @111/123

Рекомендуемые атрибуты чека:

1
2
3
4
5
withcard (value: 0,1) - использование карты лояльности
discount (value: decimal(10,4)) - скидка на покупку
bonus_sp (value: decimal(10,4)) - использование бонусных баллов
procspd (value: int) - время обработки чека, сек.
paytype/[cash,card,visa,master, e.t.c.] (value: decimal(10,4)) - разбиение суммы по платежам или указание типа платежа.

Возможно использовать свои названия под разработку доп. KPI.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
  "jsonrpc": "2.0",
  "id": "7241520367540836",
  "method": "purchaseRegisterBatch",
  "params": {
    "receipts": [
      {
        "amount": 100,
        "discount": 0,
        "ts": "2019-08-13T16:39:51.000Z",
        "cashier": "Марина Ивановна{2}",
        "extId": "bb802ad3-d268-4946-b80c-b963aaf66b21",
        "positions": [
          {
            "name": "Пирожок с повидлом",
            "count": 10,
            "total": 100,
            "seller": "Марина Ивановна",
            "category": "Вкусное",
            "extId": "10002346"
          }
        ],
        "attributes": [
          {
            "name": "withcard",
            "value": "0"
          },
          {
            "name": "procspd",
            "value": "32"
          }
        ],
        "poskey": "@111/123"
      },
      {
        "amount": 250,
        "discount": 0,
        "ts": "2019-08-13T16:55:01.000Z",
        "cashier": "Илона Давыдовна",
        "extId": "34c39902-5554-4be3-a3b2-042c3e2a6262",
        "positions": [
          {
            "name": "Пирожок с повидлом",
            "count": 10,
            "total": 250,
            "seller": "Илона Давыдовна",
            "category": "Вкусное",
            "extId": "1066"
          }
        ],
        "attributes": [
          {
            "name": "withcard",
            "value": "1"
          },
          {
            "name": "procspd",
            "value": "25"
          }
        ],
        "poskey": "@111/123"
      }
    ]
  }
}
Пример ответа purchaseRegisterBatch

1
2
3
4
5
6
7
8
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "count": 2, //Кол-во зарегистрированных чеков /* Unsigned INT */
    "ts": "2019-08-13 16:55:02" //Время регистрации чеков на сервере
  }
}
Ошибка обработки purchaseRegisterBatch

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "jsonrpc": "2.0",
  "id": "3061520885622532",
  "error": {
    "message": "Текст ошибки",
    "code": "Код ошибки",
    "receipt": {
      "amount": 100,
      "discount": 0,
      "ts": "2019-08-13T16:39:51.000Z",
      "cashier": "Марина Ивановна",
      "extId": "bb802ad3-d268-4946-b80c-b963aaf66b21",
      "positions": [
        {
          "name": "Пирожок с повидлом",
          "count": 10,
          "total": 100,
          "seller": "Марина Ивановна",
          "category": "Вкусное"
        }
      ]
    }
  }
}

purchaseRegister;

purchaseRegister( token, amount, cart [, poskey ] )

POST Web-адрес запроса:

- https://api.heado.ru/device/<Auth_Key>
- https://gamma.heado.ru/device/<Auth_Key> (для ключей домена gamma)

Отчёты по торговой точке

reports;

reports(id [, params ] )

POST Web-адрес запроса:

- https://api.heado.ru/device/<Auth_Key>
- https://gamma.heado.ru/device/<Auth_Key> (для ключей домена gamma)

Метод предназначен для получения отчётов по торговой точке к которой относится использованный в запросе auth_key.

При ошибке возвращает код и описание ошибки.

Параметры запроса:

NAME TYPE DESCRIPTION
id string(20) - 'metrics' - Получение общего отчёта "Показатели" (страница 4 инструкции)
- 'bysellers' - Получение отчёта "Продавцы" (страница 5 инструкции)
- 'bytradepoints' - Получение отчёта "Рейтинг торговых точек" (страница 6 инструкции)
params object { "filter": { } , "range" : [ { "type": , "from": "Y-m-d H:i", "to":"Y-m-d H:i"},..]

Пример запроса reports(metrics[, params ]):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "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"
}

Пример ответа reports(metrics[, params ]) 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
{
    "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
                        }
                    ]
                }
            }
        }
    }
}

Пример запроса reports(bysellers[, params ])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "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"
}

Пример ответа reports(bysellers[, params ])

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
    "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

regısterEvent (name,ts [,params])

POST Web-адрес запроса:

- https://api.heado.ru/device/<Auth_Key>
- https://gamma.heado.ru/device/<Auth_Key> (для ключей домена gamma)

Метод предназначен для отправки сигнала о событии: открытие/закрытие торговой точки

При ошибке возвращает код и описание ошибки.

Параметры запроса:

NAME TYPE DESCRIPTION
name string ‘shift/start’ сигнал открытия смены
‘shift/stop’ сигнал закрытия смены
ts string ‘shift/start’, ‘Y-m-d H:i:s’ /Локальное время открытия смены/
‘shift/stop’, ‘Y-m-d H:i:s’ /Локальное время закрытия смены/
params string в params можно передавать массив метаданных:
- seller : string ФИО
- localtimezone: offset ± hours

Пример запроса registerEvent (сигнал открытия)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "id": "8361549266426897",
  "method": "registerEvent",
  "params": {
    "name": "shift/start",
    "ts": "2019-07-24 11:00",
    "params": {}
  },
  "jsonrpc": "2.0"
}
Пример ответа registerEvent

1
2
3
4
5
6
7
8
{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "ts": "2019-07-24 11:00",
        "now": "2019-07-24 11:41"
    }
}

Управление планами

planSet;

planSet( metric, plan, year [, month, day, day_corr_plan ] )

POST Web-адрес запроса:

- https://api.heado.ru/device/<Auth_Key>
- https://gamma.heado.ru/device/<Auth_Key> (для ключей домена gamma)

Метод устанавливает/удаляет плановые значения торговой точки к которой относится использованный в запросе auth_key.

При ошибке возвращает код и описание ошибки.

Параметры запроса:

NAME TYPE DESCRIPTION
metric string(40) Мнемоника, либо прямой идентификатор правила:
- income: Выручка
- average : Средний чек
- count: Кол-во продаж
- category: Выручка по СТМ
- complexity : Комлексность чека по кол-ву товаров
- p/<идентификатор показателя> - прямой идентификатор показателя в системе HEADO
plan DECIMAL(13,4) Если =0, то установка планового значения = plan
Если <0, то удаление
year int Год
month
(необязательный)		 int Месяц, если не указан или =-1, то выставляется план на год
day
(необязательный)		 int День, если не указан или =-1, то выставляется план на месяц, иначе - на день
day_corr_plan
(необязательный)		 int Коррекционное значение плана на день (если указан день)

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

1
result: { "addressId" : ИД торговой точки, "metric": Идентификатор показателя, "plan": Установленный план, "year": Год, "month" : Месяц, "day": День}

planPublish;

planPublish( auto )

POST Web-адрес запроса:

- https://api.heado.ru/device/<Auth_Key>
- https://gamma.heado.ru/device/<Auth_Key> (для ключей домена gamma)

Метод публикует установленные плановые значения торговой точки к которой относится использованный в запросе auth_key.

При ошибке возвращает код и описание ошибки.

Параметры запроса:

NAME TYPE DESCRIPTION
auto boolean - true - Использовать сервисную аналитику распределения по периодам.
- false - Не использовать аналитику (равномерное распределение по нижним периодам)

Параметры ответа:

1
result: { "addressId" : ИД торговой точки, "auto": Автоматическое распределение}