API
Прыватнага канцэпта няма. Нават для інтэрфейсу.
У большасці прадуктаў два API: дакументаваны, які вам прапануюць, і цікавы, якім карыстаюцца іх уласныя экраны. Другі заўсёды лепшы, і вам ніколі не даюць да яго доступу. Тут існуе толькі адзін, а інтэрфейс — яго кліент, як і ўсё астатняе. Гэта абмежаванне для нас і прычына, па якой усё, што вы хочаце збудаваць, магчыма.
Што гэтае правіла каштуе на самой справе
Гэта значыць, што экран часам мусіць чакаць, пакаты API будзе правільным, а не абыходзіць яго за адным зручным полем. Дзень, калі экрану патрабуецца нешта, што публічны API даць не можа, — гэта дзень, калі API няправільны, і выпраўленне — гэта API.
Перавага ў тым, што тры розныя кліенты каштуюць амаль нічога дадаткова. Сервер MCP — кліент. Пазіцыя dash-b — кліент. Ваш уласны скрыпт — кліент. Ніводзін з іх не з'яўляецца грамадзянінам другога сорту, які абыходзіць паверхню, спраектаваную для кагосьці іншага, бо іншай паверхні няма.
Дакументаваны і выпрабаваны
OpenAPI генеруецца на /docs, і для кожнага маршруту ёсць тэст, які ёсць прыкладам у дакументацыі. Дакументацыя, напісаная асобна ад кода, расходзіцца з ім за месяц; дакументацыя, якая ламае зборку пры памылцы, — не.
Уваход
Ваш уліковы запіс castomo праз аўтарызацыйны паток з кодам і 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
Гэта важней, чым здаецца. Калі вы ўжо выклікаеце адзін з іх, вы ўжо ведаеце, як гэты адказвае, памыляецца і разбівае на старонкі.
Адзін канверт памылак
Кожная памылка мае аднолькавы выгляд, стабільны код і паведамленне, прызначанае для чалавека. Ніводзін маршрут не прыдумляе свой спосаб быць незадаволеным.
Пагінацыя курсорам
Не зрушэннямі. Спіс, які змяняецца, пакуль вы яго праглядаеце, не прапускае і не паўторна паказвае радкі, што пагінацыя зрушэннямі робіць ціха і пастаянна.
Ключы ідэмпатэнтнасці
На кожным маршруце змены. Паўтарыце запыт, у якім не ўпэўнены, што ён дайшоў, і атрымаеце той самы адказ, а не другі кантакт, другую кампанію ці другую адпраўку.
Абмежавана праектам
Токен адрасуе аднаго арэндніка і адзін праект — абодва. Бяспека на ўзроўні радкоў забяспечваецца самай базай даных, а не памяццю дадаць умову.
Вэбхукі выходзяць
Падпісаныя, з паўторамі з затрымкай і дастаўкай прынамсі адзін раз — таму ваш канцэпт таксама павінен быць ідэмпатэнтным. Падзеі маюць той самы слоўнік, што і справаздачы.
Выдаленне і экспарт
Кантакт можна экспартаваць або выдаліць праз API, і выдаленне дасягае кожнага сястрынскага сэрвісу, які захоўваў копію праз уласны ўнутраны канал сям'і.
Усё, што ўмее інтэрфейс, можа зрабіць POST.
Падзеі — самая цікавая частка
Усё астатняе на гэтай старонцы — тэхнічная начынка, якую вы і чакалі. POST /v1/events — гэта маршрут, які змяняе прызначэнне прадукта.
Ваша праграма ўжо ведае тое, што не можа назіраць ні адзін маркетнгавы інструмент: хто завяршыў увод у сістэму, хто запрасіў калегу, хто сутыкнуўся з лімітам, хто экспартаваў свае даныя ў нядзелю пасля абеду. Адпраўляйце гэта як падзеі са сваім токенам, і кожная з іх стане трыгерам, умовай і сегментам.
Астатняе вынікае з мадэлі кантактаў. Падзеі дадаюцца ў канец і ніколі не рэдагуюцца; гэта журнал, на якім трымаецца ўвесь прадукт. Варонка, якая спрацоўвае на падзеі, якую вы вызначылі, — гэта не інтэграцыя; гэта той жа механізм, што выкарыстоўвае message_opened
- 1Вы адпраўляеце яе
POST /v1/events— назва, кантакт, карысная нагрузка, ключ ідэмпатэнтнасці. - 2Яна трапляе ў сістэмуДадаецца ў канец журналу кантакта. Больш ніхто не павінен ведаць пра яе існаванне.
- 3Варонка стартуеЛюба варонка, чыя ўваходная кропка называе гэтую падзею — для любога кантакта, які адпавядае яе правілам уваходу.
- 4Іншыя варонкі галіняцца па ёй"Ці адбылася гэтая падзея за апошнія 14 дзён" — звычайны прэдыкат сегмента.
- іІ яна завяршае прагоныВузел мэты, які называе тую ж падзею, спыняе паслядоўнасць у той момант, калі чалавек робіць патрэбнае дзеянне.
Ваш слоўнікВаш токен
Межы, пра якія варта ведаць да пачатку працы
ClickSomo захоўвае пра вас тры ідэнтыфікатары — арандатара, праект і карыстальніка — у выглядзе непразрыстых ідэнтыфікатараў, і нічога больш. Ні пароля, ні профілю, ні карты, ні рахунка. Ліміты тарифнага плана прыходзяць як лікі: колькі кантактаў, колькі рассылак, колькі генерацый. Плацёжная тэрміналогія не перасякае гэтую мяжу ні ў адзін бок.
Вашы кантакты належаць вам. Вы з'яўляецеся кантралёрам даных; мы — апрацоўшчык. Не існуе маршруту, па якім іншы прадукт сям'і мог бы чытаць або змяняць ваш спіс кантактаў, і няма канала прёму для такога доступу.
Калі вы сур'ёзна гэта ацэньваеце: прачытайце /docs, перш чым чытаць што-небудзь яшчэ на гэтым сайце. API — гэта сумленнае апісанне таго, што робіць прадукт, і кажды выказ на гэтых старонках адпавядае маршруту або тыпу вузла, якія вы там знойдзеце. Калі схема змяняецца, змяняюцца і гэтыя старонкі.