API-токен — секретный ключ, по которому связка Альбато получает доступ к API магазина — программному интерфейсу для чтения и изменения заказов, клиентов, цен и остатков. Токены выпускают в разделе «Подключения» → вкладка «Альбато» → вкладка «API-токены». Ниже — как выпустить токен с нужными правами, скопировать его, следить за использованием и отозвать.
Создание токена
Нажмите «Создать токен» над списком «Выданные токены» — откроется форма «Создание API-токена». Заполните её и нажмите «Создать токен» внизу формы; кнопка «Отмена» закрывает форму без создания. Форму видят только сотрудники с правом «Изменение настроек».
- В поле «Название токена» напишите, для какой связки он нужен, например «Альбато — заказы в таблицу». По умолчанию там стоит «Albato», длина — до 200 символов.
- В поле «Действует до» укажите дату и время окончания по местному времени. Если оставить поле пустым, токен будет бессрочным. Дату в прошлом форма не примет.
- Отметьте права. В каждой группе сначала включите «Чтение»: остальные флажки группы до этого неактивны.
- Нажмите «Создать токен».
Если флажок серый и подписан «Нет прав для выдачи», у вас самих нет этих прав. Токен не может получить больше, чем есть у сотрудника, который его выпускает.
Права токена
Отмечайте только права, которые нужны связке: токену, который выгружает заказы в таблицу, достаточно чтения заказов. Права сгруппированы по данным магазина. Через API доступны в том числе данные покупателей, поэтому лишние права — лишний доступ к персональным данным (подробнее — в статье «Персональные данные»). Какой флажок нужен каждому методу, указано в статьях «Методы API»: «заказы и клиенты», «товары и остатки», «исполнители и записи».
| Флажок | Что разрешает через API |
|---|---|
| «Заказы и записи на услуги» | |
| «Чтение» | Получать заказ по номеру и список заказов, фильтры списка, записи на услуги |
| «Создание заказов, отправка клиенту и действия с записями» | Создавать заказы и добавлять в них позиции; подтверждать, завершать и отменять записи, отмечать неявку |
| «Редактирование, статусы, оплата и доставка» | Менять заказ и его позиции, подтверждать, завершать и отменять заказ, отклонять запрос на отмену, менять статус и отметку об оплате; менять запись на услугу и ссылку на онлайн-встречу |
| «Удаление» | Удалять позиции из заказа |
| «Клиенты и сообщения» | |
| «Чтение» | Получать список клиентов и карточку клиента |
| «Создание и изменение клиентов, бонусы и сообщения» | Создавать и изменять клиентов |
| «Удаление» | Методов удаления клиентов в API нет, отмечать не нужно |
| «Товары и остатки» | |
| «Чтение» | Получать товары и историю движений остатка |
| «Создание товаров и корректировка остатков» | Создавать товары, оформлять приход и списание остатка |
| «Редактирование» | Изменять товары, в том числе цену |
| «Удаление» | Удалять товары |
| «Точки и исполнители» | |
| «Чтение» | Получать исполнителей, их график и отсутствия |
| «Создание» | Добавлять исполнителей и их отсутствия |
| «Редактирование» | Изменять данные исполнителей и их график |
| «Удаление» | Удалять исполнителей и отсутствия |
Права выбираются один раз, при создании. Чтобы расширить или сузить их, выпустите новый токен, замените его в связке и отзовите старый.
Копирование токена
Нажмите «Скопировать токен» в блоке «Токен создан — скопируйте его сейчас» и сразу вставьте значение в связку Альбато или в менеджер паролей. Блок появляется сразу после создания токена. Связка передаёт токен в заголовке X-Service-Token. Кнопка «Закрыть токен» убирает блок.
⚠️ Важно: токен показывается один раз. Магазин хранит не сам токен, а его отпечаток, поэтому посмотреть значение повторно нельзя ни в панели, ни через поддержку. Если токен потерян, выпустите новый и отзовите старый.
Выданные токены
Блок «Выданные токены» показывает все токены магазина, кроме отозванных. У каждого токена указаны:
- название и дата создания;
- состояние — «Активен» или «Срок истёк»;
- «Действует до» — дата окончания или «без срока»;
- «Последнее использование» — время последнего запроса или «ещё не использовался»;
- «Права токена» — раскрывающийся список выданных прав.
Список не обновляется сам. Чтобы увидеть свежее время использования, нажмите «Обновить список».
💡 «Последнее использование» помогает найти забытые токены: если токен не использовался несколько месяцев, скорее всего, связка удалена и токен можно отозвать.
Отзыв токена
- В строке токена нажмите «Отозвать».
- В окне «Отозвать токен?» прочитайте предупреждение: связки с этим токеном потеряют доступ к API магазина.
- Нажмите «Отозвать».
Отзыв действует со следующего запроса: API ответит кодом 401. Вернуть отозванный токен нельзя, для восстановления связки понадобится новый. Отозванный токен исчезает из списка.
Токен с истёкшим сроком тоже получает ошибку 401, но остаётся в списке с пометкой «Срок истёк», пока его не отзовут.
Ограничения токена
- Токен работает только со своим магазином. Запрос к заказу, товару или клиенту другого магазина получит ошибку 403.
- Через токен нельзя открыть настройки интеграции, выпустить или отозвать токен и вызвать методы, которых нет в справочнике API. Что ещё недоступно по токену, перечислено в конце каждой статьи «Методы API».
- Пока услуга Альбато отключена, все запросы с токенами получают ошибку 403.
- Токен не привязан к сотруднику. Если удалить учётную запись того, кто его выпустил, токен продолжит работать — отзывайте его отдельно.
Короткие ответы
Где посмотреть значение уже выданного токена?
Нигде: значение токена показывается только в момент создания, а магазин хранит лишь его отпечаток. Выпустите новый токен с теми же правами, замените значение в связке Альбато и отзовите старый.
Можно ли добавить права существующему токену?
Нет, права задаются при создании и дальше не меняются. Выпустите новый токен с нужным набором прав, подставьте его в заголовок X-Service-Token в связке и отзовите прежний, чтобы не оставлять лишний доступ.
Почему API отвечает 403, хотя токен скопирован верно?
Код 403 означает, что токен распознан, но действие запрещено. Чаще всего у токена нет нужного флажка — в ответе будет поле requiredCapability с кодом недостающего права. Ещё две причины: объект принадлежит другому магазину или услуга Альбато отключена. Неверный, отозванный или истёкший токен даёт другой код — 401.
Сколько действует API-токен?
Бессрочно, если при создании не заполнить поле «Действует до». После указанной даты токен получает ошибку 401 и остаётся в списке с пометкой «Срок истёк», пока его не отзовут.