Публичный API превращает продукт из закрытого сервиса в платформу: партнёры подключают свои системы, разработчики строят интеграции, а вы растёте за счёт чужих усилий. Но открытый интерфейс без продуманной схемы доступа — это дыра в безопасности и нагрузка на инфраструктуру, за которую платите вы. Три кита безопасной интеграции — API-ключи, документация и лимиты запросов. Разберём, как настроить каждый из них так, чтобы партнёрам было удобно, а вашему бизнесу — безопасно.
Зачем бизнесу открывать публичный API
Когда у сервиса появляется публичный API, вокруг него формируется экосистема: агентства пишут коннекторы к 1С, партнёры синхронизируют данные с CRM, клиенты автоматизируют рутину скриптами. Это прямой аргумент в продажах — корпоративные клиенты на этапе выбора продукта первым делом спрашивают, есть ли API и что через него можно сделать. Наличие открытого API сокращает цикл сделки и снижает отток: клиент, у которого интегрированы пять внешних систем, уйти к конкуренту уже не сможет без потери автоматизации. Наконец, API — отдельный источник выручки: доступ к нему можно продавать тарифами, как это делают платёжные сервисы и маркетплейсы.
API-ключи: выдача, хранение и отзыв
Ключ — это одновременно паспорт и пропуск клиента в вашей системе. Основные правила работы с ними:
- Самообслуживание через личный кабинет. Ключ должен выдаваться автоматически после регистрации — ручная выдача через почту не масштабируется.
- Секрет показывается один раз. В базе хранится только хэш ключа; повторно посмотреть его нельзя — только перевыпустить.
- Раздельные ключи для теста и боя. Тестовый контур с фиктивными данными убережёт боевые операции от случайных списаний и удалений.
- Минимальные права (scopes). Ключ для чтения статистики не должен уметь удалять заказы.
- IP-ограничения. Для server-to-server интеграций привязка ключа к белому списку адресов почти полностью исключает его кражу.
Перевыпуск ключа должен занимать у клиента пару минут и не ломать активные интеграции: старый ключ продолжает работать, например, 24 часа после выпуска нового.
Статические ключи или OAuth 2.0
Статический API-ключ подходит, когда интеграция работает от имени всей компании: сервер клиента общается с вашим сервером. Он прост в реализации, но не различает, чьи именно данные запрашиваются. Как только сторонние разработчики получают доступ к данным ваших пользователей — например, приложение партнёра читает заказы конкретного магазина, — нужен OAuth 2.0: пользователь сам выдаёт разрешение, а партнёр получает временный access-токен с ограниченным сроком жизни и refresh-токеном для продления. Так вы получаете аудит «кто, чьи данные и когда смотрел» и можете отозвать доступ точечно, не трогая остальных. Рабочая схема для большинства сервисов: статические ключи для server-to-server, OAuth — для публичных приложений и маркетплейса интеграций.
Лимиты запросов: защита инфраструктуры и честное распределение
Rate limiting решает две задачи: защищает вашу инфраструктуру от лавины запросов и не даёт одному активному клиенту деградировать сервис для остальных. Разумный стартовый лимит — 50–100 запросов в минуту на ключ с возможностью кратковременных всплесков (burst) до 2–3 номиналов: скрипты редко бьют ровным потоком. При превышении API должен отвечать кодом 429 Too Many Requests и заголовком Retry-After, а не обрывать соединение молча. Обязательно отдавайте служебные заголовки X-RateLimit-Limit и X-RateLimit-Remaining — тогда разработчики партнёров построят очередь запросов сами, без обращений в поддержку. Для тяжёлых сценариев вроде выгрузки всех заказов за год лучше предусмотреть отдельные пакетные эндпоинты, а не заставлять партнёра делать 10 000 мелких запросов.
Документация, по которой интеграция действительно работает
Хорошая документация экономит десятки часов вашей поддержки. Минимальный состав:
- Quick start. Первый успешный запрос за 5 минут: скопировал ключ, вставил cURL, получил ответ.
- Справочник эндпоинтов. Для каждого — параметры, типы, обязательность и все коды ответов с расшифровкой.
- Примеры кода. Минимум cURL, PHP и Python — на них приходит большинство интеграций в РФ.
- Тестовая песочница. Возможность «пощупать» API в браузере без написания кода.
- Описания ошибок. Что означает «конфликт версий заказа» и что с этим делать.
- Changelog. Лента изменений с датами и уведомлениями на почту.
Отдельно заложите ресурсы на поддержку документации: API с устаревшими доками превращается в легаси, которое все боятся трогать.
Версионирование и обратная совместимость
Версию выносите в URL — /v1/orders, /v2/orders — и никогда не меняйте поведение внутри версии молча. Добавление новых полей в ответах допустимо, удаление или переименование старых — нет: у партнёров работают интеграции, которые вы не контролируете. Если критичное изменение неизбежно, выпускайте новую версию и держите старую работоспособной минимум 6–12 месяцев, рассылая уведомления и статистику — кто из клиентов ещё не перешёл. Возможность «заморозить» версию на год — сильный аргумент доверия для корпоративных клиентов.
Вебхуки вместо опроса
Если партнёру нужно узнавать о новых заказах, заставлять его дёргать эндпоинт раз в минуту — расточительство для обеих сторон. Вебхуки инвертируют логику: ваш сервер сам отправляет событие на URL партнёра, когда что-то произошло. Обязательные атрибуты — HMAC-подпись запроса (чтобы партнёр проверял подлинность), повторные доставки при недоступности приёмника и идемпотентность: событие может прийти дважды, и обработчик не должен создать два заказа. Полезно также дать партнёру журнал доставки вебхуков в личном кабинете — половина вопросов в поддержку снимается сама.
Ошибки, которые дорого обходятся
Типичные проблемы, которые мы регулярно находим при аудите чужих API:
- Один общий ключ на всех партнёров. При утечке невозможно понять источник и отозвать доступ точечно.
- Лимиты «на доверии». Просьба к разработчику партнёра «не шлите больше 100 запросов» — не защита; лимит должен enforced на вашей стороне.
- Отсутствие логов запросов. Без них инцидент «кто-то выгрузил базу клиентов» не расследуется.
- Секреты в параметрах URL. Ключи попадают в access-логи, прокси и историю браузера — передавайте их в заголовках.
- Нет мониторинга аномалий. Резкий рост запросов с одного ключа — часто первый признак утечки или бага у партнёра.
С чего начать
Публичный API — это продукт внутри продукта, и относиться к нему стоит так же: с продуманным онбордингом, метриками и поддержкой. Начните с малого — 5–10 ключевых эндпоинтов, простые ключи с scopes, честные лимиты и документация с Quick start. Этого достаточно, чтобы первые партнёры подключились и начала расти экосистема. Когда интеграций станет больше десятка, добавьте OAuth 2.0, маркетплейс приложений и платные тарифы доступа. Если хотите открыть API своего сервиса без боли для команды — напишите нам: поможем спроектировать архитектуру и запустить первую версию за 4–6 недель.