# Projetos e conexões

Fonte: https://apiwpp.com/docs/guias/projetos-e-conexoes
Seção: Guias
Atualizado em: 2026-09-29

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.

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ível | Na API | O que guarda |
| --- | --- | --- |
| Organização | `organizationId` | O plano, a assinatura e os números contratados, que valem para todos os projetos dela. |
| Projeto | `tenant`, `tenantId` | O webhook (endereço, token, cabeçalhos, segredo de assinatura), as chaves de API e as conexões. |
| Conexão | `connection`, `connectionId` | Um número de WhatsApp: a sessão, a fila de envio, os templates e o histórico. |

> **Quem cria o projeto**
>
> Por enquanto, o projeto é criado pela nossa equipe, junto com o endereço que recebe os webhooks dele (`webhookBaseUrl`): peça pelo suporte. O projeto não tem custo; a cobrança é por número conectado. Depois de criado, você mesmo configura o webhook pela API, como mostra este guia.

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](https://apiwpp.com/docs/autenticacao)).

## Consultar o projeto

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

**Consultar o projeto**

```bash
curl -s https://api.apiwpp.com/tenants/$TENANT_ID -H "Authorization: Bearer $API_KEY"
```

Resposta `200`

```json
{
  "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}`](https://apiwpp.com/docs/api/projetos/atualizar-projeto), 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}`.

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `webhookBaseUrl` | string | O 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`. |
| `webhookToken` | string | Enviado em toda entrega no cabeçalho `X-Webhook-Token`. Nunca é devolvido. |
| `webhookHeaders` | objeto ou `null` | Cabeçalhos extras de toda entrega, de nome para valor. Substitui os anteriores; `null` remove todos. Só os nomes são devolvidos. |
| `webhookSecret` | string ou `null` | O segredo da assinatura HMAC (`X-Sales-Signature`). `null` ou `""` desliga a assinatura. Nunca é devolvido. |
| `emitOutgoing` | boolean | Ativa o evento [`message.outgoing`](https://apiwpp.com/docs/webhooks/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**

```bash
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}'
```

**Node.js**

```javascript
const res = await fetch(`https://api.apiwpp.com/tenants/${tenantId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    webhookBaseUrl: 'https://crm.example.com/api/whatsapp/events',
    emitOutgoing: true,
  }),
})
const tenant = await res.json()
if (!res.ok) throw new Error(`${res.status}: ${tenant.error}`)
console.log(tenant.hasWebhookSecret, tenant.webhookHeaderNames)
```

> **O que só a nossa equipe muda**
>
> `name`, `planId`, `isActive` e os limites de envio próprios do projeto (`maxPerMinute`, `maxPerHour`, `maxPerDay`) aparecem na resposta, mas não podem ser alterados por você: enviá-los responde `403` (`Only the platform can change …`) e nada é salvo. O plano muda no painel; para o resto, fale com o suporte.

Antes de trocar o endereço, teste o novo com [`POST /tenants/webhook-test`](https://apiwpp.com/docs/api/projetos/testar-webhook): ele envia um evento [`ping`](https://apiwpp.com/docs/webhooks/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.

**Testar o endereço novo**

```bash
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'"}'
```

Resposta `200`

```json
{ "ok": true, "status": 200, "latencyMs": 184, "error": null }
```

O guia [Webhooks e assinatura](https://apiwpp.com/docs/guias/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}`](https://apiwpp.com/docs/api/projetos/desativar-projeto), 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`.

> **Só a nossa equipe reativa**
>
> Como `isActive` é só da plataforma, você não consegue reativar um projeto pela API. Para voltar a usá-lo, fale com o suporte: as sessões guardadas permitem reconectar os números sem um QR code novo.

## Criar uma conexão

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

- [`POST /connections`](https://apiwpp.com/docs/api/conexoes/criar-conexao), com o projeto no corpo (`tenantId`, obrigatório), responde só `{ connectionId, externalId }`.
- [`POST /tenants/{id}/connections`](https://apiwpp.com/docs/api/projetos/criar-conexao-no-projeto), 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](https://apiwpp.com/docs/guias/proxy-e-ip-dedicado)).

**cURL**

```bash
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"}'
```

**Node.js**

```javascript
const res = await fetch('https://api.apiwpp.com/connections', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ tenantId, externalId: 'shop-42' }),
})
const body = await res.json()

if (res.status === 402 && body.code === 'number_limit_reached') {
  // Todos os números contratados estão em uso: exclua uma conexão ou contrate mais
} else if (!res.ok) {
  throw new Error(`${res.status}: ${body.error}`)
}
const { connectionId } = body
```

Resposta `200`

```json
{ "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](https://apiwpp.com/docs/guias/parear-um-numero).

**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`.

| Status | `code` | Quando |
| --- | --- | --- |
| `400` | — | Falta o `tenantId`, a verificação do proxy recusou a URL, ou a conexão não pôde ser iniciada. |
| `402` | `number_limit_reached` | Todos os números contratados estão em uso. |
| `402` | `subscription_inactive` | O 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. |
| `501` | `unsupported_by_provider` | O 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`](https://apiwpp.com/docs/api/conexoes/listar-conexoes) 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`](https://apiwpp.com/docs/api/projetos/listar-conexoes-do-projeto) lista as conexões de um projeto, com o status gravado, em maiúsculas (`OPEN`, `CLOSE`…).
- [`GET /tenants/{id}/connections/{connId}`](https://apiwpp.com/docs/api/projetos/consultar-conexao) 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](https://apiwpp.com/docs/guias/parear-um-numero).

## Histórico de heartbeats

A apiwpp confere periodicamente se cada conexão aberta está viva. [`GET /tenants/{id}/connections/{connId}/heartbeats`](https://apiwpp.com/docs/api/projetos/historico-de-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.

**Últimas 48 horas**

```bash
curl -s "https://api.apiwpp.com/tenants/$TENANT_ID/connections/$CONNECTION_ID/heartbeats?hours=48" \
  -H "Authorization: Bearer $API_KEY"
```

Resposta `200`

```json
{
  "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ção | Operação | A sessão | O número contratado |
| --- | --- | --- | --- |
| Desconectar | [`POST /connections/{id}/disconnect`](https://apiwpp.com/docs/api/conexoes/desconectar) ou [`POST /tenants/{id}/connections/{connId}/disconnect`](https://apiwpp.com/docs/api/projetos/desconectar-conexao-do-projeto) | Preservada | Continua ocupado |
| Reconectar | [`POST /tenants/{id}/connections/{connId}/connect`](https://apiwpp.com/docs/api/projetos/reconectar-conexao) | Usada, se existir | Continua ocupado |
| Sair do WhatsApp | [`POST /connections/{id}/logout`](https://apiwpp.com/docs/api/conexoes/sair-do-whatsapp) | Apagada | Continua ocupado |
| Excluir | [`DELETE /tenants/{id}/connections/{connId}`](https://apiwpp.com/docs/api/projetos/excluir-conexao) | Apagada, com a conexão | Liberado |

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.

> **Excluir não tem volta**
>
> A exclusão apaga a conexão, a sessão, os templates e o histórico da conexão, e não pode ser desfeita. Para só parar um número por um tempo, desconecte.

## Próximos passos

- [Parear um número](https://apiwpp.com/docs/guias/parear-um-numero): QR code, código de pareamento e os status da conexão.
- [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura): receber os eventos e conferir a assinatura.
- [Autenticação](https://apiwpp.com/docs/autenticacao): as chaves de API de cada projeto e os escopos.
- [Referência: Projetos](https://apiwpp.com/docs/api/projetos/atualizar-projeto): os parâmetros e as respostas de cada operação.
