API управления группами

URL

https://api.onstor.ru/common/company/1.0/

Поддерживаются GET и POST. Структурированные данные отправляйте в raw JSON с Content-Type: application/json.

Аутентификация

Каждый запрос должен содержать действительный токен компании в строке запроса или JSON-теле. Токен определяет компанию и доступные языки.

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

Структура ответа

{
  "auth": {
    "status": "OK",
    "company": {
      "id": 228,
      "lang": "[...]",
      "country": {"currency_code": "USD"}
    },
    "languages": [
      {"code": "EN", "name": "English"},
      {"code": "ES", "name": "Español"}
    ]
  },
  "payload": {
    "status": "OK",
    "error": "",
    "data": []
  },
  "time": {"execution": 12.34}
}

• auth.status — результат аутентификации.
• auth.company — данные авторизованной компании.
• auth.languages — настроенные языки компании.
• payload.status — результат операции: OK или ERROR.
• payload.error — сообщение об ошибке операции.
• payload.data — объект группы или массив групп в зависимости от метода.
• time.execution — время выполнения на сервере в миллисекундах.

Методы записи также возвращают payload.request_id. Списки содержат payload.total и следующее смещение payload.offset; на последней странице оно равно false.

Справочник полей

Поле	Тип	Запись	Описание
group_id	integer	Нет	Внутренний идентификатор группы.
external_group_id	string / null	Да	Внешний идентификатор группы, уникальный в пределах компании. Значения длиннее 50 символов обрезаются.
company	integer	Нет	Идентификатор компании.
title	object	Да	Название группы с ключами-кодами языков, например {"EN":"Lunch","ES":"Almuerzo"}.
description	object	Да	Описание группы с ключами-кодами языков.
product	array	Да	Товары группы. См. «Ссылки на товары».
status	integer	Да	Статус группы. При создании по умолчанию: 1.
date_create	datetime	Нет	Дата и время создания.
date_update	datetime	Нет	Дата и время последнего обновления.
creator	integer	Нет	Идентификатор создателя.
img	string / object / null	Да	В ответе — ссылка на сохранённое изображение; в запросе записи — URL или параметры обработки. Размер результата: 100×100 пикселей.
size	integer	Да	Настройка размера отображения.
scroll	integer	Да	Настройка прокрутки и отображения.
color	object / array / null	Да	Цвета группы, сохранённые в JSON.
btn_color	object / array / null	Да	Цвета кнопки, сохранённые в JSON.
multibuy	boolean	Да	Включает цены multibuy.
multibuy_quantity	decimal	Да	Количество товаров для предложения multibuy.
multibuy_price	decimal	Да	Цена multibuy.
multibuy_date_start	datetime / null	Да	Начало предложения в формате YYYY-MM-DD HH:MM:SS.
multibuy_date_finish	datetime / null	Да	Окончание предложения в формате YYYY-MM-DD HH:MM:SS.

Также допустимы форматы YYYY-MM-DDTHH:MM и YYYY-MM-DD HH:MM; секунды добавляются автоматически.

Выбор возвращаемых полей

По умолчанию методы чтения и записи возвращают все поля. Передайте fields — массив публичных имён полей, чтобы ограничить каждый возвращаемый объект.

{
  "api": "group",
  "method": "get-all",
  "token": "...",
  "fields": ["group_id", "external_group_id", "title", "status"]
}

• Неизвестные имена полей игнорируются.
• Без fields возвращаются все поля.
• Если ни одно запрошенное поле не допустимо, для каждого элемента списка возвращается пустой объект. Метаданные пагинации сохраняются.

1. Получить все группы

Возвращает постраничный список групп авторизованной компании, упорядоченный по group_id.

Запрос

Методы: GET / POST
URL: https://api.onstor.ru/common/company/1.0/?api=group&method=get-all&token={token}&limit={limit}&offset={offset}

Параметры

Название	Тип	Описание	Обязательное
api	string	group	Да
method	string	get-all	Да
token	string	Токен аутентификации компании.	Да
limit	integer	Размер страницы: по умолчанию 500, минимум 1, максимум 1000.	Нет
offset	integer	Начальное смещение. По умолчанию: 0.	Нет
fields	array	Возвращаемые поля.	Нет
filter	object	Условие фильтрации. См. «Фильтрация результатов».	Нет

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

