API e webhooks: enviar e receber dados do AceleraZap

Como conseguir o endereço no painel

1. 1

   Abra a tela do webhook

   No painel, entre em Integrações e escolha o cartão Webhook. Abra a aba Receber dados.

   Integrações → Webhook → Receber dados

2. 2

   Crie a conexão

   Clique em + Novo webhook. Se a tela ainda estiver vazia, o botão se chama + Conectar CRM/webhook. Dê um nome, como Formulário do site, e clique em Continuar.

3. 3

   Copie a URL de recebimento

   Ela já leva o seu token. Cole na ferramenta que vai enviar os leads. Só quem pode editar os formulários vê o endereço completo.

4. 4

   Envie um teste e detecte os campos

   Clique em Detectar campos e faça um envio de teste pela sua ferramenta. O AceleraZap fica ouvindo por 15 minutos e mostra os campos que chegaram.

5. 5

   Diga o que é cada campo

   Clique em Concluir e mapear. Para cada campo escolha: Nome, WhatsApp, E-mail, Mensagem, Etapa do funil, Atendente (dono), Extra ou Ignorar.

6. 6

   Ative

   Clique em Salvar e ativar captura. A partir daí, cada envio vira um lead no funil.

Enviar um lead

Faça um POST na URL de recebimento. O token vai no próprio endereço, em ?token=. O corpo pode ser JSON, x-www-form-urlencoded ou multipart/form-data. Os nomes dos campos são os que a sua ferramenta já usa. O mapeamento que você fez no painel diz o que cada um significa.

curl -X POST "https://app.acelerazap.com.br/api/v1/inbound/capture?token=SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nome":"Maria Souza","whatsapp":"27999998888","email":"[email protected]","mensagem":"Quero um orçamento para o plano empresarial","etapa":"Qualificado","atendente":"[email protected]","utm_source":"google","utm_medium":"cpc","url":"https://seu-site.com.br/contato?utm_source=google&utm_medium=cpc&utm_campaign=orcamento-outubro"}'

curl -X POST "https://app.acelerazap.com.br/api/v1/inbound/capture" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nome":"Maria Souza","whatsapp":"27999998888","email":"[email protected]","mensagem":"Quero um orçamento para o plano empresarial","etapa":"Qualificado","atendente":"[email protected]","utm_source":"google","utm_medium":"cpc","url":"https://seu-site.com.br/contato?utm_source=google&utm_medium=cpc&utm_campaign=orcamento-outubro"}'

O que cada campo vira

Na etapa Mapear, você escolhe o destino de cada campo que a ferramenta enviou. Campo que você não mapeou entra como Extra.

Testar sem criar lead

Abra o endereço no navegador, ou faça um GET. Com um token válido, a resposta diz se a conexão está pronta. Esse teste não cria lead.

curl "https://app.acelerazap.com.br/api/v1/inbound/capture?token=SEU_TOKEN"
# {"ok":true,"tokenValid":true,"ready":true,"status":"Pronto pra receber envios por POST.", ...}

O que o AceleraZap responde

Limites

E se o lead já existir

• O lead é único por conta e telefone. O telefone é comparado só pelos dígitos, sem o 55: 27999998888 e +55 (27) 99999-8888 são a mesma pessoa.
• Se o telefone já existe, o envio atualiza o lead e a resposta traz created false. Nome, e-mail e mensagem novos substituem os antigos, e se o envio vier sem nome o lead passa a se chamar pelo e-mail ou pelo telefone. A etapa enviada é ignorada, e a origem do primeiro contato é mantida.
• Sem telefone, o lead é reconhecido pelo e-mail. Sem telefone e sem e-mail, cada envio cria um lead novo.
• Cada lead novo conta no limite de leads do mês do seu plano. Acima do limite, o lead entra bloqueado no painel e a resposta continua sendo 200.

curl -X POST "https://app.acelerazap.com.br/api/v1/inbound/webhook" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name":"João Silva","phone":"11999998888","email":"[email protected]","source":"n8n","deal_stage":"Qualificado"}'

curl -X POST "https://app.acelerazap.com.br/api/v1/inbound/status" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"leadId":"ID_DO_LEAD","stage":"won","value":"1.299,90"}'

Como configurar no painel

1. 1

   Abra a tela do webhook

   No painel, entre em Integrações, escolha o cartão Webhook e fique na aba Enviar dados.

   Integrações → Webhook → Enviar dados

2. 2

   Informe o endereço do seu sistema

   No campo URL do endpoint, cole o endereço que vai receber o POST. Ele precisa começar com https://.

