API & integrações

Base URL: o mesmo domínio da aplicação. Todos os recursos estão disponíveis gratuitamente. Envie Authorization: Bearer SUA_CHAVE. Todos os recursos são limitados ao workspace da chave.

Gerar e usar seu token

1. Entre na plataforma e abra API → Gerar chave.
2. Dê um nome à integração e copie o token. Os novos tokens ficam criptografados e podem ser selecionados novamente no modal de integração das mensagens iniciais, após entrar na conta. Tokens antigos sem valor recuperável continuam válidos, mas não podem ser preenchidos automaticamente.
3. Envie o token no cabeçalho Authorization: Bearer. Para invalidá-lo, use Revogar na mesma tela.

As chaves não têm expiração automática. Uma chave revogada ou de uma conta bloqueada retorna 401. A chave tem acesso aos recursos do seu workspace e pode gerenciar outras chaves dessa conta; não a exponha em páginas públicas. Se perder o token, gere outro.

curl https://umbotao.com.br/api/projects   -H "Authorization: Bearer SEU_TOKEN"

A primeira chave é criada com sua sessão autenticada no painel. Depois, uma chave existente também pode criar outra por POST /api/keys. Requisições autenticadas por cookie que alteram dados exigem Origin: https://umbotao.com.br.

POST /api/keys
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{"name":"Integração CRM"}

Resposta 201: {"id":"UUID_DA_CHAVE","token":"lf_..."}

DELETE /api/keys/UUID_DA_CHAVE
Authorization: Bearer SEU_TOKEN

Recursos

Filtros e paginação

Analytics, leads e distribuições aceitam projectId, from e to (AAAA-MM-DD, UTC, máximo 366 dias). Leads e distribuições retornam 50 registros por página: page=1. Distribuições aceitam format=csv para exportação completa do período.

Criar projeto

POST /api/projects
Content-Type: application/json
Authorization: Bearer lf_...

{"name":"Imobiliária SP","slug":"imobiliaria-sp","message":"Olá!","destinations":[{"name":"Equipe comercial","phone":"5511999999999","whatsapp":"5511999999999","active":true}]}

Criar destino WhatsApp

POST /api/projects/{id}/destinations

{"name":"João","phone":"5511999999999","whatsapp":"5511999999999","dailyLimit":null}

Criar destino com link externo

Use type: external e uma URL HTTP ou HTTPS completa. Não é necessário informar telefone. Cada projeto pode ter um ou mais destinos WhatsApp, externos ou misturados; os acessos alternam entre os destinos ativos na ordem cadastrada, respeitando os limites diários.

POST /api/projects/{id}/destinations

{"name":"Página de vendas","type":"external","url":"https://exemplo.com/oferta","active":true}

O endereço é preservado, incluindo parâmetros e fragmento. Mensagens iniciais se aplicam somente ao WhatsApp. Eventos e webhooks incluem destination_type e destination_url para links externos. O formulário de captura pode ser usado antes de qualquer tipo de destino.

Formulário de captura

O link /capture/identidade é uma página pública de formulário, não a documentação da API. Os links de distribuição usam /r/SLUG. Com captureEnabled ativo, o visitante preenche os campos antes de ser direcionado ao atendente.

PATCH /api/projects/UUID_DO_PROJETO
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{"captureEnabled":true,"captureFields":["name","phone","email"],"captureDesign":{"phoneLabel":"WhatsApp","buttonColor":"#146c50","title":"Fale com nossa equipe"}}

O campo phone representa WhatsApp e é salvo com código internacional. captureDesign aceita as opções de aparência descritas no OpenAPI; quando enviado, ele substitui a configuração de aparência e os campos omitidos recebem seus padrões. O slug automático existe no painel: pela API, envie name, slug e destinations ao criar o projeto. É obrigatório pelo menos um destino ativo; a API retorna 400 e não cria o projeto se ele estiver ausente ou inválido. Projeto e destinos são salvos juntos. As consultas de projetos retornam availability com ready e reason; o QR Code retorna 409 quando não há destino disponível.

