Management API
Общие положения
Для взаимодействия с Management API требуется ключ доступа (auth_key) типа терминала: "Административный терминал". Получить auth_key можно через ЛК HEADO
Обращение к Management API выполняется через URI:
https://api.heado.ru/management/<auth_key>
https://gamma.heado.ru/management/<auth_key> (для ключей домена gamma)
Уровень доступа к данным, ограничен на уровне <auth_key> торговой сети, которой он принадлежит

Конфигурация торговой сети
cashbox.create(store_ext_id, cashbox_ext_id, name [, params]);
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)
Метод позволяет зарегистрировать устройство (касса, POS, ECR, ККМ) в аккаунте HEADO и получить auth_key устройства для работы с Device API.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
store_ext_idstring(40)Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
cashbox_ext_idstring(64)Внешний идентификатор устройства в HEADO
namestring(200)Название устройства (Кассы,Сервера,ПК)
paramsobjectпараметр type (boolean) имеет 2 значения:
  • gui - используется для взаимодействия с Device API и для установки ПО HEADO на рабочее место торгового предприятия для отображения показателей;
  • server - используется для взаимодействия с Device API и для установки ПО HEADO на сервер торгового предприятия (используется как мидсервер, без графического интерфейса)
Пример запроса cashbox.create
{
  "id": "1251506945251332",
  "method": "cashbox.create",
  "params": {
    "store_ext_id": "26",
    "cashbox_ext_id": "01",
    "name": "Касса №1",
    "params": {
      "type": "gui"
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа cashbox.create
{
  "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( filter);
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)
Метод для получения списка торговых точек и устройств в аккаунте HEADO.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
filterobject Можно применить фильтрацию (опционально):
Пример запроса cashbox.list
{
  "id": "1251506945251332",
  "method": "cashbox.list",
  "params": {
    "filter": {
      "store_ext_id": "26"
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа cashbox.list
{
  "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": "Название устройства (Кассы и т.д.)",
        "address": {
          "type": "postal",
          "city": "Екатеринбург",
          "street": "Добролюбова",
          "house": "2"
        },
        "status": "enabled"
      }
    ],
    "networks": {
      "510": { 
        "id": "значение network_id",
        "ext_id": "значение network_ext_id",
        "name": "Название «Торговой сети» сети в аккаунте HEADO",
        "city": "Основной город сети в аккаунте HEADO"
      }
    },
    "account": {
      "name": "Название аккаунта",
      "role": "Системный идентификатор роли",
      "login": "Логин аккаунта"
    }
  }
}

cashbox.get(cashbox_ext_id);
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)
Метод для данных по конкретному устройству в аккаунте HEADO. Полный список устройств, можно получить через метод cashbox.list
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
cashbox_ext_idobject Можно применить фильтрацию (опционально):
  • cashbox_ext_id (string(64)): Внешний идентификатор «устройства» в HEADO
Пример запроса cashbox.get
{
  "id": "8361549266426897",
  "method": "cashbox.get",
  "params": {
    "cashbox_ext_id": "01"
  },
  "jsonrpc": "2.0"
}
Пример ответа cashbox.get
{
  "jsonrpc": "2.0",
  "id": "8361549266426897",
  "result": {
    "data": [
      {
        "cashbox_id": "120497",
        "cashbox_ext_id": "01",
        "store_ext_id": "26",
        "name": "Касса №1",
        "address": "Добролюбова, 2"
      }
    ]
  }
}

cashbox.update(cashbox_ext_id, params);
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод позволяет изменить название и внешний идентификатор устройства (касса, POS, ECR, ККМ) в аккаунте HEADO и получить auth_key устройства для работы с Device API.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
cashbox_ext_idstring(64)Внешний идентификатор «устройства» в HEADO
paramsobjectВозможно изменить 2 параметра:
Пример запроса cashbox.update
{
  "id": "8361549266426897",
  "method": "cashbox.update",
  "params": {
    "cashbox_ext_id": "01",
    "params": {
      "name": "Касса №01",
      "new_ext_id": "kassa01"
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа cashbox.update
{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "cashbox_id": "120497",
        "name": "Касса №01",
        "store_ext_id": "26",
        "pos_ext_id": "kassa01",
        "auth_key": "Ключ устройства для работы с Device API"
    }
}

setCashbox( location, extid);
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод позволяет зарегистрировать Торговую точку/Устройство (касса, POS, ECR, ККМ) в аккаунте HEADO и получить auth_key устройства для работы с Device API.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
locationobjectСодержит следующие поля:
  • 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
{
  "jsonrpc": "2.0",
  "id": "1551506945251343",
  "method": "setCashbox",
  "params": {
    "location": {
      "country": "Россия",
      "city": "Екатеринбург",
      "street": "Вайнера",
      "house": "9",
      "store_ext_id": "111",
      "name": "Server"
    },
    "extid": "22"
  }
}
Пример ответа setCashbox
{
  "jsonrpc": "2.0",
  "id": "1551506945251343",
  "result": {
    "cashbox_id": "идентификатор устройства в HEADO",
    "auth_key": "Ключ устройства для работы с Device API"
  }
}

store.create (store_ext_id, params = [] )
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод регистрирует новую Торговую точку с указанным количеством устройств (касса, POS, ECR, ККМ) в аккаунте HEADO и возвращает в массиве cashbox_id и auth_key устройства для работы с Device API.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
store_ext_id(string(40)Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
paramsobject name (string(100)): Название торговой точки
cashboxcount (uint = 0): Кол-во устройств создаваемых автоматически при создании торговой точки (до 30 устройств). Если = 0, то устройства будут созданы автоматически при получении чека.
Объект location: Содержит следующие поля:
  • type (string): тип адреса торговой точки postal (почтовый адрес) и internet (электронный, создается по согласованию с HEADO)>
  • country (string(60)): Название страны по КЛАДР или ФИАС
  • city (string(60)): Название города по КЛАДР или ФИАС
  • street (string(100): Название улицы по КЛАДР или ФИАС
  • house (string(20): Дом, включая корпуса, литеры и т.п. (например 10/1а)
Пример запроса store.create
{
  "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
{
    "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 ([ network_ext_id ])
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод для получения списка торговых точек. Область видимости определяется ключем auth_key устройства, используемого для вызова и параметром network_ext_id запроса.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
network_ext_idstring(200)
Опционально
Внешний идентификатор «Торговой сети» в торговой системe
Пример запроса store.list ([ network_ext_id ])
{
  "id": "1251506945251332",
  "method": "store.list",
  "params": {
    "filter": [
      {
        "network_ext_id": ""
      }
    ]
  },
  "jsonrpc": "2.0"
}
Пример ответа store.list ([ network_ext_id ])
{
	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(store_ext_id)
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод возвращает параметры торговой точки.
При ошибке возвращает код и описание ошибки
NAMETYPEDESCRIPTION
store_ext_idstring(40)Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
Пример запроса store.get(store_ext_id)
{
  "id": "8361549266426897",
  "method": "store.get",
  "params": {
    "store_ext_id": "44"
  },
  "jsonrpc": "2.0"
}
Пример ответа store.get(store_ext_id)
{
    "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
          }
        ]
            }
        ]
    }
}

storeSchedule(store_ext_id,schedule);
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод актуализирует расписание работы торговой точки на каждый день рабочей недели.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
store_ext_idstring(40)Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
scheduleArray of Objects Объект массива:
- wday (tinyint) : 1-Понедельник, ... 7 - Воскресенье. Если у торговой точки выходной, то расписание не указывается
- from (string(5) ЧЧ:ММ) : Начало работы торговой точки
- to (string(5) ЧЧ:ММ): Конец работы торговой точки
Пример запроса storeSchedule
{
  "id": "1251506945251332",
  "method": "storeSchedule",
  "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"
}
Пример ответа storeSchedule
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "addressId": "4490" /*<Идентификатор в системе Гифтоман>*/ 
  }
}

store.assignTags(store_ext_id, tags)
store.removeTags(store_ext_id, tags)
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Методы назначают и удаляют теги на торговой точке зарегистрированной в ЛК HEADO.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
store_ext_idstring(40)Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
tagsArray of String(200)Массив строк-идентификаторов
Пример запроса store.assignTags(store_ext_id, tags)
{
  "id": "1251506945251332",
  "method": "store.assignTags",
  "params": {
    "store_ext_id": "5",
    "tags": [
      "01",
      "02",
      "03",
      "04"
    ]
  },
  "jsonrpc": "2.0"
}

store.update(store_ext_id , params)
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод позволяет изменить статус торговой точки (включить/выключить) зарегистрированной в ЛК HEADO.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
store_ext_idstring(40)Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
namestring(100)
опционально
Название торговой точки (можно изменить, отправив новое значение)
statusboolean
опционально
- enabled - Меняет статус торговой точки на "Включен".
- disabled - Меняет статус торговой точки на "Выключен"
- test - Меняет статус на "тестовый". Используется для торговых точек, готовящихся к открытию.
metaarray
опционально
Произвольная структура данных, длиной до 32к символов для сквозного хранения слабоупорядоченных структур.
Пример запроса store.update
{
  "id": "1251506945251332",
  "method": "store.update",
  "params": {
    "store_ext_id": "26",
    "params": {
      "status": "enabled",
      "name": "Новое название",
      "meta": {
        "key1": "value1",
        "stockCostTarget": "Норма товарного запаса в руб",
        "tradeType": "формат торговой точки"
      }
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа store.update
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "addressId": "18209",
        "store_ext_id": "26"
    }
}

tag.organize(root_tag, tags)
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод позволяет группировать мелкие формации тегов в более крупные (Регионы и т.п.)
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
root_tagstring(200)Корневой метатег (назание групп привязки в "администрировании зон".)
tagsArray of String(200)Массив строк-идентификаторов
Пример запроса tag.organize
{
  "id": "1251506945251332",
  "method": "tag.organize",
  "params": {
    "root_tag": "test",
    "tags": [
      "01",
      "02",
      "03"
    ]
  },
  "jsonrpc": "2.0"
}
Пример ответа tag.organize
{
    "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
{
  "id": "1251506945251332",
  "method": "tag.list",
  "params": {},
  "jsonrpc": "2.0"
}
Пример ответа tag.list
{
  "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(name)
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод возвращает параметры указанного тега. Список тегов с указанием внутренних идентификаторов можно получить с помощью tag.list().
При ошибке возвращает код и описание ошибки
Пример запроса tag.get
{
  "id": "1251506945251332",
  "method": "tag.get",
  "params": {
    "name": "01"
  },
  "jsonrpc": "2.0"
}
Пример запроса tag.get
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "data": {
        "id": "1554204958",   // Системный идентификатор тега
        "name": "01",         //Название тега
        "is_meta": false,     // true, если Метатег
        "tags": null          // null, если не Метатег
    }
  }
}

Передача фактов торговой точки
receipt.processBatch (items);
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод предназначен для пакетной загрузки чеков продажи или возврата. Максимальный размер пакета - 100 чеков.
В случае успешной загрузки возвращает количество загруженных чеков и время их регистрации в HEADO.
При ошибке возвращает код и описание ошибки
ВАЖНО: Для регистрации чеков возврата параметр amount и значения value атрибутов чека передавать с отрицательным значением.
Параметры запроса:
NAMETYPEDESCRIPTION
itemsArray of ObjectsОбъект массива:
- amount (decimal(10,4)) : Итоговая сумма по чеку (скидки вычтены). Если >0, то продажа, если <0, то возврат
- 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 при возврате)
},..
]
- path Ключ маппинга к устройству и торговой точки
-- Общий формат: @store_ext_id/extid
--- store_ext_id (string(40)) - Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
--- extid (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
{
  "jsonrpc": "2.0",
  "id": "7241520367540836",
  "method": "receipt.processBatch",
  "params": {
    "items": [
      {
        "amount": 69.98,
        "discount": 0,
        "ts": "2022-02-13T16:39:51.000Z",
        "cashier": "Илона Давыдовна",
        "extId": "bb802ad3-d268-4946-b80c-b963aaf66b22",
        "positions": [
          {
            "name": "Слойка с вишней",
            "count": 2,
            "total": 69.98,
            "seller": "Марина Ивановна",
            "category": "Хлеб и хлебобулочные изделия&&Выпечка&&Изделия из слоеного теста",
            "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.000Z",
        "cashier": "Илона Давыдовна",
        "extId": "34c39902-5554-4be3-a3b2-042a3a2a6262",
        "positions": [
          {
            "name": "Хлебцы ржаные",
            "count": 1,
            "total": 71.99,
            "seller": "Марина Ивановна",
            "category": "Хлеб и хлебобулочные изделия&&Хлебобулочные изделия&&Хлебцы",
            "extId": "10002326"
          }
        ],
        "attributes": [
          {
            "name": "withcard",
            "value": "1"
          },
          {
            "name": "procspd",
            "value": "25"
          }
        ],
        "path": "@26/110"
      }
    ]
  }
}
Пример ответа receipt.processBatch
{
    "jsonrpc": "2.0",
    "id": "7241520367540836",
    "result": {
        "count": 2,
        "ts": "2022-02-17 08:49:05"
    }
}

price.inventoryReset();
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод сбрасывает количество товарных запасов в системе, загруженных через метод inventoryUpdateBatch
При ошибке возвращает код и описание ошибки
Пример запроса price.inventoryReset
{
  "id": "1951565327032225",
  "method": "price.inventoryReset",
  "params": {},
  "jsonrpc": "2.0"
}
Пример ответа price.inventoryReset
{
  "jsonrpc": "2.0",
  "id": "1951565327032225",
  "result": {
    "status": "ok"
  }
}

inventoryUpdateBatch(items);
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Данный метод предназначен для загрузки состояния запасов на торговой точке на указанный момент времени. В случае успеха возвращает количество загруженных в HEADO номенклатурных позиций.
Дополнительно загружает признак присутствия номенклатурной позиции в ассортиментной матрице торговой точки.
Один из параметров in_matrix, qty, sell_price, prime_cost должен присутствовать обязательно. Значения отсутствующих параметров остаются в HEADO неизменными. Таким образом метод может быть использован для раздельной загрузки сведений о присутствии номенклатурной позиции в ассортиментной матрице и количества запаса.
При ошибке возвращает код и описание ошибки
ВАЖНО:
- Рекомендуем обновлять информацию о запасах не реже одного раза в сутки, например передавать остатки на конец завершенного рабочего дня.
- Первая выгрузка остатков, должна выполняться полностью по действующей номенклатуре, а каждая последующая только по номенклатуре, где произошли изменения.
- Рекомендуем реализовать выгрузку номенклатурного справочника, так как при отсутствии товара в системе HEADO, то остатки по ней не будут обновлены.
- После реализации задачи, обязательно выполняется сверка по остаткам товаров.
Параметры запроса:
NAMETYPEDESCRIPTION
itemsArray of Objects - Максимум 1000 элементов - items: [ {
-- store_ext_id (string(40)) - Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
-- price_ext_id (string(40)) - Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв. Обязательно должен соответствовать внешнему уникальному идентификатору получаемого из чека.
-- snapshot_datetime (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) - дата и время операции
]
},...
- ]
Пример запроса inventoryUpdateBatch
{
  "id": "1251506945251332",
  "method": "inventoryUpdateBatch",
  "params": {
    "items": [
      {
        "store_ext_id": "26",
        "price_ext_id": "1239187239487",
        "snapshot_datetime": "2021-06-01 12:00",
        "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"
}
Пример ответа inventoryUpdateBatch
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "count": 2 /*<кол-во загруженных позиций в систему>*/ 
  }
}

storeRegisterEvent(store_ext_id, name, ts [, params])
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Данный метод предназначен для загрузки в сервис HEADO событий(движения SKU, открытие/закрытие торговой точки), относящихся к торговой точке.
События используются для подтверждения выполнения задач в их жизненном цикле
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
namestring - shift/start - событие открытия торговой точки (например: открытие самой первой кассовой смены)
- shift/stop - событие закрытия торговой точки (например: закрытие самой последней кассовой смены)
- sku/writeoff - Списание товара
- sku/move - Перемещение товара
- sku/income - Приход товара
- sku/return - Возврат товара
paramsassociative array{
ts: (string(20): ISO8601), // Дата/время события
store_ext_id: (string(40)), // Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
ext_id: (string(40) (Опционально)(, // Идентификатор события (уникальный для sku/writeoff в пределах Клиента/Сети) генерируемого в торговой системе
owner: { // Объект владельца (ответственного) транзакции
name: (string(200)), // ФИО
ext_id: (string(40) (Опционально)), // Идентификатор ответственного в торговой системе },
sku: { // Объект SKU
ext_id: (string(40)), // идентификатор SKU в торговой системе
qty: (decimal(10,4)) // Количество единиц списываемого товара
}
}
Пример запроса storeRegisterEvent (списание sku)
{
  "id": "8361549266426897",
  "method": "storeRegisterEvent",
  "params": {
    "store_ext_id": "4",
    "name": "sku/writeoff",
    "ts": "2021-02-11 12:00",
    "ext_id": "4656489",
    "params": {
      "owner": {
        "name": "Иванов И.И.",
        "ext_id": "123"
      },
      "sku": {
        "ext_id": "100827806",
        "qty": "1"
      }
    }
  },
  "jsonrpc": "2.0"
}
Пример запроса storeRegisterEvent (открытие смены)
{
  "id": "8361549266426897",
  "method": "storeRegisterEvent",
  "params": {
    "store_ext_id": "2",
    "name": "shift/start",
    "ts": "2020-02-12 09:00",
    "params": {}
  },
  "jsonrpc": "2.0"
}
Пример ответа storeRegisterEvent
{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "ts": "2021-02-11 12:00",
        "now": "2021-02-11 13:45"
    }
}

Управление номенклатурой
price.categoryReset();
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод очищает все позиции справочника номенклатуры от присвоенных категорий из ранее загруженного дополнительного номенклатурного справочника. Выполняется в случае, если далее будет обновляться не весь номенклатурный справочник.
При ошибке возвращает код и описание ошибки
Пример запроса priceCategoryReset
{
  "id": "1951565327032225",
  "method": "price.categoryReset",
  "params": {},
  "jsonrpc": "2.0"
}
Пример ответа priceCategoryReset
{
  "jsonrpc": "2.0",
  "id": "1951565327032225",
  "result": {
    "status": "ok"
  }
}

price.updateBatch(items );
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Данный метод предназначен для пакетного обновления параметров номенклатурных позиций (справочника товаров). В случае отсутствия позиции с переданным extId (номенклатуры) создается новая.
Максимальное количество позиций в одном запросе 1000.
В случае успешного выполнения возвращает количество загруженных/обновленных номенклатурных позиций.
При ошибке возвращает код и описание ошибки
ВАЖНО:
- Если требуется обновить категории/метки перед вызовом priceUpdateBatch выполните успешный вызов price.categoryReset.
- Реализация метода обязательна для интеграций, использующих методы, ссылающиеся на extId (номенклатурной позиции), вызов которых возможен до регистрации первой продажи номенклатурной позиции. Например inventoryUpdateBatch, registerEvent. Выполнение по расписанию, период в соответствии с изменением номенклатуры, но не реже одного раза в неделю.

Параметры запроса:
NAMETYPEDESCRIPTION
itemsArray of Objects - Максимум 1000 элементов Объект массива:
- name (string(200)) : Название товара
- params (array) : объект параметров товарной позиции {
-- extid (string(40)) - Уникальный «Внешний идентификатор товара» из справочника торговой системы предприятия, состоящий из цифр или латинских букв. Обязательно должен соответствовать внешнему уникальному идентификатору получаемого из чека.
-- category (string(200)) (опционально) - Иерархическая структура категорий/подкатегорий товара и дополнительные метки. Структура передается последовательно, начиная с первого уровня с использованием разделителя '&&'. Общая длина строки 2000 символов.
Опционально: перед доп.меткой в квадратных скобках можно через запятую, можно указать идентификаторы торговых точек (store_ext_id) на которую применяется данная метка на товара (например метка акции для одного или нескольких магазинов)
Пример: Категория&&Подкатегория&&..&&[1,3]Акция.
-- price (decimal(10,4)) (опционально) - Цена позиции (допускается передавать 0)
-- vat (decimal(4,2)) (опционально) - Ставка НДС в процентах (например 20.00 для 20%)
-- unit_type (опционально) - единица измерения: 1 - шт, 10 - литры, 11 - мл, 20 - кг, 21 - граммы, 30 - метры
-- unit_ratio (decimal(10,4)) (опционально) - Коэффициент, пакетное соотношение проданного количества к unit_type
-- ean (array)(опционально) - Массив штрих-кодов EAN8/13 до 100 элементов в массиве
-- meta (array)(опционально) - мета данные, позволяет передавать произвольную структуру данных длиной до 32к символов для сквозного хранения слабоупорядоченных структур.
Пример запроса priceUpdateBatch
{
  "id": "1251506945251332",
  "method": "price.updateBatch",
  "params": {
    "items": [
      {
        "name": "Носки \"Бумеранг\" 41-43",
        "params": {
          "extId": "1239187239487",
          "category": "Одежда&&Возможно нижняя&&СТМ",
          "price": "150.00",
          "vat": "18",
          "unit_type": "1",
          "unit_ratio": "1",
          "ean": [
            "4602850003263",
            "2150000000017"
          ],
          "meta": {
            "manufacturer": "Фабрика России"
          }
        }
      },
      {
        "name": "Пиво разливное\"Темноё\"",
        "params": {
          "extId": "3219187239487",
          "category": "Алкоголь&&Акция",
          "price": "120.00",
          "vat": "18",
          "unit_type": "10",
          "unit_ratio": "0.5",
          "ean": [
            "46000026"
          ],
          "meta": {
            "key1": "value1",
            "key2": "value2",
            "classif": [
              "value_cat1",
              "value_cat2",
              "value_cat3"
            ],
            "priceGroup": "Значение"
          }
        }
      }
    ]
  },
  "jsonrpc": "2.0"
}
Пример ответа priceUpdateBatch
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "networkId": "510",   /*<Идентификатор «Торговой сети» в HEADO>*/ 
        "count": 2            /*<Кол-во принятых позиций>*/ 
    }
}

Управление показателями
KPIList()
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод возвращает список показателей аккаунта.
При ошибке возвращает код и описание ошибки
Пример запроса KPIList
{ 
    "id":"1251506945251332",
    "method":"KPIList",
    "params":{},     
   "jsonrpc":"2.0"
}
Пример ответа KPIList
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "data": [
      {
        "kpi_id": "1437627895975733192",
        "name": "Дневная выручка",
        "type": "SUM",
        "order": "1"
      },
      {
        "kpi_id": "1437627895975733187",
        "name": "Выручка за месяц",
        "type": "SUM",
        "order": "2"
      }
    ]
  }
}

KPITypes()
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод возвращает список типов показателей.
При ошибке возвращает код и описание ошибки
Пример запроса KPITypes
{ 
    "id":"1251506945251332",
    "method":"KPITypes",
    "params":{},     
   "jsonrpc":"2.0"
}
Пример ответа KPITypes
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "data": {
            "sum": "Выручка",
            "avg": "Средний чек",
            "count": "Количество продаж",
            "complexity": "Комплексность по корзине",
            "complexitylines": "Комплексность строковая",
            "refund": "Возвраты",
            "refund_count": "Количество возвратов",
            "attr_sum": "Сумма по атрибутам",
            "attr_avg": "Среднее по атрибутам",
            "position_count": "Кол-во по позициям"
        }
    }
}

KPIAdd(name, [type = 'SUM', order = 0,params=[] ])
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод создает в аккаунте новый показатель, в случае успеха возвращает внутренний идентификатор созданного показателя.
При ошибке возвращает код и описание ошибки
ВАЖНО: Состав фильтра показателя формируется в момент вызова метода, не зарегистрированные в HEADO сущности, на которые ссылаются фильтры не будут включены в показатель. В этом случае, для регистрации сущности, можно использовать метод priceUpdateBatch
Параметры запроса:
NAMETYPEDESCRIPTION
namestring(128)Название показателя
typestringТип показателя из списка "Типов показателей"
orderuint = 0Сортировка показателя (чем меньше - тем первее), 0 - по умолчанию
paramsobject { // Объект расширенных настроек показателя (опционально)
-- status: (int) // >0 - Выключен, 1 - включен, 2 - Архивный (Из архивного статуса показатель не возвращается этим методом)
-- showOnDevices: (boolean) // true - Отображать Показатель в интерфейсе пользователя, false - не отображать
-- 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) },.. // До 1000 позиций
],
--- categories: [ {
---- name: (string (200)),
},.. // До 1000 категорий
],
--- attributes : [ { // Фильтрация по атрибутам чека
---- name: (string(20)), // Название атрибута
---- value: (string(10)) // Значение атрибута
},.. // Не более 100 атрибутов
]
-- sku_monitor_control: (boolean) // Опциональный признак контроля SKU меток для монитора с помощью этого показателя
}
Пример запроса KPIAdd
{
  "id": "1251506945251332",
  "method": "KPIAdd",
  "params": {
    "name": "Тест акционного KPI",
    "type": "sum",
    "order": 99,
    "params": {
      "status": 1,
      "showOnDevices": true,
      "zone": {
        "type": 3,
        "id": 12429
      },
      "workPeriod": {
        "from": "2020-05-12",   //Акция стартует 12.05.2020 в 00:00:00
        "to": "2020-05-13"     //Акция завершится 12.05.2020 в 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"
}
Пример ответа KPIAdd
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "kpi_id": "1437627895975742077" /*<идентификатор созданного показателя>*/
    }
}

KPIDelete(kpi_id)
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод удаляет показатель по внутреннему идентификатору. Список показателей с указанием внутренних идентификаторов можно получить с помощью KPIList.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
kpi_idbigintУдаляемый идентификатор показателя
Пример запроса KPIDelete
{
  "id": "1251506945251332",
  "method": "KPIDelete",
  "params": {
        "kpi_id": "1437627895975742072"
  },
  "jsonrpc": "2.0"
}
Пример ответа KPIDelete
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": []
}