{
  "status": "OK",
  "error": "",
  "data": [
    {
      "group_id": 42,
      "external_group_id": "lunch-specials",
      "title": {"EN": "Lunch specials", "ES": "Especiales de almuerzo"},
      "status": 1
    }
  ],
  "total": 1,
  "offset": false
}

2. Получить сведения о группе

Возвращает одну группу по group_id (также принимается id) или external_group_id.

Запрос по внутреннему идентификатору

https://api.onstor.ru/common/company/1.0/?api=group&method=get-group&token={token}&group_id=42

Запрос по внешнему идентификатору

https://api.onstor.ru/common/company/1.0/?api=group&method=get-group&token={token}&external_group_id=lunch-specials

Параметры

Название	Тип	Описание	Обязательное
api	string	group	Да
method	string	get-group	Да
token	string	Токен аутентификации компании.	Да
group_id	integer	Внутренний идентификатор группы.	Требуется один идентификатор
id	integer	Альтернативное имя group_id.	Требуется один идентификатор
external_group_id	string	Внешний идентификатор группы.	Требуется один идентификатор
fields	array	Возвращаемые поля.	Нет

3. Фильтрация результатов

Метод get-all поддерживает объект filter. Ключи фильтра должны быть публичными именами из справочника полей.

Поддерживаемые операторы

Оператор	Описание	Пример
eq	Равно	"status":{"eq":1}
ne	Не равно	"status":{"ne":0}
gt	Больше	"size":{"gt":1}
gte	Больше или равно	"group_id":{"gte":100}
lt	Меньше	"group_id":{"lt":500}
lte	Меньше или равно	"size":{"lte":3}
like	Поиск по шаблону; указывайте символы % явно	"external_group_id":{"like":"lunch%"}
in	Значение входит в список	"group_id":{"in":[1,2,3]}
nin	Значение не входит в список	"status":{"nin":[0,2]}
between	Диапазон с включёнными границами	"group_id":{"between":[100,200]}
is_null	Проверка NULL	"external_group_id":{"is_null":false}

Простой фильтр AND

{
  "api": "group",
  "method": "get-all",
  "token": "...",
  "filter": {
    "status": {"eq": 1},
    "group_id": {"gte": 100}
  }
}

Группы AND / OR

{
  "filter": {
    "and": [
      {"status": {"eq": 1}},
      {"group_id": {"between": [100, 200]}}
    ],
    "or": [
      {"external_group_id": {"like": "lunch%"}},
      {"external_group_id": {"like": "dinner%"}}
    ]
  }
}

• in: [] не соответствует ни одной записи.
• nin: [] соответствует любой записи.
• Логические значения преобразуются в 0 или 1.
• Неизвестные поля и неподдерживаемые операторы игнорируются.

4. Создать / обновить группы

Метод: POST
URL: https://api.onstor.ru/common/company/1.0/

Отправляйте raw JSON. payload может содержать один объект группы или массив объектов.

Параметры

Название	Тип	Описание	Обязательное
api	string	group	Да
method	string	put-group or put-groups	Да
token	string	Токен аутентификации компании.	Да
payload	object / array	Данные группы.	Да
language	string	Код языка, если title или description передан строкой.	Нет
fields	array	Возвращаемые поля каждой сохранённой группы.	Нет
webhook	string	URL обратного вызова для асинхронной обработки изображений.	Нет

Пример создания

{
  "api": "group",
  "method": "put-group",
  "token": "...",
  "language": "EN",
  "payload": {
    "external_group_id": "lunch-specials",
    "title": {
      "EN": "Lunch specials",
      "ES": "Especiales de almuerzo"
    },
    "description": "Available on weekdays",
    "product": [101, {"external_id": "combo-2"}],
    "status": 1,
    "size": 2,
    "scroll": 1,
    "color": {"background": "#ffffff", "text": "#222222"},
    "btn_color": {"background": "#ff887a", "text": "#ffffff"},
    "multibuy": true,
    "multibuy_quantity": 2,
    "multibuy_price": 19.90,
    "multibuy_date_start": "2026-09-15 09:00:00",
    "multibuy_date_finish": "2026-09-30 23:59:59"
  }
}

