A API
Non hai endpoint privado. Nin sequera para a interface.
A maioría dos produtos teñen dúas APIs: a documentada que se te ofrece e a interesante que usan as súas propias pantallas. A segunda sempre é mellor, e nunca te deixan achegarte a ela. Aquí só hai unha, e a interface é un cliente dela como calquera outra cousa — o cal é unha restrición para nós, e a razón pola que todo o que queres construír é posible.
O que custa realmente esa regra
Significa que unha pantalla ás veces ten que esperar a que a API estea ben, en vez de contornala para obter un campo cómodo. O día en que unha pantalla necesita algo que a API pública non pode darlle é o día en que a API está mal, e a solución é a API.
A recompensa é que tres clientes moi distintos non custan case nada extra. O servidor MCP é un cliente. Unha tesela de dash-b é un cliente. O teu propio script é un cliente. Ningún deles é un cidadán de segunda clase que contornea unha superficie deseñada para outra persoa, porque non hai outra superficie á que ser segundo.
Documentada e exercida
OpenAPI xérase en /docs e cada ruta ten unha proba que é o exemplo da documentación. A documentación que se escribe separada do código deriva nun mes; a documentación que fai fallar a compilación cando está mal, non.
Inicio de sesión
A túa conta de castomo, mediante o fluxo de código de autorización con PKCE — a mesma conta que usas para dash-b e o resto da familia. Unha páxina sen servidor propio executa ese fluxo perfectamente; é para o que foi deseñado. Para traballo de máquina a máquina, unha clave de API con ámbito de proxecto.
- 1Persoas
/v1/contacts·/lists·/segments·/tags·/imports - 2Contido
/v1/creatives, con validación, vista previa e renderizado por destino - 3Automatización
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Emisión
/v1/campaigns, con audiencia, materialización, programación e envío como pasos distintos - 5Eventos de entrada
/v1/events— os eventos da túa propia aplicación, como disparadores - 6Entrega
/sender-identities·/domains·/apps·/webhooks - 7Números
/v1/reports/*, e/track/*no host de seguimento
OpenAPI en /docs/mcp no mesmo proceso
Convencións
A mesma forma que calquera outro servizo de castomo
O que importa máis do que parece. Se xa chamas a un destes, xa sabes como este responde, falla e pagina.
Un só sobre de erros
Cada fallo ten a mesma forma, un código estable e unha mensaxe pensada para unha persoa. Ningunha ruta inventa o seu propio xeito de estar descontenta.
Paginación por cursor
Non desprazamentos. Unha lista que cambia mentres a percorres non salta nin repite filos en silencio, o que a paginación por desprazamento fai caladamente e constantemente.
Chaves de idempotencia
En cada ruta de modificación. Repite unha solicitude da que non estás seguro de que chegase e obterás a mesma resposta en vez dun segundo contacto, unha segunda campaña ou un segundo envío.
Con ámbito de proxecto
Un token dirixe un inquilino e un proxecto, os dous. A seguranza a nivel de fila aplícase na propia base de datos, non dependendo de lembrar de engadir unha cláusula.
Webhooks de saída
Asinados, reintentados con retroceso e entregados polo menos unha vez — así que o teu endpoint debería ser idempotente tamén. Os eventos usan o mesmo vocabulario que os informes.
Supresión e exportación
Un contacto pódese exportar ou eliminar a través da API, e unha supresión chega a todos os servizos irmáns que tiñan unha copia a través da canle interna da propia familia.
Todo o que pode facer a interface, un POST pode facelo.
Os eventos son a parte interesante
Todo o demais desta páxina é fontanería que esperarías. POST /v1/events é a ruta que cambia para que serve o produto.
A túa aplicación xa sabe cousas que ningunha ferramenta de marketing pode observar: quen rematou a incorporación, quen convidou a un colega, quen alcanzou un límite, quen exportou os seus datos un domingo pola tarde. Publícaos como eventos co teu propio token, e cada un convértese nun disparador, nunha condición e nun segmento.
O resto dedúcese do modelo de contacto. Os eventos engádense, nunca se editan; son o rexistro do que pendura todo o produto. Un funil que se activa cun evento que ti definiches non é unha integración — é o mesmo mecanismo que usa message_opened, con outro nome dentro.
- 1Ti publícao
POST /v1/events— un nome, un contacto, unha carga, unha chave de idempotencia. - 2Chega ao seu destinoEngádese ao rexistro do contacto. Ninguén máis precisa saber que existe.
- 3Comeza un funilCalquera funil cuxa entrada nomea ese evento, para calquera contacto elixible segundo a súa especificación de entrada.
- 4Outros funis ramifícanse por el"Produciuse este evento nos últimos 14 días" é un predicado de segmento ordinario.
- iE remata execuciónsUn nodo de obxectivo que nomea o mesmo evento detén unha secuencia no momento en que a persoa fai a cousa.
O teu vocabularioO teu token
Límites que convén coñecer antes de construír
ClickSomo almacena tres identificadores sobre ti — un inquilino, un proxecto e un usuario, como ids opacos — e nada máis. Sen contrasinal, sen perfil, sen tarxeta, sen factura. Os límites do plan chegan como números: cantos contactos, cantos envíos, cantas xeracións. O vocabulario de pagos non cruza esa liña en ningunha dirección.
Os teus contactos son teus. Ti es o responsable do tratamento; nós somos o encargado. Non existe ningunha ruta pola que outro produto da familia poida ler ou escribir a túa lista de contactos, nin ningunha canle de inxesta para que a use.
Se estás a avaliar isto en serio: le /docs antes de ler máis desta web. A API é a descrición honesta do que fai o produto, e cada afirmación destas páxinas corresponde a unha ruta ou a un tipo de nodo que podes atopar alí. Cando cambia o esquema, cambian estas páxinas.