Criar lead
O lead entra no CRM e o rodízio escolhe o dono, como se tivesse chegado pelo formulário do site. Com Idempotency-Key, um timeout do seu lado não vira dois leads do nosso.
POST /leads
API pública
Ligue o seu sistema ao CRM Volpato
Uma API REST para mandar lead, acompanhar o funil e virar cliente — sem planilha no meio, sem ninguém digitando de novo o que o seu sistema já sabe.
a sua primeira chamada
curl -X POST https://seu-crm.com.br/api/publica/v1/leads \ -H "Authorization: Bearer vlp_test_…" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: pedido-8814" \ -d '{"nome":"Maria Souza","telefone":"31999990000"}' { "ok": true, "lead": { "id": "1042", "nome": "Maria Souza" } }
O que dá para fazer
Sete operações. As três primeiras cobrem a integração que a maioria precisa; o resto existe para quem vai mais longe.
Consultar
Leia qualquer lead da empresa, com o estado atual: quem atende, se já virou cliente, quando. É por aqui que o seu sistema sabe o que aconteceu depois que ele mandou.
GET /leads/{id}
Converter em cliente
A mesma conversão que o funil usa quando a venda fecha: cards, propostas, conversas e tarefas passam para o cliente novo. Sem corpo — os dados saem do próprio lead.
POST /leads/{id}/converter
Descartar
Tira o lead do caminho marcando como perdido. Reversível, e idempotente: chamar de novo responde a mesma coisa em vez de parecer falha.
DELETE /leads/{id}
Catálogo e preços
Os produtos da empresa, com valores, para o seu sistema montar orçamento com os mesmos números que o vendedor vê.
GET /produtos
Propostas
O que foi proposto, para quem e por quanto. Útil para conciliar com o que o seu ERP já tem registrado.
GET /propostas
Funil
Os funis, as etapas e os cards. Comece por GET /funil: a etapa é referida por id, e id de etapa é inventado por empresa.
GET /funil
Como começar
01
Peça as chaves
A Volpato gera duas de uma vez e manda para o e-mail da empresa um link que abre uma única vez. Você copia as duas e guarda num cofre de senhas — elas não aparecem de novo.
02
Integre com a de teste
A chave vlp_test_ alcança os dados da própria empresa, mas o lead que ela cria NÃO entra no rodízio: fica com o funcionário da integração, e nenhum vendedor recebe lead de teste. Erre à vontade — ninguém vai ligar para o seu “Teste da Silva”.
03
Troque para produção
Quando estiver pronto, troque a chave no seu .env por vlp_live_. Nenhuma URL muda, nenhum campo muda — é a chave que decide. Se algo der errado, voltar é trocar de volta.
vlp_test_…
Para integrar. O lead criado fica fora do rodízio, e o registro nasce marcado como de teste. É a chave com que você erra.
vlp_live_…
Para valer. O lead segue o caminho normal e cai na fila de um vendedor de verdade.
As duas alcançam os dados da mesma empresa. O prefixo diz qual é qual — trate a de teste com o mesmo cuidado da outra.
O que você pode contar
Integração não quebra por falta de recurso — quebra por falta de previsibilidade. Estas são as decisões que já estão no código.
Erro nunca vem com HTTP 200
O código HTTP é sempre real, e o corpo traz erro.codigo para a sua máquina tratar. Nada de sucesso com “status: false” escondido dentro do JSON.
401 e 403 querem dizer coisas diferentes
401 é “não sei quem você é” — vale tentar outra credencial. 403 é “sei quem você é, e você não pode” — repetir não resolve. Tratar os dois igual põe o seu sistema a reautenticar em laço.
Repetir não duplica
Mande Idempotency-Key no POST de lead e a repetição devolve o mesmo lead, com status 200 e marcado como repetida. O seu retry deixa de ser um risco.
Um envelope só, para todas as listagens
dados, pagina, por_pagina, total, total_paginas. Quem aprende uma listagem sabe as quatro. Valor inválido na paginação vira o padrão em vez de derrubar a chamada.
A ordem é estável
A paginação ordena por id, nunca por data. Com data, dois registros do mesmo segundo empatam e um deles escorrega entre páginas — você importaria a base com um buraco e sem erro nenhum.
Servidor para servidor
Não há cabeçalho CORS, de propósito. A chave vale pela empresa inteira e não expira sozinha: no JavaScript da sua página, qualquer visitante a copia pelo DevTools.
Perguntas
Não. É HTTP com JSON e um header de autorização. Qualquer linguagem que faça requisição serve — e o `curl` do topo desta página é uma integração completa de criar lead.
A documentação tem todas as rotas, e um botão para testar cada uma
Cole a sua chave lá e dispare a chamada sem sair da página.
Abrir a documentação