API для ботов и программ — как получить доступ на чтение
Если ваша программа должна сама забирать данные DelRes — например, бот загружает чеки для бухгалтерии или скрипт раз в день сверяет склад, — ей нужен программный доступ. Он выдаётся отдельной учётной записью «Выгрузка по API», и только на чтение: ничего изменить, создать или удалить через неё нельзя.
Это не «ключ сайта»: ключ сайта общий с приложением и витриной и создаёт заказы, поэтому для ботов не используется.
Шаг 1. Заведите учётную запись
Заголовок раздела «Шаг 1. Заведите учётную запись»-
Откройте Настройки → Пользователи и права → Пользователи (Пользователи системы) и нажмите «Добавить».
-
В «Типе учётной записи» выберите «Выгрузка по API». Сотрудник не нужен — это программа, а не человек.
-
Задайте логин, пароль (не короче 8 символов) и повторите его в поле «Повтор пароля». Если программе нужна одна точка, выберите торговую точку. Если организаций несколько, учётка заводится в той, что выбрана в меню слева.
-
Оставьте включённой «Активность» и нажмите «Создать».
Учётка привязана к организации и видит только её данные.
Шаг 2. Получите токен
Заголовок раздела «Шаг 2. Получите токен»Программа входит так же, как человек, но запросом к API вашего рабочего пространства. Адрес API сообщит поддержка (меню аккаунта → «Поддержка»).
POST /api/v2/auth/loginс полямиloginиpassword. В ответе, в блокеdata, придётtoken. Токен действует 30 суток с момента входа: программе не нужно входить заново перед каждым запросом, достаточно сохранить его и получить новый, когда срок выйдет. В полеexpires_atответа указано, когда токен перестанет приниматься.- Во всех остальных запросах передавайте заголовок
Authorization: Bearer <токен>. - Чтобы проверить, что доступ настроен верно, запросите
GET /api/v2/auth/me: он вернёт учётку, роль и список прав. - Когда срок токена вышел, запрос вернёт ошибку авторизации (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) входит заново и сохраняет новый токен.
Бот видит не все данные. Учётка привязана к организации; данные других организаций и клиентская база ей недоступны. Если нужна другая организация или точка, заведите для неё отдельную учётку.