KPIUpdate(id, name,[ order,params = [] ])
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод обновляет существующий в аккаунте показатель, в случае успеха возвращает внутренний идентификатор обновленного показателя. Выбор показателя для обновления строго по внутреннему идентификатору, список показателей с указанием внутренних идентификаторов можно получить с помощью KPIList.
При ошибке возвращает код и описание ошибки
ВАЖНО: Состав фильтра показателя формируется в момент вызова метода, не зарегистрированные в HEADO сущности, на которые ссылаются фильтры не будут включены в показатель. В этом случае, для регистрации сущности, можно использовать метод priceUpdateBatch
Параметры запроса:
NAMETYPEDESCRIPTION
idbigintПрямой идентификатор показателя в системе HEADO
namestring(200)Новое название показателя
orderuintНовое место в сортировке (опционально)
paramsobject { // Объект расширенных настроек показателя (опционально)
-- status: (int) // 0 - Выключен, 1 - включен, 2 - Архивный (Из архивного статуса показатель не возвращается этим методом)
-- showOnDevices: (boolean) // true - Отображать Показатель на устройствах, false - не отображать
-- 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 },.. // До 1000 позиций
],
--- categories: [ {
---- name: (string (200)),
},.. // До 1000 категорий
],
--- attributes : [ { // Фильтрация по атрибутам чека
---- name: (string(20)), // Название атрибута
---- value: (string(10)); // Значение атрибута
},.. // Не более 100 атрибутов
]
-- sku_monitor_control: (boolean); // Опциональный признак контроля SKU меток для монитора с помощью этого показателя
}
Пример запроса KPIUpdate
{
    "id": "1251506945251332",
    "method": "KPIUpdate",
    "params": {
        "name": "выручка",
        "id": "1437627895975737496",
        "order": 99,
        "params": {
            "status": 1,
            "showOnDevices": true,
            "filters": {
                "reset ": false,
        "positions": [
          {
            "name": "Мед МООП Цветочный 500г с/б (16)",
            "ext_id": "9433"
          },
          {
            "name": "Блузка жен Sevenext F-025белый/красный",
            "ext_id": "000000001082016006"
          }
                ]
            },
            "sku_monitor_control": true
        }
    },
    "jsonrpc": "2.0"
}
Пример ответа KPIUpdate
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "kpi_id": "1437627895975737496"
    }
}

