# Criar conexão

Fonte: https://apiwpp.com/docs/api/conexoes/criar-conexao
Seção: Conexões
Atualizado em: 2026-09-28

`POST /connections`

Cria uma conexão de WhatsApp num projeto e devolve o `connectionId` para parear um número com o QR code ou com o código de pareamento. Se o projeto já tem uma conexão com o mesmo `externalId`, nada é criado: essa conexão é conectada de novo e o `connectionId` dela volta. 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` |

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `tenantId` | `string · uuid` | sim | Identificador do projeto (`tenantId`) em que a conexão é criada. O projeto precisa ser de quem chama e estar ativo. |
| `externalId` | `string` | não | Seu identificador para a conexão (por exemplo, o id da loja ou do cliente no seu sistema). Volta como `externalId` no envelope de todos os webhooks da conexão. Se o projeto já tem uma conexão com esse `externalId`, ela é conectada de novo em vez de uma nova ser criada. |
| `proxy` | `object \| null` | não | Um proxy seu para a conexão, no mesmo formato de `PUT /connections/{id}/proxy`: o socket do WhatsApp e os uploads e downloads de mídia dela saem por ele desde o primeiro socket. Omitido ou `null`: sem proxy próprio. |
| `proxy.url` | `string` | sim | URL do proxy: `socks5://`, `socks5h://` (nos dois, é o proxy que resolve os nomes de host), `http://` ou `https://` (os dois últimos por HTTP CONNECT), com `usuario:senha@` opcional. Só esquema, credenciais, host e porta, sem caminho, query ou fragmento; o host precisa ser público. É gravada criptografada e nunca volta em nenhuma resposta. (de 1 a 2048 caracteres) |
| `proxy.country` | `string \| null` | não | País de onde o proxy precisa sair, em ISO 3166-1 alfa-2 (por exemplo, `BR`). Omitido ou `null`: qualquer país. (formato `^[A-Za-z]{2}$`) |

## Exemplo de requisição

### cURL

```bash
curl -X POST \
  https://api.apiwpp.com/connections \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
    "externalId": "loja-42"
  }'
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/connections`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tenantId: '3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61',
    externalId: 'loja-42',
  }),
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->post("https://api.apiwpp.com/connections", [
        'tenantId' => '3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61',
        'externalId' => 'loja-42',
    ]);
```

### Python

```python
import requests

response = requests.post(
    "https://api.apiwpp.com/connections",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
        "externalId": "loja-42",
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | A conexão foi criada (ou a do `externalId` foi conectada de novo). Traz `connectionId` e `externalId`; pareie com o QR code ou com o código de pareamento. |
| 400 |  | O projeto está inativo (`Tenant is inactive: …`), ou a conexão não pôde ser iniciada; `error` diz por quê. |
| 400 |  | A URL do proxy não é aceita: não é uma URL, o esquema não é `socks5`, `socks5h`, `http` ou `https`, tem caminho, query ou fragmento, tem senha sem usuário, o host não é público, ou `country` não tem duas letras. |
| 400 | `FST_ERR_VALIDATION` | A requisição não segue o schema da operação (por exemplo, um `id` que não é um UUID); `message` diz o que está errado. |
| 401 |  | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. O corpo é `{"error": "Unauthorized"}`. |
| 402 | `number_limit_reached` | A organização já tem todos os números que contratou (`The organization holds its N number(s)…`): exclua uma conexão ou contrate mais números. |
| 402 | `subscription_inactive` | A organização dona da conexão não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Pague para voltar a usar. |
| 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: o de outra pessoa responde exatamente como um que não existe. |
| 422 |  | A verificação pelo proxy falhou, e a mensagem diz só como: o proxy não foi alcançado ou não alcançou o serviço que informa o IP de saída (`the proxy could not be reached…`, inclusive por tempo esgotado), recusou as credenciais (`the proxy refused the credentials`), não disse de onde sai (`the IP echo endpoint did not tell where the proxy exits`) ou sai em outro país que não o de `country`. |
| 429 |  | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de `Retry-After`. Cabeçalhos: `Retry-After`. |
| 501 | `unsupported_by_provider` | O provedor da conexão não faz esta operação: por exemplo, a conexão que o `externalId` indica roda num provedor que não usa proxy, e o corpo trouxe um `proxy`. |
| 503 |  | Com `proxy`: este gateway não consegue guardar URLs de proxy, porque nenhuma chave de criptografia está configurada. Nada é 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
{
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "externalId": "shop-42"
}
```

## Detalhes

Cada conexão ocupa um dos números que a organização do projeto contratou, até ser excluída. Passando disso, a resposta é `402` com `code: number_limit_reached`; conectar de novo a conexão que um `externalId` indica não ocupa outro número.

Com `proxy`, o proxy é verificado antes de qualquer coisa ser criada (`400`, `422` ou `503` quando recusado, e nada é criado) e gravado antes do primeiro socket: nem o primeiro QR code sai por fora dele. Com o `externalId` de uma conexão que já existe, o proxy dela é trocado, e um socket ativo se reconecta por ele. Veja [Proxy e IP dedicado](https://apiwpp.com/docs/guias/proxy-e-ip-dedicado).

Depois de criar, mostre o QR code com [GET /connections/{id}/qr](https://apiwpp.com/docs/api/conexoes/qr-code-e-status) ou peça um código com [POST /connections/{id}/pairing-code](https://apiwpp.com/docs/api/conexoes/codigo-de-pareamento). O webhook `connection.status` com `status: open` avisa quando o número foi pareado.

`POST /tenants/{id}/connections` faz o mesmo com o projeto no caminho (veja [Criar conexão no projeto](https://apiwpp.com/docs/api/projetos/criar-conexao-no-projeto)).

Guia: [Parear um número](https://apiwpp.com/docs/guias/parear-um-numero).
