Чому інтеграції “ламаються”
Найчастіша причина інцидентів у B2B‑інтеграціях — не “баг”, а відсутність домовленостей: як виглядає контракт, що означає статус‑код, що робити при таймауті, як обробляти повторні запити. Якщо ці правила не зафіксовані, кожен клієнт інтегрується “по‑своєму”, а підтримка перетворюється на пожежу.
1) Контракт: OpenAPI/Swagger як джерело правди
- Описуй ендпоїнти, схеми, приклади, коди відповіді та помилки.
- Валідуй запити/відповіді на бекенді (щоб “неочікуване” не доходило до бізнес‑логіки).
- Генеруй клієнти/SDK, якщо інтеграторів багато.
2) Версіонування: що стабільне, а що можна міняти
Підтримуй зворотну сумісність, де можливо: додавай нові поля, але не прибирай старі без deprecation‑періоду.
- URL‑версії (/v1, /v2) — зрозуміло, але вимагає підтримки двох гілок.
- Header‑версії — гнучко, але складніше дебажити.
- Фіксуй “breaking changes” політику: як попереджаємо, як мігруємо.
3) Ідемпотентність і повтори
Платежі, створення замовлень, бронювання — типові “ризикові” операції. При таймауті клієнт робить повтор, і без ідемпотентності ви отримуєте дублікати.
- Використовуй Idempotency‑Key на POST/PUT для критичних операцій.
- Зберігай результат операції по ключу на TTL.
- Проєктуй ретраї: exponential backoff + jitter.
4) Помилки: код + повідомлення + деталі
Один формат помилок для всіх ендпоїнтів спрощує інтеграцію:
- HTTP‑статус (400/401/403/404/409/422/429/500).
- error.code — стабільний машинний код.
- error.message — коротко для людини.
- error.details — поля/валідація.
5) Спостережуваність (observability)
- Кореляційний requestId у відповіді та логах.
- Метрики: latency, error rate, 429, timeouts, retries.
- Логи без персональних даних, але з контекстом.
Підсумок
Хороше API — це продукт: контракт, правила сумісності, робота з повторами й помилками. Тоді інтеграції масштабуются, а підтримка не з’їдає команду.