Como integrar formulários externos personalizados via API

Se você já tem um formulário próprio, seja em um site, landing page ou sistema interno, e quer que cada lead capturado seja enviado automaticamente para a Atendare, sem precisar copiar dados manualmente ou importar planilhas, este artigo é para você.

Aqui você vai aprender a conectar seu formulário externo à Atendare por meio de uma integração via API: desde a criação do formulário receptor dentro da plataforma, passando pela obtenção do form_token, até o envio seguro dos dados via requisição server-to-server. Também mostramos a estrutura completa da requisição, como vincular o contato a uma empresa, os erros mais comuns (e como resolvê-los) e as boas práticas de segurança que você deve seguir para proteger sua chave de API.

Vale reforçar: esta integração é indicada apenas para formulários externos e personalizados. Se você utiliza os formulários nativos da Atendare, não é necessária nenhuma configuração adicional — a integração já acontece automaticamente.

TÓPICOS DESTE ARTIGO

1. O que você vai conseguir fazer com essa integração
2. Quando este artigo é indicado para você
3. Antes de começar: o que você precisa
4. Criando o formulário na Atendare
5. Obtendo o form_token
6. Como enviar os dados com segurança
7. Estrutura da requisição e campos disponíveis
8. Campos especiais: empresa
9. Erros comuns e como resolver
10. Boas práticas de segurança
11. Recursos e materiais de apoio

1. O Que você vai conseguir fazer com essa integração

Com essa integração, qualquer pessoa que preencher um formulário no seu site, landing page ou ferramenta externa será automaticamente cadastrada como contato na Atendare. Você não precisará copiar dados manualmente nem exportar planilhas.

Isso é possível porque a Atendare disponibiliza um endpoint de API que recebe os dados do formulário diretamente do seu servidor e os registra na Atendare em tempo real.

2. Quando este artigo é indicado para você

Este guia é voltado para quem criou um formulário personalizado fora da Atendare e quer que os leads capturados cheguem automaticamente à Atendare. Isso inclui situações como:

1. Sites desenvolvidos do zero.
2. Portais e sistemas internos: Aplicações web, dashboards ou sistemas próprios com formulários de cadastro que precisam alimentar a Atendare.

Este artigo não cobre

Formulários nativos da Atendare. Esses já se integram automaticamente, sem nenhuma configuração de API.

3. Antes de começar: o que você precisa

1. Uma chave de API (Access Token). Solicitada ao suporte da Atendare.
2. Um formulário criado dentro da Atendare.
3. Acesso ao código ou às configurações do seu site ou ferramenta externa.
4. Um desenvolvedor ou conhecimento técnico para configurar a camada de back-end.

Como solicitar sua chave de API

A chave de API é gerada pela nossa equipe de suporte. Para solicitá-la, envie um e-mail para [email protected] informando que você precisa de um Access Token para integração via API.

Guarde essa chave em local seguro. Ela funciona como uma senha de acesso à sua conta e jamais deve ser exposta publicamente.

4. Criando o formulário na Atendare

Mesmo que o formulário visual esteja em outra plataforma, você precisa criar um formulário correspondente dentro da Atendare. Ele funciona como o receptor das informações e não precisa ser exibido para o visitante.

1. No menu lateral, clique em Marketing
2. Clique em Campanhas e depois em Formulários.
3. Clique no botão Novo formulário (canto superior direito).
4. Dê um nome ao formulário (ex.: Formulário Landing Page) e configure os campos que deseja capturar: nome, e-mail, telefone, empresa etc.
5. Clique em salvar.

5. Obtendo o form_token

Após criar o formulário, você precisará do form_token: um identificador único que instrui a API a registrar os dados no formulário correto.

1. Acesse Marketing › Campanhas › Formulários.
2. Clique nos três pontinhos (⋮) ao lado do formulário desejado.
3. Selecione a opção Copiar token.

