> ## 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/phone-lines/{id}/activations — Códigos de Ativação
> Obtenha o código de verificação do WhatsApp de uma linha telefônica: abra uma janela de captura de 5 minutos, peça ao WhatsApp que ligue para a linha e consulte o pedido até o código transcrito chegar.
# Obter o código de ativação do WhatsApp
O WhatsApp verifica um número fixo **ligando para ele** e falando um código de 6 dígitos. Estes endpoints capturam essa ligação para você: você abre uma janela de captura na linha telefônica, pede ao WhatsApp que ligue e lê o código — transcrito da ligação — pela API.
| Método | Endpoint | Descrição |
| ------ | -------------------------------------------- | -------------------------------------------------------------------- |
| `POST` | `/v1/phone-lines/{id}/activations` | Abre um novo pedido de código na linha (janela de 5 minutos). |
| `GET` | `/v1/phone-lines/activations/{activationId}` | Consulta um pedido: o `status` e, quando estiver pronto, o `code`. |
| `GET` | `/v1/phone-lines/{id}/activations` | O histórico de códigos da linha, do mais recente para o mais antigo. |
Exige uma chave **com escopo de tenant**. Com um token OAuth / MCP, o usuário precisa ser **Proprietário ou Administrador** (`phone_lines:read`) — caso contrário, `403 PERMISSION_DENIED`. Toda resposta que traz um pedido de código é enviada com `Cache-Control: no-store`: **o código é uma credencial** — quem o tiver pode registrar uma conta de WhatsApp na linha.
## Como funciona
`POST /v1/phone-lines/{id}/activations`. A linha é reiniciada na operadora, para que a gravação de uma ligação anterior nunca possa ser lida como o código deste pedido, e o pedido abre em `WAITING` até `pollDeadline` — **5 minutos** depois. Uma ligação que chegar antes de este pedido existir não é capturada.
Registre o número no WhatsApp Business e, quando for perguntado como receber o código, escolha a opção de receber o código por **ligação** ("Call me" no app em inglês). A linha é um número fixo e não recebe SMS — esperar por um SMS só consome a janela.
Verificamos a linha **a cada 15 segundos, aproximadamente,** enquanto a janela está aberta. Quando aparece uma gravação, nós a armazenamos (`CAPTURED`), a transcrevemos e extraímos o código (`TRANSCRIBED`).
Consulte `GET /v1/phone-lines/activations/{activationId}` a cada alguns segundos — ou aguarde o webhook [`phone_line.code_received`](/pt-BR/api/phone-lines/webhooks) — e digite o `code` no WhatsApp.
## Solicitar um código
`POST https://pilotstatus.com.br/v1/phone-lines/{id}/activations` — sem corpo. Responde **`201`** com o novo pedido.
* Permitido enquanto a linha está `ACTIVE` ou `PAYMENT_PENDING` (incluindo uma linha `ACTIVE` cancelada no fim do período). Uma linha `SUSPENDED`, `RETURNED` ou `CANCELED` recebe **409 `LINE_NOT_ACTIVE`**.
* **Um pedido em espera por linha.** Enquanto um pedido estiver em `WAITING` e seu `pollDeadline` ainda não tiver passado, outro `POST` responde **409 `ACTIVATION_IN_PROGRESS`** — em vez disso, consulte o pedido que você já tem.
* **Sem limite de pedidos ao longo do tempo.** Peça de novo sempre que precisar (um novo registro do WhatsApp, uma janela que expirou); cada pedido aberto incrementa o `activationCount` da linha.
```bash cURL theme={null}
curl -X POST "https://pilotstatus.com.br/v1/phone-lines/cmg5k2l1n0001pl8example9x/activations" \
-H "x-api-key: ps_your_tenant_scoped_key"
```
```json Resposta (201) theme={null}
{
"activation": {
"id": "cmg5k3a7c0002ac8example4q",
"lineId": "cmg5k2l1n0001pl8example9x",
"status": "WAITING",
"requestedAt": "2026-10-01T14:10:00.000Z",
"pollDeadline": "2026-10-01T14:15:00.000Z",
"code": null,
"capturedAt": null,
"transcribedAt": null,
"failureReason": null,
"hasAudio": false
}
}
```
## Consultar o pedido
`GET https://pilotstatus.com.br/v1/phone-lines/activations/{activationId}` retorna `{ "activation": { … } }`. Um pedido de outro workspace responde **404 `ACTIVATION_NOT_FOUND`**, da mesma forma que um pedido que não existe.
```bash cURL theme={null}
curl "https://pilotstatus.com.br/v1/phone-lines/activations/cmg5k3a7c0002ac8example4q" \
-H "x-api-key: ps_your_tenant_scoped_key"
```
```json Resposta (200) theme={null}
{
"activation": {
"id": "cmg5k3a7c0002ac8example4q",
"lineId": "cmg5k2l1n0001pl8example9x",
"status": "TRANSCRIBED",
"requestedAt": "2026-10-01T14:10:00.000Z",
"pollDeadline": "2026-10-01T14:15:00.000Z",
"code": "123456",
"capturedAt": "2026-10-01T14:11:42.000Z",
"transcribedAt": "2026-10-01T14:11:51.000Z",
"failureReason": null,
"hasAudio": true
}
}
```
Consultar a cada alguns segundos é suficiente: o status só pode mudar depois da nossa próxima verificação da linha, feita a cada 15 segundos.
### Status
| `status` | `code` | `failureReason` | `hasAudio` | O que significa | Próximo passo |
| ------------- | ---------- | --------------------------------------------- | :--------: | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `WAITING` | `null` | `null` | `false` | A janela está aberta e nenhuma ligação foi capturada ainda. | Continue consultando. Confira se você pediu ao WhatsApp para **ligar**. |
| `CAPTURED` | `null` | `null` | `true` | A ligação foi gravada; a transcrição está em andamento. | Continue consultando. |
| `CAPTURED` | `null` | `transcription_failed` | `true` | Gravada, mas a transcrição falhou. **Definitivo.** | Ouça a gravação no painel. |
| `TRANSCRIBED` | `"123456"` | `null` | `true` | O código foi lido. **Definitivo.** | Digite-o no WhatsApp. |
| `TRANSCRIBED` | `null` | `no_code_in_transcript` | `true` | A ligação foi transcrita, mas nenhum código de 6 dígitos foi encontrado nela. **Definitivo.** | Ouça a gravação no painel ou solicite um novo código. |
| `TIMED_OUT` | `null` | `no_call_in_window` | `false` | Nenhuma ligação foi capturada antes de `pollDeadline`. **Definitivo.** | Solicite um novo código e peça ao WhatsApp para ligar de novo. |
| `FAILED` | `null` | `audio_download_failed`, `audio_store_failed` | `false` | Uma gravação apareceu, mas não pôde ser baixada ou armazenada. **Definitivo.** | Solicite um novo código. |
| `FAILED` | `null` | `poll_not_scheduled` | `false` | Não conseguimos começar a monitorar a linha (o `POST` respondeu `503`). **Definitivo.** | Solicite um novo código — permitido imediatamente. |
**Não pare de consultar no primeiro status diferente de `WAITING`.** `CAPTURED` também é o estado intermediário enquanto a transcrição está em andamento: continue consultando enquanto `status` for `WAITING`, ou `CAPTURED` com `failureReason: null`. E `TRANSCRIBED` não garante um código — verifique `code`. A transcrição leva segundos: se um pedido ficar em `CAPTURED` com `failureReason: null` por mais de alguns minutos, trate-o como falho — ouça a gravação no painel ou solicite um novo código.
* `TIMED_OUT` é registrado na primeira verificação depois de `pollDeadline`, então pode aparecer até cerca de 15 segundos depois do prazo. Essa verificação encerra o pedido sem procurar uma gravação, então uma ligação que chegue nos últimos segundos da janela pode se perder — peça ao WhatsApp que ligue assim que o pedido estiver aberto. Se um pedido ainda estiver em `WAITING` bem depois do seu `pollDeadline`, trate-o como expirado: um novo `POST` já é permitido, porque a regra de um pedido por vez só conta pedidos cujo `pollDeadline` ainda não passou.
* `failureReason` é sempre um dos valores fixos da tabela (`no_call_in_window`, `no_code_in_transcript`, `transcription_failed`, `audio_download_failed`, `audio_store_failed`, `poll_not_scheduled`) ou `null`. Você pode tomar decisões com base nele; trate um valor desconhecido como falha, já que novos valores podem ser adicionados.
* **O código vem de reconhecimento de fala.** O WhatsApp fala o código durante a ligação; transcrevemos a gravação e ficamos com a sequência de 6 dígitos ouvida com mais frequência. Se o WhatsApp rejeitar o código, ouça a gravação no painel.
* **A gravação fica só no painel.** `hasAudio: true` só indica que existe uma gravação para ouvir em **Linhas** → a linha em questão. Não há endpoint de áudio na API pública, e a transcrição bruta nunca é retornada.
## Histórico de códigos
`GET https://pilotstatus.com.br/v1/phone-lines/{id}/activations` retorna os pedidos da linha, **do mais recente para o mais antigo**, com os códigos: `{ "activations": [ … ] }`. Também funciona em linhas suspensas — elas mantêm o histórico.
De 1 a 100. Qualquer outro valor (0, 101, um número decimal, texto, vazio) → **400 `INVALID_LIMIT`**.
Uma linha de outro workspace responde **404 `LINE_NOT_FOUND`** — nunca uma lista vazia.
```bash theme={null}
curl "https://pilotstatus.com.br/v1/phone-lines/cmg5k2l1n0001pl8example9x/activations?limit=5" \
-H "x-api-key: ps_your_tenant_scoped_key"
```
## Campos do objeto de ativação
O id do pedido (`activationId`).
A linha à qual o pedido pertence.
`WAITING`, `CAPTURED`, `TRANSCRIBED`, `TIMED_OUT` ou `FAILED` — veja [Status](#status).
ISO 8601 — quando o pedido foi aberto.
ISO 8601 — fim da janela de captura, 5 minutos depois do pedido.
O código de 6 dígitos, quando o pedido está `TRANSCRIBED` e o código foi encontrado. `null` caso contrário.
ISO 8601 — quando a gravação da ligação foi armazenada.
ISO 8601 — quando a transcrição terminou.
Por que um pedido em estado definitivo não tem código — veja [Status](#status).
Se uma gravação da ligação está armazenada e pode ser ouvida no painel.
## Erros
| Status | `code` | Onde | Significado |
| ------ | ------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `INVALID_LIMIT` | histórico | `limit` não é um inteiro de 1 a 100. |
| `401` | — | todos | Credencial ausente ou inválida. |
| `403` | `NUMBER_SCOPE_NOT_ALLOWED` | todos | Chave com escopo de número (ou concessão OAuth por número). Use a chave com escopo de tenant. |
| `403` | `WORKSPACE_MEMBERSHIP_REQUIRED` | todos | Token OAuth / MCP de um usuário que não é mais membro ativo. |
| `403` | `PERMISSION_DENIED` | todos | Token OAuth / MCP de um usuário que não é Proprietário nem Administrador. |
| `404` | `LINE_NOT_FOUND` | `POST`, histórico | Nenhuma linha com esse id no seu workspace. |
| `404` | `ACTIVATION_NOT_FOUND` | consulta | Nenhum pedido com esse id no seu workspace. |
| `409` | `LINE_NOT_ACTIVE` | `POST` | A linha está `SUSPENDED`, `RETURNED` ou `CANCELED`. Nada foi criado. |
| `409` | `ACTIVATION_IN_PROGRESS` | `POST` | Um pedido nesta linha ainda está aguardando a ligação. |
| `503` | `SUPPLIER_UNAVAILABLE` | `POST` | A operadora não conseguiu reiniciar a linha (nada foi criado), ou não conseguimos começar a monitorá-la (um pedido `FAILED` com `poll_not_scheduled` permanece no histórico). Tente de novo — um novo `POST` é permitido imediatamente. |
| `500` | `INTERNAL_ERROR` | todos | Falha inesperada. |