API и события

У API две стороны. Внутрь — вы кладёте в AISSE каталог: товары, услуги, технику. Наружу — AISSE присылает вам события: посетитель оставил заявку, ничего не нашёл, поставил оценку. Этого набора хватает, чтобы связать помощника с CRM, таблицей или учётной системой — своим кодом или связкой в Albato, ApiX-Drive и любом другом сервисе, который умеет вебхуки и HTTP-запросы.

Базовый адрес — https://aisse.ru/v1. Интерактивная схема всех методов: /docs.

1. Ключ

Все методы, кроме справочника событий, требуют ключ в заголовке X-API-Key. Ключ выдаётся в кабинете: «Подключение» → «Доступы» → «Настройки ключей». Показывается он один раз — в базе лежит только его хеш.

У ключа есть права: catalog — писать в каталог, search — звать поиск, stats — читать статистику, hooks — заводить подписки на события. Для связки в no-code сервисе нужен ключ с полным доступом.

curl https://aisse.ru/v1/ping -H "X-API-Key: ВАШ_КЛЮЧ"

2. Каталог

Каталог ведёт один источник. Если сайт подключён нашим плагином CMS, каталог заливает плагин, и вызовы с другим ключом получат отказ 409 — источник переключается в кабинете.

POST /v1/items — одна карточка, завести или обновить. Метод для no-code связок: они шлют строку за строкой.

curl -X POST https://aisse.ru/v1/items \
  -H "X-API-Key: ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  --data-binary @item.json

{
  "external_id": "SKU-1024",
  "title": "Экскаватор-погрузчик JCB 3CX",
  "description": "Глубина копания 5,5 м, ковш 0,3 м³",
  "category": "Экскаваторы-погрузчики",
  "price_shift": 24000,
  "address": "Москва, Варшавское шоссе",
  "url": "https://ваш-сайт.ru/catalog/sku-1024",
  "active": true
}

DELETE /v1/items/SKU-1024 — убрать карточку из поиска. Строка остаётся: статистика по ней уже собрана, а товар обычно возвращается.

POST /v1/catalog — пакетная заливка. mode: "full" гасит всё, чего нет в пакете, "increment" — только обновляет присланное.

3. События

Подписка — это пара «событие + адрес». На одно событие можно завести несколько адресов: заявку сразу в CRM и в чат отдела. Подписки заводятся в кабинете («Доступы» → «Настройки вебхука») или методом API — так их и создаёт связка в no-code сервисе.

POST   /v1/hooks      {"event": "booking.intent", "url": "https://…", "label": "Заявки в amoCRM"}
GET    /v1/hooks      список подписок
DELETE /v1/hooks/12   убрать подписку
GET    /v1/events     справочник событий, без ключа

В ответ на создание приходит secret — им подписано тело. Повторный вызов с тем же событием и адресом возвращает ту же подписку, дублей не будет.

4. Что приходит в приёмник

Всегда POST с JSON. Конверт одинаковый у всех событий, различается только data.

POST ваш-адрес
X-AISSE-Event: booking.intent
X-AISSE-Signature: sha256=…

{
  "event": "booking.intent",
  "tenant": "ваш-проект",
  "sent_at": "2026-09-16T12:00:00+00:00",
  "data": {
    "session_id": "…",
    "external_id": "SKU-1024",
    "task_summary": "подача бетона на 45 м",
    "query": "поднять бетон на 14 этаж",
    "params": {"location_text": "Казань"},
    "tags": ["бетон на высоту"]
  }
}

Подпись — HMAC-SHA256 от тела запроса на вашем секрете. Проверять её стоит: адрес приёмника не тайна, а подпись подделать нельзя.

import hmac, hashlib
ok = hmac.compare_digest(
    request.headers["X-AISSE-Signature"],
    "sha256=" + hmac.new(SECRET.encode(), request.body, hashlib.sha256).hexdigest(),
)

Приёмник должен ответить кодом 2xx. На 5xx и на обрыв связи мы повторяем отправку ещё дважды, с паузами; на 4xx не повторяем — это осознанный отказ. Если адрес молчит два десятка раз подряд, подписка выключается сама, и в кабинете видно, почему.

5. Поиск из своего кода

POST /v1/message — реплика диалога. Первый вызов без session_id заводит разговор, дальше передавайте полученный session_id. Ответ — либо карточки, либо уточняющий вопрос, либо честное «такого у нас нет».

curl -X POST https://aisse.ru/v1/message \
  -H "X-API-Key: ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  --data-binary @query.json

Метод доступен не на всех тарифах — на «Старте» и «Росте» он закрыт, и вызов вернёт 402.

6. Связка без кода

Порядок одинаковый в Albato, ApiX-Drive и похожих сервисах:

• чтобы забирать события из AISSE — заведите в сервисе блок входящего вебхука, скопируйте выданный им адрес и добавьте его подпиской в кабинете. Кнопка «Тест» рядом с подпиской пошлёт образец события, чтобы связке было что разбирать;
• чтобы класть данные в AISSE — используйте блок HTTP-запроса: POST на https://aisse.ru/v1/items с заголовком X-API-Key.

Своего приложения в каталогах этих сервисов у нас пока нет, поэтому связка собирается универсальными блоками. Работает это уже сегодня и от появления приложения не сломается.

7. Ошибки

В теле ошибки всегда есть detail с человеческой причиной. Её можно показывать пользователю как есть.