Интеграция с Альбато

Настройке интеграции и данным, которые она передаёт, посвящены отдельные статьи:

• Настройка вебхуков. Вебхук — запрос, который магазин сам отправляет на адрес Альбато, когда в магазине что-то происходит. В статье: адрес, секрет подписи, выбор событий, проверка подключения и журнал доставок.
• События вебхуков — какие события отправляет магазин и какие поля в них приходят.
• API-токены. API — программный интерфейс, через который связки Альбато читают и меняют данные магазина, API-токен — ключ доступа к нему. В статье: выпуск токена, права, отзыв.
• Методы API. Заказы и клиенты — общие правила запросов и коды ответов, методы для заказов, оплаты и клиентов.
• Методы API. Товары и остатки — поиск и изменение товаров, корректировка остатков и история движений.
• Методы API. Исполнители и записи — исполнители, их график и отсутствия, действия с записями на услуги.
• Справочник API — полная техническая документация: все запросы к API магазина с примерами, на русском и английском.
• Персональные данные — какие данные покупателей уходят в Альбато и что проверить владельцу магазина до включения интеграции.

Данные передаются в две стороны, и каждое направление настраивается отдельно:

• Из магазина в Альбато — вебхуки. Когда в магазине оформляют заказ или меняется остаток, магазин отправляет запрос с данными на адрес, который выдал Альбато. Связка в Альбато получает данные и запускает следующие шаги: создаёт сделку в системе учёта клиентов (CRM), добавляет строку в таблицу, пишет сообщение в рабочий чат.
• Из Альбато в магазин — API. Шаг связки отправляет запрос к API магазина и передаёт в заголовке API-токен. Так связка получает заказ целиком, меняет его статус, обновляет цену товара или отмечает запись на услугу завершённой.

Связке часто хватает одного направления: выгрузке заказов в Google Таблицы нужны только вебхуки, синхронизации цен из учётной системы — только API. Если связка передаёт данные покупателей в сторонние сервисы, прочитайте статью «Персональные данные».

Интеграция с Альбато — платная функция магазина, её статус показан вверху вкладки «Альбато». Пока услуга не подключена, на вкладке видна пометка «Платная функция»; чтобы подключить её, обратитесь в поддержку BOTFARM.

Учётная запись и тариф в самом Альбато оформляются отдельно, на сайте сервиса. Связки тоже создаются в Альбато: панель магазина отвечает только за свою сторону подключения.

⚠️ Важно: если услугу отключить, выданные токены перестанут работать, и API будет отвечать на их запросы кодом 403. Новые события в очередь не попадут.

Под статусом услуги на вкладке «Альбато» расположены четыре вкладки:

• «Обзор» — карточки «Отправка событий» (включена ли отправка, адрес и выбранные события, кнопка тестового события) и «Доступ к данным» (число действующих токенов), а также последние доставки;
• «Вебхуки» — включение и пауза отправки, адрес для событий, секрет подписи, выбор событий и блок «Проверка доставки»;
• «API-токены» — выпуск токенов, список выданных и отзыв;
• «Журнал доставок» — последние 20 событий магазина со статусом отправки и текстом ошибки.

1. Проверьте, что вверху вкладки «Альбато» стоит статус «Услуга подключена».
2. Прочитайте статью «Персональные данные» и решите, какие события и права нужны связке: данные покупателей начнут уходить в Альбато сразу после включения отправки.
3. В Альбато создайте подключение «Вебхук» и скопируйте адрес, который он выдаст.
4. На вкладке «Вебхуки» вставьте адрес в поле «URL вебхука», нажмите «Создать секрет», отметьте нужные события и включите переключатель «Отправлять события в Albato» вверху блока «Отправка событий». Нажмите «Сохранить настройки».
5. В блоке «Проверка доставки» нажмите «Отправить тестовое событие». Если адрес верный, появится сообщение «Тестовое событие принято».
6. Если связке нужно обращаться к данным магазина, на вкладке «API-токены» выпустите токен с минимально нужными правами. Какие запросы может отправлять связка и какой флажок нужен каждому, описано в статьях «Методы API»: «заказы и клиенты», «товары и остатки», «исполнители и записи».

Магазин отправляет 23 вида событий. Они разбиты на те же группы, что и в форме настройки:

• заказы — новый заказ, смена статуса, оплата, отмена;
• клиенты и сообщения — новый клиент, изменение клиента, входящее сообщение в MAX;
• товары и остатки — создание, изменение и удаление товара, изменение остатка, малый остаток;
• исполнители — добавление, изменение и удаление исполнителя, его отсутствия;
• записи на услуги — новая запись, подтверждение, завершение, отмена, неявка, перенос.

Через API связка работает с заказами и их составом, клиентами (статья «Методы API. Заказы и клиенты»), товарами и остатками («Методы API. Товары и остатки»), исполнителями и записями на услуги («Методы API. Исполнители и записи»). Какие именно действия разрешены, определяют права токена.

• Адрес вебхука у магазина один. Все выбранные события приходят на него, а разные связки в Альбато отбирают свои события условием по полю event.
• События возникают при действиях в панели, на витрине, в ботах и через API. Импорт каталога из файла и прямые изменения в базе данных событий не создают.
• Событие — снимок данных на момент действия. Если заказ потом изменят, уже отправленное событие не обновится: актуальное состояние связка получает через API.
• Одно и то же событие иногда приходит дважды, например если Альбато принял запрос, но ответил ошибкой. Повторы отсеивают по полю deliveryId.
• В событии не указано, кто выполнил действие. Если связка меняет данные через API, магазин пришлёт об этом событие, и связка, которая реагирует на него тем же действием, зациклится.

Нужен ли программист, чтобы подключить Альбато?

Для типовых связок — нет. События принимает стандартный инструмент «Вебхук» в Альбато, поля выбираются из пришедшего примера. Для запросов к API понадобится шаг «HTTP Запрос»: адрес, заголовок с токеном и тело запроса заполняются по примерам из технической документации API.

Через сколько секунд после заказа запускается связка в Альбато?

Обычно через 10–15 секунд: очередь событий проверяется раз в 10 секунд. Если Альбато не ответил или вернул ошибку, магазин повторит отправку через 5, а затем через 30 секунд. После массовых изменений, например корректировки остатков сотен товаров, доставка может растянуться на несколько минут.

Что станет с настройками интеграции, если отключить услугу?

Настройки сохранятся: адрес, секрет, выбранные события и токены останутся на месте, неотправленные события будут ждать. Пока услуга выключена, токены получают ошибку 403, а новые события не создаются. После повторного подключения интеграция продолжит работать без перенастройки.

Можно ли принимать события магазина на свой сервер, а не в Альбато?

Да, вебхук отправляется на любой адрес из поля «URL вебхука». Чтобы сервер отличал запросы магазина от поддельных, проверяйте подпись в заголовке X-Webhook-Signature — порядок описан в статье «События вебхуков».