Skip to content

Management API

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

Для взаимодействия с Management API требуется ключ доступа (auth_key ) типа терминала: "Административный терминал". Получить auth_key можно через ЛК HEADO

URI для запросов (POST):

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

Конфигурация торговой сети

address.check

Метод позволяет проверить и нормализовать почтовый адрес из произвольной (неформализованной) строки.

При невозможности формализовать адрес возвращает ошибку -32404 Искомое не найдено

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

NAME TYPE DESCRIPTION
address mixed Произвольная строка почтового адреса или их массив

Пример запроса address.check

1
2
3
4
5
6
7
8
{
  "id": "1251506945251332",
  "method": "address.check",
  "params": {
    "address": [ "624804, Свердловская обл, Сухоложский р-н, г Сухой Лог, ул Белинского 54Е", "С добрым утром" ]
  },
  "jsonrpc": "2.0"
}
Пример ответа address.check

 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
{
  "jsonrpc": "2.0",
  "id": "8361549266426897",
  "result": [
    {
    "request":  "624804, Свердловская обл, Сухоложский р-н, г Сухой Лог, ул Белинского 54Е",
    "found": true,
    "country": "Россия",
    "city": "Сухой Лог",
    "street": "Белинского",
    "house": "54е",
    "fias_id": "73db2c11-9534-4a44-82d6-f009fc7a1bb8",
    "kladr_id": "66024001000000200",
    "geo_lat": "56.901734",
    "geo_lon": "62.025751"
   },
    {
    "request": "С добрым утром",
    "found": false,
    "country": "",
    "city": "",
    "street": "",
    "house": "",
    "fias_id": "",
    "kladr_id": "",
    "geo_lat": "",
    "geo_lon": ""
   }

  ]
}

cashbox.create

Метод позволяет зарегистрировать устройство (касса, POS, ECR, ККМ) в аккаунте HEADO и получить auth_key устройства для работы с Device API.

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

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

NAME TYPE DESCRIPTION
store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
cashbox_ext_id string(64) Внешний идентификатор устройства в HEADO
name string(200) Название устройства (Кассы,Сервера,ПК)
params object параметр type (boolean) имеет 2 значения:
- gui - используется для взаимодействия с Device API и для установки ПО HEADO на рабочее место торгового предприятия для отображения показателей;
- server - используется для взаимодействия с Device API и для установки ПО HEADO на сервер торгового предприятия (используется как мидсервер, без графического интерфейса)

Пример запроса cashbox.create

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "id": "1251506945251332",
  "method": "cashbox.create",
  "params": {
    "store_ext_id": "26",
    "cashbox_ext_id": "01",
    "name": "Касса №1",
    "params": {
      "type": "gui"
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа cashbox.create

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "cashbox_id": "120506",
    "name": "Касса №1",
    "store_ext_id": "26",
    "pos_ext_id": "01",
    "auth_key": "Ключ устройства для работы с Device API"
  }
}

cashbox.list

Метод для получения списка торговых точек и устройств в аккаунте HEADO.

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

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

NAME TYPE DESCRIPTION
filter object Можно применить фильтрацию (опционально):
- network_ext_id (string(60)): Внешний идентификатор «Торговой сети» в торговой системe
- store_ext_id (string(40): Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр

Пример запроса cashbox.list

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "id": "1251506945251332",
  "method": "cashbox.list",
  "params": {
    "filter": {
      "store_ext_id": "26"
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа cashbox.list

 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
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "data": [
      {
        "cashbox_id": "Идентификатор устройства в HEADO",
        "store_ext_id": "Внешний идентификатор торговой точки в HEADO",
        "cashbox_ext_id": "Внешний идентификатор устройства в HEADO",
        "network_id": "Идентификатор «Торговой сети» в HEADO",
        "network_ext_id": "Внешний идентификатор «Торговой сети» в HEADO",
        "offset": "Часовой пояс",
        "schedule": {},
        "name": "Название устройства (Кассы и т.д.)",
        "auth_key": "128 символьный ключ устройства для работы с Device API",
        "address": {
          "type": "postal",
          "city": "Екатеринбург",
          "street": "Добролюбова",
          "house": "2"
        },
        "status": "enabled"
      }
    ],
    "networks": {
      "2060": {
        "id": "значение network_id",
        "ext_id": "значение network_ext_id",
        "name": "Название «Торговой сети» сети в аккаунте HEADO",
        "city": "Основной город сети в аккаунте HEADO"
      }
    },
    "account": {
      "name": "Название аккаунта",
      "role": "Системный идентификатор роли",
      "login": "Логин аккаунта"
    }
  }
}

cashbox.get

Метод для данных по конкретному устройству в аккаунте HEADO.

Полный список устройств, можно получить через метод cashbox.list

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

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

NAME TYPE DESCRIPTION
cashbox_ext_id object Можно применить фильтрацию (опционально):
- cashbox_ext_id (string(64)): Внешний идентификатор «устройства» в HEADO

Пример запроса cashbox.get

1
2
3
4
5
6
7
8
{
  "id": "8361549266426897",
  "method": "cashbox.get",
  "params": {
    "cashbox_ext_id": "01"
  },
  "jsonrpc": "2.0"
}
Пример ответа cashbox.get

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "jsonrpc": "2.0",
  "id": "8361549266426897",
  "result": {
    "data": [
      {
        "cashbox_id": "120497",
        "cashbox_ext_id": "01",
        "store_ext_id": "26",
        "name": "Касса №1",
        "address": "Добролюбова, 2"
      }
    ]
  }
}

cashbox.update

Метод позволяет изменить название и внешний идентификатор устройства (касса, POS, ECR, ККМ) в аккаунте HEADO и получить auth_key устройства для работы с Device API.

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

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

NAME TYPE DESCRIPTION
cashbox_ext_id string(64) Внешний идентификатор «устройства» в HEADO
params object Возможно изменить 2 параметра:
-name - string(200) Новое название устройства;
- new_ext_id - string(64) Новый внешний идентификатор устройства в HEADO

Пример запроса cashbox.update 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "id": "8361549266426897",
  "method": "cashbox.update",
  "params": {
    "cashbox_ext_id": "01",
    "params": {
      "name": "Касса №01",
      "new_ext_id": "kassa01"
    }
  },
  "jsonrpc": "2.0"
}

Пример ответа cashbox.update 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "cashbox_id": "120497",
        "name": "Касса №01",
        "store_ext_id": "26",
        "pos_ext_id": "kassa01",
        "auth_key": "Ключ устройства для работы с Device API"
    }
}

setCashbox

Метод позволяет зарегистрировать Торговую точку/Устройство (касса, POS, ECR, ККМ) в аккаунте HEADO и получить auth_key устройства для работы с Device API.

  • Если задан существующий *store_ext_id* то новое устройство регистрируется в составе (подчиненности) этому store_ext_id.
  • Если задан несуществующий *store_ext_id, то регистрируется **новая торговая точка и *устройство** в составе (подчиненности) этому store_ext_id.
  • При вызове с существующими store_ext_id и extId (устройства) регистрация нового устройства не происходит, метод возвращает cashbox_id и auth_key для существующего устройства.

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

При вызове с существующим *store_ext_id* название торговой точки будет заменено новым значением name.

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

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

