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