Pular para o conteúdo
apiwpp
Recurso

Projetos e chaves de API com escopo

Separe sistemas ou clientes em projetos, cada um com chaves de API e webhook próprios, numa fatura só. Chaves com escopo, validade e rotação sem downtime.

Atualizado em

Uma integração com WhatsApp raramente fica sozinha. A loja manda confirmações de pedido, o CRM recebe as conversas, o sistema de cobrança avisa vencimentos, e uma agência atende dezenas de clientes, cada um com o próprio número. Se tudo isso usasse a mesma chave e o mesmo webhook, um vazamento em qualquer ponto abriria todos os números, e os eventos de um cliente chegariam no sistema do outro.

Na apiwpp essa separação é o modelo da conta: a organização (a sua empresa) tem projetos, e cada projeto tem os próprios números, o próprio endereço de webhook e as próprias chaves de API. A cobrança fica na organização, numa assinatura só.

Organização, projetos e conexões

São três níveis, e cada um tem um papel:

NívelO que éO que fica nele
OrganizaçãoA sua conta, o cliente da apiwppA assinatura, a fatura e as pessoas do painel
ProjetoUm sistema ou cliente seu (tenant na API)O endereço de webhook, o segredo de assinatura e as chaves de API
ConexãoUm número de WhatsApp dentro de um projetoA sessão, a fila de envio e o aquecimento

Um projeto não custa nada: a cobrança é por número conectado, e cada organização pode ter até 20 projetos por padrão. Por isso vale criar um projeto para cada coisa que você quer isolar. Uma agência cria um por cliente; um SaaS pode separar produção e homologação; uma empresa com dois sistemas dá a cada um o seu.

Cada número conectado ocupa um dos números contratados pela organização, não importa em qual projeto esteja. Com todos em uso, criar mais uma conexão responde 402 com code: number_limit_reached, e basta aumentar a quantidade na assinatura: o número extra fica disponível na hora, com o restante do mês cobrado de forma proporcional.

Um webhook e chaves próprias por projeto

Todos os números de um projeto enviam os eventos para o endereço de webhook daquele projeto, assinados com o segredo daquele projeto. Um cliente da agência nunca recebe as mensagens de outro, e trocar o servidor de um sistema não mexe nos demais. O campo tenantId de cada evento diz de qual projeto ele veio, e o connectionId, de qual número. Os detalhes da entrega estão na página de webhooks assinados.

As chaves também pertencem a um projeto só. Uma chave do projeto A não enxerga, não envia e não configura nada no projeto B. Se a chave de um cliente vazar, o estrago fica restrito a ele, e você a revoga sem tocar nos outros.

Chaves com escopo: cada sistema com o mínimo que precisa

Cada chave é criada com a lista de escopos que pode usar. Uma chamada fora deles responde 403, com o escopo que faltou na mensagem de erro:

EscopoO que libera
connections:readVer conexões e o status de cada número
connections:writeCriar conexões e receber o QR code e o código de pareamento
messages:sendColocar mensagens na fila de envio
templates:writeCriar e editar templates de mensagem
webhooks:writeConfigurar o webhook do projeto e o segredo de assinatura
logs:readConsultar o histórico de mensagens e de entregas de webhook
usage:readConsultar o uso
keys:read, keys:writeListar e gerenciar as chaves do projeto

Na prática, isso muda o tamanho do risco. O serviço que só dispara confirmações de pedido recebe uma chave com messages:send e mais nada. A tela do seu produto que mostra se o número está conectado usa connections:read, que vê o status mas recebe o QR code como null: escanear o QR conecta um número, então só uma chave com connections:write o recebe.

Uma chave nunca cria outra mais poderosa do que ela. Uma chave com keys:write só cria, revoga ou rotaciona chaves com escopos que ela mesma tem, e uma chave com validade só cria chaves que expiram até a mesma data.

Como a chave é enviada e guardada

A chave tem o formato wag_live_… e aparece uma única vez, na criação. A apiwpp guarda só um hash dela; nas listagens aparece mascarada, com o prefixo e reticências. Guarde-a num cofre de segredos ou numa variável de ambiente, nunca no código nem no repositório.