NAME TYPE DESCRIPTION
location object Содержит следующие поля:
- country (string(60)): Название страны по КЛАДР или ФИАС
- city (string(60)): Название города по КЛАДР или ФИАС
- street (string(100): Название улицы по КЛАДР или ФИАС
- house (string(20): Дом, включая корпуса, литеры и т.п. (например 10/1а)
- store_ext_id (string(40): Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
- name (string(100)): Название торговой точки (можно изменить, отправив новое значение)
extid(устройства) string(64)
опционально		 Идентификатор устройства (касса, POS, ECR, ККМ), уникальный в пределах торговой точки.
ВАЖНО: Не передавать при регистрации устройства для передачи групповых данных о продажах (сервер торговой точки, группы торговых точек)

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "jsonrpc": "2.0",
  "id": "1551506945251343",
  "method": "setCashbox",
  "params": {
    "location": {
      "country": "Россия",
      "city": "Екатеринбург",
      "street": "Вайнера",
      "house": "9",
      "store_ext_id": "111",
      "name": "Server"
    },
    "extid": "22"
  }
}
Пример ответа setCashbox

1
2
3
4
5
6
7
8
{
  "jsonrpc": "2.0",
  "id": "1551506945251343",
  "result": {
    "cashbox_id": "идентификатор устройства в HEADO",
    "auth_key": "Ключ устройства для работы с Device API"
  }
}

store.create

Метод регистрирует новую Торговую точку с указанным количеством устройств (касса, POS, ECR, ККМ) в аккаунте HEADO и возвращает в массиве cashbox_id и auth_key устройства для работы с Device API. При ошибке возвращает код и описание ошибки

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

NAME TYPE DESCRIPTION
store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
params object name (string(100)): Название торговой точки
cashboxcount (uint = 0): Кол-во устройств создаваемых автоматически при создании торговой точки (до 30 устройств).Если = 0, то устройства будут созданы автоматически при получении чека
Объект location: Содержит следующие поля:
- type (string): тип адреса торговой точки postal (формальный почтовый адрес), postal-normalize (почтовый адрес, требующий формализации), internet (электронный, создается по согласованию с HEADO)
- country (string(60)): Название страны по КЛАДР или ФИАС
- city (string(60)): Название города по КЛАДР или ФИАС
- street (string(100): Название улицы по КЛАДР или ФИАС
- house (string(20): Дом, включая корпуса, литеры и т.п. (например 10/1а)
- meta (object: Произвольная структура метаданных

Пример запроса store.create

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "id": "1251506945251332",
  "method": "store.create",
  "params": {
    "store_ext_id": "test3",
    "params": {
      "name": "Торговая точка",
      "cashboxcount": "2",
      "location": {
        "type": "postal",
        "country": "Россия",
        "city": "Екатеринбург",
        "street": "Добролюбова",
        "house": 5
      }
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа store.create

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "addressId": "Идентификатор в системе HEADO",
        "store_ext_id": "test3",
        "cashboxes": [
            {
                "cashbox_id": "идентификатор устройства в HEADO",
                "auth_key": "Ключ устройства для работы с Device API"
            },
            {
                "cashbox_id": "идентификатор устройства в HEADO",
                "auth_key": "Ключ устройства для работы с Device API"
            }
        ]
    }
}

store.list

Метод для получения списка торговых точек. Область видимости определяется ключем auth_key устройства, используемого для вызова и параметром network_ext_id запроса. При ошибке возвращает код и описание ошибки

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

NAME TYPE DESCRIPTION
filter object Параметры фильтрации опциональны.
- network_ext_id (string(60)): Внешний идентификатор «Торговой сети» в торговой системe
- status (boolean): статус торговой точки. enabled - Включен, disabled (выключена)
- store_ext_id (string(40): Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
- limit: установленный лимит записей в ответе
-- offset: смещение выводимых записей (по умолчанию 0)
-- count: количество выводимых записей (по умолчанию 500)

Пример запроса store.list (filter)*

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "id": "1251506945251332",
  "method": "store.list",
  "params": {
    "filter": {
      "network_ext_id": "",
      "status":"enabled",
      "limit": {
        "offset": 0,
        "count": 500
      }
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа store.list (filter)

 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
{
    id : <ulong>, // Внутренний идентификатор ТТ
    network_ext_id: <string(40)>, //Внешний идентификатор Сети
    store_ext_id: <string(40)>, //Внешний идентификиатор ТТ
    workgroup : <array of  [  
        <string(64) /*Role*/>  : <string(200) /*Name*/>, // Роль-Имя
        ..
        ], >
    offset: <utinyint(3)>, // Часовой пояс
    schedule : <array of [
      <utinyint(2)[1-7] /*weekday*/> : [ {
        from:<string(4)[0-2359] HHii>,
        to:<string(4)[0-2359] HHii>
      },.. ]
    ] >,
    name : <string(200)>, //Название ТТ
    address : { 
        type: <in ['postal','internet']>, //Тип адреса почтовый или электронный
        < // Если почтовый
        city: <string(64)>, // Город
        street: <string(200)>, //Улица
        house: <string(20)>,// Дом со всеми литералами
        >
    }
    ,
    tags : <array of string(200)> ,
}

store.get

Метод возвращает параметры торговой точки.

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

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

NAME TYPE DESCRIPTION
store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр

Пример запроса store.get(store_ext_id)

1
2
3
4
5
6
7
8
{
  "id": "8361549266426897",
  "method": "store.get",
  "params": {
    "store_ext_id": "44"
  },
  "jsonrpc": "2.0"
}
Пример ответа store.get(store_ext_id) 
 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
{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "data": [
            {
                "id": "ulong", // Внутренний идентификатор торговой точки
                "network_ext_id": "",  //Внешний идентификатор Сети
                "store_ext_id": "3073",  //Внешний идентификатор ТТ
                "workgroup": { // Роль
                    "PartnerTopManagerRole": "Нет",
                    "PartnerHeadRole": "Иванов И.И.",
                    "PartnerZoneManagerRole": "Петров Э.М.",
                    "PartnerManagerRole": "Магазин"
                },
                "offset": "4", // Часовой пояс
                "schedule": { //Расписание работы*/
                    "1": [
                        {
                            "from": 800,
                            "to": 2100
                        }
                    ],
                    "11": 0,
                    "12": 0,
                    "13": 0,
                    "14": 0,
                    "15": 0,
                    "16": 0,
                    "17": 0,
                    "2": [
                        {
                            "from": 800,
                            "to": 2100
                        }
                    ],
                    "3": [
                        {
                            "from": 800,
                            "to": 2100
                        }
                    ],
                    "4": [
                        {
                            "from": 800,
                            "to": 2100
                        }
                    ],
                    "5": [
                        {
                            "from": 800,
                            "to": 2100
                        }
                    ],
                    "6": [
                        {
                            "from": 800,
                            "to": 2100
                        }
                    ],
                    "7": [
                        {
                            "from": 900,
                            "to": 2100
                        }
                    ]
                },
                "name": "Магазин",   //Название ТТ
                "address": {
                    "type": "postal", //Тип адреса (почтовый/электронный)
                    "city": "Екатеринбург", //Город
                    "street": "Добролюбова", //Улица
                    "house": "2" //Дом со всеми литералами
                },
                "tags": [
                    "тег"
                ],
        "meta": [
          {
            "key1": "value1",  //Произвольное мета название из метода store.update
            "key2": "value2"  //Произвольное мета значения из метода store.update
          }
        ]
            }
        ]
    }
}

store.schedule

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

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

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

NAME TYPE DESCRIPTION
store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
schedule Array of Objects Объект массива:
- wday (tinyint) : 1-Понедельник, ... 7 - Воскресенье. Если у торговой точки выходной, то расписание не указывается
- from (string(5) ЧЧ:ММ) : Начало работы торговой точки
- to (string(5) ЧЧ:ММ): Конец работы торговой точки

Пример запроса store.schedule

 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
{
  "id": "1251506945251332",
  "method": "store.schedule",
  "params": {
    "store_ext_id": 123,
    "schedule": [
      {
        "wday": 1,
        "from": "10:00",
        "to": "20:00"
      },
      {
        "wday": 2,
        "from": "10:00",
        "to": "20:00"
      },
      {
        "wday": 3,
        "from": "10:00",
        "to": "20:00"
      },
      {
        "wday": 4,
        "from": "10:00",
        "to": "20:00"
      },
      {
        "wday": 5,
        "from": "10:00",
        "to": "22:00"
      },
      {
        "wday": 6,
        "from": "11:00",
        "to": "19:00"
      },
      {
        "wday": 7,
        "from": "11:00",
        "to": "19:00"
      }
    ]
  },
  "jsonrpc": "2.0"
}

Пример ответа store.schedule*

1
2
3
4
5
6
7
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "addressId": "4490" /*<Идентификатор в системе Гифтоман>*/ 
  }
}

store.removeTags

store.assignTags

Методы назначают и удаляют теги на торговой точке зарегистрированной в ЛК HEADO.

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

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

NAME TYPE DESCRIPTION
store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
tags Mixed(String(20), Array of String(200)) Массив строк-идентификаторов: tags = '@all' - удалить все теги

Пример запроса store.assignTags(store_ext_id, tags)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "id": "1251506945251332",
  "method": "store.assignTags",
  "params": {
    "store_ext_id": "5",
    "tags": [
      "01",
      "02",
      "03",
      "04"
    ]
  },
  "jsonrpc": "2.0"
}

store.update

Метод позволяет изменить статус торговой точки (включить/выключить) зарегистрированной в ЛК HEADO.

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

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

NAME TYPE DESCRIPTION
store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
params object {
name (string(100)): Название торговой точки (можно изменить, отправив новое значение)
status (boolean): - enabled - Меняет статус торговой точки на "Включен".
- disabled - Меняет статус торговой точки на "Выключен"
- test - Меняет статус на "тестовый". Используется для торговых точек, готовящихся к открытию.
meta (object): Произвольная структура, объёмом до 32Кб для хранения неупорядоченных данных
}

Пример запроса store.update*

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "id": "1251506945251332",
  "method": "store.update",
  "params": {
    "store_ext_id": "26",
    "params": {
      "status": "enabled",
      "name": "Новое название",
      "meta": {
        "key1": "value1",
        "stockCostTarget": "Норма товарного запаса в руб",
        "tradeType": "формат торговой точки"
      }
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа store.update

1
2
3
4
5
6
7
8
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "addressId": "18209",
        "store_ext_id": "26"
    }
}

tag.organize

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

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

Метод позволяет группировать мелкие формации тегов в более крупные (Регионы и т.п.)

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

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

NAME TYPE DESCRIPTION
root_tag string(200) Корневой метатег (назание групп привязки в "администрировании зон".)
tags Array of String(200) Массив строк-идентификаторов

Пример запроса tag.organize

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "id": "1251506945251332",
  "method": "tag.organize",
  "params": {
    "root_tag": "test",
    "tags": [
      "01",
      "02",
      "03"
    ]
  },
  "jsonrpc": "2.0"
}
Пример ответа tag.organize

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "data": {
            "root_tag": "test",
            "tags": [
                "01",
                "02",
                "03"
            ]
        }
    }
}

tag.list

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

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

Метод возвращает список тегов аккаунта.

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

Пример запроса tag.list

1
2
3
4
5
6
{
  "id": "1251506945251332",
  "method": "tag.list",
  "params": {},
  "jsonrpc": "2.0"
}
Пример ответа tag.list

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "data": [
      {
        "id": "1554204958",   // Системный идентификатор тега
        "name": "01",         //Название тега
        "is_meta": false,     // true, если Метатег
        "tags": null          // null, если не Метатег
      },
      {
        "id": "1634726826",
        "name": "test223",
        "is_meta": false,
        "tags": null
      }
    ]
  }
}

