API-интеграция без боли: что уточнить до разработки

API-интеграция. Готовность - когда понятны сбои, а не когда «запрос один раз прошёл» без тестового стенда и лимитов.

Интеграция кажется простой до первого 500

Документация устарела, тестового доступа нет, ошибка - «something went wrong». На сайте в это время человек нажал «отправить» и думает, что заявка ушла.

Что спросить до разработки

• Есть ли sandbox и тестовые ключи.
• Как выдаются и обновляются токены, кто хранит.
• Лимиты запросов в минуту и сутки.
• Webhooks или только polling.
• Формат ошибок и idempotency.
• Контакт техподдержки API на случай блокировки.

Мини-пример обработки

const res = await fetch('https://api.example.com/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name, phone })
})

if (!res.ok) {
  await saveLeadLocally({ name, phone })
  throw new Error('CRM не приняла заявку: ' + res.status)
}

Заявку нельзя терять, если внешний сервис лежит. Локальный лог, очередь, письмо админу - выберите хоть что-то. Это часть ТЗ.

Типовые риски

Интеграция готова, когда известно, что делать при сбое - не когда демо один раз зелёное.

Оцените объём заранее - сколько стоит похожая работа и что спросить до предоплаты. API редко «на час».

Документируйте интеграцию для себя

Один файл в репозитории: endpoint, поля, пример запроса, коды ошибок, контакт поддержки, дата последней проверки. Через год вы забудете, почему стоит костыль с retry - запись спасёт.

Мониторинг: раз в сутки тестовый ping или алерт при росте ошибок формы. Простой cron с записью в лог лучше, чем узнать от клиента «у вас неделю не работает».

Версионирование API

Уточните, стабилен ли endpoint. v1 может измениться без предупреждения на «бесплатных» интеграциях. Заложите время на адаптацию при смене версии или абстракцию через свой слой.

Webhook подписи проверяйте на staging. Подделка webhook без verify - дыры в CRM.

Очереди и повторы

Если CRM упала, заявки копятся в очереди (Redis, файл, БД) и отправляются retry с exponential backoff. Не 100 запросов в секунду в упавший API - получите бан.

Idempotency key по hash телефона+timestamp минуты - защита от двойных кликов «отправить».

Контракты и mock

Если API не готов - mock server (MSW, json-server) и параллельная разработка фронта. Контракт OpenAPI или хотя бы пример JSON в репо.

Staging CRM + staging site - тестовые лиды не в prod базу клиента.

Логирование request id от API - поддержка быстрее отвечает с id, чем «у нас не работает».

Типовые интеграции на лендинге и их реальная цена

«Подключим CRM» в смете одной строкой - почти всегда недооценка. Каждая система - отдельный пункт с часами на mapping полей, тесты и обработку ошибок.

Безопасность: минимум для форм и API

Секреты только на backend. Rate limit на endpoint формы. CORS только для своего домена. Логи без телефонов в открытом виде - маскируйте или храните за auth. Honeypot и минимальное время заполнения - дешевле, чем борьба со спамом post-factum.

// Пример: не светим token клиенту
app.post('/api/lead', rateLimit, async (req, res) => {
  const lead = validateLead(req.body)
  await persistWithFallback(lead)
  res.json({ ok: true })
})

Тестирование интеграции перед продом

Чеклист, который прогоняю сам:

• Успешная заявка в sandbox CRM.
• Ошибка 500 CRM - лид в резерве, пользователь видит сообщение.
• Таймаут 30 сек - то же.
• Двойной клик «отправить» - один лид, не три.
• Невалидный телефон - 400, понятный текст.

Демо «один раз сработало» - не приёмка. Приёмка - сценарии сбоев.

Форма на сайте без резерва - тема потери заявок. Hosting и SSL для backend - hosting, домен и SSL. Оценка объёма - сколько стоит сайт.

Когда интеграцию лучше отложить

MVP: форма в Telegram + таблица. CRM подключаете, когда процесс обработки стабилен и есть человек, который ведёт статусы. Иначе платите за интеграцию в пустую систему. Про CRM с нуля vs коробка - когда CRM с нуля не нужна.

Ваш чеклист

1. Получите тестовый доступ и пример рабочего запроса.
2. Опишите в ТЗ, куда сохраняется лид при ошибке CRM.
3. Проксируйте API через свой backend.
4. Логируйте статусы ответов без персональных данных в открытом виде.
5. Согласуйте, кто обновляет токены и как часто.
6. Проведите тест «отключили CRM - заявка не потерялась».

Ловушки на этом этапе

• Тестировать только на прод-ключах с реальными клиентами.
• Хранить секреты в frontend-коде.
• Не обрабатывать таймауты и 5xx.
• Верить документации без пробного запроса.
• Не закладывать время на согласование с поддержкой API.

Когда без подрядчика не обойтись. Без разработчика интеграция на сайте обычно превращается в дырку в безопасности или в потерянные заявки - backend, retry и секреты не делаются конструктором. Ориентиры по срокам и бюджету - на странице цен, услуги - в разделе услуг.

Рядом по теме: ТЗ на сайт, Вопросы до предоплаты, Сколько стоит сайт.

Webhook с retry и idempotency key - две строки в ТЗ, которые спасают от дублей лидов в CRM при сбое сети.