ConnectWiz + API та вебхуки
Інтеграція працюєAPI, який ми продаємо, — це той самий API, яким користуємося ми
Уся платформа описана одним контрактом OpenAPI, з якого генеруються наша власна панель і мобільний застосунок, — жодних тіньових ендпоінтів, жодного розходження з документацією. Поверх нього: ключі Commerce API з дозволами, захищені тригери-вебхуки і сценарії, які викликають ваші системи.
Розробникам
Що саме вміє
Один еталонний контракт
Один документ OpenAPI 3 описує платформу; наші власні клієнти на TypeScript генеруються з нього — документація не може розійтися з дійсністю, бо дійсність будується з документації.
Ключі Commerce API
Ключі, видані орендарем, із явними дозволами — читання каталогу, читання замовлень, запис замовлень — живлять вашу власну вітрину чи застосунок на тому самому рушії замовлень, причому ціни завжди визначаються на сервері.
Вхідні вебхуки під захистом
Кожен тригер-вебхук у сценарії має власну URL і власний секрет, перевірку HMAC над сирим тілом запиту і захист від повторів. Payload може назвати людину, але ніколи не може керувати нутрощами сценарію.
Назовні — через сценарії
Крок REST викликає ваші системи рівно в ті моменти, які ви намалювали на полотні: замовлення оформлено, згоду надано, бронь створено.
Технічна частина
Позиції в дизайні API, названі прямо
Ціни ніколи не приходять від клієнта
Запит на замовлення каже що і скільки — назву й ціну читають із каталогу в цю мить, на сервері, і записують у позицію знімком. Підроблений запит не вигадає собі знижки.
Спершу можливості, потім виклики
Кожен інтеграційний вхід публікує контракт можливостей — чи вміє він зіставляти за телефоном, перелічувати гостьові замовлення, створювати замовлення? — і виклик повз оголошене «ні» падає одразу, а не десь у глибині.
Помилки, які щось означають
Транспорт відрізняє «немає доступу» від «сервіс лежить» — тож «магазин недосяжний» ніколи не показується як «цей клієнт нічого не купував». Названі помилки — це різниця між API і грою в угадайку.
Вебхуки, стійкі до повторів
Кожна вхідна подія до обробки займає унікальний ключ у реєстрі ідемпотентності — повторна чи відтворена доставка помирає на рівні бази даних, а не у вашій автоматизації.
Ключі хешовані, секрети обмежені дозволами
Ключі API зберігаються хешами, і на вході можна дістати лише хеш і дозволи — вкрадений рядок бази не називає жодного робочого простору і не відмикає нічого поза своїми дозволами.
Чернетки й підтвердження — явні
Створення замовлення приймає явний параметр confirm — публічний API за замовчуванням створює підтверджене, а сценарії в панелі можуть готувати чернетки, — тож «це справжнє?» є полем, а не домовленістю.
Налаштування
Як підключається
Випустіть ключ
Створіть у панелі ключ Commerce API з дозволами; відкликати його так само просто.
Підключіть вебхук
Створіть сценарій із тригером-вебхуком; підписуйте запити його секретом.
Викликайте назовні
Додайте кроки REST там, де ваші системи мають про це почути.
Разом краще
З чим поєднується
Flows
Тригери-вебхуки запускають сценарії; кроки REST викликають ваші системи у ті моменти, які ви намалювали, — вхідна і вихідна автоматизація живуть на одному полотні.
Commerce
За API стоїть каталог і рушій замовлень — той самий, яким користуються чат-магазин і ШІ: одна правда про замовлення, четверо дверей.
Ваша власна вітрина
Команди вже будують headless-вітрини на Commerce API — саме цей шлях чесно рекомендує сторінка Shopify доти, доки будується нативний конектор.
Безпека та гарантії
Нудні гарантії
HMAC над сирим тілом
Перевірка вебхука підписує сире тіло запиту секретом конкретного тригера і порівнює за сталий час — розбір починається лише після доказу.
Payload — це дані, а не команди
Payload вебхука може посилатися на людину, але ніколи не може керувати нутрощами сценарію, переписувати промпти чи викликати інструменти. Межа між даними й інструкціями архітектурна, а не поведінкова.
Ліміти частоти на кожних дверях
Публічні ендпоінти проходять стандартне обмеження частоти, а ліміти читання обмежуються на сервері — клієнт, що поводиться погано, гальмує сам себе, а не платформу.
Дрібний шрифт — без прикрас
Межі, названі прямо
Суцільного потоку подій поки немає
Універсальної стрічки вебхуків «підпишися на все» ще немає — вихідні події сьогодні відбуваються через кроки сценаріїв. Написано тут, щоб жоден дзвінок із продажів не натякав на інше.
Обмежене читання — за задумом
Читання повертає до 100 рядків із курсором — цей API зроблено для операційної інтеграції, а не для масового експорту. Масові вивантаження — це тема для розмови, а не лазівка.
FAQ про API та вебхуки
Відповіді без води
Решту читайте в повному розділі FAQ — або напишіть нам напряму.
Чесна інтеграція краща за гучну.
Кожну інтеграцію тут описано за тим, що вона насправді робить, — разом із напрямком, власністю на дані та обмеженнями.