KPISetValues(kpis)
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод устанавливает значение показателя. До 1000 показателей в одном запросе. Использует для передачи в HEADO значения показателя из внешней системы с возможностью отображения в интерфейсе HEADO. Выбор показателя для установки значения строго по внутреннему идентификатору, список показателей с указанием внутренних идентификаторов можно получить с помощью KPIList.
При ошибке возвращает код и описание ошибки
ВАЖНО:
  • Необходимо отправлять итоговые значения за указанный час. Система самостоятельно посчитает итоговые значения за разные часы.
  • В настройках показателя, обязательно включить опцию "Значения из внешнего источника данных"
NAMETYPEDESCRIPTION
kpisArray of Objects - Максимум 1000 элементов [ {
--- kpi_id: (bigint) - прямой идентификатор показателя в системе HEADO,
--- store_ext_id: (@string) - Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр,
--- ts: (string: ISO 8601 YYYY-MM-DD[Thh:mm]) - Дата/время регистрируемого значения,
--- value: (decimal(10,4)) - Значение показателя за указанный час (система агрегирует значения кратные одному часу),
--- weight: (decimal(10,4) = 1) - Вес показателя (для корректной работы AVG-показателей, по умолчанию = 1),
-- },... ]
Пример запроса KPISetValues
{
  "id": "1251506945251332",
  "method": "KPISetValues",
  "params": {
    "kpis": [
      {
        "kpi_id": "1437627895975737496",
        "store_ext_id": "206",
        "ts": "2020-01-20 12:00",
        "value": "9",
        "weight": "1"
      }
    ]
  },
  "jsonrpc": "2.0"
}
Пример ответа KPISetValues
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "count": 1 /*<кол-во обновленных показателей>*/
    }
}