Autenticação e respostas

A API responde JSON. Listagens de projetos e chaves retornam arrays; leads e distribuições retornam {items, total, page}. O QR retorna image/svg+xml e a exportação retorna CSV. Não há limites comerciais; proteções de frequência podem retornar 429.

Webhooks assinados

O evento lead.distributed contém event_id, project_id, project_name, destination_id, destination_name, destination_phone, timestamp, utm_source, utm_medium, utm_campaign e referer. A entrega é pelo menos uma vez: deduplique por event_id. Até cinco tentativas, com espera exponencial de 30 segundos a 4 minutos entre as tentativas.

Calcule HMAC-SHA256(segredo, timestamp + "." + corpo bruto). Compare em tempo constante com X-Leadflow-Signature (prefixo sha256=). Valide X-Leadflow-Timestamp dentro de cinco minutos e armazene IDs processados. Responda com 2xx.

Erros

JSON com error. 400 validação; 401 sem autenticação; 403 permissão; 404 recurso; 409 duplicidade; 429 limite de uso. Links públicos também retornam 410 quando desativados e 503 quando não há atendente disponível.

Privacidade

O IP completo não é armazenado. Visitantes únicos são uma estimativa por HMAC de IP + User Agent. País só é registrado quando o proxy confiável fornece esse dado; caso contrário, aparece como desconhecido. UTMs são preservadas no evento e no caminho pelo formulário.

Variações de mensagem e confirmação de atendimento

Adicione mensagens na página do projeto. A primeira variação adicionada também inclui a mensagem original na distribuição. As versões ativas alternam por redirecionamento e possuem códigos MSG-… estáveis. Textos são imutáveis para preservar o histórico: pause e crie outra versão para mudar a abordagem.

O WhatsApp recebe apenas o texto configurado, sem código ou referência. Na sua integração, associe a frase recebida ao código MSG da abordagem. O painel permite copiar um cURL com o código, projeto e token preenchidos. GET /api/projects/ID/messages também lista os textos e códigos. Use textos distintos; versões históricas iguais exigem escolha explícita do código na integração.

POST /api/attendances
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{"projectId":"UUID_DO_PROJETO","messageCode":"MSG-0123456789AB","externalId":"ID_UNICO_DO_ATENDIMENTO"}

Envie um externalId real, único por atendimento no projeto. Repetir o mesmo ID e código retorna recorded=false, sem duplicar. Reutilizar o ID com outro código retorna 409. Projeto ou mensagem de outra conta retorna 404. Dados inválidos retornam 400; sem autenticação, 401. A API aceita códigos de versões pausadas para retornos posteriores.

A confirmação antiga por reference UB continua disponível para integrações que recebem essa referência pelo webhook lead.distributed. Ela não aparece no texto do WhatsApp. Escolha um único modo de confirmação por atendimento: não envie o mesmo retorno pelos dois modos.

GET /api/projects/ID/messages?days=30 lista variações e o relatório (7, 30 ou 90 dias). POST no mesmo endereço aceita { "action": "add", "text": "Olá!" } ou { "action": "toggle", "code": "MSG-…", "active": false }. Limite de 30 versões por projeto; ao menos uma deve permanecer ativa.

A taxa é atendimentos confirmados divididos pelos redirecionamentos de cada mensagem. Cliques usam a data do acesso; confirmações por MSG usam a data de recebimento pela API. São totais do período, sem atribuição individual: retornos tardios podem produzir taxas acima de 100%. Confirmações legadas por UB seguem a data do clique. Zero confirmações pode significar ausência de integração. O umbotao não identifica automaticamente mensagens enviadas nem lê conversas do WhatsApp. Projetos sem variações mantêm o fluxo anterior, sem referência.