API-ключ Нотифлоу: как получить и использовать

API-ключ Нотифлоу — это UUID, по которому платформа понимает, к какому проекту относится запрос. Один и тот же ключ обслуживает виджет на сайте и REST API: подставляется в loader-скрипт и одновременно передается в заголовке X-Api-Key для серверных вызовов. Ключ создается автоматически при первой подписке и виден в кабинете в разделе «Подписка → Ключ виджета».

Зачем нужен API-ключ?

Без ключа Нотифлоу не знает, какому аккаунту принадлежит трафик. Ключ нужен для:

• инициализации виджета на сайте (nw('init', { apiKey: '...' }))
• серверного создания контактов через REST API v1
• отправки событий и обновления атрибутов с бэкенда
• встраивания виджета в карточку amoCRM (через тот же ключ)

Один ключ — на одну подписку. Перевыпуск (ротация) сразу делает старый ключ невалидным, поэтому планируйте обновление кода заранее.

Где найти ключ в личном кабинете?

Войдите в cp.notiflow.ru, откройте «Подписка». В блоке «Установка виджета» уже сгенерирован готовый <script>-сниппет с подставленным ключом. Кнопка «Скопировать» рядом — копирует целиком.

Если домен еще не добавлен, сначала пройдите добавление домена, иначе виджет не запустится — ключ работает только на доменах из белого списка.

Как подключить ключ к скрипту виджета?

Скрипт установки выглядит так:

<script>
    (function(w,d,s,o,f,js,fjs){
        w[o]=w[o]||function(){(w[o].q=w[o].q||[]).push(arguments)};
        js=d.createElement(s),fjs=d.getElementsByTagName(s)[0];
        js.id=o;js.src=f;js.async=1;fjs.parentNode.insertBefore(js,fjs);
    }(window,document,'script','nw','https://cp.notiflow.ru/js/widget.js'));
    nw('init', {apiKey:'YOUR_API_KEY_UUID'});
</script>

YOUR_API_KEY_UUID — это и есть ваш ключ. В реальном сниппете из кабинета он уже подставлен. Скрипт грузится async, на скорость страницы влияет минимально.

Как использовать ключ для серверных вызовов?

Серверная аутентификация — заголовок X-Api-Key. Пример upsert контакта через REST API v1:

curl -X POST https://cp.notiflow.ru/api/v1/contacts \
  -H "X-Api-Key: YOUR_API_KEY_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_42",
    "email": "anna@example.com",
    "name": "Анна",
    "attributes": {
      "plan": "growth",
      "signed_up_at": "2026-04-15"
    }
  }'

Тот же запрос на PHP через Guzzle:

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://cp.notiflow.ru/api/v1/']);
$response = $client->post('contacts', [
    'headers' => [
        'X-Api-Key' => getenv('НОТИФЛОУ_API_KEY'),
    ],
    'json' => [
        'external_id' => 'user_42',
        'email' => 'anna@example.com',
        'name' => 'Анна',
        'attributes' => ['plan' => 'growth'],
    ],
]);

Доступные эндпоинты v1: POST /v1/contacts (upsert), GET/DELETE /v1/contacts/{externalId}, POST /v1/contacts/{externalId}/tags, POST /v1/companies, POST /v1/events. Ключ один и тот же на фронте и на бэке — поэтому не светите серверные вызовы из браузера, всю работу с REST API делайте только с сервера.

Как проверить, что ключ работает?

Отправьте тестовый upsert на /v1/contacts с минимальным payload:

curl -X POST https://cp.notiflow.ru/api/v1/contacts \
  -H "X-Api-Key: YOUR_API_KEY_UUID" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"test_ping","email":"ping@example.com"}'

Ответ 200 с телом контакта — ключ валиден. Ответ 401 «Missing X-Api-Key header» или «Invalid API key» — ключ не передан или отозван. Ответ 403 — ключ есть, но домен не в белом списке (для виджет-эндпоинтов).

Для виджета: откройте сайт с установленным скриптом, в DevTools Network найдите запросы к cp.notiflow.ru/api/widgets/data — заголовок X-Api-Key с вашим UUID отправляется автоматически.

Где хранить ключ и что делать при утечке?

Ключ — в переменных окружения (.env, vault, AWS Secrets Manager). Не коммитьте в git, добавьте .env в .gitignore. В CI/CD пробрасывайте через секреты раннера.

Если ключ утек (попал в публичный репозиторий, в логи Sentry с реальными данными, в скриншот) — ротируйте в кабинете. Кнопка «Перевыпустить ключ» в разделе «Подписка». После ротации старый UUID моментально перестает работать — обновите его на сайте, в бэкенд-сервисах и интеграциях.

После ротации в журнале запросов в кабинете видно, не пытался ли кто-то воспользоваться старым ключом — если было обращение с незнакомого IP, есть смысл проверить логи приложения на стороннюю активность.

Ротация ключа: процедура без даунтайма

Поскольку один ключ обслуживает и виджет, и API, прямая ротация в один клик даст короткий период «виджет работает на старом ключе, бэкенд читает новый». Чтобы избежать этого:

1. Подготовьте деплой кода со ссылкой на новый ключ через ENV
2. Перевыпустите ключ в кабинете — старый сразу невалиден
3. Сразу же раскатите деплой с новым значением ENV
4. Обновите код установки виджета на сайте (если он зашит, а не подгружается из API)

На больших сайтах с CDN-кэшем HTML после смены ключа возможна 1-2 минуты, пока кэшированные страницы не обновятся — на это время виджет может не инициализироваться у части посетителей. Планируйте ротацию в часы низкого трафика.

Часто задаваемые вопросы

Подключите API-ключ за пять минут — зарегистрируйтесь в Нотифлоу и откройте раздел «Подписка». После этого пригодятся гайды по настройке вебхуков и передаче атрибутов пользователя. Полный список интеграций — на странице платформы.