3. 3

   Escolha os eventos

   Marque Lead criado, Lead atualizado e Etapa do lead mudou, conforme o que o seu sistema precisa. Por padrão vem só Lead criado.

4. 4

   Crie o webhook e guarde o segredo

   Clique em Criar webhook. O segredo aparece inteiro só agora: copie e guarde no seu sistema. Depois, a tela mostra só o final. Se perder, use Regenerar e atualize o segredo no seu sistema.

5. 5

   Envie um teste

   Clique em Enviar teste. O seu endereço recebe um lead de teste, com o cabeçalho X-AceleraZap-Test: true. Em Últimas entregas você vê o resultado de cada envio, com o botão Reenviar nos que falharam.

Os eventos

Cabeçalhos de cada envio

O corpo do envio

O corpo é sempre JSON, com o lead inteiro. Este é um lead.created. Os outros eventos têm o mesmo desenho, mudando event e changes.

{
  "id": "evt_a1b2c3d4e5f6a7b8",
  "event": "lead.created",
  "createdAt": "2026-10-20T18:20:00.000Z",
  "account": {
    "id": "acc_xxx",
    "name": "Sua Empresa"
  },
  "lead": {
    "id": "lead_xxx",
    "name": "Maria Souza",
    "phone": "27999998888",
    "phoneE164": "+5527999998888",
    "email": "[email protected]",
    "message": "Quero um orçamento",
    "channel": "google_ads",
    "device": "mobile",
    "browser": "Chrome",
    "os": "Android",
    "state": "ES",
    "url": "/contato",
    "fullUrl": "https://seu-site.com.br/contato?utm_source=google&utm_medium=cpc&utm_campaign=orcamento",
    "status": "new",
    "stageId": "etapa_xxx",
    "stageName": "Novo",
    "widgetSiteId": null,
    "departmentId": null,
    "departmentName": null,
    "createdAt": "2026-10-20T18:19:55.000Z",
    "attribution": {
      "gclid": "Cj0KCQjw...",
      "gbraid": null,
      "wbraid": null,
      "fbclid": null,
      "fbp": null,
      "fbc": null,
      "ctwaClid": null,
      "utmSource": "google",
      "utmMedium": "cpc",
      "utmCampaign": "orcamento",
      "utmTerm": null,
      "utmContent": null,
      "adCampaignId": "123456789",
      "adCampaignName": "Orçamento"
    },
    "dealValue": null,
    "dealValueBRL": null,
    "currency": "BRL",
    "dealClosedAt": null,
    "assignedSeller": {
      "id": "sel_xxx",
      "name": "Carlos"
    },
    "tags": [
      "Cliente VIP"
    ],
    "lostReason": null,
    "conversationChannel": "whatsapp",
    "origin": "other",
    "formName": null,
    "lastActivityAt": "2026-10-20T18:19:55.000Z",
    "qualificationAnswers": [
      {
        "questionId": "q_xxx",
        "label": "Qual produto?",
        "value": "Telha"
      }
    ]
  },
  "changes": null
}

Quando o lead é movido para Fechado, sai um lead.status_changed, com o status de antes e o de agora em changes. O valor costuma ser anotado depois, e então sai um lead.updated com o valor. Estes são os dois trechos:

{
  "id": "evt_9f8e7d6c5b4a3210",
  "event": "lead.status_changed",
  "lead": {
    "id": "lead_xxx",
    "status": "won",
    "stageName": "Fechado",
    "dealValue": null,
    "dealValueBRL": null,
    "currency": "BRL",
    "dealClosedAt": "2026-10-22T14:03:00.000Z"
  },
  "changes": {
    "from": "qualified",
    "to": "won",
    "fromStageName": "Qualificado",
    "toStageName": "Fechado"
  }
}

Os campos principais

Valores de lead.status

Contam como venda fechada won, post_sale, support e renewal. Nelas o lead traz dealClosedAt e, quando alguém anotou o valor, dealValue.

Como conferir a assinatura

A assinatura é o HMAC SHA256 do corpo, calculado com o segredo da sua conta e escrito em hexadecimal. Ela vai no cabeçalho X-AceleraZap-Signature, com o prefixo sha256=. Para conferir, refaça a conta com o mesmo segredo e compare.

const crypto = require("node:crypto");

