Autenticação

Toda requisição leva um token permanente no header Authorization, com o esquema Bearer.

Informe o token permanente de acesso da sua conta em cada chamada:

Authorization: Bearer pn_0000000000000000000000

Exemplo completo:

curl "https://api.aidasystem.com.br/core/v1/contact?PageSize=10" \
  -H "Authorization: Bearer pn_0000000000000000000000"

Sem o header, ou com token inválido, a resposta é 401. Chamadas de login integrado e envio de mensagens devem ser feitas só a partir do seu backend, nunca do navegador, para não expor o token.

Paginação

Os endpoints de listagem usam pageNumber (página desejada) e pageSize (itens por página, no máximo 100). Nos endpoints GET eles vão na query como PageNumber e PageSize. Mantenha o pageSize constante enquanto percorre as páginas, pois mudá-lo altera o conteúdo de cada pageNumber.

{
  "pageNumber": 1,
  "pageSize": 50,
  "totalPages": 5,
  "totalItems": 250,
  "hasMorePages": true,
  "items": [ { } ]
}

Rate limiting

Para garantir a estabilidade, a segurança e o desempenho da API, aplicamos limites de requisições, em duas camadas complementares.

1. Limite principal (uso contínuo). Até 1.000 requisições a cada 5 minutos, o que equivale a uma média aproximada de 3 requisições por segundo. Ele controla o uso regular da API ao longo do tempo.
2. Limite de proteção contra picos (burst). Além do limite principal, existe um limite de segurança de 200 requisições a cada 5 segundos. Ele evita picos repentinos de chamadas, mesmo que o limite principal ainda não tenha sido atingido.

Comportamento em caso de excesso#

Requisições que ultrapassarem qualquer um dos limites recebem o status 429 Too Many Requests. Aguarde o limite se restabelecer antes de voltar a disparar. Os limites são aplicados por conta.