tag.get

Метод возвращает параметры указанного тега. Список тегов с указанием внутренних идентификаторов можно получить с помощью tag.list().

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

Пример запроса tag.get 

1
2
3
4
5
6
7
8
{
  "id": "1251506945251332",
  "method": "tag.get",
  "params": {
    "name": "01"
  },
  "jsonrpc": "2.0"
}
Пример ответа tag.get

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "data": {
        "id": "1554204958",   // Системный идентификатор тега
        "name": "01",         //Название тега
        "is_meta": false,     // true, если Метатег
        "tags": null          // null, если не Метатег
    }
  }
}

Передача фактов торговой точки

receipt.processBatch

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

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

Attention

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

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

NAME TYPE DESCRIPTION
items 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)) : ФИО продавца для конкретной позиции (необходим для мотивации продавцов из разнных отделов).
-- categories (array) : [Массив групп товаров] Иерархическая структура категорий/подкатегорий товара и дополнительные метки. Структура передается последовательно, начиная с первого уровня. Длина каждой категории/метки не более 120 символов
-- extId (string(40)) : Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв.
},..
]
- attributes (array) : [ Массив свободных атрибутов чека (карты лояльности, платёжные системы и т.п.) для дополнительной аналитики.{
-- name (string(20)) : Название атрибута (английские мнемоники),
-- value (decimal(12,4)) : Значение атрибута (<0 при возврате)
},..
]
- path Ключ маппинга к устройству и торговой точки
-- Общий формат: @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.

Пример запроса receipt.processBatch 

 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
{
  "jsonrpc": "2.0",
  "id": "7241520367540836",
  "method": "receipt.processBatch",
  "params": {
    "items": [
      {
        "amount": 69.98,
        "discount": 0,
        "ts": "2022-02-13T16:39:51+05:00",
        "cashier": "Илона Давыдовна{2}",
        "extId": "bb802ad3-d268-4946-b80c-b963aaf66b22",
        "positions": [
          {
            "name": "Слойка с вишней",
            "count": 2,
            "total": 69.98,
            "seller": "Марина Ивановна",
            "categories": [
              "Хлеб и хлебобулочные изделия",
              "Выпечка",
              "Изделия из слоеного теста"
            ],
            "extId": "10002399"
          }
        ],
        "attributes": [
          {
            "name": "withcard",
            "value": "0"
          },
          {
            "name": "procspd",
            "value": "32"
          }
        ],
        "path": "@26/110"
      },
      {
        "amount": 71.99,
        "discount": 0,
        "ts": "2022-02-13T16:55:01+05:00",
        "cashier": "Илона Давыдовна",
        "extId": "34c39902-5554-4be3-a3b2-042a3a2a6262",
        "positions": [
          {
            "name": "Хлебцы ржаные",
            "count": 1,
            "total": 71.99,
            "seller": "Марина Ивановна",
            "categories": [
              "Хлеб и хлебобулочные изделия",
              "Хлебобулочные изделия",
              "Хлебцы"
            ],
            "extId": "10002326"
          }
        ],
        "attributes": [
          {
            "name": "withcard",
            "value": "1"
          },
          {
            "name": "procspd",
            "value": "25"
          }
        ],
        "path": "@26/110"
      }
    ]
  }
}

Пример ответа receipt.processBatch

1
2
3
4
5
6
7
8
{
    "jsonrpc": "2.0",
    "id": "7241520367540836",
    "result": {
        "count": 2,         \\кол-во зарегистрированных чеков
        "ts": "2022-02-17 08:49:05"
    }
}

price.inventoryReset

Метод сбрасывает количество товарных запасов в системе, загруженных через метод inventoryUpdateBatch

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

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

NAME TYPE DESCRIPTION
store_ext_ids string(40) (опционально) Массив строк-уникальных «Внешних идентификаторов торговых точек» торговой системы предприятия, состоящий из латинских букв или цифр. Параметр используется для сброса переданных товарных запасов на выбранных торговых точках

Пример запроса price.inventoryReset 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "id": "1951565327032225",
  "method": "price.inventoryReset",
  "params": {
    "store_ext_ids": [
      "26"
    ]
  },
  "jsonrpc": "2.0"
}
Пример ответа price.inventoryReset

1
2
3
4
5
6
7
{
  "jsonrpc": "2.0",
  "id": "1951565327032225",
  "result": {
    "status": "ok"
  }
}

inventory.updateBatch

Данный метод предназначен для загрузки состояния запасов на торговой точке на указанный момент времени (до 1000 позиций в запросе). В случае успеха возвращает количество загруженных в HEADO номенклатурных позиций. Дополнительно загружает признак присутствия номенклатурной позиции в ассортиментной матрице торговой точки. Один из параметров запаса должен присутствовать обязательно. Значения отсутствующих параметров остаются в HEADO неизменными. Таким образом метод может быть использован для раздельной загрузки сведений о присутствии номенклатурной позиции в ассортиментной матрице и количества запаса.

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

Attention

  • Рекомендуем реализовать выгрузку номенклатурного справочника, так как при отсутствии товара в системе HEADO, остатки по ней не будут обновлены.

  • Обновление информации о запасах должно выполняться не реже одного раза в сутки, например передавать остатки на конец завершенного рабочего дня.

  • Первая выгрузка остатков, должна выполняться полностью по действующей номенклатуре при выполнении хотя бы одного из условий (остатков > 0 или включен в матрицу)

  • Каждая последующая выгрузка должна выполнять дифференциально, т.е. только по номенклатуре по которой произошли изменения (включая остаток=0, если товара не осталось на складе по любой причине)

  • После реализации задачи, обязательно выполняется сверка по остаткам товаров.

  • Если в процессе передачи изменений накоплены ошибки, необходимо полностью сбросить информацию о товарных запасов, используя метод price.inventoryReset, а затем выполнить их выгрузку как при первой выгрузке

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

NAME TYPE DESCRIPTION
items Array of Objects
- Максимум 1000 элементов		 - items: [ {
-- store_ext_id (string(40)) - Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
-- price_ext_id (string(40)) - Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв. Обязательно должен соответствовать внешнему уникальному идентификатору получаемого из чека.
-- snapshot_datetime (string(ISO 8601 datetime)) - дата и время выгрузки актуального состояния инвентаря
-- last_sell_ts (string(ISO 8601 datetime)) - (опционально) дата и время последней продажи
Следующие параметры не являются обязательным, но один из них должен быть передан обязательно:
-- in_matrix (boolean) - признак наличия в товарной матрице торговой точки. 1-входит,0-не входит.
-- qty (decimal(13,4)) - количество товара на момент выгрузки состояния
-- sell_price (decimal(12,4)) - цена продажи за единицу
-- prime_cost (decimal(12,4)) - себестоимость товара "без НДС" за единицу (Стоимость всего остатка / количество = средневзвешенная цена)
-- min_stock_level (unsigned decimal(13,4)) (опционально) - минимальный товарный запас в единицах учета, если задано на группу товаров, то транслировать значение для группы на все товары группы.
-- stock_in_days (unsigned smallint) (опционально) - норма товарного запаса в днях, если задано на группу товаров, то транслировать значение для группы на все товары группы.
-- operations (Array of Objects) (опционально) - массив операций, которые произошли на конкретным SKU между snapshot_datetime
[
{
--- type (string) - тип операции: "income"(Приход), "writeoff"(Списание), "move"(Перемещение), "return"(Возврат)
--- qty (decimal(13,4)) - количество товара
--- ts (string(ISO 8601 datetime) - дата и время операции
]
},...
- ]

Пример запроса inventory.updateBatch

 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
{
  "id": "1251506945251332",
  "method": "inventory.updateBatch",
  "params": {
    "items": [
      {
        "store_ext_id": "226",
        "price_ext_id": "1239187239487",
        "snapshot_datetime": "2021-06-01 12:00",
        "last_sell_ts": "2021-06-01 23:05",
        "in_matrix": "1",
        "qty": "5",
        "sell_price": "15.00",
        "prime_cost": "5.00",
        "min_stock_level": "1",
        "stock_in_days": "2",
        "operations": [
          {
            "type": "income",
            "qty": "1",
            "ts": "2021-05-31 12:00"
          },
          {
            "type": "return",
            "qty": "1",
            "ts": "2021-05-31 12:10"
          }
        ]
      },
      {
        "store_ext_id": "21",
        "price_ext_id": "1239187239487",
        "snapshot_datetime": "2021-06-01 12:00",
        "in_matrix": "1",
        "qty": "5",
        "purchase_price": "15.00",
        "prime_cost": "5.00",
        "min_stock_level": "1",
        "stock_in_days": "2",
        "operations": [
          {
            "type": "income",
            "qty": "1",
            "ts": "2021-05-31 12:05"
          }
        ]
      }
    ]
  },
  "jsonrpc": "2.0"
}

Пример ответа inventory.updateBatch

1
2
3
4
5
6
7
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "count": 2 /*<кол-во загруженных позиций в систему>*/ 
  }
}

