API простими словами: як програми говорять між собою

API (application programming interface, програмний інтерфейс) це домовленість, за якою одна програма просить іншу віддати дані чи виконати дію. Сайт питає CRM «створи ліда з таким імʼям і телефоном», CRM відповідає «створено, номер 1542». Облікова система питає банк «дай виписку за вчора», банк повертає список операцій. Людина в цьому не бере участі: програми домовляються самі за правилами, які описані в документації API.

Для власника бізнесу API це відповідь на питання «чи можна це автоматизувати». Нижче пояснюємо, як API працює, на що дивитися при виборі системи і на чому інтеграції ламаються найчастіше.

Аналогія з рестораном

Ви (програма-клієнт) сидите за столиком. Кухня (інша система) вміє готувати, але на кухню вас не пускають. Офіціант (API) приймає замовлення за меню, передає на кухню і приносить результат. Меню це документація API: що можна замовити, які параметри вказати, що принесуть у відповідь. Замовити страву, якої немає в меню, неможливо, навіть якщо кухня технічно вміє її приготувати.

З чого складається API

• Адреса (endpoint). Куди звертатись: наприклад, адреса для створення ліда чи отримання замовлень.
• Метод. Що зробити: отримати (GET), створити (POST), змінити (PUT, PATCH), видалити (DELETE).
• Параметри. Що саме: період, номер клієнта, фільтр за статусом.
• Авторизація. API-ключ чи токен, який показує, хто звертається і що йому дозволено.
• Відповідь. Дані у форматі JSON і код результату: 200 означає успіх, 400 помилку в запиті, 401 відсутність доступу, 429 перевищення ліміту запитів.
• Ліміти. Скільки запитів можна робити за хвилину чи день.

Що дає API бізнесу

• Заявки з сайту одразу в CRM без копіювання вручну.
• Замовлення з магазину в облікову систему, залишки з обліку на сайт.
• Статуси доставки від служби доставки у картку замовлення.
• Банківські виписки в облік і платіжний календар.
• AI-агент, що діє: агент без доступу до API ваших систем може лише радити, з доступом він створює заявки, перевіряє статуси і ставить задачі.

Приклад: одна перевірка, два входи

У нашому продукті перевірки контрагентів звіт можна отримати у веб-кабінеті або з AI-асистента через MCP-сервер. Обидва входи викликають одну й ту саму внутрішню функцію перевірки з тими самими правами і квотою. Для кабінету ми додали окремий API-метод перевірки, і він не має жодної другої логіки: лише ще одні двері до того самого механізму. Результат видається у кількох форматах, серед яких JSON для інтеграції у внутрішні системи клієнта.

Принцип, який тут видно, корисний для будь-якої системи: одна логіка, кілька входів. Тоді кабінет, API і інтеграції не можуть розійтись у результатах.

Приклад: коли API працює не так, як написано

Для чат-помічниці бренду шовкових аксесуарів бот перевіряє наявність і впізнає клієнтів через API KeyCRM. На практиці виявилось, що пошук товарів і покупців через API повертає весь перелік замість відфільтрованого результату. Тому бот тримає власні кеші: каталог оновлюється раз на годину, покупці раз на годину, замовлення кожні пʼять хвилин, а пошук робиться локально по кешу. Інша особливість: видалення ліда через API немає, тому тестові ліди позначаються префіксом і закриваються зміною статусу, щоб не лишатись у живій воронці.

Урок загальний: документація API описує намір, а реальна поведінка перевіряється тестом на живих даних до того, як на ній будується процес. Детальніше про інтеграції з CRM у статті інтеграція сайту з CRM.

Приклад: без API теж можна почати

У чат-агенті енергокомпанії агент пояснює нарахування на вивантаженнях білінгу. А рішення «Дашборд CFO» прямо передбачає старт на ваших вивантаженнях без інтеграції. Це нормальний шлях: пілот працює на файлах, а API підключають, коли цінність уже доведена і зрозуміло, які саме дані потрібні щодня.

REST, GraphQL, SOAP: чи треба в цьому розбиратись

Ці слова часто трапляються в описах систем. REST найпоширеніший стиль: окремі адреси для різних обʼєктів і прості запити. GraphQL дозволяє одним запитом отримати саме ті поля, які потрібні. SOAP старший стандарт, що досі живе в банківських і державних системах. Для власника бізнесу важливо інше: чи є API взагалі, чи він документований і чи дає потрібні дії. Зі стилем розробник розбереться сам.

Як читати документацію API без технічної освіти

Відкрийте документацію системи, яку обираєте, і пошукайте три речі. Перелік обʼєктів: замовлення, клієнти, товари, рахунки. Для кожного подивіться, чи можна його отримати, створити і змінити. Потім знайдіть розділ про вебхуки чи події. Якщо потрібний вам обʼєкт є лише в режимі читання, автоматично створювати його з інших систем не вийде. Такий пʼятихвилинний огляд до покупки системи часто економить місяці обхідних рішень після.

На що дивитися при виборі системи

1. Чи є публічна документація API. Якщо її треба просити у менеджера, це тривожний знак.
2. Які дії доступні. Лише читання чи і запис? Чи можна створити документ, змінити статус?
3. Вебхуки. Чи вміє система сама повідомляти про події (нове замовлення, оплата), щоб не питати її щохвилини.
4. Ліміти. Скільки запитів дозволено, і чи вистачить їх на ваш обсяг.
5. Тестове середовище. Чи можна перевірити інтеграцію без ризику для живих даних.
6. Стабільність версій. Як система попереджає про зміни API.

Безпека API

• Ключі зберігаються у менеджері секретів і ніколи не потрапляють у код сайту чи у листування.
• Кожна інтеграція має окремий ключ з мінімальними правами.
• Ключі перевипускають при зміні підрядника чи працівника.
• Вхідні дані перевіряються: сервер, що приймає запити, не довіряє їм наосліп.
• Журнал запитів дозволяє розібрати, хто що змінив.

Типові проблеми інтеграцій

• Дублікати. Одна заявка створилась двічі через повторну спробу після помилки мережі.
• Різні довідники. Товар в одній системі має один код, в іншій інший. Потрібна таблиця відповідностей.
• Тиха помилка. Інтеграція перестала працювати, і ніхто не помітив тиждень. Потрібен моніторинг і сповіщення.
• Ліміти. У розпал сезону система впирається в ліміт запитів.

Інтеграції через API ми будуємо в напрямах інтеграції з CRM та інтеграції з BAS і 1С. Опишіть, які системи треба звʼязати, у формі на головній, оцінку дамо після брифу за робочий день.