Интеграции: API, очереди, webhooks

Что такое интеграция

Аналогия: интеграция — когда два магазина договорились работать вместе: один принимает заказ, другой доставляет, третий шлёт SMS. Клиент видит один сервис, а за кулисами участвуют несколько.

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

Примеры из жизни продукта:

• сайт ↔ платёжная система;
• заказ ↔ сервис уведомлений (email / SMS / push);
• CRM ↔ склад;
• мобильное приложение ↔ бэкенд.

Снаружи пользователь нажал кнопку. Внутри могли пройти 2–5 обменов между разными системами.

Поэтому баг «на кнопке» часто на самом деле баг в связи между системами.

API в интеграциях

Аналогия: API — как телефон с понятным списком команд: «создай платёж», «проверь статус», «верни деньги».

В интеграциях API — основной способ сказать другой системе: «сделай вот это и ответь».

Обычно это выглядит так:

1. наш сервис отправляет запрос;
2. внешняя система отвечает сразу: успех / ошибка / «принято в работу»;
3. мы сохраняем результат и показываем его пользователю.

Что проверять

• Ушёл ли запрос?
• Какой код ответа: 200/201 или 4xx/5xx?
• Совпадают ли данные (сумма, id заказа, статус)?
• Что видит пользователь при ошибке?

Подробнее про API и коды ответов — на странице HTTP / API / REST.

Очереди

Аналогия: очередь — как окошко в банке с талончиками. Вы оставили задачу в ряд, вам не обязательно ждать у стойки: работу возьмут по порядку, когда освободится сотрудник.

Очередь нужна, когда действие не обязательно делать «прямо сейчас в этом же запросе».

Например:

• отправить письмо;
• построить тяжёлый отчёт;
• уведомить несколько сервисов о новом заказе;
• повторить попытку, если внешняя система временно недоступна.

Чем очередь отличается от обычного API-вызова

• API «здесь и сейчас» — ждём ответ сразу.
• Очередь — положили задачу и идём дальше; результат будет позже.

Если письмо/SMS «не пришло сразу», это не всегда баг. Иногда так и задумано: задача ещё в очереди. Баг — если задача потерялась, застряла или падает снова и снова.

Webhooks

Аналогия: webhook — как «перезвоните мне сами». Вместо того чтобы каждые 10 секунд спрашивать «оплата прошла?», платёжка сама пишет вам: «оплата прошла».

Webhook — это когда внешняя система сама присылает вам уведомление о событии на ваш адрес (URL).

Типичный сценарий оплаты:

1. пользователь начал оплату;
2. наш сервис ждёт;
3. платёжка позже вызывает наш webhook: «платёж успешен» или «платёж отклонён»;
4. мы обновляем статус заказа.

Что важно знать новичку

• Webhook приходит позже, не в момент клика.
• Он может прийти повторно (дубликат) — система должна это пережить.
• Если наш endpoint недоступен, событие может потеряться или прийти с задержкой.

Где интеграции обычно ломаются

• Таймаут — внешняя система слишком долго отвечает.
• Неверный формат данных — ожидали число, пришла строка; не хватает поля.
• Ошибка авторизации — ключ/токен просрочен или нет прав.
• Дубли — одно и то же событие пришло дважды (двойное списание/письмо).
• Потеря сообщения — задача не попала в очередь или webhook не дошёл.
• Рассинхрон статусов — у оплаты «успех», у заказа всё ещё «ожидает».

Мини-практика на 15–20 минут

1. Возьмите сценарий: «пользователь оплатил заказ и получил письмо».
2. Разложите шаги: что идёт через API, что может уйти в очередь, где возможен webhook.
3. Придумайте 3 поломки: таймаут оплаты, письмо не ушло, webhook пришёл дважды.
4. Для каждой поломки напишите: что увидит пользователь и где искать причину.
5. Своими словами объясните разницу: API = спросил и получил ответ; очередь = задача на потом; webhook = нам написали сами.

Если объяснение получается без сложных слов — день 8–9 пройден.