store.registerEvent

Данный метод предназначен для загрузки в сервис HEADO событий(движения SKU, открытие/закрытие торговой точки), относящихся к торговой точке. События используются для подтверждения выполнения задач в их жизненном цикле

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

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

NAME TYPE DESCRIPTION
store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
pos_ext_id string(64)
(Опционально) «Внешний идентификатор устройства» (кассы/сервера) из торговой системы предприятия, состоящий из латинских букв или цифр
name string ** - shift/start** - событие открытия торговой точки (например: открытие самой первой кассовой смены)
** - shift/stop** - событие закрытия торговой точки (например: закрытие самой последней кассовой смены)
** - sku/writeoff** - Списание товара
- sku/move - Перемещение товара
- sku/income - Приход товара
- sku/return - Возврат товара
ts string(40)
(Опционально)		 Дата/время события
ext_id string(20):
(ISO8601)		 Идентификатор события (уникальный для sku/writeoff в пределах Клиента/Сети) генерируемого в торговой системе
params associative array {
owner: { // Объект владельца (ответственного) транзакции
name: (string(200)), // ФИО
ext_id: (string(40) (Опционально)), // Идентификатор ответственного в торговой системе },
sku: { // Объект SKU
ext_id: (string(40)), // идентификатор SKU в торговой системе
qty: (decimal(10,4)) // Количество единиц списываемого товара
}
}

Пример запроса store.registerEvent (списание sku)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "id": "8361549266426897",
  "method": "store.registerEvent",
  "params": {
    "store_ext_id": "226",
    "name": "sku/writeoff",
    "ts": "2023-12-04 12:01",
    "ext_id": "55165",
    "params": {
      "owner": {
        "name": "Иванов И.И.",
        "ext_id": "123"
      },
      "sku": {
        "ext_id": "105",
        "qty": "1"
      }
    }
  },
  "jsonrpc": "2.0"
}

Пример запроса store.registerEvent (открытие смены) 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "id": "8361549266426897",
  "method": "store.registerEvent",
  "params": {
    "store_ext_id": "2266",
    "pos_ext_id": "110",
    "name": "shift/start",
    "ts": "2024-04-10 15:00",
    "params": {}
  },
  "jsonrpc": "2.0"
}

Пример ответа store.registerEvent

1
2
3
4
5
6
7
8
{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "ts": "2021-02-11 12:00",
        "now": "2021-02-11 13:45"
    }
}

Управление номенклатурой

price.categoryReset

Метод очищает все позиции справочника номенклатуры от присвоенных категорий из ранее загруженного дополнительного номенклатурного справочника. Выполняется в случае, если далее будет обновляться не весь номенклатурный справочник.

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

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

NAME TYPE DESCRIPTION
store_ext_ids string(40) (опционально) Массив строк-уникальных «Внешних идентификаторов торговых точек» торговой системы предприятия, состоящий из латинских букв или цифр. Параметр используется для сброса загруженных категорий на выбранных торговых точках

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "id": "1951565327032225",
  "method": "price.categoryReset",
  "params": {
    "store_ext_ids": [
      "26"
    ]
  },
  "jsonrpc": "2.0"
}

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

1
2
3
4
5
6
7
{
  "jsonrpc": "2.0",
  "id": "1951565327032225",
  "result": {
    "status": "ok"
  }
}

price.updateBatch

Данный метод предназначен для пакетного обновления параметров номенклатурных позиций (справочника товаров). В случае отсутствия позиции с переданным **extId (номенклатуры) создается новая. Максимальное количество позиций в одном запросе 1000. В случае успешного выполнения возвращает количество загруженных/обновленных номенклатурных позиций.**

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

Attention

  • Если требуется полностью сбросить обновить категории/метки перед вызовом price.UpdateBatch выполните успешный вызов price.categoryReset.

  • Реализация метода обязательна для интеграций, использующих методы, ссылающиеся на extId (номенклатурной позиции), вызов которых возможен до регистрации первой продажи номенклатурной позиции. Например inventoryUpdateBatch, registerEvent. Выполнение по расписанию, период в соответствии с изменением номенклатуры, но не реже одного раза в неделю.

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

NAME TYPE DESCRIPTION
items Array of Objects
- Максимум 1000 элементов		 Объект массива:
- name (string(200)) : Название товара
- params (array) : объект параметров товарной позиции
{
-- extid (string(40)) - Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв. Обязательно должен соответствовать внешнему уникальному идентификатору получаемого из чека.
-- sku_id (string(40)) - «Человекочитаемый идентификатор товара» для отображения сотрудникам при постановке задач (используется, если extid товара сложный для восприятия)
-- categories (array) (опционально) - [Массив групп товаров] Иерархическая структура категорий/подкатегорий товара и дополнительные метки. Структура передается последовательно, начиная с первого уровня. Длина каждой категории/метки не более 120 символов
Опционально: перед доп.меткой в квадратных скобках, через запятую можно указать идентификаторы торговых точек (store_ext_id) на которую применяется данная метка на товара (например метка акции для одного или нескольких магазинов)
Пример: [1,3]Акция.
-- price (decimal(10,4)) (опционально) - Цена позиции (допускается передавать 0)
--vat (decimal(4,2)) (опционально) - Ставка НДС в процентах (например 20.00 для 20%)
-- units (опционально) - единица измерения:
--- alc_volume (опционально) - объем единицы товара в декалитрах, используемый в журнале учета объема розничной продажи алкогольной продукции
--- net_weight (опционально) - вес нетто единицы товара выраженный в килограммах
--- gross_weight (опционально) - общий вес единицы товара выраженный в килограммах
--- volume (опционально) - объем единицы товара выраженный в кубических метрах
--- area (опционально) - площадь единицы товара выраженная в квадратных метрах
--- length (опционально) - длина единицы товара выраженная в метрах
--- height (опционально) - высота единицы товара выраженная в метрах
--- width (опционально) - ширина единицы товара выраженная в метрах
--- items (опционально) - количество унитарных единиц в единице товара
-- ean (array)(опционально) - Массив штрих-кодов EAN8/13 до 100 элементов в массиве
-- meta (array)(опционально) - мета данные, позволяет передавать произвольную структуру данных длиной до 32к символов для сквозного хранения слабоупорядоченных структур.

Параметры запроса (архивная версия):

NAME TYPE DESCRIPTION
items Array of Objects
- Максимум 1000 элементов		 Объект массива:
- name (string(200)) : Название товара
- params (array) : объект параметров товарной позиции
{
-- extid (string(40)) - Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв. Обязательно должен соответствовать внешнему уникальному идентификатору получаемого из чека.
-- categories (array) (опционально) - [Массив групп товаров] Иерархическая структура категорий/подкатегорий товара и дополнительные метки. Структура передается последовательно, начиная с первого уровня. Длина каждой категории/метки не более 120 символов
Опционально: перед доп.меткой в квадратных скобках, через запятую можно указать идентификаторы торговых точек (store_ext_id) на которую применяется данная метка на товара (например метка акции для одного или нескольких магазинов)
Пример: [1,3]Акция.
-- price (decimal(10,4)) (опционально) - Цена позиции (допускается передавать 0)
-- vat (decimal(4,2)) (опционально) - Ставка НДС в процентах (например 20.00 для 20%)
-- unit_type (опционально) - единица измерения:
- 1 - шт
- 10 - литры
- 11 - мл
- 12 - ДАЛ (декалитры)
- 20 - кг
- 21 - граммы
- 30 - метры
- 31 - квадратные метры
-- unit_ratio (decimal(10,4)) (опционально) - Коэффициент, пакетное соотношение проданного количества к unit_type
-- ean (array)(опционально) - Массив штрих-кодов EAN8/13 до 100 элементов в массиве
-- meta (array)(опционально) - мета данные, позволяет передавать произвольную структуру данных длиной до 32к символов для сквозного хранения слабоупорядоченных структур.

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

 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
{
  "id": "1251506945251332",
  "method": "price.updateBatch",
  "params": {
    "items": [
      {
        "name": "Товар",
        "params": {
          "extId": "b0d42e5d-2757-5099-948c-cfa80ba94f86",
          "sku_id": "rt-00000082",
          "categories": [
            "Основная категория",
            "Подкатегория",
            "СТМ",
            "[shop1,shop5]Акция"
          ],
          "price": "150.00",
          "vat": "18",
          "units": {
            "alc_volume": "0.1",
            "net_weight": "1",
            "gross_weight": "2",
            "volume": "0.2",
            "area": "0.004",
            "length": "0.12",
            "height": "0.23",
            "width": "0.34",
            "items": "2"
          },
          "ean": [
            "4602850003263",
            "2150000000017"
          ],
          "meta": {
            "manufacturer": "Фабрика России"
          }
        }
      }
    ]
  },
  "jsonrpc": "2.0"
}

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

1
2
3
4
5
6
7
8
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "networkId": "510",   /*<Идентификатор «Торговой сети» в HEADO>*/ 
        "count": 1            /*<Кол-во принятых позиций>*/ 
    }
}