// corpoCru: o corpo exatamente como chegou (Buffer ou texto).
// cabecalho: o valor de X-AceleraZap-Signature.
function assinaturaValida(corpoCru, segredo, cabecalho) {
  const esperada =
    "sha256=" + crypto.createHmac("sha256", segredo).update(corpoCru).digest("hex");
  const a = Buffer.from(esperada);
  const b = Buffer.from(cabecalho || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Tentativas e desativação automática

Boas práticas

Como conseguir o token

1. 1

   Crie o token

   A API de leads é liberada a pedido, no plano Business. Com a API liberada na conta, o administrador entra em Integrações e escolhe o cartão API de leads. Dê um nome ao token, escolha as permissões (Ler leads, Criar e editar leads) e a validade. Se a tela disser que a API não está liberada, peça ao suporte.

   Integrações → API de leads

2. 2

   Copie o token na hora

   Ele aparece inteiro uma vez só, logo depois de criado, e começa com azp_. O AceleraZap não guarda o token, só uma impressão digital dele, que não serve para refazê-lo: se perder, crie outro e revogue o antigo.

3. 3

   Envie no cabeçalho

   Toda chamada leva o cabeçalho Authorization: Bearer seguido do token. Token na URL não é aceito.

Endereços

Todos começam em https://app.acelerazap.com.br/api/v1/public/leads. A permissão é a que você marcou ao criar o token.

Listar e paginar

A lista vem em data, do lead mais novo para o mais antigo. Quando há mais leads, a resposta traz nextCursor: mande o valor em cursor para pegar a página seguinte. Quando nextCursor vem null, acabou.

curl "https://app.acelerazap.com.br/api/v1/public/leads?status=won&createdFrom=2026-10-01&limit=100" \
  -H "Authorization: Bearer SEU_TOKEN_DA_API"
# {"data":[{"id":"clx...","name":"Maria Souza", ...}],"nextCursor":"MjAyNi0x..."}

Criar e editar

O POST segue a regra de sempre: o lead é único por conta e telefone. Telefone que já existe atualiza o lead e responde 200 com created: false. Lead novo responde 201, entra na etapa Novo e conta no limite de leads do mês.

curl -X POST "https://app.acelerazap.com.br/api/v1/public/leads" \
  -H "Authorization: Bearer SEU_TOKEN_DA_API" \
  -H "Content-Type: application/json" \
  -d '{"name":"Maria Souza","phone":"27999998888","email":"[email protected]","message":"Pediu orçamento pelo sistema da loja","source":"ERP"}'
# 201 {"data":{"id":"clx...", ...},"created":true}

curl -X PATCH "https://app.acelerazap.com.br/api/v1/public/leads/ID_DO_LEAD" \
  -H "Authorization: Bearer SEU_TOKEN_DA_API" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'
# 200 {"data":{"id":"ID_DO_LEAD", ...}}

Erros

Todo erro vem como { "error": { "code": "...", "message": "..." } }. O code não muda; a mensagem é para pessoas e pode mudar.

Limites

1. 1

   O visitante preenche o formulário da sua página

   O formulário é seu, feito como você quiser. Ele envia nome, WhatsApp e mensagem para o seu servidor.

2. 2

   O seu servidor envia o lead ao AceleraZap

   Um POST na URL de recebimento, com o token guardado em variável de ambiente. O token nunca vai para o navegador.

3. 3

   O lead aparece no funil

   A resposta traz created true e o leadId. O lead entra na etapa que o mapeamento indicar, e a conversa pode começar no WhatsApp.

4. 4

   O atendente fecha a venda no painel

   Ele move o lead para Fechado. Isso gera o evento lead.status_changed, com o valor se ele já tiver sido anotado antes.

5. 5

   O atendente anota o valor

   O valor pode ser anotado em qualquer etapa, e costuma vir depois de fechar. Quando ele é gravado, sai um lead.updated com dealValue em centavos e dealValueBRL em reais.

6. 6

   O AceleraZap avisa o seu CRM

   O webhook de saída envia os dois eventos assinados. O seu CRM confere a assinatura, ignora repetidos e atualiza o cliente pelo lead.id, guardando o valor quando ele deixar de ser null.

Passo 2: o seu servidor envia o lead

// No seu servidor: recebe o formulário e repassa ao AceleraZap.
app.post("/contato", express.json(), async (req, res) => {
  const { nome, whatsapp, mensagem } = req.body;

  const resposta = await fetch("https://app.acelerazap.com.br/api/v1/inbound/capture", {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.ACELERAZAP_TOKEN,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ nome, whatsapp, mensagem, etapa: "Novo" }),
  });

  const dados = await resposta.json();
  // dados.leadId é o id do lead no AceleraZap. Guarde se precisar.
  res.status(resposta.ok ? 200 : 502).json({ ok: resposta.ok });
});

Passo 6: o seu CRM recebe a venda

// No seu CRM: recebe o evento do AceleraZap.
// assinaturaValida é a função da seção "Como conferir a assinatura".
const jaProcessados = new Set(); // em produção, use o seu banco

