Документация

HTTP API

Один эндпоинт для отправки события с сервера и один — для браузера. Всё остальное — необязательные поля.

Ключи доступа

Ключи создаются в кабинете на вкладке «Подключение». Их два типа, и они не взаимозаменяемы.

sk_live_…: Секретный. Только для кода на вашем сервере. Показывается один раз при создании.
pk_live_…: Публичный. Вставляется в HTML, виден посетителям. Умеет только создавать события и только с разрешённых доменов.

Секретный ключ не должен попадать в код страницы, в репозиторий и в мобильное приложение. Если он утёк — отзовите его в кабинете и создайте новый, старый перестанет работать сразу.

Отправка с сервера

POST/api/v1/notify

Заголовок Authorization: Bearer sk_live_…. Тело — JSON.

curl -X POST https://notily.ru/api/v1/notify \
  -H "Authorization: Bearer sk_live_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Новая заявка",
    "body":  "Иван, +7 900 000-00-00",
    "level": "info",
    "source": "Форма на главной",
    "url":   "https://mysite.ru/zayavka",
    "fields": {
      "Имя":     "Иван",
      "Телефон": "+7 900 000-00-00"
    }
  }'

Отправка из браузера

POST/api/v1/collect

Используется сниппетом. Ключ передаётся в поле key внутри тела, а не в заголовке: этого требует navigator.sendBeacon, который единственный не теряет запрос при уходе со страницы.

notily.notify({
  title: 'Оплата прошла',
  body:  'Заказ №4812 · 34 900 ₽',
  level: 'success',
  fields: { 'Заказ': '4812', 'Сумма': '34 900 ₽' }
})

Функция notily.notify появляется после подключения сниппета. Автоматический перехват форм при этом продолжает работать.

Поля запроса

title: Обязательное. Заголовок, до 200 символов. Принимается также как message или text.
body: Текст под заголовком, до 4000 символов.
level: info · success · warning · error. По умолчанию info. Влияет на цвет и на фильтр по важности.
source: Откуда пришло: «Форма на главной», «Онлайн-касса».
url: Ссылка кнопки «Открыть». Только http и https.
fields: Объект из строк: поля формы. До 50 штук.
dedupKey: Схлопывание дублей в пределах окна, заданного в настройках проекта.
idempotencyKey: Защита от повторной отправки при ретрае. Повтор вернёт тот же id события.

Ответы

{ "ok": true, "id": "evt_...", "status": "created" }

status равен duplicate, если событие схлопнулось с предыдущим или пришло с уже использованным idempotencyKey. Это не ошибка — повторять запрос не нужно.

400: Тело не JSON или превышает 64 КБ.
401: Ключ не найден или отозван.
403: Не тот тип ключа либо домен не в списке разрешённых.
422: Не хватает обязательного поля или значение не проходит проверку.
429: Превышен лимит. В заголовке Retry-After — через сколько секунд повторить.
402: Исчерпан месячный лимит тарифа.

Лимиты

По ключу: 120 запросов в минуту
По IP на публичном эндпоинте: 20 запросов в минуту
Размер тела: 64 КБ
Хранение событий: зависит от тарифа: от 10 до 60 дней

При штатной работе лимиты незаметны. Они существуют, чтобы ошибка в цикле на одном сайте не мешала остальным.

Проверка ключа

GET/api/v1/ping

curl https://notily.ru/api/v1/ping \
  -H "Authorization: Bearer sk_live_ВАШ_КЛЮЧ"

{ "ok": true, "keyType": "secret" }

Отвечает, жив ли ключ, не создавая события в ленте. Удобно для проверки после настройки.