kpiGroups.list()
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод возвращает список групп показателей аккаунта.
При ошибке возвращает код и описание ошибки
Параметры запроса:
Пример запроса kpiGroups.list
{ 
    "id":"1251506945251332",
    "method":"kpiGroups.list",
    "params":{},     
   "jsonrpc":"2.0"
}
Пример ответа kpiGroups.list
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "data": [
            {
                "id": "87",
                "name": "название группы показателей",
                "role": "0",     /*Системный идентификатор роли*/
                "order": "1",    /*<порядок сортировки группы показателя>*/
                "status": "1"    /*<статус группы показателя(0 выключен)>*/
            }
        ]
    }
}

kpiGroups.add( name [, order, role ])
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод позволяет создать группу для показателей. Выбор показателя и группы строго по внутренним идентификаторам:
  • Метод kpi.addToGroups - добавляет показатель в группу показателей
  • Метод KPIList - возвращает список идентификаторов и настроек показателей
  • Метод kpiGroups.list - возвращает список идентификаторов и настроек групп показателей
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
namestringНазвание группы показателей
orderint(3)Порядок сортировки группы показателя (чем меньше - тем первее)
rolestringСистемный идентификатор роли (если 0, то все). Список ролей описан в параметрах метода account.create
Пример запроса kpiGroups.add
{
  "id": "8361549266426897",
  "method": "kpiGroups.add",
  "params": {
    "name": "Категорийные показатели",
    "order": "3",
    "role": "PartnerCategoryManagerRole"
  },
  "jsonrpc": "2.0"
}
Пример ответа kpiGroups.add
{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "data": {
            "id": null,
            "name": "Категорийные показатели",
            "role": "PartnerCategoryManagerRole",
            "order": "3",
            "status": 1
        }
    }
}