app.post(
  "/webhook/acelerazap",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const assinatura = req.get("x-acelerazap-signature");
    if (!assinaturaValida(req.body, process.env.ACELERAZAP_SEGREDO, assinatura)) {
      return res.status(401).send("assinatura invalida");
    }

    const evento = JSON.parse(req.body.toString("utf8"));
    if (jaProcessados.has(evento.id)) return res.sendStatus(200);
    jaProcessados.add(evento.id);

    res.sendStatus(200); // responda antes de processar

    const mudouOuAtualizou = ["lead.status_changed", "lead.updated"].includes(evento.event);
    if (mudouOuAtualizou && evento.lead.status === "won") {
      // atualize o cliente pelo evento.lead.id. O valor pode vir já no
      // status_changed ou só depois, em um lead.updated: grave
      // evento.lead.dealValueBRL quando ele não for null.
    }
  },
);

Captura no site

Google Sheets, pelo Apps Script

Cada lead vira uma linha na sua planilha, e a mesma linha é atualizada quando o lead muda de etapa. Você cola um script na sua própria planilha e nos entrega só o endereço dele.

1. 1

   Abra a tela do Google Sheets

   No painel, entre em Integrações e escolha o cartão Google Sheets.

   Integrações → Google Sheets

2. 2

   Cole o script na sua planilha

   Na planilha, vá em Extensões → Apps Script e cole o script que a tela mostra.

3. 3

   Publique como app da Web

   Clique em Implantar → Nova implantação e publique como app da Web. Copie o endereço que termina em /exec.

4. 4

   Cole o endereço no AceleraZap

   Volte à tela do Google Sheets, cole o endereço e clique em Salvar. A planilha continua sendo sua: o AceleraZap guarda só o endereço, que você pode revogar quando quiser.

Cada linha tem as colunas: leadId, nome, telefone, email, mensagem, etapa, origem, campanha, estado, criadoEm. A coluna leadId é a chave: o script atualiza a linha do lead em vez de criar outra.

Conversões para anúncios

Quando o lead vira venda, o AceleraZap envia o resultado, com o valor, para onde você anuncia. Aqui o sentido é de saída, e você não programa nada.

Para entender o que a venda de volta muda nas campanhas, veja Conversões para Google e Meta.

Conexão só pelo painel

Para saber como o AceleraZap trata os dados, leia a Política de Privacidade.

1. 1

   A URL está completa?

   Ela começa com https://app.acelerazap.com.br/api/v1/inbound/capture e termina com ?token= e o seu token. Abra no navegador: um GET com token válido mostra se a conexão está pronta.

2. 2

   O token está certo?

   Erro 401 é token errado, cortado ou com espaço sobrando. Ele começa com fc_ e tem 35 caracteres.

3. 3

   A conexão está mapeada e ativa?

   Resposta 200 com skipped quer dizer que o envio chegou, mas a conexão não tem mapeamento salvo ou está pausada. Volte a Receber dados e conclua o mapeamento.

4. 4

   A detecção de campos ficou ligada?

   Enquanto ela escuta, se a conexão ainda não está mapeada ou está pausada, os envios viram amostra (sample true) e não viram lead. Ela se desliga sozinha depois de 15 minutos.

5. 5

   O método e o corpo estão certos?

   Só o POST cria lead. Corpo vazio dá empty_payload, e envio sem nome, telefone e e-mail dá no_identity.

6. 6

   O telefone é válido?

   Precisa ter de 10 a 13 dígitos. Se não tiver, o lead entra sem telefone e sem o botão de WhatsApp.

7. 7

   O plano permite?

   Criar a conexão e o webhook de saída exigem o plano Pro ou Business. No Starter, a tela mostra o convite para mudar de plano.

8. 8

   O limite de leads do mês acabou?

   Acima do limite de leads do plano, o lead é recebido, mas entra bloqueado no painel.

9. 9

   O lead já existia?

   A resposta com created false quer dizer que o telefone já estava na conta e o lead foi atualizado, não duplicado.

10. 10

    O webhook de saída não chega?

    Confira se o endereço usa https, se responde em até 8 segundos, se não redireciona e se o selo não está em Auto-desativado. A lista Últimas entregas mostra o código e o erro de cada tentativa.

11. 11

    A assinatura não bate?

    Use o segredo atual: depois de Regenerar, o antigo não vale mais. Calcule sobre o corpo cru e compare com o texto completo do cabeçalho, que começa com sha256=.

Se tudo estiver certo e o lead não chegar, abra um chamado em Ajuda e suporte, no painel. Conte o horário do envio e a resposta que a sua ferramenta recebeu.