Настройка API-интеграции: чеклист перед подключением

Каждый раз, когда клиент присылает бриф «нужно подключить сайт к CRM, эквайрингу или службе доставки», я начинаю не с кода, а с чеклиста. Настройка API-интеграции без подготовки почти всегда превращается в разбор проблем с поддержкой сервиса на третий день после дедлайна: то у ключа не хватает прав, то формат дат в вебхуках не совпадает, то лимит запросов срезает половину заказов в пиковые часы. Собрал список того, что проверяю перед тем, как написать первую строчку кода, на реальных проектах с эквайрингом Т‑Банка, СДЭК, Tilda-скриптами и Telegram-ботами на aiogram.

Зачем сверяться с чеклистом до старта работы над API

Пропущенный пункт на старте почти никогда не остаётся незамеченным, он просто всплывает позже и обходится дороже. На проекте с интернет-магазином на WooCommerce и эквайрингом Т‑Банка я один раз понадеялся на дефолтные настройки вебхука и не проверил, какой статус заказа сервис присылает при частичном возврате. В итоге два дня разбирал логи вместо того, чтобы один раз прочитать раздел документации про коды событий.

Похожая история с СДЭК: если не свериться заранее со списком городов и тарифов, которые реально поддерживает личный кабинет клиента, виджет расчёта доставки на Tilda будет красиво показывать стоимость для городов, куда компания физически не возит грузы. Чеклист закрывает именно такие случаи, не экзотические баги, а рутинные несостыковки между тем, что написано в документации, и тем, что реально приходит в ответ от сервера.

Отдельно чеклист экономит время на созвонах с заказчиком. Когда я прихожу с готовым списком вопросов про права доступа, лимиты и формат вебхуков, обсуждение занимает 20-30 минут вместо нескольких итераций переписки, растянутых на неделю.

Документация и песочница: что проверяю в первую очередь

Прежде чем писать код, читаю документацию не по порядку разделов, а по конкретному списку вопросов.

• Версия API и срок её поддержки. У некоторых сервисов старые версии отключают через полгода-год после выхода новой, и об этом сообщают только в рассылке для разработчиков.
• Наличие тестовой среды. У Т‑Банка есть демо-терминал с тестовыми картами, у WooCommerce тестовый режим включается прямо в настройках плагина эквайринга, у СДЭК выдают тестовый номер договора. Без песочницы любая ошибка в коде превращается в реальную транзакцию или реальную заявку на забор груза.
• Формат ответа при ошибках. Часть сервисов возвращает код ошибки в теле JSON даже при HTTP 200, и если не заложить это в обработку, скрипт решит, что всё прошло успешно.
• Лимиты запросов и квоты. Некоторые API считают лимит не на аккаунт, а на IP-адрес или на конкретный метод, это критично, если интеграция работает через общий сервер с другими проектами.
• Порядок прихода вебхуков. Статус оплаты и статус доставки могут прийти не в том порядке, в котором произошли события на стороне сервиса.

Аутентификация и хранение ключей доступа

Три способа авторизации встречаются чаще всего. API-ключ в заголовке запроса, обычно самый простой вариант, его использует часть платёжных шлюзов и сервисов доставки для тестовых интеграций. OAuth2 с обновляемым токеном, характерен для CRM и облачных сервисов, требует хранить refresh-токен и обновлять access-токен по расписанию. HMAC-подпись запроса, когда сервис подписывает тело запроса секретным ключом и ждёт такую же подпись в ответ, принята у большинства платёжных провайдеров и у СДЭК для проверки вебхуков.

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

Если интеграция связана с CRM и передачей контактов клиентов, данные храню на серверах в России, а не в иностранных облачных таблицах вроде Google Sheets или Airtable. Это требование 152-ФЗ о локализации персональных данных, и на практике проще сразу спроектировать хранение правильно, чем переносить базу уже после запуска.

Лимиты запросов, повторные попытки и идемпотентность