kpi.addToGroups(id, groups)
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод позволяет добавить показатель в существующие группы показателей. Выбор показателя и группы строго по внутренним идентификаторам:
  • Метод KPIList - возвращает список идентификаторов и настроек показателей
  • Метод kpiGroups.list - возвращает список идентификаторов и настроек групп показателей
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
idbigintИдентификатор показателя
groupsbigintМассив идентификаторов групп
Пример запроса kpi.addToGroups
{
  "id": "8361549266426897",
  "method": "kpi.addToGroups",
  "params": {
    "id": 1437627895975748400,
    "groups": [87, 88]
  },
  "jsonrpc": "2.0"
}
Пример ответа kpi.addToGroups
{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "kpi_id": "1437627895975748474",
        "groups": [87,88]
    }
}

kpi.removeFromGroups(id, groups)
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод позволяет удалить принадлежность показателей из существующих групп показателей. Выбор показателя и группы строго по внутренним идентификаторам:
  • Метод KPIList - возвращает список идентификаторов и настроек показателей
  • Метод kpiGroups.list - возвращает список идентификаторов и настроек групп показателей
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
idbigintИдентификатор показателя
groupsbigintМассив идентификаторов групп
Пример запроса kpi.removeFromGroups
{
	"id":"8361549266426897",
	"method":"kpi.removeFromGroups",
	"params":{
		"id":1437627895975748474,
        "groups":[87]
      
	},
	"jsonrpc":"2.0"
}
Пример ответа kpi.removeFromGroups
{
    "jsonrpc": "2.0",
    "id": "8361549266426897",
    "result": {
        "kpi_id": "1437627895975748474",
        "groups": [87]
    }
}

