Pular para o conteúdo

Projetos e conexões

Como organização, projeto e conexão se relacionam, o que você configura no projeto pela API e o ciclo de vida de um número: criar, desconectar, sair e excluir.

Ver em Markdown

Tudo na apiwpp pertence a uma organização, a conta do painel. Dentro dela ficam os projetos (o tenant da API): cada projeto é um sistema seu, com o próprio endereço de webhook e as próprias chaves de API. Cada conexão é um número de WhatsApp de um projeto.

NívelNa APIO que guarda
OrganizaçãoorganizationIdO plano, a assinatura e os números contratados, que valem para todos os projetos dela.
Projetotenant, tenantIdO webhook (endereço, token, cabeçalhos, segredo de assinatura), as chaves de API e as conexões.
Conexãoconnection, connectionIdUm número de WhatsApp: a sessão, a fila de envio, os templates e o histórico.

Uma chave de API pertence a um único projeto: ela só enxerga esse projeto e as conexões dele. Para trabalhar com outro projeto, crie uma chave nele (veja Autenticação).

Consultar o projeto

GET /tenants lista os projetos que a credencial alcança (com uma chave de API, o projeto dela), e GET /tenants/{id} devolve um projeto com o número de conexões. As duas pedem o escopo connections:read.

bashVer na referência
curl -s https://api.apiwpp.com/tenants/$TENANT_ID -H "Authorization: Bearer $API_KEY"
200
{
  "id": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
  "name": "acme-crm",
  "webhookBaseUrl": "https://crm.example.com/api/whatsapp/events",
  "webhookHeaderNames": ["X-Crm-Account"],
  "emitOutgoing": true,
  "maxPerMinute": null,
  "maxPerHour": null,
  "maxPerDay": null,
  "hasWebhookSecret": true,
  "planId": "b7e2c9d4-1f3a-4c5b-8d6e-9f0a1b2c3d4e",
  "subscriptionStatus": "active",
  "trialEndsAt": null,
  "currentPeriodEnd": "2026-10-24T12:00:00.000Z",
  "isActive": true,
  "createdAt": "2026-09-01T12:00:00.000Z",
  "updatedAt": "2026-09-24T12:00:00.000Z",
  "connectionCount": 1
}

As credenciais do webhook nunca voltam na resposta: o token não aparece, o segredo vira hasWebhookSecret e dos cabeçalhos só vêm os nomes, em webhookHeaderNames. planId, subscriptionStatus, trialEndsAt e currentPeriodEnd são da organização, iguais em todos os projetos dela.

Configurar o webhook do projeto

PATCH /tenants/{id}, com o escopo webhooks:write, muda a configuração de webhook do projeto. Envie só os campos que quer mudar; a resposta é o projeto atualizado, no formato de GET /tenants/{id}.

CampoTipoDescrição
webhookBaseUrlstringO endereço que recebe os eventos. Conferido quando muda: https, sem usuário e senha na URL, e o host precisa resolver só para endereços públicos. Senão, 400.
webhookTokenstringEnviado em toda entrega no cabeçalho X-Webhook-Token. Nunca é devolvido.
webhookHeadersobjeto ou nullCabeçalhos extras de toda entrega, de nome para valor. Substitui os anteriores; null remove todos. Só os nomes são devolvidos.
webhookSecretstring ou nullO segredo da assinatura HMAC (X-Sales-Signature). null ou "" desliga a assinatura. Nunca é devolvido.
emitOutgoingbooleanAtiva o evento message.outgoing para as mensagens que o número envia.

A mudança vale para as próximas entregas de todas as conexões do projeto.

curl -s -X PATCH https://api.apiwpp.com/tenants/$TENANT_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhookBaseUrl": "https://crm.example.com/api/whatsapp/events", "emitOutgoing": true}'

Antes de trocar o endereço, teste o novo com POST /tenants/webhook-test: ele envia um evento ping assinado, com as mesmas regras e o mesmo limite de 10 segundos das entregas reais, e não salva nada. Com o tenantId, a assinatura usa o segredo guardado do projeto; o token e os cabeçalhos guardados só são reaproveitados se o webhookBaseUrl for o mesmo que está salvo, e para outro endereço o webhookToken é obrigatório.

bashVer na referência
curl -s -X POST https://api.apiwpp.com/tenants/webhook-test \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhookBaseUrl": "https://crm.example.com/api/whatsapp/events", "webhookToken": "'$WEBHOOK_TOKEN'", "tenantId": "'$TENANT_ID'"}'
200
{ "ok": true, "status": 200, "latencyMs": 184, "error": null }

O guia Webhooks e assinatura mostra como o seu servidor confere a assinatura e o que acontece quando ele não responde.

Desativar o projeto

DELETE /tenants/{id}, com o escopo connections:write, desativa o projeto e responde { "deleted": true }. Nada é apagado: as conexões são desconectadas com as sessões preservadas.

Um projeto inativo:

  • não recebe webhooks;
  • não aparece nas conexões de GET /connections;
  • não aceita chaves de API: todas as chaves do projeto passam a responder 401, inclusive a que fez a chamada, e criar uma chave nele responde 409.

Criar uma conexão

Há dois caminhos para criar uma conexão, ambos com o escopo connections:write:

  • POST /connections, com o projeto no corpo (tenantId, obrigatório), responde só { connectionId, externalId }.
  • POST /tenants/{id}/connections, com o projeto no caminho, responde a conexão completa, como GET /tenants/{id}/connections a lista.

