Перейти к содержимому

API для ботов и программ — как получить доступ на чтение

Если ваша программа должна сама забирать данные DelRes — например, бот загружает чеки для бухгалтерии или скрипт раз в день сверяет склад, — ей нужен программный доступ. Он выдаётся отдельной учётной записью «Выгрузка по API», и только на чтение: ничего изменить, создать или удалить через неё нельзя.

Это не «ключ сайта»: ключ сайта общий с приложением и витриной и создаёт заказы, поэтому для ботов не используется.

  1. Откройте Настройки → Пользователи и права → Пользователи (Пользователи системы) и нажмите «Добавить».

  2. В «Типе учётной записи» выберите «Выгрузка по API». Сотрудник не нужен — это программа, а не человек.

  3. Задайте логин, пароль (не короче 8 символов) и повторите его в поле «Повтор пароля». Если программе нужна одна точка, выберите торговую точку. Если организаций несколько, учётка заводится в той, что выбрана в меню слева.

  4. Оставьте включённой «Активность» и нажмите «Создать».

Учётка привязана к организации и видит только её данные.

Программа входит так же, как человек, но запросом к API вашего рабочего пространства. Адрес API сообщит поддержка (меню аккаунта → «Поддержка»).

  1. POST /api/v2/auth/login с полями login и password. В ответе, в блоке data, придёт token. Токен действует 30 суток с момента входа: программе не нужно входить заново перед каждым запросом, достаточно сохранить его и получить новый, когда срок выйдет. В поле expires_at ответа указано, когда токен перестанет приниматься.
  2. Во всех остальных запросах передавайте заголовок Authorization: Bearer <токен>.
  3. Чтобы проверить, что доступ настроен верно, запросите GET /api/v2/auth/me: он вернёт учётку, роль и список прав.
  4. Когда срок токена вышел, запрос вернёт ошибку авторизации (401): войдите заново тем же логином и паролем и сохраните новый токен. Каждый вход создаёт новый токен, а прежние работают до конца своего срока, поэтому входите по необходимости, а не перед каждым запросом. Отозвать токен, которым сделан запрос, можно через POST /api/v2/auth/logout.

Ответы API завёрнуты в { "success": true, "data": … }, ошибки — { "success": false, "error": { "code": …, "message": … } }. На вход действует ограничение — не больше 60 попыток в минуту с одного адреса и логина. Если учётка выключена или организация заблокирована, вход ответит «Учётная запись заблокирована» или «Организация заблокирована».

Учётка «Выгрузка по API» читает:

  • заказы и фискальные чеки, закрытия дня, отчёт по продажам (orders, fiscal-receipts, day-closings);
  • складские документы — приходы, возвраты, инвентаризации, перемещения, списания, акты выпуска (stock-documents) — и складские отчёты: остатки, движение, закупки;
  • кассовые документы — приходы, расходы, переводы между кассами, акты услуг (cash-documents) — и кассовую книгу;
  • справочники, без которых в выгрузке остались бы одни номера: организации, точки, склады, кассы, способы оплаты, контрагенты, ингредиенты и блюда с их категориями.

Клиентской базы, зарплат и настроек у неё нет. Но в самих заказах указаны имя и телефон гостя — поэтому токен надо беречь. Создавать и менять что-либо учётка не может.

Параметры запросов, фильтры и примеры ответов — в клиентской документации API. Её и помощь с подключением даёт поддержка: напишите нам (меню аккаунта → «Поддержка»), укажите, какие данные нужны программе и в какой организации.

Можно ли создавать заказы или менять цены через API? Через учётку «Выгрузка по API» — нет, она только читает. Если программе нужно записывать данные, напишите нам, что именно она должна делать.

Как отозвать доступ программы? Выключите «Активность» у её учётки: токены перестанут работать.

Бот перестал получать данные через месяц после запуска. Токен действует 30 суток. Пусть программа при ошибке авторизации (401) входит заново и сохраняет новый токен.

Бот видит не все данные. Учётка привязана к организации; данные других организаций и клиентская база ей недоступны. Если нужна другая организация или точка, заведите для неё отдельную учётку.