# Criar conexão no projeto

Fonte: https://apiwpp.com/docs/api/projetos/criar-conexao-no-projeto
Seção: Projetos
Atualizado em: 2026-09-28

`POST /tenants/{id}/connections`

Como [`POST /connections`](https://apiwpp.com/docs/api/conexoes/criar-conexao), para o projeto do caminho: cria uma conexão de WhatsApp e já inicia o pareamento. Se o `externalId` já indica uma conexão do projeto, conecta essa em vez de criar outra. A resposta é a conexão no formato de `GET /tenants/{id}/connections` (sem `tenantName`, com `status` em minúsculas). Escopo necessário: `connections:write`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |
| `Content-Type` | sim | `application/json` |

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string · uuid` | sim | Identificador do projeto (`tenantId`). |

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `externalId` | `string` | não | Seu identificador da conexão (por exemplo, o id da loja ou do cliente no seu sistema). Volta como `externalId` em todos os webhooks da conexão. Se o projeto já tem uma conexão com esse valor, ela é conectada em vez de uma nova ser criada. |
| `proxy` | `object \| null` | não | Proxy próprio da conexão, no mesmo formato de [`PUT /connections/{id}/proxy`](https://apiwpp.com/docs/api/conexoes/definir-proxy): o socket e os envios e downloads de mídia saem por ele desde o primeiro. |
| `proxy.url` | `string` | sim | URL do proxy: `socks5://` ou `socks5h://` (nos dois, o proxy resolve os nomes), `http://` ou `https://` (HTTP CONNECT), com `usuário:senha@` opcional; só esquema, credenciais, host e porta. Só de escrita: as respostas nunca trazem a URL nem as credenciais. (de 1 a 2048 caracteres) |
| `proxy.country` | `string \| null` | não | País por onde o proxy precisa sair (ISO 3166-1 alfa-2, como `BR`), conferido antes do pareamento; ausente ou `null`: qualquer país. (formato `^[A-Za-z]{2}$`) |

## Exemplo de requisição

### cURL

```bash
curl -X POST \
  https://api.apiwpp.com/tenants/$TENANT_ID/connections \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "shop-42"
  }'
```

### Node.js

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

### PHP

```php
$response = Http::withToken($apiKey)
    ->post("https://api.apiwpp.com/tenants/{$tenantId}/connections", [
        'externalId' => 'shop-42',
    ]);
```

### Python

```python
import requests

response = requests.post(
    f"https://api.apiwpp.com/tenants/{tenant_id}/connections",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "externalId": "shop-42",
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | A conexão criada (ou a que o `externalId` indica), com `status` `pending` até o número ser pareado. |
| 400 |  | A `proxy.url` é inválida (esquema diferente de `socks5`, `socks5h`, `http` ou `https`, com caminho, longa demais, ou com um host que resolve para um endereço não público), ou `proxy.country` não é um código de duas letras. Nada foi criado. |
| 400 |  | A conexão não pôde ser iniciada: por exemplo, o projeto está inativo (`Tenant is inactive`). `error` diz o motivo. |
| 400 | `FST_ERR_VALIDATION` | O corpo não segue o schema da operação, ou `id` não é um UUID; `message` diz o que está errado. |
| 401 |  | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. A chave de um projeto desativado também responde `401`. |
| 402 | `subscription_inactive` | A organização dona do projeto não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. O corpo traz `error` e `code`; regularize a assinatura no painel. |
| 402 | `number_limit_reached` | A organização já usa todos os números que contratou: exclua uma conexão ou contrate mais números. O corpo traz `error` e `code`. |
| 403 |  | A chave não tem o escopo `connections:write`; a mensagem de erro cita o escopo que falta. |
| 404 |  | O projeto não existe ou não é de quem chama (`Tenant not found`): uma chave de API alcança só o próprio projeto, e o de outra pessoa responde igual a um que não existe. |
| 422 |  | A verificação pelo proxy falhou: ele não conectou, ou saiu por um país diferente de `proxy.country`. Nada foi criado. |
| 429 |  | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de `Retry-After`. Veja [Limites](https://apiwpp.com/docs/referencia/limites). Cabeçalhos: `Retry-After`. |
| 500 |  | A conexão foi iniciada, mas não foi encontrada no banco logo depois (`Connection created but not persisted`). Repita com o mesmo `externalId`: se a conexão existir, ela é conectada em vez de uma nova ser criada. |
| 501 | `unsupported_by_provider` | O provedor da conexão não aceita isso: por exemplo, um `proxy` para a conexão que o `externalId` indica, quando ela roda num provedor que não mantém uma sessão própria. |
| 503 |  | Este gateway não pode guardar URLs de proxy, porque não há uma chave de criptografia configurada. Nada foi criado. |
| 503 |  | A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere os segundos de `Retry-After` e tente de novo. |

### 200 OK

```json
{
  "id": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "status": "pending",
  "phoneNumber": null,
  "lastHeartbeat": null,
  "lastConnectedAt": null,
  "createdAt": "2026-09-24T12:00:00.000Z"
}
```

## Detalhes

Cada conexão ocupa um dos números que a organização do projeto contratou até ser excluída: além deles, `402 number_limit_reached`. Conectar a conexão que um `externalId` indica não ocupa outro número.

Com `proxy`, ele é verificado antes de qualquer coisa (`400`, `422` ou `503` quando recusado, e nada é criado) e gravado antes do primeiro socket: nem o primeiro QR code sai por fora dele. Veja [Proxy e IP dedicado](https://apiwpp.com/docs/guias/proxy-e-ip-dedicado).

Depois, pareie o número com o QR code de [`GET /tenants/{id}/connections/{connId}/qr`](https://apiwpp.com/docs/api/projetos/qr-code-como-imagem) ou com o código de [`POST /connections/{id}/pairing-code`](https://apiwpp.com/docs/api/conexoes/codigo-de-pareamento). Veja [Parear um número](https://apiwpp.com/docs/guias/parear-um-numero).

Guia: [Projetos e conexões](https://apiwpp.com/docs/guias/projetos-e-conexoes).
