> ## 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. # Solicitar código de ativação > Prepara a linha para capturar uma NOVA ligação de verificação do WhatsApp — sem corpo. O WhatsApp verifica um número fixo **ligando para ele** e falando um código de 6 dígitos; este endpoint abre a janela de captura, ele **não** faz a ligação. 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. Depois do `201`, registre o número no WhatsApp Business e 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. Então consulte `GET /v1/phone-lines/activations/{activationId}` a cada alguns segundos (ou aguarde o webhook `phone_line.code_received`) e digite o `code` no WhatsApp. Permitido enquanto a linha está `ACTIVE` ou `PAYMENT_PENDING`; 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` — consulte o pedido que você já tem, ou cancele-o com `POST /v1/phone-lines/{id}/activations/{activationId}/cancel` para pedir de novo na hora. Sem limite de pedidos ao longo do tempo; cada pedido aberto incrementa o `activationCount` da linha. Enviado com `Cache-Control: no-store`: o código é uma credencial. **Exige uma chave com escopo de tenant** — uma chave com escopo de número (ou concessão OAuth por número) recebe `403 NUMBER_SCOPE_NOT_ALLOWED`. Permissão `phone_lines:read`: com um token OAuth / MCP, o usuário precisa ser **Proprietário ou Administrador** (caso contrário, `403 PERMISSION_DENIED`). ## OpenAPI ````yaml openapi.pt.json POST /v1/phone-lines/{id}/activations openapi: 3.1.0 info: title: API Pilot Status version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- API REST pública do Pilot Status. Autentique com o header `x-api-key: ps_...` (ou `x-api-key-id`). Base URL: https://pilotstatus.com.br servers: - url: https://pilotstatus.com.br security: - apiKey: [] - apiKeyId: [] paths: /v1/phone-lines/{id}/activations: post: tags: - Phone Lines summary: Solicitar um código de ativação description: >- Prepara a linha para capturar uma NOVA ligação de verificação do WhatsApp — sem corpo. O WhatsApp verifica um número fixo **ligando para ele** e falando um código de 6 dígitos; este endpoint abre a janela de captura, ele **não** faz a ligação. 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. Depois do `201`, registre o número no WhatsApp Business e 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. Então consulte `GET /v1/phone-lines/activations/{activationId}` a cada alguns segundos (ou aguarde o webhook `phone_line.code_received`) e digite o `code` no WhatsApp. Permitido enquanto a linha está `ACTIVE` ou `PAYMENT_PENDING`; 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` — consulte o pedido que você já tem, ou cancele-o com `POST /v1/phone-lines/{id}/activations/{activationId}/cancel` para pedir de novo na hora. Sem limite de pedidos ao longo do tempo; cada pedido aberto incrementa o `activationCount` da linha. Enviado com `Cache-Control: no-store`: o código é uma credencial. **Exige uma chave com escopo de tenant** — uma chave com escopo de número (ou concessão OAuth por número) recebe `403 NUMBER_SCOPE_NOT_ALLOWED`. Permissão `phone_lines:read`: com um token OAuth / MCP, o usuário precisa ser **Proprietário ou Administrador** (caso contrário, `403 PERMISSION_DENIED`). operationId: post_phone_lines_id_activations parameters: - name: id in: path required: true schema: type: string example: cmg5k2l1n0001pl8example9x description: >- O `id` da linha (de `GET /v1/phone-lines`) — não o número de telefone. responses: '201': description: >- Pedido de código aberto (`WAITING`). Enviado com `Cache-Control: no-store`. headers: Cache-Control: description: '`no-store`' schema: type: string enum: - no-store content: application/json: schema: type: object properties: activation: type: object properties: id: type: string description: O id do pedido (`activationId`). lineId: type: string description: A linha à qual o pedido pertence. status: type: string enum: - WAITING - CAPTURED - TRANSCRIBED - TIMED_OUT - FAILED description: >- `WAITING`, `CAPTURED`, `TRANSCRIBED`, `TIMED_OUT` ou `FAILED`. Continue consultando enquanto `status` for `WAITING`, ou `CAPTURED` com `failureReason: null`; qualquer outra combinação é definitiva. requestedAt: type: string format: date-time description: ISO 8601 — quando o pedido foi aberto. pollDeadline: type: string format: date-time description: >- ISO 8601 — fim da janela de captura, 5 minutos depois do pedido. code: type: - string - 'null' description: >- O código de 6 dígitos, quando o pedido está `TRANSCRIBED` e o código foi encontrado. `null` caso contrário. **É uma credencial** — quem o tiver pode registrar uma conta de WhatsApp na linha. capturedAt: type: - string - 'null' format: date-time description: >- ISO 8601 — quando a gravação da ligação foi armazenada. transcribedAt: type: - string - 'null' format: date-time description: ISO 8601 — quando a transcrição terminou. failureReason: type: - string - 'null' description: >- Por que um pedido em estado definitivo não tem código: `no_call_in_window`, `canceled_by_customer`, `no_code_in_transcript`, `transcription_failed`, `audio_download_failed`, `audio_store_failed`, `poll_not_scheduled`, ou `null`. Trate um valor desconhecido como falha, já que novos valores podem ser adicionados. hasAudio: type: boolean description: >- Se uma gravação da ligação está armazenada — para baixar em `GET /v1/phone-lines/activations/{activationId}/audio` e ouvir no painel. required: - id - lineId - status - requestedAt - pollDeadline - code - capturedAt - transcribedAt - failureReason - hasAudio required: - activation example: 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 '401': description: >- Header `x-api-key` / `x-api-key-id` ausente ou inválido (o corpo traz só `error`) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Invalid API key '403': description: >- Chave com escopo de número ou concessão OAuth por número (`NUMBER_SCOPE_NOT_ALLOWED`); token OAuth/MCP de um usuário que não é Proprietário nem Administrador (`PERMISSION_DENIED`) ou que não é mais membro ativo (`WORKSPACE_MEMBERSHIP_REQUIRED`); workspace arquivado (`WORKSPACE_ARCHIVED`). `TENANT_REQUIRED`: credencial sem workspace content: application/json: schema: type: object properties: error: type: string code: type: string examples: number_scope_not_allowed: summary: Chave com escopo de número value: error: This endpoint requires a tenant-scoped API key code: NUMBER_SCOPE_NOT_ALLOWED permission_denied: summary: Papel sem phone_lines:read value: error: >- Your workspace role does not allow this action (phone_lines:read). code: PERMISSION_DENIED workspace_membership_required: summary: Não é mais membro value: error: >- The user behind this token is not an active member of this workspace. code: WORKSPACE_MEMBERSHIP_REQUIRED workspace_archived: summary: Workspace arquivado value: error: >- This workspace has been archived and its API is closed. | Este workspace foi arquivado e sua API está encerrada. code: WORKSPACE_ARCHIVED tenantRequired: summary: Credencial sem workspace value: error: This credential is not bound to a workspace. code: TENANT_REQUIRED '404': description: >- Nenhuma linha com esse id no seu workspace (uma linha de outro workspace responde igual) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Line not found. | Linha não encontrada. code: LINE_NOT_FOUND '409': description: >- `LINE_NOT_ACTIVE` — a linha está `SUSPENDED`, `RETURNED` ou `CANCELED`, nada foi criado; `ACTIVATION_IN_PROGRESS` — um pedido nesta linha ainda está aguardando a ligação: consulte-o, ou cancele-o para pedir de novo agora content: application/json: schema: type: object properties: error: type: string code: type: string examples: activation_in_progress: summary: Já há um pedido em espera value: error: >- A code request is already waiting for the call on this line. | Já existe um pedido de código esperando a ligação nesta linha. code: ACTIVATION_IN_PROGRESS line_not_active: summary: Linha SUSPENDED, RETURNED ou CANCELED value: error: >- This line is not active, so it cannot receive a new code. | Esta linha não está ativa, então não pode receber um novo código. code: LINE_NOT_ACTIVE '500': description: Falha inesperada content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unexpected error. | Erro inesperado. code: INTERNAL_ERROR '503': description: >- 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. content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- Phone lines are temporarily unavailable. Try again in a few minutes. | As linhas estão temporariamente indisponíveis. Tente de novo em alguns minutos. code: SUPPLIER_UNAVAILABLE components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Sua chave de API ps_ apiKeyId: type: apiKey in: header name: x-api-key-id description: Id da chave de API (alternativa ao x-api-key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.