API
Приватного ендпоінта немає. Навіть для самого інтерфейсу.
У більшості продуктів два API: задокументований, який пропонують вам, і цікавий, яким користуються їхні власні екрани. Другий завжди кращий, і вас до нього ніколи не пускають. Тут він один, а інтерфейс — це його клієнт, як і все інше. Це обмеження для нас — і причина, з якої все, що ви хочете створити, можливо.
Скільки насправді коштує це правило
Це означає, що екрану часом доводиться чекати, поки API стане правильним, замість того, щоб обходити його заради одного зручного поля. День, коли екрану потрібне те, чого публічний API дати не може, — це день, коли API неправильний, і виправлення полягає в API.
Винагорода в тому, що три дуже різні клієнти майже нічого не коштують додатково. MCP-сервер — це клієнт. Плитка dash-b — це клієнт. Ваш власний скрипт — це клієнт. Жоден з них не є громадянином другого сорту, що обходити поверхню, створену для когось іншого, бо іншої поверхні, якій можна бути другим, просто немає.
Задокументований і перевірений
OpenAPI генерується на /docs, і кожен маршрут має тест, який є прикладом у документації. Документація, написана окремо від коду, розходиться з ним за місяць; документація, яка ламає збірку, коли вона неправильна, — ні.
Вхід
Ваш обліковий запис castomo через authorization code flow з PKCE — той самий обліковий запис, що й для dash-b та решти родини. Сторінка без власного сервера чудово виконує цей потік; саме для цього його й створили. Для роботи «машина-машина» — API-ключ у межах проєкту.
- 1Люди
/v1/contacts·/lists·/segments·/tags·/imports - 2Вміст
/v1/creatives— з валідацією, попереднім переглядом і рендером для кожної цілі - 3Автоматизація
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Ефір
/v1/campaigns— з аудиторією, матеріалізацією, розкладом і надсиланням як окремими кроками - 5Події на вході
/v1/events— події вашого власного застосунку як тригери - 6Доставка
/sender-identities·/domains·/apps·/webhooks - 7Числа
/v1/reports/*, а також/track/*на хості відстеження
OpenAPI на /docs/mcp в тому самому процесі
Конвенції
Той самий формат, що й у кожного іншого сервісу castomo
Це важливіше, ніж здається. Якщо ви вже викликаєте один із цих сервісів, ви вже знаєте, як цей відповідає, помиляється і розбиває на сторінки.
Єдиний конверт помилок
Кожна помилка має однакову форму, стабільний код і повідомлення, призначене для людини. Жоден маршрут не вигадує власний спосіб бути нещасним.
Пагінація курсором
Не зсувами. Список, який змінюється, поки ви його переглядаєте, не пропускає і не повторює рядки мовчки — чого пагінація зсувами робить тихо й постійно.
Ключі ідемпотентності
На кожному маршруті, що змінює дані. Повторіть запит, у якому не впевнені, що він дійшов, і отримайте ту саму відповідь, а не другого контакта, другу кампанію чи друге надсилання.
У межах проєкту
Токен адресує один тенант і один проєкт — обидва. Безпека на рівні рядків застосовується в самій базі даних, а не завдяки пам'яті додати умову.
Вебхуки на виході
Підписано, повторено з затримкою та доставлено щонайменше один раз — тож ваш endpoint теж має бути ідемпотентним. Події використовують той самий словник, що й звіти.
Видалення та експорт
Контакт можна експортувати або видалити через API, а видалення через власний внутрішній канал сімейства сягає кожного сусіднього сервісу, що зберігав копію.
Усе, що вміє інтерфейс, вміє і POST.
Події — найцікавіша частина
Усе інше на цій сторінці — інфраструктура, якої ви й очікували. POST /v1/events — це маршрут, який змінює призначення продукту.
Ваша програма вже знає те, чого не може побачити жоден маркетинговий інструмент: хто завершив onboarding, хто запросив колегу, хто досяг ліміту, хто експортував свої дані в неділю вдень. Надсилайте їх як події зі своїм токеном — і кожна стане тригером, умовою та сегментом.
Решта випливає з моделі контакту. Події додаються в кінець і ніколи не редагуються; це журнал, на якому тримається весь продукт. Воронка, що спрацьовує на подію, яку ви визначили, — це не інтеграція, а той самий механізм, що й у message_opened, лише з іншою назвою всередині.
- 1Ви надсилаєте її
POST /v1/events— назва, контакт, payload, ключ ідемпотентності. - 2Вона надходитьДодається до журналу контакту. Ніхто інший не мусить знати про її існування.
- 3Запускається воронкаБудь-яка воронка, у вході якої згадано цю подію, для будь-якого контакту, що відповідає її вхідним критеріям.
- 4Інші воронки розгалужуються на ній«Чи відбувалася ця подія за останні 14 днів» — звичайний предикат сегмента.
- iІ вона завершує запускиВузол цілі, що згадує ту саму подію, зупиняє послідовність у мить, коли людина робить цю дію.
Ваш словникВаш токен
Межі, про які варто знати до початку розробки
ClickSomo зберігає про вас три ідентифікатори — tenant, проєкт і користувача, як непрозорі id — і нічого більше. Ніякого пароля, профілю, картки чи рахунка. Ліміти плану надходять як числа: скільки контактів, скільки надсилань, скільки генерацій. Платіжна лексика не перетинає цю межу в жодному напрямку.
Ваші контакти належать вам. Ви — контролер даних; ми — обробник. Не існує шляху, яким інший продукт сімейства міг би читати чи змінювати ваш список контактів, і немає каналу ingestu для цього.
Якщо ви оцінюєте це серйозно: прочитайте /docs, перш ніж читати решту цього сайту. API — це чесний опис того, що робить продукт, і кожне твердження на цих сторінках відповідає маршруту чи типу вузла, які ви там знайдете. Коли змінюється схема, змінюються й ці сторінки.