> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/numbers — Criar um Número

> Crie um número de WhatsApp via API — QR code / código de pareamento para números não oficiais, fluxos do provedor META, regenerar QR e excluir.

# Criar, conectar e excluir números

Crie um número de WhatsApp via API pública, conecte-o (QR code ou código de pareamento) e exclua-o quando não for mais necessário.

<Note>
  Use uma chave de API **com escopo de tenant** (recomendada para plataformas SaaS que gerenciam múltiplos números). Uma chave com escopo de número também funciona, com o comportamento de `linkToApiKey` descrito abaixo. Autentique com `x-api-key: ps_...`.
</Note>

## POST /v1/numbers — Criar um número

```bash theme={null}
curl -X POST "https://pilotstatus.com.br/v1/numbers" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_token_here" \
  -d '{
    "name": "My WhatsApp",
    "number": "+5511999999999",
    "linkToApiKey": true
  }'
```

<ParamField body="name" type="string" required>
  Nome de exibição do número.
</ParamField>

<ParamField body="number" type="string" required>
  O número de telefone no formato E.164 (ex.: `+5511999999999`).
</ParamField>

<ParamField body="linkToApiKey" default="true" type="boolean">
  Afeta **apenas chaves com escopo de número**. Quando você cria um número com uma chave com escopo de número e `linkToApiKey` é true, essa chave é reapontada para o novo número, de modo que os envios sejam roteados para ele. Com uma chave **com escopo de tenant**, o parâmetro não tem efeito — uma chave com escopo de tenant nunca é vinculada (`linkedApiKeyId: null`).
</ParamField>

A resposta inclui `qrcodeBase64` e `pairingCode` (código de pareamento por letras do WhatsApp; pode ser `null` se o provedor não retornar um). Mostre o QR code para a pessoa dona do telefone, ou deixe-a digitar o código de pareamento.

<Warning>
  Chame estes endpoints apenas a partir do seu **backend** — nunca exponha sua chave `ps_` no navegador.
</Warning>

### Números Meta (API oficial da Cloud)

`POST /v1/numbers` cria um número **não oficial (pareado por QR)**. Para números oficiais da Meta Cloud API, use um dos fluxos Meta em vez disso:

* `POST /v1/numbers/meta` — BYO-WABA direto: traga suas próprias credenciais de WABA, ou
* Meta Embedded Signup hospedado via um [link de pareamento remoto](/pt-BR/api/numbers/remote-pairing) com `metaFlow`.

### POST /v1/numbers/meta — traga sua própria WABA

Provisiona um **número oficial da Meta Cloud API** a partir de credenciais de WABA que você já possui. Este fluxo é para plataformas que já controlam a WABA e têm um **token de system user**. Se você não tem essas credenciais, use o Embedded Signup hospedado via um [link de pareamento remoto](/pt-BR/api/numbers/remote-pairing) com `provider=META`.

Exige uma chave de API **com escopo de tenant**.

```bash theme={null}
curl -X POST "https://pilotstatus.com.br/v1/numbers/meta" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_token_here" \
  -d '{
    "name": "My Official Number",
    "number": "+5511999999999",
    "metaPhoneId": "123456789012345",
    "metaWabaId": "987654321098765",
    "metaAccessToken": "EAAG...",
    "metaAppSecret": "your_meta_app_secret",
    "metaAppId": "112233445566778"
  }'
```

<ParamField body="name" type="string" required>
  Nome de exibição do número (1–60 caracteres).
</ParamField>

<ParamField body="number" type="string" required>
  O número de telefone em dígitos, com `+` inicial opcional.
</ParamField>

<ParamField body="metaPhoneId" type="string" required>
  O **phone number ID** da Meta do telefone da WABA.
</ParamField>

<ParamField body="metaWabaId" type="string" required>
  O **ID da WhatsApp Business Account (WABA)**.
</ParamField>

<ParamField body="metaAccessToken" type="string" required>
  Um **token de acesso de system user** com acesso à WABA.
</ParamField>

<ParamField body="metaAppSecret" type="string" required>
  O app secret do seu app Meta.
</ParamField>

<ParamField body="metaAppId" type="string" required>
  O ID do seu app Meta.
</ParamField>

<ParamField body="linkToApiKey" type="boolean">
  Opcional — mesma semântica de `linkToApiKey` do `POST /v1/numbers` acima.
</ParamField>

Erros:

* `400` — erro de validação (campos do corpo ausentes ou inválidos).
* `403 NUMBERS_GRANT_NOT_ALLOWED` — grants OAuth por número não podem provisionar números.
* `409` — "Number already exists" (o número já existe).

## GET /v1/numbers/{id}/connect — Regenerar o QR code

Gera um **novo QR code e código de pareamento** quando a instância não está `OPEN`.

```bash theme={null}
curl "https://pilotstatus.com.br/v1/numbers/wa_abc/connect" \
  -H "x-api-key: ps_your_token_here"
```

* A resposta inclui `qrcodeBase64` e `pairingCode` novos.
* Se o número já estiver conectado (`OPEN`), o endpoint retorna **409** — não há nada para parear.
* Não se aplica a números **Meta** (eles não usam pareamento por QR).
* Reflete o mesmo estado de conexão que a página de Números no painel.

## DELETE /v1/numbers/{id} — Remover um número

```bash theme={null}
curl -X DELETE "https://pilotstatus.com.br/v1/numbers/wa_abc" \
  -H "x-api-key: ps_your_token_here"
```

Remove o registro da Pilot Status e tenta encerrar ou remover a sessão de WhatsApp associada quando aplicável (HTTP 404 das etapas de limpeza é ignorado).

## Webhooks relacionados

* `number.created` — dispara quando a instância é criada.
* `number.connected` — dispara quando o cliente completa a conexão via QR / pareamento (estado `OPEN`).
* `number.removed` — dispara na exclusão.

Consulte a [referência de eventos de webhook](/pt-BR/api/webhooks/events).