A API
Não existe endpoint privado. Nem sequer para a interface.
A maioria dos produtos tem duas APIs: a documentada que te oferecem, e a interessante que os seus próprios ecrãs usam. A segunda é sempre melhor, e nunca te deixam chegar perto dela. Aqui existe uma, e a interface é um cliente dela como qualquer outra coisa — o que é uma restrição para nós, e a razão pela qual tudo o que queres construir é possível.
O que essa regra custa realmente
Significa que um ecrã ocasionalmente tem de esperar que a API esteja certa, em vez de a contornar para obter um campo conveniente. O dia em que um ecrã precisa de algo que a API pública não lhe pode dar é o dia em que a API está errada, e a correção é a API.
A vantagem é que três clientes muito diferentes custam quase nada extra. O servidor MCP é um cliente. Um tile do dash-b é um cliente. O teu próprio script é um cliente. Nenhum deles é um cidadão de segunda classe a contornar uma superfície desenhada para outra pessoa, porque não há outra superfície de que ser segundo.
Documentada, e exercitada
O OpenAPI é gerado em /docs e cada rota tem um teste que é o exemplo da documentação. Documentação escrita separadamente do código desalinha-se num mês; documentação que falha a build quando está errada, não.
Iniciar sessão
A tua conta castomo, através do fluxo de código de autorização com PKCE — a mesma conta que usas para o dash-b e o resto da família. Uma página sem servidor próprio executa esse fluxo perfeitamente bem; é para isso que o fluxo foi desenhado. Para trabalho máquina-a-máquina, uma chave de API com âmbito de projeto.
- 1Pessoas
/v1/contacts·/lists·/segments·/tags·/imports - 2Conteúdo
/v1/creatives, com validação, pré-visualização e renderização por destino - 3Automação
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Transmissão
/v1/campaigns, com audiência, materialização, agendamento e envio como passos distintos - 5Eventos a entrar
/v1/events— os eventos da tua própria aplicação, como gatilhos - 6Entrega
/sender-identities·/domains·/apps·/webhooks - 7Números
/v1/reports/*, e/track/*no host de rastreio
OpenAPI em /docs/mcp no mesmo processo
Convenções
A mesma forma de todos os outros serviços castomo
O que importa mais do que parece. Se já chamas um destes, já sabes como este responde, falha e pagina.
Um único envelope de erro
Toda falha tem a mesma forma: um código estável e uma mensagem pensada para uma pessoa. Nenhuma rota inventa a sua própria maneira de estar infeliz.
Paginação por cursor
Nada de offsets. Uma lista que muda enquanto a percorres não salta nem repete linhas em silêncio, o que a paginação por offset faz discreta e constantemente.
Chaves de idempotência
Em todas as rotas de mutação. Repete um pedido de que não tens a certeza de que chegou e obtém a mesma resposta, em vez de um segundo contacto, uma segunda campanha ou um segundo envio.
Limitado a um projeto
Um token endereça um tenant e um projeto, ambos. A segurança ao nível da linha é imposta pela própria base de dados, não por alguém se lembrar de acrescentar uma cláusula.
Webhooks de saída
Assinados, repetidos com backoff e entregues pelo menos uma vez — por isso o teu endpoint também deve ser idempotente. Os eventos usam o mesmo vocabulário dos relatórios.
Eliminação e exportação
Um contacto pode ser exportado ou eliminado através da API, e uma eliminação chega a todos os serviços irmãos que tinham uma cópia, pelo canal interno da própria família.
Tudo o que a interface consegue fazer, um POST consegue fazer.
Os eventos são a parte interessante
Todo o resto desta página é canalização que já esperavas. POST /v1/events é a rota que muda o propósito do produto.
A tua aplicação já sabe coisas que nenhuma ferramenta de marketing consegue observar: quem terminou o onboarding, quem convidou um colega, quem atingiu um limite, quem exportou os seus dados num domingo à tarde. Publica-os como eventos com o teu próprio token, e cada um torna-se um gatilho, uma condição e um segmento.
O resto decorre do modelo de contacto. Os eventos são acrescentados, nunca editados; são o registo de que todo o produto depende. Um funil desencadeado por um evento que tu definiste não é uma integração — é o mesmo mecanismo que o message_opened usa, com outro nome lá dentro.
- 1Tu publicas
POST /v1/events— um nome, um contacto, um payload, uma chave de idempotência. - 2ChegaAcrescentado ao registo do contacto. Nada mais precisa de saber que existe.
- 3Um funil começaQualquer funil cuja entrada mencione esse evento, para qualquer contacto elegível segundo a sua especificação de entrada.
- 4Outros funis ramificam com ele"Este evento aconteceu nos últimos 14 dias" é um predicado de segmento comum.
- iE termina execuçõesUm nó de objetivo que mencione o mesmo evento interrompe uma sequência no momento em que a pessoa faz a coisa.
O teu vocabulárioO teu token
Limites que vale a pena conhecer antes de construir
A ClickSomo guarda três identificadores sobre ti — um tenant, um projeto e um utilizador, como ids opacos — e nada mais. Sem password, sem perfil, sem cartão, sem fatura. Os limites do plano chegam como números: quantos contactos, quantos envios, quantas gerações. O vocabulário de pagamentos não atravessa essa linha em nenhuma direção.
Os teus contactos são teus. Tu és o responsável pelos dados; nós somos o processador. Não existe nenhuma rota pela qual outro produto da família possa ler ou escrever a tua lista de contactos, e nenhum canal de ingestão para um deles usar.
Se estás a avaliar isto a sério: lê /docs antes de leres mais alguma coisa deste site. A API é a descrição honesta do que o produto faz, e cada afirmação nestas páginas corresponde a uma rota ou a um tipo de nó que lá encontras. Quando o schema muda, estas páginas mudam.