Autenticação

A API da Wevi usa a API key (wevi_*) como credencial. Ela funciona em todos os endpoints (contatos, envio de mensagens, etc.) e é passada no header Authorization: Bearer <TOKEN>.

API key (`wevi_*`)

Funciona em todos os endpoints da API, incluindo:

POST /contacts e GET /contacts-schema (criar e consultar contatos)
POST /send-message, POST /send-template e os demais endpoints de envio no WhatsApp

Características:

Múltiplas chaves por organização (uma por integração: uma pra n8n, outra pro app interno, etc).
Prefixo wevi_ seguido de 64 caracteres hex.
Mostrada uma única vez ao criar. Depois fica armazenada como hash, sem como recuperar.
Escopos por chave: cada chave carrega só as permissões que você marcar.
Expiração opcional: 30 dias, 90 dias, 1 ano ou sem prazo.
Pode ser revogada e/ou excluída a qualquer momento.

Como gerar

Entre no app.wevi.chat.
Vá em Conta → Desenvolvedores → API Keys.
Dê um nome (ex: n8n-vendas).
Em Permissões e expiração, marque só os escopos que aquela integração precisa e escolha se a chave expira.
Clique em Criar chave e copie imediatamente. A chave não será mostrada de novo.

Só quem tem papel de administrador na organização cria, revoga ou exclui chave.

Chaves de teste

Marque Chave de teste ao criar e a chave sai com o prefixo wevi_test_. Ela responde igual à chave normal, registra o envio, devolve um wamid começando com wamid.TEST e dispara os webhooks, mas nada chega no WhatsApp de verdade.

Toda resposta de uma chave de teste traz o header Wevi-Test-Mode: true.

Construa a integração inteira com ela. Só troque pela chave normal quando for para valer.

Escopos

Cada chave carrega uma lista de escopos. Uma chamada a um endpoint fora do escopo devolve 403 com Insufficient scope.

Escopo	Dá acesso a
`contacts:read`	Ler contatos e metadados (`GET /contacts`, `GET /contacts-schema`)
`contacts:write`	Criar e alterar contatos, tags, notas, campos, etapa de funil e dono
`conversations:read`	Ler conversas e mensagens
`conversations:write`	Assumir, encerrar e etiquetar conversas
`messages:send`	Todos os endpoints de envio (`/send-*`)
`agents:read`	Ler agentes e configurações
`agents:write`	Alterar agentes
`campaigns:write`	Criar e disparar campanhas
`webhooks:manage`	Gerenciar webhooks de saída
`analytics:read`	Ler métricas

Chave criada antes dos escopos existirem continua valendo para tudo. Ao criar uma nova, o padrão é vir com todos marcados: desmarque o que aquela integração não precisa.

O que cada plano libera

Ter chave e ler dados funciona em qualquer plano, inclusive no Básico. Escrever e enviar mensagem pela API exige um plano com o recurso de API (Pro, Ultra ou trial). Quando o plano não cobre, a resposta é 402 com plan_limit_exceeded e o campo feature: "api".

Como usar

curl -X POST https://api.wevi.chat/functions/v1/send-template \
  -H "Authorization: Bearer wevi_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"connection_id":"...","template_name":"boas_vindas","to":"+5511999999999"}'

await fetch("https://api.wevi.chat/functions/v1/send-template", {
  method: "POST",
  headers: {
    "Authorization": "Bearer wevi_abc123...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    connection_id: "...",
    template_name: "boas_vindas",
    to: "+5511999999999",
  }),
});

A mesma chave funciona nos endpoints de contatos:

curl -X POST https://api.wevi.chat/functions/v1/contacts \
  -H "Authorization: Bearer wevi_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"email":"cliente@exemplo.com","name":"João"}'

O disparo de automação por fluxo (POST /automation-trigger) usa um token próprio, gerado por fluxo. Veja automações.

Erros de autenticação

Status	`error`	Causa
401	`Missing Authorization header`	Header `Authorization` ausente.
401	`Invalid API key` / `Invalid token`	API key não existe, foi revogada ou está digitada errada.
401	`Expired API key`	A chave passou da data de expiração. Gere uma nova.
403	`Insufficient scope: this key needs <escopo>`	A chave existe mas não tem o escopo daquele endpoint.
402	`plan_limit_exceeded`	O plano não inclui escrita e envio pela API. Leitura continua liberada.

Boas práticas

Nunca commite tokens em repositório público. Use variáveis de ambiente.
Crie uma API key por integração, com só os escopos daquela integração. Se uma vazar, você revoga só ela e o estrago fica limitado ao que ela podia fazer.
Use expiração em chave de teste, de fornecedor ou de projeto temporário.
Se vazar, vá em Conta → Desenvolvedores e revogue/gere uma nova imediatamente.

Revogação

Ao revogar uma chave, ela pode continuar aceita por até 30 segundos, o tempo do cache de autorização nas instâncias que a atenderam. Se precisar cortar na hora, revogue e troque o segredo dos webhooks que ela criou.

IPs permitidos

Ao criar a chave, você pode informar de quais endereços ela é aceita. Em branco, ela funciona de qualquer lugar, que é o padrão.

Aceita IP ou faixa, separados por vírgula:

203.0.113.10, 203.0.113.0/24

Vale a pena quando a chave vive num servidor de endereço fixo: se ela vazar, ainda precisa sair de lá. Chamada de fora da lista recebe 403 ip_not_allowed, com o seu endereço em details.your_ip para você conferir qual configurar.

Trocar a lista vale em até 30 segundos, o tempo do cache de autorização.

Validade

A sugestão ao criar é 1 ano. Chave que nunca vence é chave que fica para sempre no servidor de alguém que já saiu da empresa. "Sem expiração" continua disponível como escolha explícita.

Sete dias antes de vencer, a chave aparece em alerts no `GET /org` e no painel.

Paginação

→