Rate limit почти у каждого API описан в документации, но не всегда очевидно, что происходит при его превышении: одни сервисы возвращают HTTP 429, другие молча отбрасывают запрос без ответа. Для повторных попыток использую экспоненциальную задержку с ограничением числа попыток, обычно 3-5 раз, и логирую каждый неудачный запрос отдельно от успешных.

Для платёжных операций важна идемпотентность: если сеть оборвалась после отправки запроса на списание, но до получения ответа, повторный запрос с тем же идемпотентным ключом не должен провести повторное списание. Т‑Банк и большинство эквайрингов поддерживают такой ключ, и его стоит передавать всегда, а не только при подозрении на сбой.

С Telegram Bot API на aiogram отдельная особенность: лимит около 30 сообщений в секунду на бота и более жёсткие ограничения на рассылку в один чат, поэтому массовые уведомления через бота отправляю через очередь с паузами, а не одним циклом.

Для интеграций, где нужно связать несколько сервисов между собой, например заявку с сайта на Tilda, CRM и уведомление в Telegram, использую n8n: повторные попытки и логирование ошибок там настраиваются в самом сценарии, без отдельного кода под каждый узел.

Форматы данных, вебхуки и таймзоны

Формат дат ломает интеграции чаще, чем кажется. Одни сервисы присылают время в ISO 8601 с указанием часового пояса, другие - Unix-таймстампом в секундах, третьи - таймстампом в миллисекундах. Если не свериться заранее, дата заказа может съехать на несколько часов, а иногда и на день, если сервер работает в UTC, а клиент ждёт московское время.

Перед тем как доверять телу входящего вебхука, проверяю подпись запроса, если сервис её присылает. Без проверки подписи любой человек, узнавший адрес обработчика, может отправить туда поддельный запрос и, например, имитировать оплату заказа. У платёжных систем и у СДЭК подпись обычно строится на HMAC с секретным ключом из личного кабинета.

На практике с Tilda-скриптами частая связка такая: форма на сайте отправляет данные на вебхук в n8n, сценарий проверяет подпись и формат полей, дальше уже раскладывает данные по CRM и в уведомление в Telegram-бота. Если задача сложнее типового скрипта, такую связку обычно собираю как комплексную интеграцию с CRM, эквайрингом и службой доставки, а не как набор отдельных доработок.

Тестовая среда, логирование и мониторинг после запуска

Даже после успешного запуска интеграция продолжает жить: сервисы меняют версии API, обновляют сертификаты, иногда меняют формат ответа без предупреждения. Отдельно храню логи неудачных запросов и вебхуков, которые не прошли обработку, с телом запроса и кодом ошибки, но без секретных ключей внутри лога.

Тестовый контур держу отдельно от боевого не только по ключам API, но и по базе данных и очереди сообщений, чтобы отладка новой доработки не отправляла тестовые заказы в реальную CRM клиента. Для уведомлений об ошибках вебхуков настраиваю отдельный канал в Telegram-боте, куда падает сообщение при каждом неудачном запросе. Это экономит время на мониторинге по сравнению с ручной проверкой логов раз в день.

Частые вопросы

Сколько времени занимает настройка API-интеграции

Простая доработка, например виджет с одним запросом к внешнему сервису, занимает 2-4 дня. Комплексная интеграция с CRM, эквайрингом и службой доставки, с обработкой вебхуков и повторных попыток, обычно требует от полутора до трёх недель в зависимости от количества сервисов и качества их документации.

Нужно ли переделывать интеграцию при обновлении версии API

Обычно нет, если версия API поддерживается официально и сервис сохраняет обратную совместимость. Проблемы возникают, когда сервис отключает старую версию совсем, тогда приходится переписывать часть запросов под новый формат ответа.

Как проверить, что вебхук пришёл от сервиса, а не от постороннего запроса

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

Что делать, если у сервиса нет тестовой песочницы

Работаю с минимальными суммами и тестовыми заказами прямо на боевом контуре, но обязательно с отдельным логированием и ручным подтверждением перед массовым использованием интеграции. Такой сценарий стоит закладывать в сроки заранее, а не обнаруживать его на этапе тестирования.