L'API
No hi ha cap endpoint privat. Ni tan sols per a la interfície.
La majoria de productes tenen dues API: la documentada que t'ofereixen, i la interessant que fan servir les seves pròpies pantalles. La segona sempre és millor, i mai no t'hi deixen accedir. Aquí només n'hi ha una, i la interfície n'és un client com qualsevol altra cosa — cosa que és una restricció per a nosaltres, i la raó per la qual tot el que vols construir és possible.
El que aquesta regla costa realment
Significa que una pantalla de tant en tant ha d'esperar que l'API sigui correcta, en lloc d'eludir-la per obtenir un camp convenient. El dia que una pantalla necessiti alguna cosa que l'API pública no pot donar-li és el dia que l'API és errònia, i la solució és l'API.
La recompensa és que tres clients molt diferents no costen gairebé res addicional. El servidor MCP és un client. Una peça de dash-b és un client. El teu propi script és un client. Cap d'ells és un ciutadà de segona classe que treballa al voltant d'una superfície dissenyada per a algú altre, perquè no hi ha cap altra superfície per ser-hi segon.
Documentada, i exercitada
L'OpenAPI es genera a /docs i cada ruta té una prova que és l'exemple de la documentació. La documentació escrita separadament del codi divergeix en un mes; la documentació que fa fallar la compilació quan és errònia, no.
Inici de sessió
El teu compte de castomo, mitjançant el flux de codi d'autorització amb PKCE — el mateix compte que fas servir per a dash-b i la resta de la família. Una pàgina sense servidor propi executa aquest flux perfectament; és per això que es va dissenyar el flux. Per a treball de màquina a màquina, una clau d'API amb àmbit de projecte.
- 1Persones
/v1/contacts·/lists·/segments·/tags·/imports - 2Contingut
/v1/creatives, amb validació, previsualització i render per objectiu - 3Automatització
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Emissió
/v1/campaigns, amb audiència, materialització, programació i enviament com a passos diferenciats - 5Esdeveniments d'entrada
/v1/events— els esdeveniments de la teva pròpia aplicació, com a activadors - 6Lliurament
/sender-identities·/domains·/apps·/webhooks - 7Xifres
/v1/reports/*, i/track/*a l'amfitrió de seguiment
OpenAPI a /docs/mcp al mateix procés
Convencions
La mateixa forma que qualsevol altre servei de castomo
Que importa més del que sembla. Si ja crides un d'aquests, ja saps com aquest respon, falla i pagina.
Un únic sobre d'errors
Cada fallada té la mateixa forma, un codi estable i un missatge pensat per a una persona. Cap ruta s'inventa la seva pròpia manera de estar descontenta.
Paginació per cursor
No offsets. Una llista que canvia mentre la recorres no salta ni repeteix files silenciosament, cosa que la paginació per offset fa constantment i sense dir res.
Claus d'idempotència
A cada ruta de mutació. Torna a provar una petició de la qual no estàs segur que ha arribat i obtén la mateixa resposta en lloc d'un segon contacte, una segona campanya o un segon enviament.
Amb àmbit de projecte
Un token adreça un inquilí i un projecte, tots dos. La seguretat a nivell de fila s'aplica a la pròpia base de dades, no depèn de recordar afegir una clàusula.
Webhooks de sortida
Signats, reintentats amb backoff i lliurats com a mínim una vegada — així que el teu endpoint també hauria de ser idempotent. Els esdeveniments fan servir el mateix vocabulari que els informes.
Supressió i exportació
Un contacte es pot exportar o suprimir mitjançant l'API, i una supressió arriba a tots els serveis germans que en tinguin una còpia a través del carril intern propi de la família.
Tot el que pot fer la interfície, un POST ho pot fer.
Els esdeveniments són la part interessant
Tot el que hi ha en aquesta pàgina és fontaneria que t'esperaries. POST /v1/events és la ruta que canvia per a què serveix el producte.
La teva aplicació ja sap coses que cap eina de màrqueting pot observar: qui ha acabat l'onboarding, qui ha convidat un company, qui ha arribat a un límit, qui ha exportat les seves dades un diumenge a la tarda. Publica-les com a esdeveniments amb el teu propi token, i cadascun es converteix en un trigger, una condició i un segment.
La resta se segueix del model de contacte. Els esdeveniments s'afegeixen, mai no s'editen; són el registre del qual penja tot el producte. Un embut que es dispara amb un esdeveniment que has definit no és una integració — és el mateix mecanisme que fa servir message_opened, amb un nom diferent dins.
- 1Tu el publiques
POST /v1/events— un nom, un contacte, un payload, una clau d'idempotència. - 2ArribaS'afegeix al registre del contacte. Ningú més necessita saber que existeix.
- 3Comença un embutQualsevol embut l'entrada del qual anomeni aquest esdeveniment, per a qualsevol contacte elegible segons la seva especificació d'entrada.
- 4Altres embuts s'hi ramifiquen"Ha passat aquest esdeveniment en els últims 14 dies" és un predicat de segment ordinari.
- iI atura execucionsUn node d'objectiu que anomeni el mateix esdeveniment atura una seqüència en el moment en què la persona fa la cosa.
El teu vocabulariEl teu token
Límits que val la pena conèixer abans de construir
ClickSomo emmagatzema tres identificadors sobre tu — un inquilí, un projecte i un usuari, com a ids opacs — i res més. Cap contrasenya, cap perfil, cap targeta, cap factura. Els límits del pla arriben com a números: quants contactes, quants enviaments, quantes generacions. El vocabulari de pagaments no creua aquesta línia en cap direcció.
Els teus contactes són teus. Tu ets el responsable del tractament; nosaltres som l'encarregat. No hi ha cap ruta per la qual un altre producte de la família pugui llegir o escriure la teva llista de contactes, i no hi ha cap carril d'ingestió que pugui fer servir.
Si estàs avaluant això seriosament: llegeix /docs abans de llegir res més d'aquest lloc web. L'API és la descripció honesta del que fa el producte, i cada afirmació d'aquestes pàgines es correspon amb una ruta o un tipus de node que hi pots trobar. Quan l'esquema canvia, aquestes pàgines canvien.