Desenvolvedores
O protocolo, a API e o MCP do People
Toda fonte fala um protocolo só, o Standard Webhooks com o prefixo x-ccm. O seu agente lê e propõe pelo servidor MCP, com OAuth 2.1. Tudo em texto para o agente, no llms.txt do produto.
Início rápido
Crie uma fonte no painel, guarde o endereço e o segredo, e assine cada entrega. Para o agente, o caminho inteiro está num arquivo de texto.
Entrada de eventos
Cada fonte tem um endereço POST https://people.worker.mycustomers.click/events/:id e um segredo whsec_ mostrado uma vez. Toda entrega leva x-ccm-id (o mesmo id de novo é reenvio e não duplica), x-ccm-timestamp (segundos Unix, dentro de 5 minutos) e x-ccm-signature no formato v1,<base64 do HMAC-SHA256 de "id.timestamp.corpo">.
O corpo é { type, timestamp, data }, com a pessoa em data.person. O limite é de 256 KB por entrega. Trocar o segredo mantém o anterior valendo por 24 horas. O tipo é o vocabulário de quem envia; a tradução para os tipos do People fica na fonte.
Importação CSV
Uma fonte do tipo importação recebe CSV pelo painel. Os cabeçalhos são lidos em português ou em inglês (email, nome, telefone, empresa, dominio, utm_source, utm_medium, utm_campaign, created_at). Cada linha vira um person.touched; o id da linha é o e-mail ou o telefone, então importar de novo não duplica.
Servidor MCP
Streamable HTTP em POST https://people.worker.mycustomers.click/mcp, com OAuth 2.1 emitido pelo Auth. O token é validado por audiência (RFC 8707): um token emitido para outro servidor é recusado aqui. Um GET responde 405.
Leitura (auth:read): people_list_people, people_get_person e people_get_timeline. Escrita (auth:write): people_add_note e people_propose_action, que só propõem. Nenhuma ferramenta envia nada a uma pessoa, e a conta nunca é argumento: vem do token.
Autenticação
O painel e o MCP usam o JWT do Auth de uma pessoa, e a conta é o sub do token: "não existe" responde igual a "não é seu". Não há chave de API, nem de leitura. As fontes não fazem login: a prova delas é a assinatura.
Saída
Uma mensagem aprovada sai por e-mail pelo Messages, com a chave e o domínio verificado da sua conta, ou para um destino seu, assinado no mesmo protocolo x-ccm. Ao cadastrar um destino, um message.test assinado sai para conferir o endereço; três falhas seguidas pausam o destino, e as mensagens esperam com o motivo.
Erros
Toda resposta de erro é um objeto { "error": { "code", "message" } } com o status HTTP certo, nunca 200. O code é estável (UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, PAYLOAD_TOO_LARGE e outros); a message, em português, diz o que corrigir.
O agente prepara. Você aprova o que sai.
O prompt da página Comece manda o seu agente ler a documentação inteira do People antes de qualquer pedido.