Управление планами
storePlanSet(store_ext_id, metric, plan, year [, month, day] );
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод устанавливает/удаляет плановые значения торговой точки на нужный период. После установки всех плановых значений, необходимо вызвать метод storePlanPublish для публикации плана и актуализации их значений.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
store_ext_idstring(40)Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
metricstring(40)Мнемоника, либо прямой идентификатор правила:
- income: Выручка
- average: Средний чек
- count: Кол-во продаж
- category: Выручка по СТМ
- complexity: Комлексность чека по кол-ву товаров
- p/<идентификатор показателя> - прямой идентификатор показателя в системе HEADO
planDECIMAL(13,4)Если >=0, то установка планового значения = plan
Если <0, то удаление
yearintГод
month (необязательный)intМесяц, если не указан или =-1, то выставляется план на год
day (необязательный)intДень, если не указан или =-1, то выставляется план на месяц, иначе - на день
Пример запроса storePlanSet
{
  "jsonrpc": "2.0",
  "id": "5239",
  "method": "storePlanSet",
  "params": {
    "store_ext_id": "26",
    "metric": "income",
    "plan": "10955.6",
    "year": "2021",
    "month": "6",
    "day": "8"
  }
}
Параметры ответа
{
    "jsonrpc": "2.0",
    "id": "5239",
    "result": {
        "addressId": "18209",   //ИД торговой точки в HEADO
        "metric": "p/1437627895975747735",  //Идентификатор показателя
        "plan": "10955.6",   //Установленный план
        "year": "2021",   //Год
        "month": "6",     //Месяц
        "day": "8"        //День
    }
}