Guarde esse valor, você vai usá-lo no corpo de cada requisição enviada à API.

6. Como enviar os dados com segurança

ATENÇÃO – Nunca chame a API diretamente do front-end do seu site!

Se você tentar consumir a API da Atendare diretamente pelo HTML ou JavaScript do seu site, poderá enfrentar problemas de segurança e funcionamento.

• A requisição pode ser bloqueada pelo navegador devido às políticas de segurança conhecidas como CORS (Cross-Origin Resource Sharing).
• Sua chave de API ficará exposta no código da aplicação, permitindo que terceiros a obtenham e utilizem indevidamente para acessar ou manipular dados da sua conta.

A regra de ouro: a comunicação com a API da Atendare deve sempre acontecer de servidor para servidor.

7. Estrutura da requisição

Endpoint

POST  https://api.atendare.com/v2/form

Cabeçalho (Header)

Exemplo – Node.js / fetch 

Aviso: Este código deve rodar no servidor, NUNCA no front-end

const response = await fetch('https://api.atendare.com/v2/form', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Access-Token': process.env.SUA_API_KEY
  },
  body: JSON.stringify({
    form_token: 'seu_form_token_aqui',
    name:       'Maria Silva',
    email:      '[email protected]',
    phone:      '(51) 99999-0000',
    company: {
name: 'Empresa Exemplo Ltda'
    }
  })
});

const data = await response.json();

8. Campos especiais: empresa

Para vincular o contato a uma empresa na Atendare, envie o campo company como objeto. A Atendare verificará automaticamente se a empresa já existe e realizará o vínculo.

{
  "form_token": "seu_form_token",
  "name":       "Carlos Oliveira",
  "email":      "[email protected]",
  "phone":      "(11) 98888-1234",
  "company": {
    "name": "Nome Fantasia da Empresa"
  }
}

9. Erros comuns e como resolver

10. Boas práticas de segurança

O que fazer

• Utilize variáveis ​​de ambiente em vez da sua chave de API.
• Mantenha a chave armazenada com segurança do lado do servidor e faça a comunicação com a API por meio dele.
• Em caso de suspeita de vazamento, solicite bloqueio imediato pelo e-mail [email protected].

O que NÃO fazer

• Nunca implemente sua chave em ambientes do lado do cliente (HTML, Javascript).
• Nunca exponha a chave em repositórios públicos (GitHub, GitLab etc.).

11. Recursos e materiais de apoio

Atendare API – Documentação completa 

• Estrutura principal da API detalhando os principais métodos da Atendare para você que deseja integrar com nosso software https://docs.atendare.com/
• Como criar um formulário na plataforma: help.atendare.com

Para o desenvolvedor

• Como funciona o CORS: developer.mozilla.org/pt-BR/docs/Web/HTTP/CORS
• Variáveis de ambiente com dotenv: npmjs.com/package/dotenv
• Como funciona o protocolo HTTP e códigos de status de respostas: https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Status
• JSON: estrutura e boas práticas: https://developer.mozilla.org/pt-BR/docs/Learn_web_development/Core/Scripting/JSON
• Requisições HTTP com Fetch API: https://developer.mozilla.org/pt-BR/docs/Web/API/Fetch_API
• Variáveis de ambiente no Node.js: https://nodejs.org/api/environment_variables.html 
• Guia de autenticação e segurança para APIs (OWASP): https://owasp.org/www-project-api-security/
• Tratamento de erros em APIs REST: https://restfulapi.net/http-status-codes/

Dúvidas sobre a API?

Nossa equipe de suporte atua como facilitadora no uso da API, oferecendo apoio para esclarecimentos sobre endpoints, comportamento das requisições e dúvidas relacionadas ao processo de integração. A implementação da solução fica sob responsabilidade da sua equipe técnica, e seguimos disponíveis para apoiar na análise de cenários e orientar sempre que necessário.

Para suporte sobre a integração, fale com nossa equipe em [email protected]