Os dois aceitam externalId, o seu identificador para o número (por exemplo, o id do cliente no seu sistema). Se o projeto já tem uma conexão com esse externalId, a API conecta essa em vez de criar outra, e ela não ocupa mais um número. O externalId volta no envelope de todos os eventos da conexão. Os dois aceitam também um proxy opcional, conferido antes de a conexão ser criada (veja Proxy e IP dedicado).

curl -s -X POST https://api.apiwpp.com/connections \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenantId": "'$TENANT_ID'", "externalId": "shop-42"}'
200
{ "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f", "externalId": "shop-42" }

A conexão nasce aguardando o pareamento: siga com o QR code ou com o código de pareamento, em Parear um número.

Números contratados. Cada conexão ocupa um dos números que a organização contratou, somando todos os projetos, qualquer que seja o status dela, até ser excluída. Desconectar ou sair do WhatsApp não libera o número. Além do contratado, a resposta é 402 com code: number_limit_reached.

StatuscodeQuando
400—Falta o tenantId, a verificação do proxy recusou a URL, ou a conexão não pôde ser iniciada.
402number_limit_reachedTodos os números contratados estão em uso.
402subscription_inactiveO teste acabou ou uma fatura venceu e passou da carência.
404—O projeto não existe ou não é seu.
422—A verificação através do proxy falhou; nada foi criado.
501unsupported_by_providerO provedor da conexão não oferece a operação (vem no campo error).
503—A conexão está mudando de instância (com Retry-After), ou o servidor não pode guardar URLs de proxy.

Listar e consultar conexões

  • GET /connections lista as conexões dos projetos ativos da credencial, das mais novas para as mais antigas, com o status atual em minúsculas (open, close…). As conexões failed ficam de fora, a menos que você passe includeFailed=true.
  • GET /tenants/{id}/connections lista as conexões de um projeto, com o status gravado, em maiúsculas (OPEN, CLOSE…).
  • GET /tenants/{id}/connections/{connId} devolve uma conexão com os 50 eventos mais recentes dela (CONNECTED, DISCONNECTED, LOGGED_OUT e outros; os heartbeats bem-sucedidos ficam de fora), do mais novo para o mais antigo. É o primeiro lugar para entender por que um número caiu.

Todas pedem o escopo connections:read. Os status possíveis de uma conexão e o que fazer em cada um estão em Parear um número.

Histórico de heartbeats

A apiwpp confere periodicamente se cada conexão aberta está viva. GET /tenants/{id}/connections/{connId}/heartbeats devolve esse histórico em intervalos de meia hora alinhados ao relógio, do mais antigo ao atual (parcial). O parâmetro hours, de 1 a 168 (padrão 24), escolhe o período.

bashVer na referência
curl -s "https://api.apiwpp.com/tenants/$TENANT_ID/connections/$CONNECTION_ID/heartbeats?hours=48" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "buckets": [
    { "start": "2026-09-24T11:00:00.000Z", "ok": true },
    { "start": "2026-09-24T11:30:00.000Z", "ok": false },
    { "start": "2026-09-24T12:00:00.000Z", "ok": null }
  ],
  "uptimePct": 50
}

Em cada intervalo, ok é false se algum heartbeat falhou, true se só houve sucessos e null sem dados. uptimePct é a porcentagem de intervalos true entre os que têm dados, com uma casa decimal, ou null quando nenhum tem.

Desconectar, reconectar, sair e excluir

AçãoOperaçãoA sessãoO número contratado
DesconectarPOST /connections/{id}/disconnect ou POST /tenants/{id}/connections/{connId}/disconnectPreservadaContinua ocupado
ReconectarPOST /tenants/{id}/connections/{connId}/connectUsada, se existirContinua ocupado
Sair do WhatsAppPOST /connections/{id}/logoutApagadaContinua ocupado
ExcluirDELETE /tenants/{id}/connections/{connId}Apagada, com a conexãoLiberado

Todas pedem o escopo connections:write e respondem { "ok": true }.

  • Desconectar fecha a conexão com o WhatsApp e guarda a sessão: o número continua vinculado ao celular e volta sem QR code.
  • Reconectar inicia de novo uma conexão fechada. Com sessão, ela reconecta; sem sessão (depois de sair do WhatsApp), começa um pareamento novo, e o QR code aparece em GET /connections/{id}/qr. Responde 402 com subscription_inactive se a organização não está em dia, e 500 se a conexão não pôde ser iniciada.
  • Sair do WhatsApp remove o aparelho vinculado do celular e apaga a sessão. Use para trocar o número de uma conexão: saia, reconecte e pareie o número novo. Responde 404 se a conexão não existe ou se o logout falhou.
  • Excluir faz o logout e apaga a conexão com a sessão, os templates e o histórico. Se o logout falha, nada é apagado e a resposta é 409: tente de novo.

Desconectar, sair e excluir funcionam mesmo com a organização sem pagamento em dia, para que você sempre consiga liberar um número. As operações que usam a sessão do WhatsApp respondem 503 com Retry-After enquanto a conexão muda de instância: repita depois do tempo indicado.

Próximos passos

Esta página ajudou? · Atualizado em 29 set 2026