Os endpoints /chat/v1/send/* têm ainda um limite individual de 1.000 requisições a cada 2 minutos, além do limite geral da conta.

Dicas para evitar atingir o limite#

• Evite loops sem controle. Laços que disparam requisições em sequência (especialmente for ou while) devem ter sempre algum atraso ou controle de volume.
• Implemente retry com espera (backoff). Ao receber um 429, aguarde alguns segundos antes de tentar de novo. Repetir imediatamente tende a piorar o problema.
• Distribua as chamadas ao longo do tempo. Em vez de disparar muitas requisições de uma vez, espalhe-as de forma uniforme para manter uma média estável.

Dicas para quem usa n8n#

O n8n pode gerar picos de requisições sem que você perceba. Algumas configurações ajudam bastante:

• Use o node Wait. Após chamadas em massa ou dentro de loops, insira um atraso entre as execuções. Mesmo um intervalo pequeno (por exemplo, 500 ms) reduz bastante o risco de atingir o limite.
• Controle a concorrência. Ao usar nodes como HTTP Request e Split In Batches, evite executar muitos itens em paralelo. Prefira lotes menores e sequenciais.
• Configure o Split In Batches. Use lotes pequenos (por exemplo, 10 ou 20 itens) e combine com o node Wait entre os lotes.
• Trate o erro 429 explicitamente. Configure o fluxo para detectar o erro, aguardar alguns segundos e repetir a requisição automaticamente. Isso evita falhas no workflow e respeita os limites da API.

Login integrado

Permite levar o usuário já autenticado de outra plataforma para a sua conta. O seu backend pede a sessão com o token permanente e redireciona o usuário para o endereço devolvido.

Faça essa chamada apenas pelo backend, nunca pelo front-end, para não expor o token.

POST https://api.aidasystem.com.br/auth/v1/login/authenticate
Authorization: Bearer pn_000x000x000x000x000x000x000x00

{
  "phoneNumber": "5531999999999",
  "email": "email@seudominio.com",
  "redirectUrl": "/chat2/sessions/df98b9fb-2280-45z5-bce1-3fe8aa7047e5/preview"
}

Resposta:

{
  "userId": "48525e80-43a7-4e06-86e0-f6b67b7d6629",
  "tenantId": "d4ed253d-f0c6-435c-8f7f-59a0598885fe",
  "urlRedirect": "https://.../auth/external-login?code=...&userId=...&tenantId=...",
  "expiresIn": "2026-01-01T00:00:00Z"
}

Redirecione o usuário para urlRedirect e ele inicia a sessão já autenticado, até a data de expiresIn. O endereço urlRedirect aponta para a aplicação web, não para esta API.

Componente de conversas#

O componente de conversas fica na rota /chat2/sessions/XXXXXX, onde XXXXXX é o ID da conversa. Duas variações são úteis:

• /preview oculta o menu da plataforma e mostra só a conversa.
• ?interactive=true já habilita a interação com a conversa.

Combinando as duas: /chat2/sessions/XXXXXX/preview?interactive=true.

Webhooks

Os webhooks avisam o seu sistema quando algo acontece, como uma mensagem recebida ou uma alteração de contato. Crie a assinatura pela API (veja Core › Webhooks), escolhendo os eventos e uma URL pública. A plataforma envia um POST para essa URL. Para pausar o recebimento, deixe a assinatura inativa (enabled: false).

O corpo vem em application/json:

{
  "eventType": "CONTACT_UPDATE",
  "date": "2023-08-23T16:42:35.4359934Z",
  "content": {
    "id": "ed2b52f8-cf13-449b-b3d5-ae27051f4663",
    "createdAt": "2022-10-28T21:24:26.158391Z",
    "updatedAt": "2023-08-23T16:15:35.3814324Z",
    "companyId": "626fb5de-0cc2-4209-b456-47b454ee6e14",
    "name": "John Raymond Legrasse",
    "phonenumber": "+55|00000000000",
    "phonenumberFormatted": "(00) 00000-0000",
    "email": "exemplo@email.com",
    "instagram": null,
    "annotation": "",
    "tagsId": [],
    "tags": [],
    "status": "ACTIVE",
    "origin": "CREATED_FROM_HUB",
    "utm": null,
    "customFieldValues": {},
    "metadata": null
  }
}

O IP de origem das chamadas está em Informações para Firewall.

Webhook no Chatbot

Durante um atendimento por chatbot, o sistema pode chamar a sua URL por POST para buscar dados e criar fluxos alternativos. Você define a URL no nó de webhook do fluxo.

Mensagem enviada pelo chatbot traz tudo o que já foi capturado:

• responseKeys: lista das respostas possíveis que o seu webhook pode devolver, como CLIENTE_EXISTE e CLIENTE_NAO_EXISTE.
• sessionId e session: dados da conversa (id, createdAt, departmentId, userId, number e utm).
• channel: id, key, platform e displayName.
• contact: id, name, phonenumber, display-phonenumber, email, instagram, tags, além de campos personalizados e metadata.
• questions e menus: perguntas e menus já respondidos, cada um com text e answer.
• lastMessage: última mensagem (id, createdAt, type, text, fileId e file com publicUrl, extension, mimeType, name e size).

Retorno simples. Responda com HTTP 200 para seguir o fluxo de sucesso; para um fluxo alternativo, responda 200 com a chave escolhida:

{ "response": "CLIENTE_EXISTE" }

Retorno com dados do contato. Atualize o contato e guarde metadados para usar depois:

{
  "response": "CLIENTE_EXISTE",
  "metadata": { "cliente-existe": true },
  "contact": {
    "cnpj": "00.000.000/0000-00",
    "metadata": { "cod-ext": "abcd" }
  }
}

Retorno com disparo de mensagens. A lista é enviada na ordem. Cada mensagem pode ter texto, arquivo (fileUrl) ou um modelo (template com id e parameters):

{
  "response": "CLIENTE_EXISTE",
  "messages": [
    { "text": "Segue seu boleto abaixo para pagamento. Vencimento dia 10/01" },
    { "fileUrl": "https://xyz.com/boleto.pdf" },
    { "template": { "id": "ab78cd_oferta", "parameters": { "valor": "R$ 9,99" } } }
  ]
}

As três formas de retorno podem ser combinadas em uma única resposta.

Perguntas dinâmicas#

Carrega as opções de resposta em tempo real, direto do seu sistema, quando o cliente chega à etapa do fluxo.

Cada item de options tem text (obrigatório), description (opcional, só no tipo LIST) e url (opcional, só no tipo BUTTONS, para link externo).

{
  "text": "Como podemos ajudar hoje?",
  "type": "BUTTONS",
  "options": [
    { "text": "Área de Cliente", "url": "https://empresa.com/cliente" },
    { "text": "Suporte Técnico" }
  ]
}

Informações para Firewall

Para redes com regras rígidas, libere a saída para os endereços abaixo. A API fica toda em um único endereço. Os demais itens dizem respeito a arquivos e webhooks.

Os arquivos são distribuídos pelo CloudFront da AWS. Para liberá-los no firewall, adicione os intervalos de IP publicados em https://ip-ranges.amazonaws.com/ip-ranges.json.

Criar token para integração

Um token permanente permite autenticar e autorizar seu aplicativo sem implementar fluxos de autenticação. Basta criar um token e usá-lo onde precisar.

Para criar um token, clique em Ajustes > Integrações > Integração via API (Configurar). Em seguida, clique em Novo e dê um nome ao token.

Uso do token em uma chamada HTTP#

Inclua o token no header da requisição, no formato abaixo:

Header Authorization: Bearer {seu_token_aqui}

curl -X GET "https://api.aidasystem.com.br/chat/v1/channel" \
  -H "Authorization: Bearer pn_TOKEN_PERMANENTE"

Orientações de segurança#

• Geração. Você pode gerar um novo token sempre que precisar. Informe o nome da ferramenta que vai usá-lo, para identificá-lo no futuro. O token é uma chave única que dá acesso direto aos serviços, sem login contínuo.
• Uso. Use o token em integrações externas e ferramentas que precisem acessar sua conta. Mantenha-o seguro, pois ele dá acesso direto à sua conta.
• Revogação. Você tem controle total do token. Se não precisar mais dele ou quiser reforçar a segurança, exclua-o a qualquer momento. Depois de excluído, todas as integrações que o usavam deixam de funcionar.
• Segurança. Não compartilhe o token com terceiros. Se suspeitar de uso indevido, exclua-o imediatamente e gere um novo.