Задать вопрос
Device API
Общие положения
Для взаимодействия с Device API требуется ключ доступа (auth_key) типа терминала: "ККМ-сервис 2.0" или "Промежуточный сервер". Получить auth_key можно 2 способами:
Обращение к Device API выполняется через URI:
https://api.heado.ru/device/<Auth_Key>
https://gamma.heado.ru/device/<Auth_Key> (для ключей домена gamma)
Уровень доступа к данным, ограничен на уровне устройства и торговой точки, которому принадлежит <auth_key>
Регистрация продаж/возвратов
purchaseRegisterBatch(receipts);
POST Web-адрес запроса:
https://api.heado.ru/device/<Auth_Key>
https://gamma.heado.ru/device/<Auth_Key> (для ключей домена gamma)
Метод предназначен для пакетной загрузки чеков продажи или возврата. Максимальный размер пакета - 100 чеков.
В случае успешной загрузки возвращает количество загруженных чеков и время их регистрации в HEADO.
При ошибке возвращает код и описание ошибки
ВАЖНО: Для регистрации чеков возврата параметр amount и значения value атрибутов чека передавать с отрицательным значением.
Параметры запроса:
NAMETYPEDESCRIPTION
receiptsArray 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
Рекомендуемые атрибуты чека:
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

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

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

{
  "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( token, amount, cart [, poskey ] );
POST Web-адрес запроса:
https://api.heado.ru/device/<Auth_Key>
https://gamma.heado.ru/device/<Auth_Key> (для ключей домена gamma)
Метод предназначен для регистрации чека продажи или возврата.
В случае успешной регистрации чека, возвращает: сумму, идентификатор и время его регистрации в HEADO.
При ошибке возвращает код и описание ошибки.
ВАЖНО: архивный метод, см. актуальный метод purchaseRegisterBatch
Для регистрации чека возврата, параметр amount и значения value атрибутов чека передавать с отрицательным значением.
Параметры запроса:
NAMETYPEDESCRIPTION
tokenstring(32)Локальный идентификатор покупателя, если таковой отсутствует передавать 'guest'
amountdecimal(10,4)Итоговая сумма по чеку (скидки вычтены). Если >0, то продажа, если <0, то возврат
cartobjectОбъект расширяемых (опциональных) параметров чека:
- 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(2000)) : Иерархическая структура категорий/подкатегорий товара и дополнительные метки. Структура передается последовательно, начиная с первого уровня с использованием разделителя '&&'. Общая длина строки 2000 символов (длина каждой категории/метки не более 200 символов)
-- extId (string(40)) : Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв.
},..
]
- attributes (array) : [ Массив свободных атрибутов чека (карты лояльности, платёжные системы и т.п.) {
-- name (string(20)) : Название атрибута (английские мнемоники),
-- value (decimal(10,4)) : Значение атрибута (<0 при возврате)
},..
]
poskey (опциональный)string Ключ маппинга к устройству и торговой точки
-- Общий формат: @store_ext_id/extid
--- store_ext_id (string(40)) - Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
--- extid (string(64))- «Внешний идентификатор устройства» (кассы/сервера) из торговой системы предприятия, состоящий из латинских букв или цифр
-- Пример: @111/123
Пример запроса purchaseRegister

{
  "jsonrpc": "2.0",
  "id": "7241520367540836",
  "method": "purchaseRegister",
  "params": {
    "token": "guest",
    "amount": 100,
    "cart": {
      "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

{
    "jsonrpc": "2.0",
    "id": "7241520367540836",
    "result": {
        "amount": 100, //Зарегистрированная сумма  /* Decmial(10,4) */ 
        "id": "13764119911889754100", //Идентификатор чека /* Unsigned Int64 */
        "ts": "2019-08-13T21:39:51.000+00010800" //Время регистрации /* Y-m-d H:i:sT.000Z ISO 8601 формат */
    }
}
Отчёты по торговой точке
reports(id [, params ] );
POST Web-адрес запроса:
https://api.heado.ru/device/<Auth_Key>
https://gamma.heado.ru/device/<Auth_Key> (для ключей домена gamma)
Метод предназначен для получения отчётов по торговой точке к которой относится использованный в запросе auth_key.
При ошибке возвращает код и описание ошибки.
Параметры запроса:
NAMETYPEDESCRIPTION
idstring(20) - 'metrics' - Получение общего отчёта "Показатели" (страница 4 инструкции)
- 'bysellers' - Получение отчёта "Продавцы" (страница 5 инструкции)
- 'bytradepoints' - Получение отчёта "Рейтинг торговых точек" (страница 6 инструкции)
paramsobject { "filter": { } , "range" : [ { "type": <id периода>, "from": "Y-m-d H:i", "to":"Y-m-d H:i"},..]
Пример запроса reports(metrics[, params ])

{
  "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 ])

{
    "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 ])

{
  "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 ])

{
    "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])
POST Web-адрес запроса:
https://api.heado.ru/device/<Auth_Key>
https://gamma.heado.ru/device/<Auth_Key> (для ключей домена gamma)
Метод предназначен для отправки сигнала о событии: открытие/закрытие торговой точки
При ошибке возвращает код и описание ошибки.
Параметры запроса:
NAMETYPEDESCRIPTION
namestring ‘shift/start’ сигнал открытия смены
‘shift/stop’ сигнал закрытия смены
tsstring ‘shift/start’, ‘Y-m-d H:i:s’ /*Локальное время открытия смены*/
‘shift/stop’, ‘Y-m-d H:i:s’ /*Локальное время закрытия смены*/
paramsobject в params можно передавать массив метаданных:
- seller : string ФИО
- localtimezone: offset +/- hours
Пример запроса registerEvent (сигнал открытия)

{
  "id": "8361549266426897",
  "method": "registerEvent",
  "params": {
    "name": "shift/start",
    "ts": "2019-07-24 11:00",
    "params": {}
  },
  "jsonrpc": "2.0"
}
Пример ответа registerEvent

{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "ts": "2019-07-24 11:00",
        "now": "2019-07-24 11:41"
    }
}
Управление планами
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.
При ошибке возвращает код и описание ошибки.
Параметры запроса:
NAMETYPEDESCRIPTION
metricstring(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 (необязательный) DECIMAL(13,4) Коррекционное значение плана на день (если указан день)
Параметры ответа

result: { "addressId" : ИД торговой точки, "metric": Идентификатор показателя, "plan": Установленный план, "year": Год, "month" : Месяц, "day": День}
planPublish( auto );
POST Web-адрес запроса:
https://api.heado.ru/device/<Auth_Key>
https://gamma.heado.ru/device/<Auth_Key> (для ключей домена gamma)
Метод публикует установленные плановые значения торговой точки к которой относится использованный в запросе auth_key.
При ошибке возвращает код и описание ошибки.
Параметры запроса:
NAMETYPEDESCRIPTION
autoboolean - true - Использовать сервисную аналитику распределения по периодам.
- false - Не использовать аналитику (равномерное распределение по нижним периодам)
Параметры ответа

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