Пример обновления

{
  "api": "group",
  "method": "put-groups",
  "token": "...",
  "fields": ["group_id", "external_group_id", "title", "status"],
  "payload": [
    {
      "group_id": 42,
      "title": {"EN": "Updated lunch specials"},
      "status": 1
    },
    {
      "external_group_id": "dinner-specials",
      "title": {"EN": "Dinner specials"}
    }
  ]
}

Создание или обновление (upsert)

• put-group и put-groups обновляют группу с совпадающим group_id или external_group_id; если совпадений нет, создают новую.
• create всегда создаёт новую группу и игнорирует переданный group_id.
• edit требует идентификатор и возвращает ошибку, если группа не существует.
• Изменяются только переданные поля. Поля только для чтения игнорируются.
• external_group_id должен быть уникальным в пределах компании.

Многоязычные поля

title и description принимают языковой объект или строку. Для строки язык задаёт language; иначе используется первый язык компании, а при его отсутствии — EN.

{
  "language": "EN",
  "payload": {
    "title": "Lunch specials",
    "description": {
      "EN": "Available on weekdays",
      "ES": "Disponible entre semana"
    }
  }
}

Сохранённый объект содержит все языки компании. Отсутствующие переводы сохраняются пустыми строками.

Ссылки на товары

product должен быть массивом. Каждый товар определяется внутренним menu_id или внешним external_id.

{
  "product": [
    101,
    "external-product-id",
    {"menu_id": 102},
    {"external_id": "another-external-id"}
  ]
}

Все товары должны принадлежать продавцам авторизованной компании. external_id должен однозначно определять товар; при неоднозначности используйте menu_id.

Формат ответа

{
  "product": [
    {"menu_id": 101, "external_id": "external-product-id"},
    {"menu_id": 102, "external_id": null}
  ]
}

Повторные ссылки на товары удаляются. Ссылки на недоступные компании товары не включаются в ответы.

Обработка изображений

img принимает общедоступный URL изображения в виде строки:

{"img": "https://example.com/group.png"}

Также принимается объект с параметрами обработки:

{
  "img": {
    "url": "https://example.com/group.png",
    "resize": true,
    "bgcolor": "#ffffff",
    "transparent": false,
    "scale": 0.8,
    "remove_background": false,
    "auth": {
      "type": "Bearer",
      "token": "source-image-access-token"
    }
  }
}

• Итоговое изображение группы имеет размер 100×100 пикселей.
• scale должен быть больше 0 и не больше 1. Недопустимые значения заменяются на 0.8.
• Для удаления изображения передайте img = null или пустую строку.
• Обработка изображений асинхронна. Ответ записи содержит request_id; переданный webhook связывается с этим запросом.

5. Удалить группы

Метод: POST
URL: https://api.onstor.ru/common/company/1.0/

Удаляет группы по внутренним или внешним идентификаторам. payload может содержать числа, числовые строки, внешние ID или объекты с group_id, id, external_group_id.

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

{
  "api": "group",
  "method": "delete-groups",
  "token": "...",
  "payload": [42, 43]
}

Удаление по смешанным идентификаторам

{
  "api": "group",
  "method": "delete-groups",
  "token": "...",
  "payload": [
    {"group_id": 42},
    {"external_group_id": "dinner-specials"},
    "lunch-specials"
  ]
}

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

{
  "status": "OK",
  "error": "",
  "request_id": 317,
  "deleted": [42, 43]
}

Удаляются только группы авторизованной компании; они включаются в deleted. Повторные идентификаторы исключаются.

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

Ошибки и альтернативные имена методов

Основной метод	Допустимые альтернативные имена
put-group / put-groups	create, edit
delete-group / delete-groups	delete

Распространённые ошибки

Ошибка	Причина
Unknown group method	method не передан или не поддерживается.
Group ID not specified	Для метода, требующего идентификатор, не передан ни group_id, ни external_group_id.
Group not found	Указанная группа не найдена в авторизованной компании.
Incorrect payload	payload отсутствует или не является объектом / массивом.
Payload is empty	В метод записи передан пустой массив.
Group payload item must be an object	Элемент payload не является JSON-объектом.