Zapier
Приложение claritos для Zapier: триггеры для каждого события, действия для каждой конечной точки записи, поиск по каждому списку — всё сгенерировано из спецификации.
Что это за приложение
Тонкий адаптер (Zapier Platform CLI) поверх публичного API. В приложении нет предметной логики: триггеры — это подписки на вебхуки, действия и поиск вызывают HTTP-точки. Код лежит в основном репозитории в integrations/zapier; предметные части (generated/) генерируются из OpenAPI-спецификации и каталога событий и автоматически следуют за каждой версией API.
Подключение
При первом Zap Zapier запрашивает API-ключ claritos (capi_…, настройки организации → API) и среду (production или staging). Zapier проверяет ключ через GET /me и показывает имя организации как имя подключения. Scopes ключа определяют, какие триггеры и действия работают — недостающие scopes видны в истории Zap как 403 insufficient-scope.
Триггеры (REST hooks)
По одному триггеру на тип события («New Lead», «Invoice Paid», «Signature Request Completed» …). При включении Zap Zapier создаёт подписку именно на этот тип через POST /webhooks (видна во вкладке организации «API» → Webhooks); при выключении подписка удаляется. Каждая доставка проверяется по секрету адреса (подпись Standard Webhooks). «Load sample» берёт реальные недавние события через /webhooks/events/{type}/recent и при их отсутствии — документированный пример.
POST /api/v1/webhooks
{ "url": "https://hooks.zapier.com/hooks/standard/…", "eventTypes": ["leads.lead.created"], "description": "Zapier — New Lead" }
201 { "id": "wh_…", "secret": "whsec_…", … } ← Zapier merkt sich id + secret (performSubscribe)Действия и поиск
Действия соответствуют конечным точкам записи (создать контакт, выставить счёт, отправить SMS, запросить подпись …); поля берутся из схемы тела, вложенные поля (позиции, значения) вводятся как JSON. Поиск соответствует спискам с поисковым запросом и фильтрами и возвращает первую страницу. Точки клиентских данных (clients.*) и управление вебхуками намеренно не включены как действия. Ошибки приходят как Problem Details (RFC 9457) с заголовком, деталями и ошибками полей; 429 сообщается как throttle Zapier.
Генерация и версии
pnpm api:openapi в основном репозитории записывает спецификацию, каталог событий (docs/api/events.v1.json) и сгенерированные файлы платформ; pnpm api:check требует, чтобы всё было закоммичено. Версия приложения равна версии спецификации. Тесты (npm test) проверяют структуру и проверку подписи без сети; zapier validate проверяет схему.
pnpm api:openapi # Spec + Ereigniskatalog + generierte Plattform-Dateien
cd integrations/zapier && npm install && npm test
npx zapier validate && npx zapier push # oder Tag zapier-v<version>Для операторов: публикация
Один раз: аккаунт разработчика Zapier, zapier login, zapier register «claritos» (id приложения → секрет ZAPIER_APP_ID), deploy key → секрет ZAPIER_DEPLOY_KEY. Далее workflow publish-zapier публикует при каждом теге zapier-v<version> (validate + push). Для публичного размещения Zapier проводит проверку; до этого приложение доступно по пригласительной ссылке.