storePlanPublish(store_ext_id, auto);
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод публикует планы для актуализаций значений, после их установки методом storePlanSet.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
store_ext_idstring(40)Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр
autoboolean - true - Использовать сервисную аналитику распределения по периодам.
- false - Не использовать аналитику (равномерное распределение по нижним периодам)
Параметры ответа
result: { "addressId" : ИД торговой точки, "auto": Автоматическое распределение}

Отчёты по торговой точке
reports(id, filter, range );
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод возвращает значения показателей по торговой точке за указанный период.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
idstring(20)'salesplans' - Получение отчёта о планах Торговой точки
filterobject{ "storeId": /* Уникальный «Внешний идентификатор торговой точки» из торговой системы предприятия, состоящий из латинских букв или цифр */ }
rangeobject{ "from": "Y-m-d" /*Дата от*/, "to": "Y-m-d" /* Дата до */ }
Пример запроса reports
{
  "id": "1251506945251332",
  "method": "reports",
  "params": {
    "id": "salesplans",
    "filter": {
      "storeId": 100
    },
    "range": {
      "from": "2017-09-01",
      "to": "2017-10-31"
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа reports
{
"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( items )
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Метод загружает штатное расписания сотрудников.
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
itemsArray 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
{
  "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
{
  "jsonrpc": "2.0",
  "id": "1251506945251332",
  "result": {
    "count": 1
  }
}

account.create ( login [, data ] )
account.update( login [, data ] )
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Данные методы создают и обновляют аккаунт пользователя в системе для доступа в ЛК HEADO
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
loginstring(200)Email
dataobject { // Все поля опциональны (но как минимум одно должно быть указано)
-- name: (string(200)),
-- phone: (string(15)),
-- email: (string(200)),
-- 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к символов для сквозного хранения слабоупорядоченных структур.
])}
Пример запроса account.create ( login [, data ] )
{
  "id": "1251506945251332",
  "method": "account.create",
  "params": {
    "login": "test@heado.ru",
    "data": {
      "name": "Иванов",
      "phone": "8977777777",
      "email": "test@heado.ru",
      "status": "1",
      "password": "12345678",
      "manager_login": null,
      "role": "PartnerTopManagerRole",
      "meta": {
        "key1": "value1",
        "key2": "value2"
      }
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа account.create ( login [, data ] )
{
  "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 (filter)
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Данный метод возвращает список аккаунтов пользователей в системе HEADO с возможностью их фильтрации по ролям:
  • 'PartnerTopManagerRole', - Топ-менеджер
  • 'PartnerDivisionManagerRole', - Дивизиональный директор
  • 'PartnerHeadRole', - Региональный директор
  • 'PartnerZoneManagerRole', - Зональный директор
  • 'PartnerLogisticsRole', - Логист
  • 'PartnerManagerRole', - Директор магазина
  • 'PartnerSellerRole', - Продавец
  • 'PartnerAuxiliaryRole', - Вспомогательная роль
  • 'PartnerMonitorRole', - Оператор контроля
  • 'PartnerPayerRole' - Плательщик
  • 'PartnerCategoryManagerRole' - Категорийный менеджер
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
filterobject Все поля опциональны (но как минимум одно должно быть указано)
-- role: имя роли
-- network_ext_id: Внешний идентификатор Сети
-- limit: установленный лимит
--- offset: смещение выводимых записей
--- count: количество выводимых записей (по умолчанию 100)
Пример запроса account.list (filter)
{
  "id": "1951565327032225",
  "method": "account.list",
  "params": {
    "filter": {
      "role": "PartnerManagerRole",
      "network_ext_id": "",
      "limit": {
        "offset": 0,
        "count": 100
      }
    }
  },
  "jsonrpc": "2.0"
}
Пример ответа account.list (filter)
{
    "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"
        }
      ]
            }
        ],
        "full_count": "1",       // Кол-во найденных аккаунтов
        "limit": {
            "offset": 0,     
            "count": 100  
        }
    }
}

account.assignZones(login, zones)
account.removeZones(login, zones)
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Данные методы назначают и удаляют зоны видимости аккаунта пользователя к торговым точкам в системе HEADO
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
loginstring(200)Email
zonesobject [{
-- 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)
{
  "id": "1251506945251332",
  "method": "account.assignZones",
  "params": {
    "login": "test@heado.ru",
    "zones": [
      {
        "type": "account",
        "id": "",
        "ext_id": ""
      }
    ]
  },
  "jsonrpc": "2.0"
}
{
  "id": "1251506945251332",
  "method": "account.assignZones",
  "params": {
    "login": "test@heado.ru",
    "zones": [
      {
        "type": "tag",
        "id": "01",
        "ext_id": ""
      }
    ]
  },
  "jsonrpc": "2.0"
}
{
  "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)
{
    "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(login, expiry)
POST Web-адрес запроса:
https://api.heado.ru/management/<Auth_Key>
https://gamma.heado.ru/management/<Auth_Key> (для ключей домена gamma)

Данный метод позволяет выслать почтовые приглашения на активацию аккаунта пользователей в системе HEADO. Список аккаунтов можно получить, через метод account.list
При ошибке возвращает код и описание ошибки
Параметры запроса:
NAMETYPEDESCRIPTION
loginstring(200)Email - логин
dataunsigned intДобавленное время экспирации приглашения в секундах (не больше 30 дней)
Пример запроса account.sendInvite(login, expiry)
{
  "id": "1251506945251332",
  "method": "account.sendInvite",
  "params": {
    "login": "test@heado.ru",
    "expiry": "86400"
  },
  "jsonrpc": "2.0"
}
Пример ответа account.sendInvite(login, expiry)
{
    "jsonrpc": "2.0",
    "id": "1251506945251332",
    "result": {
        "data": {
            "uid": "1644405670108438016",
            "status": "ok"
        }
    }
}

Made on
Tilda