API-ul
Nu există niciun endpoint privat. Nici măcar pentru interfață.
Majoritatea produselor au două API-uri: cel documentat, care vi se oferă, și cel interesant, pe care îl folosesc propriile lor ecrane. Al doilea este întotdeauna mai bun și nu vi se permite niciodată aproape de el. Aici există unul singur, iar interfața este un client al său ca orice altceva — ceea ce este o constrângere pentru noi și motivul pentru care tot ce doriți să construiți este posibil.
Ce costă efectiv regula aceasta
Înseamnă că un ecran trebuie uneori să aștepte ca API-ul să devină corect, în loc să îl ocolească pentru un singur câmp convenabil. Ziua în care un ecran are nevoie de ceva ce API-ul public nu îi poate oferi este ziua în care API-ul este greșit, iar soluția este API-ul.
Avantajul este că trei clienți foarte diferiți nu costă aproape nimic în plus. Serverul MCP este un client. O piesă dash-b este un client. Scriptul dumneavoastră propriu este un client. Niciunul nu este un cetățean de mâna a doua care ocolește o suprafață proiectată pentru altcineva, pentru că nu există altă suprafață după care să fie al doilea.
Documentat și exercitat
OpenAPI este generat la /docs, iar fiecare rută are un test care este exemplul din documentație. Documentația scrisă separat de cod devine depășită într-o lună; documentația care rupe build-ul când este greșită nu.
Autentificarea
Contul dumneavoastră castomo, prin fluxul de autorizare cu cod și PKCE — același cont pe care îl folosiți pentru dash-b și restul familiei. O pagină fără server propriu rulează acest flux perfect; este exact pentru ce a fost proiectat fluxul. Pentru lucrări mașină-la-mașină, o cheie API delimitată la proiect.
- 1Persoane
/v1/contacts·/lists·/segments·/tags·/imports - 2Conținut
/v1/creatives, cu validare, previzualizare și randare per țintă - 3Automatizare
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Difuzare
/v1/campaigns, cu audiență, materializare, programare și trimitere ca pași distincti - 5Evenimente primite
/v1/events— evenimentele propriei aplicații, ca declanșatoare - 6Livrare
/sender-identities·/domains·/apps·/webhooks - 7Cifre
/v1/reports/*și/track/*pe hostul de urmărire
OpenAPI la /docs/mcp pe același proces
Convenții
Același format ca orice alt serviciu castomo
Ceea ce contează mai mult decât pare. Dacă apelați deja unul dintre acestea, știți deja cum răspunde, eșuează și paginează acesta.
Un singur plic de eroare
Orice eșec are același format, un cod stabil și un mesaj destinat unei persoane. Nicio rută nu își inventează propriul mod de a fi nemulțumită.
Paginare cu cursor
Nu offset-uri. O listă care se schimbă în timp ce o parcurgeți nu sare și nu repetă rânduri pe furiș, așa cum paginația prin offset face constant și discret.
Chei de idempotență
Pe fiecare rută care modifică date. Repetați o cerere despre care nu sunteți sigur că a ajuns și primiți același răspuns, nu un al doilea contact, o a doua campanie sau o a doua trimitere.
Delimitat la nivel de proiect
Un token vizează un singur tenant și un singur proiect, simultan. Securitatea la nivel de rând este aplicată chiar în baza de date, nu prin faptul că cineva are grijă să adauge o clauză.
Webhook-uri de ieșire
Semnate, reîncercate cu backoff și livrate cel puțin o dată — deci și endpoint-ul dumneavoastră ar trebui să fie idempotent. Evenimentele sunt același vocabular pe care îl folosesc rapoartele.
Ștergere și export
Un contact poate fi exportat sau șters prin API, iar o ștergere ajunge la fiecare serviciu soră care deținea o copie, prin canalul intern propriu al familiei.
Tot ce poate face interfața poate face și un POST.
Evenimentele sunt partea interesantă
Tot restul acestei pagini este infrastructura la care v-ați aștepta. POST /v1/events este ruta care schimbă chiar scopul produsului.
Aplicația dumneavoastră cunoaște deja lucruri pe care niciun instrument de marketing nu le poate observa: cine a finalizat onboarding-ul, cine a invitat un coleg, cine a atins o limită, cine și-a exportat datele într-o duminică după-amiază. Publicați-le ca evenimente cu propriul dumneavoastră token, iar fiecare devine un declanșator, o condiție și un segment.
Restul decurge din modelul de contact. Evenimentele sunt adăugate, niciodată editate; ele sunt jurnalul de care atârnă întregul produs. O pâlnie declanșată de un eveniment definit de dumneavoastră nu este o integrare — este același mecanism pe care îl folosește message_opened, doar că cu alt nume în el.
- 1Îl trimiteți
POST /v1/events— un nume, un contact, un payload, o cheie de idempotență. - 2SoseșteAdăugat la jurnalul contactului. Nimic altceva nu trebuie să știe de existența lui.
- 3Începe o pâlnieOrice pâlnie a cărei intrare numește acel eveniment, pentru orice contact eligibil conform specificației de intrare a pâlniei.
- 4Alte pâlnii se ramifică pe el„A avut loc acest eveniment în ultimele 14 zile” este un predicat de segment obișnuit.
- iȘi pune capăt rulărilorUn nod de obiectiv care numește același eveniment oprește o secvență exact în momentul în care persoana face acel lucru.
Vocabularul dumneavoastrăToken-ul dumneavoastră
Limite pe care merită să le cunoașteți înainte să construiți
ClickSomo stochează trei identificatori despre dumneavoastră — un tenant, un proiect și un utilizator, sub formă de id-uri opace — și nimic altceva. Fără parolă, fără profil, fără card, fără factură. Limitele planului ajung sub formă de numere: câte contacte, câte trimiteri, câte generări. Vocabularul plăților nu trece de această linie în nicio direcție.
Contactele dumneavoastră vă aparțin. Dumneavoastră sunteți operatorul de date; noi suntem procesatorul. Nu există nicio rută prin care un alt produs din familie să poată citi sau scrie lista dumneavoastră de contacte, și niciun canal de ingest pe care să îl folosească.
Dacă evaluați acest produs în serios: citiți /docs înainte să mai citiți orice altceva de pe acest site. API-ul este descrierea onestă a ceea ce face produsul, iar fiecare afirmație de pe aceste pagini corespunde unei rute sau unui tip de nod pe care le puteți găsi acolo. Când se schimbă schema, se schimbă și aceste pagini.