Управление показателями

kpi.list

Метод возвращает список показателей аккаунта.

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

Пример запроса kpi.list 

1
2
3
4
5
6
{ 
    "id":"1251506945251332",
    "method":"kpi.list",
    "params":{},     
   "jsonrpc":"2.0"
}
Пример ответа kpi.list

 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
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "data": [
      {
        "kpi_id": "1437627895975747735",
        "ext_id": null,
        "name": "Выручка",
        "zoneType": "1",
        "zoneId": 0,
        "calc_type": "SUM",
        "type": "sum",
        "order": "1",
        "filters": {
          "exclude": 0,
          "mode": "union"
        },
        "status": "enabled",
        "forecast_disabled": false,
        "groups": [],
        "workPeriod": {
          "from": "0000-00-00",
          "to": "9999-12-31"
        }
      },
      {
        "kpi_id": "1437627895975756023",
        "ext_id": "Promo",
        "name": "Акция",
        "zoneType": "3",
        "zoneId": 31041,
        "calc_type": "SUM",
        "type": "sum",
        "order": "99",
        "filters": {
          "positions": [
            {
              "id": "86897703",
              "extId": "9433",
              "name": "ВЕРТРАН ТАБ 24МГ №30 БЕЛУПО ЛЕКАРСТВА И КОСМЕТИКА Д.Д. - ХОРВАТИЯ"
            }
          ],
          "exclude": 0,
          "mode": "union"
        },
        "status": "enabled",
        "forecast_disabled": false,
        "groups": [],
        "workPeriod": {
          "from": "2023-12-01",
          "to": "2023-12-22"
        }
      }
    ]
  }
}

kpi.types

Метод возвращает список типов показателей.

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

Пример запроса kpi.types 

1
2
3
4
5
6
{ 
    "id":"1251506945251332",
    "method":"kpi.types",
    "params":{},     
   "jsonrpc":"2.0"
}
Пример ответа kpi.types 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "data": {
            "sum": "Выручка",
            "avg": "Средний чек",
            "count": "Количество продаж",
            "complexity": "Комплексность по корзине",
            "complexitylines": "Комплексность строковая",
            "refund": "Возвраты",
            "refund_count": "Количество возвратов",
            "attr_sum": "Сумма по атрибутам",
            "attr_avg": "Среднее по атрибутам",
            "position_count": "Кол-во по позициям"
        }
    }
}

kpi.add

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

Метод создает в аккаунте новый показатель, в случае успеха возвращает внутренний идентификатор созданного показателя.

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

Attention

Состав фильтра показателя формируется в момент вызова метода, не зарегистрированные в HEADO сущности, на которые ссылаются фильтры не будут включены в показатель.

В этом случае, для регистрации сущности, можно использовать метод priceUpdateBatch

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

NAME TYPE DESCRIPTION
name string(128) Название показателя
type string Тип показателя из списка "Типов показателей"
order uint = 0 Сортировка показателя (чем меньше - тем первее), 0 - по умолчанию. Если указать -1, автоматически подставится максимальное значение упорядочивания в списке показателей + 1 .
ext_id string(40) Уникальный «Внешний идентификатор показателя» из торговой системы предприятия, состоящий из латинских букв или цифр
params object { Объект расширенных настроек показателя (опционально)
-- status: (int) >0 - Выключен, 1 - включен, 2 - Архивный (Из архивного статуса показатель не возвращается этим методом)
-- showOnDevices: (boolean) true - Отображать Показатель в интерфейсе пользователя, false - не отображать
-- filter_roles: (array of string) [ Массив ролей, кто может видеть показатель (если не указан, видеть будут все)
--- 'PartnerAdminRole', // Админинистратор
--- 'PartnerTopManagerRole', Топ-менеджер
--- 'PartnerDivisionManagerRole', Дивизиональный директор
--- 'PartnerHeadRole', Региональный директор
--- 'PartnerZoneManagerRole', Зональный директор
--- 'PartnerLogisticsRole', Логист
--- 'PartnerManagerRole', Директор магазина
--- 'PartnerSellerRole', Продавец
--- 'PartnerAuxiliaryRole', Вспомогательная роль
--- 'PartnerMonitorRole', Оператор контроля
--- 'PartnerPayerRole' Плательщик
--- 'PartnerCategoryManagerRole' Категорийный менеджер
],
*-- zone: (object) { Зона привязки
*--- type: (int) 1 - Аккаунт, 2 - Сеть, 3 - Торговая точка, 20 - Теги
--- id: (bigint) Внутренний идентификатор торговой точки в системе HEADO(для Аккаунта = 0 )
--- ext_id: (string) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр (для Аккаунта = 0)
-- } *
**-- workPeriod: (object) { Период активности расчета показателя до момента выхода в Архивный статус (передавать период необходимо не позже начала его действия, т.е. заранее)
--- from: (date iso8601 Y-m-d), Начало периода (считает с 00 часов указанной даты)
--- to: (date iso8601 Y-m-d) Конец периода (Передавать следует именно следующий день, окончания периода)
-- } *
**-- filters: (object) Объект настроек фильтров показателя (опционально)
--- reset: [true,false] - сбросить старые значения фильтра,
--- positions: [ { Фильтрация по номенклатурным позициям
---- ext_id: (string(40)), Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв.Обязательно должен соответствовать внешнему уникальному идентификатору получаемого из чека.
---- name: (string(200)), Название номенклатурной позиции (Будет искать по нему, в случае отсутствия стабильного идентификатора ext_id)
---- price_threshold: (decimal(10,4)), //Цена товара в период проведения акции },.. До 1000 позиций
],
**--- categories: [ {
---- name: (string (200)),
},.. До 1000 категорий
],
--- attributes: [ { Фильтрация по атрибутам чека
---- name: (string(20)), Название атрибута
---- value: (string(10)) Значение атрибута
},.. Не более 100 атрибутов
]
-- sku_monitor_control: (boolean) Опциональный признак контроля SKU меток для монитора с помощью этого показателя
-- sku_pricetag_control: (boolean) Опциональный признак контроля в дисциплинах (true=включен, false=отключен)
-- forecast_disable: (boolean) Опциональный признак отключения прогнозов (true=отключены, false=включены)
-- format_value: (string) round(#,2) - # - значение, можно использовать функции round, ceil, floor
}

Пример запроса kpi.add

 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
{
  "id": "1251506945251332",
  "method": "kpi.add",
  "params": {
    "name": "Акция",
    "type": "sum",
    "order": "-1",
    "ext_id": "Promo",
    "params": {
      "status": 1,
      "showOnDevices": true,
      "filter_roles": [
        "PartnerTopManagerRole",
        "PartnerDivisionManagerRole"
      ],
      "zone": {
        "type": 3,
        "id": 31041
      },
      "workPeriod": {
        "from": "2023-12-01",   \\Акция стартует 02.08.2023 в 00:00:00
        "to": "2023-12-22"    \\Акция завершится 02.08.2023 в 23:59:59 (Передавать следует именно сл. день завершения акции завершения акции)
      },
      "filters": {
        "reset ": false,
        "positions": [
          {
            "ext_id": "163385"
          },
          {
            "ext_id": "100429664"
          },
          {
            "ext_id": "100578117"
          },
          {
            "ext_id": "100803687"
          }
        ]
      },
      "sku_monitor_control": true
    }
  },
  "jsonrpc": "2.0"
}

Пример ответа kpi.add 

1
2
3
4
5
6
7
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "kpi_id": "1437627895975742077" /*<идентификатор созданного показателя>*/
    }
}

kpi.delete

