​

Criar, conectar e excluir números

​

POST /v1/numbers — Criar um número

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

​

Números Meta (API oficial da Cloud)

• 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 com metaFlow.

​

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

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

• 400 — erro de validação (campos do corpo ausentes ou inválidos).
• 402 PLAN_NUMBER_LIMIT_REACHED — a cota de números do seu plano está cheia. No plano Free, adicionar créditos não resolve: libere um slot, compre um número extra por conta própria ou suba de plano. Em um plano pago, só é respondido quando você nunca comprou um número extra e o próximo não pode ser custeado.
• 402 INSUFFICIENT_FUNDS — só nos planos pagos: o número seria um extra pago e não há saldo na carteira nem cartão salvo.
• 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).

​

Erros de capacidade e como resolver

{
  "error": "PLAN_NUMBER_LIMIT_REACHED",
  "plan": "FREE",
  "maxNumbers": 1,
  "currentNumberCount": 1,
  "extras": 1,
  "proratedTotal": 14.95,
  "walletBalance": 0,
  "currency": "BRL"
}

​

Entrega de webhook (mensagens recebidas)

{
  "webhook": {
    "url": "https://webhook.pilotstatus.com.br/api/meta/webhook",
    "verifyToken": "…",
    "routedToPilot": false
  }
}

• Automática — passe routeWebhooksToPilot: true na requisição. A Pilot inscreve a WABA para você e a resposta retorna webhook.routedToPilot: true; nada mais a configurar.
• Manual — no seu Meta App Dashboard, defina a Callback URL do produto WhatsApp como webhook.url e o Verify token como webhook.verifyToken.

​

GET /v1/numbers//connect — Regenerar o QR code

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.
• Plano Free: quando a cota do plano já está cheia e este número nunca conectou, o endpoint retorna 402 com { "error": "PLAN_NUMBER_LIMIT_REACHED", "code": "PLAN_NUMBER_LIMIT_REACHED", "message": "…", "plan": "FREE", "maxNumbers": 1, "currentNumberCount": 1 }, e nenhum QR code é gerado. O message é uma frase bilíngue, English | Português. Reparear um número que já tinha conectado nunca é recusado. Veja Plano Free.
• 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/ — Remover um número

curl -X DELETE "https://pilotstatus.com.br/v1/numbers/wa_abc" \
  -H "x-api-key: ps_your_token_here"

{ "ok": true, "restorableUntil": "2026-10-23T12:33:06.604Z" }

• O aparelho pareado é desconectado na hora — o número para de enviar e receber.
• O número em si (id, API keys, webhooks, histórico de mensagens) fica guardado até restorableUntil e depois é apagado de vez por um job.
• Enquanto está nessa janela, criar o mesmo telefone de novo com POST /v1/numbers devolve 409 NUMBER_SOFT_DELETED (o corpo traz o numberId antigo). Restaure-o, ou purgue antes.

​

POST /v1/numbers//restore — Desfazer a exclusão

curl -X POST "https://pilotstatus.com.br/v1/numbers/wa_abc/restore" \
  -H "x-api-key: ps_sua_chave_de_tenant"

{ "ok": true, "requiresReconnect": true }

• 404 com code: RESTORE_WINDOW_EXPIRED depois dos 30 dias.
• 409 NUMBER_ALREADY_ACTIVE quando o mesmo telefone foi reconectado nesse meio-tempo — use o número ativo.
• Restaurar um número que já tinha conectado pode cobrar. Esse número volta a entrar na sua contagem de números. Se isso leva o workspace acima da capacidade que ele já pagou, um número extra é cobrado no restore, com prorata do resto do ciclo. Quando isso não pode ser pago, a resposta é 422 INSUFFICIENT_FUNDS (ou PLAN_NUMBER_LIMIT_REACHED) com proratedTotal e walletBalance, nada é cobrado e o número continua excluído. Repetir o mesmo restore nunca cobra duas vezes.
• Um número que nunca conectou não custa nada para restaurar. Ele ainda não conta, e é cobrado na primeira conexão, como qualquer outro.

​

DELETE /v1/numbers//purge — Excluir de forma permanente

curl -X DELETE "https://pilotstatus.com.br/v1/numbers/wa_abc/purge" \
  -H "x-api-key: ps_sua_chave_de_tenant"

{ "ok": true }

• Funciona com um número já excluído com DELETE /v1/numbers/{id} — o fluxo comum é excluir e depois purgar — ou com um ativo.
• Use quando o mesmo telefone precisa ser criado de novo em seguida (o caso do 409 NUMBER_SOFT_DELETED).
• Não economiza nada na cobrança em relação ao DELETE.
• Chame com uma key de tenant. A key presa ao número excluído deixa de autenticar assim que ele é excluído.
• Com token OAuth / MCP, só o OWNER do workspace pode purgar (403 PERMISSION_DENIED caso contrário).

​

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.
• number.restored — dispara quando um número excluído é restaurado dentro da janela de 30 dias (por esta rota ou pelo painel). O número volta desconectado.