Em cada requisição, envie a chave no cabeçalho Authorization: Bearer ou em X-Api-Key. Para conferir o que uma chave alcança, chame GET /me, que responde a organização, os escopos e os projetos:

curl -s https://api.apiwpp.com/me -H "Authorization: Bearer $APIWPP_KEY"

Uma chave errada, revogada ou expirada responde 401. A revogação vale a partir da próxima requisição, sem cache, e você pode dar uma data de validade à chave na criação. A API também limita as tentativas: 600 requisições por minuto por IP de origem e 20 autenticações com falha a cada 5 minutos.

Rotação sem downtime

Trocar uma chave em produção costuma ser o momento em que algo quebra: você cria a nova, e até o deploy terminar, o sistema continua mandando a antiga. Por isso a rotação da apiwpp tem uma janela de sobreposição. Ao rotacionar, a API devolve uma chave nova, com o mesmo nome, os mesmos escopos e a mesma validade, e a antiga continua funcionando até o fim da janela: 24 horas por padrão, até 7 dias, ou zero para cortá-la na hora se ela vazou.

curl -s -X POST "https://api.apiwpp.com/tenants/$TENANT_ID/api-keys/$KEY_ID/rotate" \
  -H "Authorization: Bearer $APIWPP_ADMIN_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"overlapSeconds": 86400}'

Nesse intervalo você atualiza o segredo, faz o deploy e confere que as chamadas já usam a chave nova. Cada chave é rotacionada uma vez só: um clique duplo ou uma retentativa do seu cliente HTTP responde 409 em vez de deixar chaves extras ativas.

O painel e os registros

No painel você vê os projetos, conecta números por QR code e cria, rotaciona e revoga chaves. Ali também ficam os registros de mensagens e de entregas de webhook de cada projeto, guardados por 7 dias por padrão: o status de cada envio, e a resposta HTTP que o seu servidor deu a cada evento. Os mesmos dados saem pela API com uma chave logs:read, como GET /messages?q=<clientRef> para achar um envio pelo identificador do seu sistema, e as entregas de webhook que falharam podem ser reenviadas pela API.

Quem opera vários clientes encontra o fluxo completo na página de API de WhatsApp para agências e no artigo sobre como agências gerenciam dezenas de números. Os preços por número estão em preços, e as outras proteções da conta em segurança.

Perguntas frequentes

Projetos custam alguma coisa?

Não. A cobrança é por número conectado, por mês, numa assinatura só da organização. Cada organização pode ter até 20 projetos por padrão, e os números de todos eles entram na mesma fatura, paga por PIX, boleto ou cartão.

Posso usar a mesma chave de API em dois projetos?

Não. Cada chave pertence a um projeto só e não alcança os outros. Para integrar um sistema com dois projetos, crie uma chave em cada um, cada qual com os escopos de que aquele sistema precisa.

O que acontece se uma chave vazar?

Revogue-a no painel ou pela API: a partir da próxima requisição ela responde 401. Se o sistema que a usa não pode parar, rotacione com uma janela de sobreposição curta, ou zero para cortar a chave antiga na hora, e atualize o segredo no deploy seguinte.

Quais escopos uma chave de envio precisa?

Para enviar mensagens basta messages:send. Se o mesmo sistema mostra o status do número, acrescente connections:read; se ele exibe o QR code para o seu cliente parear, connections:write. Evite dar keys:write a sistemas que só enviam.

Todos: Recursos →

Cada evento do número chega no seu servidor com um POST assinado com HMAC-SHA256. A entrega é feita pelo menos uma vez, com novas tentativas, registro de cada entrega e reenvio.

A API inteira está descrita numa especificação OpenAPI 3.1 pública, com referência interativa em português. Dela saem clientes TypeScript e PHP tipados, e você pode gerar os tipos no seu próprio projeto.

Cada número sai para o WhatsApp por um IP brasileiro de provedor de internet, compartilhado só com números do mesmo cliente. Você pode trocar pelo seu próprio proxy ou, no plano PRO, contratar um IP só para um número.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.