Метод удаляет показатель по внутреннему идентификатору. Список показателей с указанием внутренних идентификаторов можно получить с помощью kpi.list.

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

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

NAME TYPE DESCRIPTION
kpi_id bigint Удаляемый идентификатор показателя

Пример запроса kpi.delete

1
2
3
4
5
6
7
8
{
  "id": "1251506945251332",
  "method": "kpi.delete",
  "params": {
        "kpi_id": "1437627895975742072"
  },
  "jsonrpc": "2.0"
}

Пример ответа kpi.delete 

1
2
3
4
5
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": []
}

kpi.update

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

Метод обновляет существующий в аккаунте показатель, в случае успеха возвращает внутренний идентификатор обновленного показателя. Выбор показателя для обновления строго по внутреннему идентификатору, список показателей с указанием внутренних идентификаторов можно получить с помощью kpi.list.

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

Attention

Состав фильтра показателя формируется в момент вызова метода, не зарегистрированные в HEADO сущности, на которые ссылаются фильтры не будут включены в показатель.

В этом случае, для регистрации сущности, можно использовать метод priceUpdateBatch

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

NAME TYPE DESCRIPTION
id bigint Прямой идентификатор показателя в системе HEADO (обязателен при отсутствия параметра ext_id)
ext_id string(40) Уникальный «Внешний идентификатор показателя» из торговой системы предприятия, состоящий из латинских букв или цифр
name string(200) Новое название показателя
order uint Новое место в сортировке (опционально). Значение "-1" в определении максимального значения не участвует
params object { // Объект расширенных настроек показателя (опционально)
-- status: (int) // 0 - Выключен, 1 - включен, 2 - Архивный (Из архивного статуса показатель не возвращается этим методом)
-- showOnDevices: (boolean) // true - Отображать Показатель на устройствах, false - не отображать
-- filter_roles: (array of string) [ \ Массив ролей, кто может видеть показатель. Для сброса достаточно передать пустой массив Если параметр НЕ передаётся, то сброса не будет.
--- 'PartnerAdminRole', // Админинистратор
--- 'PartnerTopManagerRole', // Топ-менеджер
--- 'PartnerDivisionManagerRole', // Дивизиональный директор
--- 'PartnerHeadRole', // Региональный директор
--- 'PartnerZoneManagerRole', // Зональный директор
--- 'PartnerLogisticsRole', // Логист
--- 'PartnerManagerRole', // Директор магазина
--- 'PartnerSellerRole', // Продавец
--- 'PartnerAuxiliaryRole', // Вспомогательная роль
--- 'PartnerMonitorRole', // Оператор контроля
--- 'PartnerPayerRole' // Плательщик
--- 'PartnerCategoryManagerRole' // Категорийный менеджер
],
-- zone: (object) { // Зона привязки
--- type: (int) // 1 - Аккаунт, 2 - Сеть, 3 - Торговая точка, 20 - Теги
--- id: (bigint) // Внутренний идентификатор торговой точки в системе HEADO (для Аккаунта = 0 )
--- ext_id: (string) // Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр (для Аккаунта = 0)
-- } *
-- workPeriod: (object) { // Период работы показателя до момента выхода в Архивный статус
--- from: (date iso8601 Y-m-d), // От
--- to: (date iso8601 Y-m-d) // До
-- } *
-- filters: (object) // Объект настроек фильтров показателя (опционально)
--- reset: [true,false] - сбросить старые значения фильтра,
--- positions: [ { // Фильтрация по номенклатурным позициям
---- ext_id: (string(40)), // Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв. Обязательно должен соответствовать внешнему уникальному идентификатору получаемого из чека
---- name: (string(200)), //Название номенклатурной позиции (Будет искать по нему, в случае отсутствия стабильного идентификатора ext_id)
---- price_threshold: (decimal(10,4)), //Цена товара в период проведения акции },.. // До 1000 позиций
],
--- categories: [ {
---- name: (string (200)),
},.. // До 1000 категорий],
--- attributes : [ { // Фильтрация по атрибутам чека
---- name: (string(20)), // Название атрибута
---- value: (string(10)); // Значение атрибута
},.. // Не более 100 атрибутов
]
]
-- sku_monitor_control: (boolean) // Опциональный признак контроля SKU меток для монитора с помощью этого показателя
-- sku_pricetag_control: (boolean) // Опциональный признак контроля в дисциплинах [true=включен, false=отключен]
-- forecast_disable: (boolean) // Опциональный признак отключения прогнозов [true=отключены, false=включены]
-- format_value: (string) // round(#,2) - # - значение, можно использовать функции round, ceil, floor }

Пример запроса kpi.update

 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
{
  "id": "1251506945251332",
  "method": "kpi.update",
  "params": {
    "name": "Акция",
    "id": "1437627895975756023",
    "ext_id": "Promo",
    "order": 99,
    "params": {
      "status": 1,
      "showOnDevices": true,
      "filters": {
        "reset ": false,
        "positions": [
          {
            "name": "Мед МООП Цветочный 500г с/б (16)",
            "ext_id": "9433",
            "price_threshold": 0
          },
          {
            "name": "Блузка жен Sevenext F-025белый/красный",
            "ext_id": "000000001082016006"
          }
        ]
      },
      "sku_monitor_control": true,
      "sku_pricetag_control": false,
      "forecast_disable": false
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа kpi.update

1
2
3
4
5
6
7
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "kpi_id": "1437627895975737496"
    }
}

kpi.setValues

Метод устанавливает значение показателя. До 1000 показателей в одном запросе. Использует для передачи в HEADO значения показателя из внешней системы с возможностью отображения в интерфейсе HEADO. Выбор показателя для установки значения строго по внутреннему идентификатору, список показателей с указанием внутренних идентификаторов можно получить с помощью kpi.list.

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

Attention

  • Необходимо отправлять итоговые значения за указанный час. Система самостоятельно посчитает итоговые значения за разные часы.

  • В настройках показателя, обязательно включить опцию "Значения из внешнего источника данных"

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

NAME TYPE DESCRIPTION
kpis Array of Objects
- Максимум 1000 элементов		 [ {
--- kpi_id: (bigint) - прямой идентификатор показателя в системе HEADO (параметр игнорируется при наличии kpi_ext_id),
--- kpi_ext_id: (string(40)) - Уникальный «Внешний идентификатор показателя» из торговой системы предприятия, состоящий из латинских букв или цифр,
--- store_ext_id: (@string) - Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр,
--- ts: (string: ISO 8601 YYYY-MM-DD[Thh:mm]) - Дата/время регистрируемого значения,
--- value: (decimal(10,4)) - Значение показателя за указанный час (система агрегирует значения кратные одному часу),
--- weight: (decimal(10,4) = 1) - Вес показателя (для корректной работы AVG-показателей, по умолчанию = 1),
-- },... ]

Пример запроса kpi.setValues 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "id": "1251506945251332",
  "method": "kpi.setValues",
  "params": {
    "kpis": [
      {
        "kpi_id": "1437627895975756023",
        "kpi_ext_id": "Promo",
        "store_ext_id": "226",
        "ts": "2023-12-07 12:00",
        "value": "20",
        "weight": "1"
      }
    ]
  },
  "jsonrpc": "2.0"
}
Пример ответа kpi.setValues

1
2
3
4
5
6
7
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "count": 1 /*<кол-во обновленных показателей>*/
    }
}

kpiGroups.list

Метод возвращает список групп показателей аккаунта.

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

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

Пример запроса kpiGroups.list

1
2
3
4
5
6
{ 
    "id":"1251506945251332",
    "method":"kpiGroups.list",
    "params":{},     
   "jsonrpc":"2.0"
}

Пример ответа kpiGroups.list

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "data": [
            {
                "id": "87",
                "name": "название группы показателей",
                "role": "0",     /*Системный идентификатор роли*/
                "order": "1",    /*<порядок сортировки группы показателя>*/
                "status": "1"    /*<статус группы показателя(0 выключен)>*/
            }
        ]
    }
}

kpiGroups.add

Метод позволяет создать группу для показателей.

Выбор показателя и группы строго по внутренним идентификаторам:

  • Метод kpi.addToGroups - добавляет показатель в группу показателей
  • Метод kpi.list - возвращает список идентификаторов и настроек показателей
  • Метод kpiGroups.list - возвращает список идентификаторов и настроек групп показателей

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

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

NAME TYPE DESCRIPTION
name string Название группы показателей
order int(3) Порядок сортировки группы показателя (чем меньше - тем первее)
role string Системный идентификатор роли (если 0, то все). Список ролей описан в параметрах метода account.create

Пример запроса kpiGroups.add 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "id": "8361549266426897",
  "method": "kpiGroups.add",
  "params": {
    "name": "Категорийные показатели",
    "order": "3",
    "role": "PartnerCategoryManagerRole"
  },
  "jsonrpc": "2.0"
}

