CRM
Замовлення, клієнти, ліди, статуси, товари та додаткові поля.
Детальніше →Системи, дані та бізнес-логіка
Індивідуальний обмін там, де модуля недостатньо
З’єднуємо сайти, CRM, платіжні сервіси, логістику, маркетплейси та інші системи через API, webhooks і фонові процеси. Якщо готового модуля немає або він не закриває бізнес-задачу — проєктуємо індивідуальну логіку обміну даними.
Не просто викликаємо API — будуємо надійний бізнес-процес між системами.
Індивідуальна розробка
Коли готового модуля недостатньо
Спочатку перевіряємо API, документацію, webhooks та обмеження систем. Після цього визначаємо, який сценарій можна реалізувати.
Якщо готовий модуль стабільно закриває задачу — використовуємо його. API-розробка потрібна там, де стандартного рішення недостатньо.
- 01немає готового модуля
- 02модуль не передає потрібні поля
- 03потрібна нестандартна бізнес-логіка
- 04треба зв’язати більше двох систем
- 05потрібен двосторонній обмін
- 06потрібно оновлювати існуючі записи
- 07потрібні webhooks
- 08потрібна синхронізація за розкладом
- 09потрібен контроль дублів
- 10потрібна повторна обробка помилок
- 11треба доопрацювати чужу інтеграцію
Напрямки
Що можна інтегрувати
Не обіцяємо підключення будь-якого сервісу без перевірки. Потрібен офіційний технічний механізм обміну та достатні права доступу.
Платежі
Оплата, callbacks, статуси та оновлення замовлень.
Детальніше →Доставка
Накладні, ТТН, статуси, відділення та фулфілмент.
Детальніше →Телефонія
Дзвінки, call tracking, події та робота з лідами.
Детальніше →Маркетплейси
Товари, залишки, ціни, замовлення та статуси.
Детальніше →Інші сервіси
SaaS, внутрішні системи, кастомні API та спеціалізовані бізнес-сервіси.
Базова схема
Інтеграційна логіка керує обміном між системами
API дозволяє отримати або змінити дані, але бізнес-логіка визначає, що саме, коли і за якими правилами передавати. У складному проєкті це може бути окремий інтеграційний шар.
API Hubлогіка PromoSiteСайтCRMПлатежіДоставкаТелефоніяМаркетплейси
Запит і подія
API та Webhooks виконують різні ролі
Система виконує запит
Використовується для отримання, пошуку, створення, оновлення або перевірки даних.
- отримати або знайти дані
- створити новий запис
- оновити існуючий об’єкт
- перевірити статус
- запустити підтримувану операцію
Сервіс повідомляє про подію
Надсилається, коли у зовнішній системі відбулася доступна та налаштована подія.
- створено замовлення
- змінено статус
- отримано оплату
- відбувся дзвінок
- створено відправлення
- відбулася інша доступна подія
API відповідає на запит, webhook повідомляє про подію. У багатьох інтеграціях використовуються обидва механізми.
Дані та формати
Не всі системи говорять однією мовою
Дані двох систем часто мають різну структуру. Інтеграція перетворює їх у формат, зрозумілий стороні-одержувачу.
JSONXMLCSVform-dataURL encodedфайли та інші формати
- 01перейменувати поля
- 02нормалізувати телефони
- 03зіставити статуси
- 04зіставити SKU
- 05конвертувати дати
- 06узгодити валюти
- 07змінити структуру
- 08прив’язати external ID
Авторизація та доступ
Працюємо з механізмом конкретного API
Спосіб доступу визначає документація сервісу. Реальні credentials не публікуються у контенті, frontend або відкритому коді.
API keyBearer tokenOAuth 2.0Basic Authпідпис запитуHMACIP restrictionsінший механізм документації
- секрети зберігаються на сервері
- токени не передаються у frontend
- секрети не потрапляють у відкритий репозиторій
- секретні значення не логуються
- для обміну використовується HTTPS
Напрямок обміну
Одностороння передача або синхронізація
Односторонній обмін
Наприклад, сайт передає замовлення в CRM. Джерело даних і момент передачі визначені заздалегідь.
- один напрямок
- погоджена подія
- мапінг полів
- контроль результату
Двостороння синхронізація
Наприклад, сайт передає замовлення, а CRM повертає статус. Потрібні source of truth та правила конфліктів.
- master system
- унікальні ID
- правила оновлення
- захист від циклічних змін
Cron та фонові задачі
Не всі дані потрібно передавати під час запиту користувача
Залежно від архітектури використовуємо cron, background jobs або queue. Окремий worker чи черга потрібні не кожному проєкту.
- регулярна синхронізація
- перевірка статусів
- великі каталоги
- повторна обробка
- імпорт
- експорт
- reconciliation
- відкладені операції
Reliability layer
Інтеграція повинна враховувати тимчасову недоступність системи
Склад механізмів залежить від критичності та архітектури. Повний набір не додається автоматично до кожної інтеграції.
Подія→Перевірка→Обробка→Результатпомилка → retry / queue / failed log за погодженими правилами
- logging
- retry
- idempotency
- unique external IDs
- timeout handling
- API error handling
- rate limit handling
- queue за потреби
- повторна синхронізація
- failed jobs log за потреби
- контроль response code
- технічні повідомлення про критичні помилки
Дублікати та ID
Одна подія не повинна створити два замовлення
Стабільний ідентифікатор допомагає знайти вже існуючий об’єкт і вирішити — створити новий запис чи оновити поточний.
external IDorder IDcall IDtransaction IDSKUінший стабільний ідентифікатор
- 01коли створювати запис
- 02коли оновлювати
- 03що робити при повторному webhook
- 04як знайти існуючий об’єкт
Rate limits
API має технічні обмеження
Для великих каталогів не обіцяємо миттєвий обмін без перевірки API limits. Синхронізація може виконуватися частинами.
- кількість запитів
- частота звернень
- обсяг даних
- розмір batch
- кількість записів у request
- batch processing
- pagination
- queue за потреби
- паузи між запитами
- синхронізація частинами
Логування та діагностика
Щоб інтеграцію можна було підтримувати після запуску
Логування скорочує час пошуку проблеми, якщо сторонній API змінив поведінку або тимчасово не відповідає.
- подія
- external ID
- час
- тип функції без секретів
- response code
- помилка
- результат обробки
- паролі
- API keys і токени
- повні платіжні дані
- зайві персональні дані
Підтримка
Зовнішні API можуть змінюватися
Провайдер може змінити версію, поля, авторизацію або обмеження. Після таких змін кастомна інтеграція може потребувати доопрацювання — вона не гарантується назавжди без підтримки.
- endpoint
- версія API
- структура полів
- авторизація
- rate limits
- deprecated methods
Альтернативи
Що робити, якщо сервіс не має API
Перевіряємо лише доцільні та погоджені механізми. Scraping приватних кабінетів не пропонуємо як стандартний спосіб інтеграції.
Пріоритет — офіційний та підтримуваний сервісом механізм обміну.
- готовий модуль
- webhooks
- XML
- CSV
- імпорт або експорт файлів
- інший офіційний механізм
Процес реалізації
Від документації API до працюючого процесу
- 01
Описуємо сценарій
Фіксуємо бізнес-результат.
- 02
Отримуємо документацію
Перевіряємо офіційні матеріали.
- 03
Перевіряємо доступ
Тестуємо авторизацію та API.
- 04
Формуємо карту
Зіставляємо поля й формати.
- 05
Визначаємо source of truth
Фіксуємо основну систему.
- 06
Проєктуємо помилки
Описуємо retry та повторні події.
- 07
Реалізуємо
Будуємо інтеграційну логіку.
- 08
Тестуємо
Перевіряємо основні й помилкові сценарії.
- 09
Запускаємо
Вмикаємо погоджений обмін.
- 10
Контролюємо
Перевіряємо перші реальні операції.
Практичні сценарії
Реальні типи задач PromoSite
Показуємо типи інтеграцій без назв клієнтів, приватних endpoint-ів, внутрішніх ID або документації.
- 01WooCommerce → KeyCRM
- 02OpenCart → KeyCRM
- 03PrestaShop → KeyCRM
- 04сайт → платіжна система → CRM
- 05Ringostat → KeyCRM
- 06KeyCRM → Фулфілмент Нової пошти
- 07webhook → пошук або оновлення ліда
- 08зміна статусу після оплати
- 09синхронізація статусів
- 10cron-перевірка даних
- 11імпорт або експорт через API
- 12доопрацювання інтеграції іншого розробника
Платформи
Підключаємося до існуючих вебпроєктів
Сайт або система не обов’язково мають бути розроблені PromoSite. Перед роботою аналізуємо поточний код, архітектуру та документацію.
- WordPress
- WooCommerce
- Bitrix
- OpenCart
- PrestaShop
- Laravel / Symfony / CodeIgniter
- Кастомні PHP-проєкти
- Інші вебсистеми після аналізу
Що потрібно для старту
Готове ТЗ не обов’язкове
Достатньо назвати системи, показати поточний ручний процес і описати бажаний результат.
Описати системи- 01назви двох або більше систем
- 02посилання на сайт
- 03API-документація, якщо вона є
- 04що зараз робиться вручну
- 05які дані треба передавати
- 06напрямок передачі
- 07результат після передачі
Коротко про головне
Питання та відповіді
Чи можна інтегрувати будь-який сервіс через API?
Не завжди. Спочатку потрібно перевірити API, права доступу, документацію та технічні обмеження.
Чи потрібен готовий модуль?
Ні. Якщо система має потрібний API, інтеграцію можна реалізувати індивідуально.
Чи завжди краще писати власну інтеграцію?
Ні. Якщо готовий модуль стабільний і повністю закриває задачу, його краще використовувати.
Чим API відрізняється від webhook?
API викликається системою для отримання або зміни даних. Webhook надсилається зовнішньою системою після події.
Чи можна зробити двосторонню синхронізацію?
Так, якщо обидві системи дозволяють потрібні операції. Перед реалізацією визначаємо source of truth і правила конфліктів.
Що буде, якщо API тимчасово недоступне?
Для критичних сценаріїв можна передбачити логування, retry, queue або повторну синхронізацію.
Чи можна доопрацювати чужу інтеграцію?
Так, після аналізу існуючого коду, документації та поточного стану інтеграції.
Що робити, якщо сервіс не має API?
Перевіряємо інші офіційні механізми: модулі, webhooks, XML, CSV або імпорт та експорт.
Чи потрібне готове ТЗ?
Ні. Достатньо описати системи, дані, напрямок обміну та бажаний результат.
Наступний крок
Потрібно зв’язати дві системи через API?
Надішліть назви систем, посилання на сайт та коротко опишіть, які дані зараз доводиться переносити вручну. Ми перевіримо API та запропонуємо технічну схему інтеграції.