API — це погоджений спосіб звертатися до можливостей іншої системи. Наприклад, сайт передає замовлення до CRM або запитує наявність товару в обліку. Системи не просто пересилають текст: вони мають однаково розуміти поля, стани та відповідальність за результат. Тому інтеграція починається з правил обміну, а не з отримання ключа доступу.
Запит і повідомлення про подію вирішують різні задачі
Коли потрібна відповідь зараз, одна система надсилає запит іншій. Коли потрібно повідомити про зміну, зовнішній сервіс може надіслати webhook. Наприклад, сайт запитує ціну перед оформленням замовлення, а платіжний сервіс повідомляє про підтвердження коштів пізніше. Для обох випадків потрібні захищене з’єднання, перевірка походження звернення та зрозумілий формат відповіді.
| Ситуація |
Що погодити |
|
Запит поточних даних |
Джерело, актуальність і допустимий час очікування |
|
Створення замовлення |
Обов’язкові поля та спільний ідентифікатор |
|
Сповіщення про зміну статусу |
Перевірку відправника й поведінку при повторі |
Спільний ідентифікатор важливіший за однакову назву
Товар може називатися на сайті коротко, а в обліку — за внутрішнім стандартом. Пошук відповідності за назвою ненадійний: текст змінюється, можливі дублікати та різні мови. Погоджують стабільні ідентифікатори товарів, клієнтів і документів, а також правила створення записів, яких ще немає в іншій системі.
Так само потрібно вибрати власника кожного поля. Якщо і сайт, і CRM можуть незалежно змінювати статус або телефон, потрібне правило конфлікту. Варіант «остання зміна перемагає» також є правилом, але його наслідки слід свідомо погодити з бізнесом.
Навчальний сценарій: відповідь загубилася
Сайт надіслав замовлення, CRM його створила, але з’єднання перервалося до отримання відповіді. Просте повторення запиту може створити друге замовлення. Щоб цього не сталося, операцію пов’язують зі сталим ключем і погоджують пошук уже прийнятого результату. Після відновлення зв’язку команда повинна бачити одну бізнесову операцію, а не гадати, яку з двох копій обробляти.
Не кожну помилку потрібно повторювати автоматично. Відсутній обов’язковий реквізит потребує виправлення даних, а тимчасова недоступність сервісу може потребувати повторної спроби. Корисний журнал показує ідентифікатор операції, стан і причину збою, але не зберігає паролі чи секретні ключі у відкритому вигляді.
Як готуємо інтеграцію до реалізації
У роботі з API ALL IT Agency технічну задачу розкладаємо на події, поля та результати. Для кожного обміну потрібні приклади запиту, успішної відповіді й помилки. Перевіряємо тестове середовище, доступні права та обмеження частоти звернень. Наявність документації ще не підтверджує, що конкретний обліковий запис має потрібні можливості.
-
Опишіть, хто починає обмін і коли він завершується.
-
Перевірте повтор, затримку, відмову доступу та некоректні дані.
-
Погодьте сповіщення відповідального й спосіб ручного відновлення.
Що означає готова інтеграція
Успішний тестовий запит є лише початком перевірки. Приймання має показати, що записи узгоджуються в обох системах, помилка не губиться, а повтор не спотворює результат. Передайте команді схему обміну, власників доступів та порядок оновлення інтеграції при зміні зовнішнього API. Так з’єднання залишається керованою частиною процесу.
Джерела та подальше читання