Пример ответа kpiGroups.add

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "data": {
            "id": null,
            "name": "Категорийные показатели",
            "role": "PartnerCategoryManagerRole",
            "order": "3",
            "status": 1
        }
    }
}

kpi.addToGroups

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

Выбор показателя и группы строго по внутренним идентификаторам:

  • Метод kpi.list - возвращает список идентификаторов и настроек показателей
  • Метод kpiGroups.list - возвращает список идентификаторов и настроек групп показателей

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

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

NAME TYPE DESCRIPTION
id bigint Идентификатор показателя
groups bigint Массив идентификаторов групп

Пример запроса kpi.addToGroups

1
2
3
4
5
6
7
8
9
{
  "id": "8361549266426897",
  "method": "kpi.addToGroups",
  "params": {
    "id": 1437627895975748400,
    "groups": [87, 88]
  },
  "jsonrpc": "2.0"
}
Пример ответа kpi.addToGroups

1
2
3
4
5
6
7
8
{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "kpi_id": "1437627895975748474",
        "groups": [87,88]
    }
}

kpi.removeFromGroups

Метод позволяет удалить принадлежность показателей из существующих групп показателей.

Выбор показателя и группы строго по внутренним идентификаторам:

  • Метод kpi.list - возвращает список идентификаторов и настроек показателей
  • Метод kpiGroups.list - возвращает список идентификаторов и настроек групп показателей

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

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

NAME TYPE DESCRIPTION
id bigint Идентификатор показателя
groups bigint Массив идентификаторов групп

Пример запроса kpi.removeFromGroups

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "id":"8361549266426897",
    "method":"kpi.removeFromGroups",
    "params":{
        "id":1437627895975748474,
        "groups":[87]

    },
    "jsonrpc":"2.0"
}

Пример ответа kpi.removeFromGroups

1
2
3
4
5
6
7
8
{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "kpi_id": "1437627895975748474",
        "groups": [87]
    }
}

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

store.planSet

Метод устанавливает/удаляет плановые значения торговой точки на нужный период. После установки всех плановых значений, необходимо вызвать метод store.planPublish для публикации плана и актуализации их значений.

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

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

NAME TYPE DESCRIPTION
store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
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, то выставляется план на месяц, иначе - на день

Пример запроса store.planSet: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "jsonrpc": "2.0",
  "id": "5239",
  "method": "store.planSet",
  "params": {
    "store_ext_id": "26",
    "metric": "p/1437627895975747735",
    "plan": "10955.6",
    "year": "2022",
    "month": "7",
    "day": "10"
  }
}

Примеры ответа store.planSet: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "jsonrpc": "2.0",
    "id": "5239",
    "result": {
        "addressId": "18209",   //ИД торговой точки в HEADO
        "metric": "p/1437627895975747735",  //Идентификатор показателя
        "plan": "10955.6",   //Установленный план
        "year": "2021",   //Год
        "month": "6",     //Месяц
        "day": "8"        //День
    }
}

store.planSetBatch

Метод устанавливает/удаляет плановые значения торговых точек на нужный период. После установки всех плановых значений, необходимо вызвать метод store.planPublish для публикации плана и актуализации их значений.

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

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

NAME TYPE DESCRIPTION
items Array of Objects
- Максимум 1000 элементов		 Объект массива:
- store_ext_id (string(40)): - Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
- kpi_id (decimal(10,4)): - прямой идентификатор показателя в системе HEADO (необязателен при наличии параметра kpi_ext_id)
- kpi_ext_id (string(40)): - Уникальный «Внешний идентификатор показателя» из торговой системы предприятия, состоящий из латинских букв или цифр
- plan (decimal(10,4)):
- - Если >=0, то установка планового значения = plan
- - Если <0, то удаление
- corr_plan (decimal(12,4)): Корректировка дневного плана
- year (uint): - Год
- month (tinyint): опционально - Месяц, если не указан или =-1, то выставляется план на год
- day (tinyint): опционально - День, если не указан или =-1, то выставляется план на месяц, иначе - на день

Пример запроса store.planSetBatch

 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
{
  "jsonrpc": "2.0",
  "id": "5239",
  "method": "store.planSetBatch",
  "params": {
    "items": [
      {
        "store_ext_id": "226",
        "kpi_id": "1437627895975756023",
        "kpi_ext_id": "Promo",
        "plan": "10955.6",
        "corr_plan": "10050.6",
        "year": "2023",
        "month": "12",
        "day": "5"
      },
      {
        "store_ext_id": "32",
        "kpi_id": "1437627895975756023",
        "kpi_ext_id": "Promo",
        "plan": "89200.6",
        "year": "2023",
        "month": "12",
        "day": "5"
      }
    ]
  }
}

Параметры ответа store.planSetBatch

1
2
3
4
5
6
7
8
{
    "jsonrpc": "2.0",
    "id": "5239",
    "result": {
        "cnt": 2,
        "status": "ok"
    }
}

store.planPublish

Метод публикует планы для актуализаций значений, после их установки методом store.planSet.

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

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

NAME TYPE DESCRIPTION
store_ext_id string(40) Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
auto boolean - true - Использовать сервисную аналитику распределения по периодам.
- false - Не использовать аналитику (равномерное распределение по нижним периодам)
year number* Год (e.g. "2024") - опционально
month number* Месяц (e.g. 1) - опционально

Пример *запроса store.planPublish

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "jsonrpc": "2.0",
  "id": "5239",
  "method": "store.planPublish",
  "params": {
    "store_ext_id": "26",
    "auto": "true",
    "year": 2024
  }
}

Параметры ответа store.planPublish

1
2
3
4
5
6
7
8
{
    "jsonrpc": "2.0",
    "id": "5239",
    "result": {
        "addressId": "18209",
        "auto": true
    }
}

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

reports

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

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

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

NAME TYPE DESCRIPTION
id string(20) 'salesplans' - Получение отчёта о планах Торговой точки
filter obgect { "storeId": /* Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр */ }
range obgect { "from": "Y-m-d" /Дата от/, "to": "Y-m-d" /* Дата до */ }

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "id": "1251506945251332",
  "method": "reports",
  "params": {
    "id": "salesplans",
    "filter": {
      "storeId": 100
    },
    "range": {
      "from": "2017-09-01",
      "to": "2017-10-31"
    }
  },
  "jsonrpc": "2.0"
}

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

 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
{
"jsonrpc": "2.0",
"id": "1251506945251332",
"result": {
 "data": {
    "salesplans": {
      "id": "100",
      "uuid": "1457",
      "name": "Екатеринбург, ТЦ Курс",
      "data": {
         "periods": {
          "2017-09-01": { /* Список значений метрик на указанную дату*/
                   "1437627895975737336": { 
                      "fact": 73.16, // Фактическое значение метрики
                      "plan": 0, //Плановое значение
                      "forecast": 0 // Прогнозное (в фактических датах совпадает с фактом или = 0 для несуммарных метрик)
                     }
                 }
              }, ...
          "rules": [ // Список метрик 
                {
                    "id": "1437627895975737336",
                    "name": "Средний чек по группе",
                    "order": "0",
                    "type": "2"
                },...                                             
          ]
         }
    }
  }
 }
}

Управление пользователями

staffManning

Метод загружает штатное расписания сотрудников.

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

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

NAME TYPE DESCRIPTION
items Array of Objects - items: [ {
-- store_ext_id (string(40)) - Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр.
-- staff: {
fio (string(60)), - ФИО Сотрудника
ext_id (string(40)) (опционально), - Уникальный «Внешний идентификатор сотрудника» в торговой системе предприятия, состоящий из цифр или латинских букв
},
-- date: , - Дата записи по ISO8604 (Y-m-d)
-- workhours: [ { // Список рабочих периодов в указанный рабочий день
--- from: <ЧЧ:ММ>,
--- to: <ЧЧ:ММ>
--},... ],
-- breaks: (опционально) [ { // Периоды перерывов в указанный рабочий день. В случае отсутствия, система будет восстанавливать перерывы между рабочими периодами.
--- from: <ЧЧ:ММ>,
--- to: <ЧЧ:ММ>
--},... ],
},...
- ]

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

 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
{
  "id": "1251506945251332",
  "method": "staffManning",
  "params": {
    "items": [
      {
        "store_ext_id": "21",
        "staff": {
          "fio": "Иванов ИИ",
          "ext_id": "1"
        },
        "date": "2019-10-01",
        "workhours": [
          {
            "from": "09:00",
            "to": "18:00"
          }
        ],
        "breaks": [
          {
            "from": "12:00",
            "to": "13:00"
          }
        ]
      }
    ]
  },
  "jsonrpc": "2.0"
}
Пример ответа staffManning

1
2
3
4
5
6
7
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "count": 1
  }
}

account.create

account.update

Данные методы создают и обновляют аккаунт пользователя в системе для доступа в ЛК HEADO.

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

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

