Для разработчиков: API-ключи, OAuth и вебхуки

1. API-ключи: постоянный доступ по sk_

• «+ Выпустить ключ» — задаёте название, срок действия (или бессрочно) и набор прав (scopes): ключ получает только отмеченные права, а не права вашей учётки. Флаг «тестовый» выпускает ключ с префиксом sk_test_.
• Сырой ключ вида sk_… показывается единственный раз в окне после создания — скопируйте его сразу. Дальше в списке виден только префикс: восстановить значение невозможно, только выпустить новый ключ.
• В карточке ключа — статус (Активен / Отозван / Истёк), список прав, дата создания, «последнее использование» и срок действия. «Последнее использование: никогда» — быстрый способ найти забытые ключи.
• «Отозвать» — сервисы на этом ключе мгновенно теряют доступ. Отозвали по ошибке — «Восстановить»: ключ снова работает с тем же значением. Если ключ мог утечь — не восстанавливайте, а выпустите новый. «Удалить» (доступно только у отозванного) стирает карточку с историей навсегда.

2. OAuth-клиенты: чем отличаются от ключей

OAuth-клиент — та же идея машинного доступа, но безопаснее для внешних партнёров: вместо вечного ключа партнёр получает пару client_id / client_secret и обменивает её на короткоживущий токен (поток client_credentials). Утечка токена протухает сама; отзыв клиента останавливает выдачу новых токенов.

• Выпуск, скоупы, тестовый режим и срок действия — как у API-ключей; права на экран те же.
• client_secret показывается один раз при создании. Потеряли — выпускайте нового клиента.
• Правило выбора: свой скрипт или голосовой бот — достаточно API-ключа; внешний партнёр/маркетплейс — предпочтителен OAuth-клиент.

3. Webhooks: кабинет сам сообщает о событиях

• «+ Новая подписка» — название, URL вашего приёмника и набор событий из каталога (запись создана / перенесена / отменена и другие). Кабинет будет отправлять HTTP-запросы на URL при каждом событии — без опроса API с вашей стороны. Адрес принимается только по https и только публичный: по http тело доставки, включая телефон клиента, шло бы открытым текстом, а адреса внутри сети (localhost, 10.x, 192.168.x) отправка не примет.
• «Тест» — отправляет на ваш адрес одно демонстрационное событие с вымышленными данными и сразу показывает ответ. Так связь проверяется, не дожидаясь живой записи. В журнал доставок проба не попадает.
• Каждая доставка подписана секретом whsec_… (HMAC): проверяйте подпись на своей стороне, чтобы отличать наши запросы от подделок. Секрет показывается один раз при создании подписки.
• Подписку можно поставить на паузу и возобновить без пересоздания; удаление стирает и журнал её доставок.
• Статус подписки считается по доставкам, а не по тому, нажимали ли вы паузу: Активна — всё доходит, Ошибки — есть события, которые не дошли, Событий ещё не было — журнал пуст (это не значит, что всё хорошо: возможно, подписанных событий у вас просто не происходило), На паузе — отправка выключена вами. Рядом строка «Посл. доставка» с временем и кодом ответа.
• «Журнал доставок» — история попыток по каждой подписке: Доставлено (ответ 2xx), В очереди (ждёт повторной попытки), Ошибка (DLQ) — событие не дошло за 6 попыток и дальше не ретраится. У строки видны HTTP-код ответа и текст последней ошибки. Число рядом с кнопкой — сколько событий сейчас в DLQ.

Статус «Ошибка (DLQ)» — сигнал разобраться: проверьте доступность эндпоинта и что он отвечает 2xx быстро. Сам по себе такой доставки повтор не получит, но, починив приёмник, верните её в очередь кнопкой «Повторить» в журнале — уйдёт то же самое тело с той же подписью, обрабатывать его на своей стороне отдельно не нужно.

4. Гигиена доступа

• Выпускайте отдельный ключ на каждую интеграцию — отзыв не заденет остальные.
• Давайте минимальные скоупы: ключу для чтения расписания не нужны права на платежи.
• Периодически просматривайте «последнее использование» и отзывайте мёртвые ключи; выпуск и отзыв фиксируются в журнале аудита.

5. Если что-то пошло не так

• Не сохранили секрет — восстановить его нельзя ни для ключа, ни для OAuth-клиента, ни для webhook-подписи. Выпустите новый и замените в интеграции.
• API отвечает 401/403 — ключ отозван, истёк или у него нет нужного скоупа. Проверьте статус и список прав в карточке.
• Кнопки «Восстановить» нет — ключ истёк по сроку: восстановление не вернёт ему доступ, поэтому доступно только удаление. Выпустите новый.
• События не приходят — посмотрите статус подписки и строку «Посл. доставка». «Ошибки» — приёмник отвечает не 2xx или недоступен: нажмите «Тест», чтобы увидеть ответ прямо сейчас, а разобравшись — верните события из DLQ кнопкой «Повторить». «Событий ещё не было» — доставок не было ни одной: проверьте, что подписаны те события, которые у вас действительно происходят.
• «Нет доступа» — все три экрана открыты только владельцу и администратору.