API
Закрытого эндпоинта нет. Даже для интерфейса.
У большинства продуктов два API: документированный, который вам предлагают, и «интересный», которым пользуются их собственные экраны. Второй всегда лучше, и вам к нему никогда не подпускают. Здесь он один, а интерфейс — его клиент, как и всё остальное. Это ограничение для нас — и причина, по которой всё, что вы хотите построить, возможно.
Чем это правило обходится на самом деле
Оно означает, что экрану иногда приходится ждать, пока API станет правильным, вместо того чтобы обходить его ради одного удобного поля. День, когда экрану нужно то, что публичный API дать не может, — это день, когда API неправильный, и исправлять нужно API.
Выгода в том, что три совершенно разных клиента почти ничего не стоят дополнительно. MCP-сервер — клиент. Плитка dash-b — клиент. Ваш собственный скрипт — клиент. Ни один из них не гражданин второго сорта, обходящий поверхность, созданную для кого-то другого, потому что другой поверхности, которой можно быть вторым, нет.
Документирован и проверяется
OpenAPI генерируется в /docs, и у каждого маршрута есть тест, который является примером из документации. Документация, написанная отдельно от кода, расходится с ним в течение месяца; документация, которая ломает сборку, когда она неверна, — нет.
Вход в систему
Ваш аккаунт castomo через authorization code flow с PKCE — тот же аккаунт, что вы используете для dash-b и остальных продуктов семейства. Страница без собственного сервера прекрасно выполняет этот flow; именно для этого он и создан. Для работы машина-к-машине — 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
Это важнее, чем кажется. Если вы уже вызываете один из этих сервисов, вы уже знаете, как этот отвечает, падает и разбивает на страницы.
Один формат ошибок
Каждый сбой имеет одинаковую форму: стабильный код и сообщение, предназначенное для человека. Ни один маршрут не изобретает собственный способ быть недовольным.
Курсорная пагинация
Не смещения. Список, который меняется, пока вы его проходите, не молча пропускает и не повторяет строки — что пагинация по смещениям делает тихо и постоянно.
Ключи идемпотентности
На каждом изменяющем маршруте. Повторите запрос, в доставке которого не уверены, и получите тот же ответ, а не второй контакт, вторую кампанию или вторую отправку.
Ограничение проектом
Токен адресует один тенант и один проект, оба сразу. Безопасность на уровне строк обеспечивается самой базой данных, а не памятью добавить условие.
Исходящие вебхуки
Подписанные, с повторными попытками и backoff, доставляются как минимум один раз — так что ваш эндпоинт тоже должен быть идемпотентным. События используют тот же словарь, что и отчёты.
Стирание и экспорт
Контакт можно экспортировать или стереть через API, а стирание доходит до каждого соседнего сервиса, хранившего копию, по внутреннему каналу семейства продуктов.
Всё, что умеет интерфейс, умеет и POST-запрос.
События — самая интересная часть
Всё остальное на этой странице — обычная инфраструктура, которой вы и ожидаете. POST /v1/events — это маршрут, который меняет назначение продукта.
Ваше приложение уже знает то, чего не может увидеть ни один маркетинговый инструмент: кто завершил онбординг, кто пригласил коллегу, кто упёрся в лимит, кто экспортировал свои данные в воскресенье днём. Отправляйте их как события со своим токеном, и каждое станет триггером, условием и сегментом.
Всё остальное следует из модели контакта. События только добавляются, никогда не редактируются; это журнал, на котором держится весь продукт. Воронка, срабатывающая на определённое вами событие, — это не интеграция, а тот же механизм, что использует message_opened, только с другим именем внутри.
- 1Вы отправляете его
POST /v1/events— имя, контакт, данные, ключ идемпотентности. - 2Оно поступаетДобавляется в журнал контакта. Больше никому знать о его существовании не нужно.
- 3Запускается воронкаЛюбая воронка, вход которой называет это событие, — для любого контакта, подходящего по её условиям входа.
- 4Другие воронки ветвятся на нём«Происходило ли это событие за последние 14 дней» — обычный предикат сегмента.
- iИ оно завершает цепочкиЦелевой узел, называющий то же событие, останавливает последовательность в тот момент, когда человек совершает это действие.
Ваш словарьВаш токен
Границы, о которых стоит знать до начала работы
ClickSomo хранит о вас три идентификатора — арендатора, проект и пользователя — в виде непрозрачных идентификаторов, и ничего больше. Ни пароля, ни профиля, ни карты, ни счёта. Лимиты тарифа приходят числами: сколько контактов, сколько отправок, сколько генераций. Платёжная терминология не пересекает эту границу ни в одну из сторон.
Ваши контакты принадлежат вам. Вы — контролёр данных; мы — обработчик. Не существует пути, по которому другой продукт семейства может читать или изменять ваш список контактов, и нет канала приёма данных для этого.
Если вы всерьёз это оцениваете: прочтите /docs, прежде чем читать дальше что-либо на этом сайте. API — честное описание того, что делает продукт, и каждое утверждение на этих страницах соответствует маршруту или типу узла, которые вы там найдёте. Когда схема меняется, меняются и эти страницы.