NAME TYPE DESCRIPTION
login string(200) Email. Обязателен при создании аккаунта и при отсутсвии ext_id (ид сотрудника)
ext_id string(40) (Опционально) Уникальный идентификатор сотрудника. Обязательно при обновлении, если отсутствует Login
data object { // Все поля опциональны (но как минимум одно должно быть указано)
-- name: (string(200)),
-- phone: (string(15)),
-- email: (string(200)),
-- ext_id (string(40)), // Новый уникальный идентификатор сотрудника
-- status: ([ 0, 1, 2 ]), // 0 - Not active, 1 - Active, 2 - Block
-- password: (string(128)),с
-- manager_login: (string(200)), // Логин назначаемого менеджера
-- role: ([
--- 'PartnerTopManagerRole', // Топ-менеджер
--- 'PartnerDivisionManagerRole', // Дивизиональный директор
--- 'PartnerHeadRole', // Региональный директор
--- 'PartnerZoneManagerRole', // Зональный директор
--- 'PartnerLogisticsRole', // Логист
--- 'PartnerManagerRole', // Директор магазина
--- 'PartnerSellerRole', // Продавец
--- 'PartnerAuxiliaryRole', // Вспомогательная роль
--- 'PartnerMonitorRole', // Оператор контроля
--- 'PartnerPayerRole' // Плательщик
--- 'PartnerCategoryManagerRole' // Категорийный менеджер
-- meta (опционально) Произвольная структура данных, длиной до 32к символов для сквозного хранения слабоупорядоченных структур.
-- access: (boolean), // allow - доступ разрешен и deny - доступ запрещен
])}

Пример запроса account.create ( login [, data ] ):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "id": "1251506945251332",
  "method": "account.update",
  "params": {
    "login": "test_test02@heado.ru",
    "ext_id": "123",
    "data": {
      "name": "Иванов В.Ю.",
      "phone": "9777777771",
      "email": "test@heado.ru",
      "status": "0",
      "password": "12345678",
      "manager_login": null,
      "role": "PartnerTopManagerRole",
      "access": "deny",
      "meta": {
        "key1": "value1",
        "key2": "value2"
      },
      "ext_id": "123"
    }
  },
  "jsonrpc": "2.0"
}

Пример ответа account.create ( login [, data ] ):

 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
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "data": {
      "id": "1606230962628279808",
      "name": "Иванов",
      "login": "test@heado.ru",
      "manager": {     // Назначенный менеджер, false, если нет.
        "id": "0",
        "name": "",
        "login": null,
        "phone": null,
        "email": null,
        "image": "",     //Ссылка на изображение
        "role": []     //Системный идентификатор роли
      },
      "zones": [],     // account : Аккаунт, network: Сеть, tag: Тег, address: ТТ
      "phone": "8977777777",
      "email": "test@heado.ru",
      "image": "",     //Ссылка на изображение
      "role": "PartnerTopManagerRole",
      "roleTitle": "Топ-менеджер",     //Человекочитаемое название роли
      "lang": "ru_ru",     //Выбранная локализация
      "meta": [   //мета данные
               {
          "key1": "key1",
          "key2": "value2"
        }
      ]
    }
  }
}

account.list

Данный метод возвращает список аккаунтов пользователей в системе HEADO с возможностью их фильтрации по ролям:

  • 'PartnerTopManagerRole', - Топ-менеджер
  • 'PartnerDivisionManagerRole', - Дивизиональный директор
  • 'PartnerHeadRole', - Региональный директор
  • 'PartnerZoneManagerRole', - Зональный директор
  • 'PartnerLogisticsRole', - Логист
  • 'PartnerManagerRole', - Директор магазина
  • 'PartnerSellerRole', - Продавец
  • 'PartnerAuxiliaryRole', - Вспомогательная роль
  • 'PartnerMonitorRole', - Оператор контроля
  • 'PartnerPayerRole' - Плательщик
  • 'PartnerCategoryManagerRole' - Категорийный менеджер

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

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

NAME TYPE DESCRIPTION
filter object Все поля опциональны (но как минимум одно должно быть указано)
-- role: имя роли
-- network_ext_id: Внешний идентификатор Сети
-- limit: установленный лимит
--- offset: смещение выводимых записей
--- count: количество выводимых записей (по умолчанию 100)

Пример запроса account.list (filter):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "id": "1951565327032225",
  "method": "account.list",
  "params": {
    "filter": {
      "role": "PartnerManagerRole",
      "network_ext_id": "",
      "limit": {
        "offset": 0,
        "count": 100
      }
    }
  },
  "jsonrpc": "2.0"
}

Пример ответа account.list (filter): 

 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
{
    "jsonrpc": "2.0",
    "id": "1951565327032225",
    "result": {
        "data": [
            {
                "id": "1555505106436699136",
                "ext_id": "",
                "login": "test@heado.ru",
                "name": "Иванов",
                "email": "test@heado.ru",
                "phone": "8977777777",
                "role": "PartnerManagerRole",
                "zones": [ ],     // account : Аккаунт, network: Сеть, tag: Тег, address: ТТ
                "image": "",     //Ссылка на изображение
                "status": "1",
                "manager": {     // Назначенный менеджер, false, если нет.
                    "id": "0",
                    "login": null,
                    "name": null,
                    "email": null,
                    "phone": null,
                    "role": "",      //Системный идентификатор роли
                    "extId": "",
                    "zones": [],       // account : Аккаунт, network: Сеть, tag: Тег, address: ТТ
                    "status": "0"
                },
                "role_title": "Директор магазина",     //Человекочитаемое название роли
                "lang": "ru_ru",     //Выбранная локализация
      "meta": [ //мета данные
        {
          "key": "key1",
          "value": "value1"
        },
        {
          "key": "key2",
          "value": "value2"
        }
      ],
      "access": "allow"    //allow - разрешен доступ и deny - запрещен
            }
        ],
        "full_count": "1",       // Кол-во найденных аккаунтов
        "limit": {
            "offset": 0,     
            "count": 100  
        }
    }
}

account.assignZones

account.removeZones

Данные методы назначают и удаляют зоны видимости аккаунта пользователя к торговым точкам в системе HEADO

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

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

NAME TYPE DESCRIPTION
login string(200) Email
zones object [{
-- type: ([account, network, tag, address, category]), // Тип зоны: account: Аккаунт, network: Сеть, tag: Тег, address: Торг.точки, category: категория Сети
-- id: (string(200)), // Внутренний идентификатор торговой точки в системе HEADO. Отсутствует у account
-- ext_id: (string(40)), // Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр. Может быть использовано с [network,address]
-- control: (boolean), // (опционально) true(1), false(0) состояние зоны "Под контролем".
}]

Примеры запросов account.assignZones(login, zones)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "id": "1251506945251332",
  "method": "account.assignZones",
  "params": {
    "login": "test@heado.ru",
    "zones": [
      {
        "type": "account",
        "id": "",
        "ext_id": ""
      }
    ]
  },
  "jsonrpc": "2.0"
}


 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "id": "1251506945251332",
  "method": "account.assignZones",
  "params": {
    "login": "test@heado.ru",
    "zones": [
      {
        "type": "tag",
        "id": "01",
        "ext_id": ""
      }
    ]
  },
  "jsonrpc": "2.0"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "id": "1251506945251332",
  "method": "account.assignZones",
  "params": {
    "login": "test@heado.ru",
    "zones": [
      {
        "type": "address",
        "id": null,
        "ext_id": "5"
      }
    ]
  },
  "jsonrpc": "2.0"
}

Пример ответа account.assignZones(login, zones)

 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
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "data": {
            "id": "1606230962628279808",
            "name": "Иванов",
            "login": "test@heado.ru",
            "manager": {
                "id": "0",
                "name": "",
                "login": null,
                "phone": null,
                "email": null,
                "image": "",
                "role": []
            },
            "zones": [
                {
                    "type": "account"     // тип зоны: account : Аккаунт, network: Сеть, tag: Тег, address: торг.точки
                }
            ],
            "phone": "8977777788",
            "email": "test@heado.ru",
            "image": "",     //Ссылка на изображение
            "role": "PartnerTopManagerRole",
            "roleTitle": "Топ-менеджер",     //Человекочитаемое название роли
            "lang": "ru_ru"     //Выбранная локализация
        }
    }
}

account.sendInvite

Данный метод позволяет выслать почтовые приглашения на активацию аккаунта пользователей в системе HEADO. Список аккаунтов можно получить, через метод account.list

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

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

NAME TYPE DESCRIPTION
login string(200) Email - логин
data unsigned
int		 Добавленное время экспирации приглашения в секундах (не больше 30 дней)

Пример запроса account.sendInvite(login, expiry)

1
2
3
4
5
6
7
8
9
{
  "id": "1251506945251332",
  "method": "account.sendInvite",
  "params": {
    "login": "test@heado.ru",
    "expiry": "86400"
  },
  "jsonrpc": "2.0"
}

Пример ответа account.sendInvite(login, expiry) 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "data": {
            "uid": "1644405670108438016",
            "status": "ok"
        }
    }
}