API
Nie ma prywatnego endpointu.Nawet dla interfejsu.
Większość produktów ma dwa API: to udokumentowane, które Ci oferują, i to ciekawe, którego używają ich własne ekrany. Drugie jest zawsze lepsze i nigdy nie masz do niego dostępu. Tutaj jest jedno, a interfejs jest jego klientem jak wszystko inne — co jest ograniczeniem dla nas i powodem, dla którego wszystko, co chcesz zbudować, jest możliwe.
Ile ta zasada naprawdę kosztuje.
Tyle, że ekran musi czasem poczekać, aż API będzie właściwe, zamiast sięgnąć obok niego po jedno wygodne pole. Dzień, w którym ekranowi brakuje czegoś, czego publiczne API nie umie dać, jest dniem, w którym to API jest złe — i poprawiamy API.
Zysk jest taki, że trzej bardzo różni klienci kosztują niemal nic więcej. Serwer MCP jest klientem. Kafelek w dash-b jest klientem. Twój własny skrypt jest klientem. Żaden z nich nie jest obywatelem drugiej kategorii obchodzącym powierzchnię zaprojektowaną dla kogoś innego, bo nie ma innej powierzchni, wobec której mógłby być drugi.
Udokumentowane i przetestowane
OpenAPI generuje się pod /docs, a każda trasa ma test, który jest przykładem w dokumentacji. Dokumentacja pisana osobno od kodu rozjeżdża się w miesiąc; dokumentacja, która wywala build, gdy jest błędna, nie.
Logowanie
Twoje konto castomo, przepływem authorization code z PKCE — to samo konto, którego używasz w dash-b i reszcie rodziny. Strona bez własnego serwera obsługuje ten przepływ bez trudu; właśnie do tego został zaprojektowany. Do pracy maszyna–maszyna służy klucz API ograniczony do projektu.
- 1Ludzie
/v1/contacts·/lists·/segments·/tags·/imports - 2Treści
/v1/creatives, z walidacją, podglądem i renderowaniem per postać - 3Automatyzacja
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Wysyłka masowa
/v1/campaigns, z odbiorcami, materializacją, harmonogramem i wysyłką jako osobnymi krokami - 5Zdarzenia na wejściu
/v1/events— zdarzenia Twojej aplikacji jako wyzwalacze - 6Doręczanie
/sender-identities·/domains·/apps·/webhooks - 7Liczby
/v1/reports/*oraz/track/*na hoście śledzącym
OpenAPI pod /docs/mcp w tym samym procesie
Konwencje
Ten sam kształt co każda inna usługa castomo.
Co znaczy więcej, niż brzmi. Jeśli wołasz już którąś z nich, wiesz już, jak ta odpowiada, jak zawodzi i jak stronicuje.
Jedna koperta błędu
Każda porażka ma ten sam kształt, stabilny kod i komunikat pisany dla człowieka. Żadna trasa nie wymyśla własnego sposobu bycia niezadowoloną.
Paginacja kursorowa
Nie offsety. Lista, która zmienia się w trakcie przechodzenia, nie pomija po cichu wierszy ani ich nie powtarza, a paginacja po offsecie robi to nieustannie i bezgłośnie.
Klucze idempotencji
Na każdej trasie zmieniającej dane. Ponów żądanie, którego nie jesteś pewien, i dostaniesz tę samą odpowiedź, a nie drugi kontakt, drugą kampanię ani drugą wysyłkę.
Zakres projektu
Token adresuje jednocześnie jednego najemcę i jeden projekt. Bezpieczeństwo na poziomie wierszy jest egzekwowane w samej bazie, a nie przez pamiętanie o dopisaniu warunku.
Webhooki na zewnątrz
Podpisane, ponawiane z wycofaniem i dostarczane co najmniej raz — więc Twój endpoint też powinien być idempotentny. Zdarzenia są tym samym słownikiem, którego używają raporty.
Usunięcie i eksport
Kontakt można wyeksportować albo usunąć przez API, a usunięcie dociera do każdej siostrzanej usługi, która miała kopię, wewnętrznym kanałem rodziny.
Wszystko, co potrafi interfejs,
potrafi POST.
Zdarzenia to najciekawsza część.
Wszystko inne na tej stronie to hydraulika, której byś się spodziewał. POST /v1/events to trasa, która zmienia to, do czego ten produkt służy.
Twoja aplikacja już wie rzeczy, których żadne narzędzie marketingowe nie zaobserwuje: kto skończył onboarding, kto zaprosił kolegę, kto uderzył w limit, kto wyeksportował swoje dane w niedzielne popołudnie. Wyślij je jako zdarzenia własnym tokenem, a każde stanie się wyzwalaczem, warunkiem i segmentem.
Reszta wynika z modelu kontaktu. Zdarzenia są dopisywane, nigdy edytowane; to dziennik, na którym wisi cały produkt. Lejek uruchamiany Twoim zdarzeniem to nie integracja — to ten sam mechanizm, którego używa message_opened, tylko z inną nazwą w środku.
- 1Wysyłasz je
POST /v1/events— nazwa, kontakt, ładunek, klucz idempotencji. - 2LądujeDopisane do dziennika kontaktu. Nic innego nie musi wiedzieć, że istnieje.
- 3Startuje lejekKażdy lejek, którego wejście wskazuje to zdarzenie, dla każdego kontaktu kwalifikowanego przez specyfikację wejścia.
- 4Inne lejki się na nim rozgałęziają„Czy to zdarzenie było w ostatnich 14 dniach” to zwykły predykat segmentu.
- iI kończy przebiegiWęzeł celu wskazujący to samo zdarzenie zatrzymuje sekwencję w chwili, gdy człowiek zrobi swoje.
Twoje słownictwoTwój token
Granice,
które warto znać przed budowaniem.
ClickSomo przechowuje o Tobie trzy identyfikatory — najemcę, projekt i użytkownika, jako nieprzezroczyste ids — i nic więcej. Bez hasła, profilu, karty i faktury. Limity planu przychodzą jako liczby: ile kontaktów, ile wysyłek, ile generowań. Słownictwo płatności nie przekracza tej granicy w żadną stronę.
Twoje kontakty są Twoje. Ty jesteś administratorem danych, my podmiotem przetwarzającym. Nie ma trasy, którą inny produkt rodziny mógłby czytać albo zapisywać Twoją listę, i nie ma kanału wejścia, z którego mógłby skorzystać.
Jeśli oceniasz to na poważnie: przeczytaj /docs, zanim przeczytasz więcej tej strony. API jest uczciwym opisem tego, co produkt robi, a każde twierdzenie na tych stronach odpowiada trasie albo rodzajowi węzła, który tam znajdziesz. Gdy zmienia się schemat, zmieniają się te strony.
Napisz, co dziś wysyłasz i do ilu osób.
Pokażemy, jak to wygląda tutaj — zwykle z narysowanym lejkiem, bo to szybsze niż akapit o nim.
Otwórz ClickSomo Porozmawiaj z człowiekiem