> ## 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. # Cancelar linha > ⚠️ **Efeito colateral real — NÃO é uma simulação, inclusive pelo playground.** Cancela a linha e responde com a linha **como ela fica depois**. O que acontece depende do `status`: | `status` antes | Resultado | Resposta | | --- | --- | --- | | `ACTIVE` | **Cancelada no fim do período, sem estorno.** A linha continua `ACTIVE` e totalmente utilizável — inclusive para códigos de ativação — até `currentPeriodEnd`; ela não é renovada e passa a `CANCELED` quando o período termina. | `200`, `status: "ACTIVE"`, `cancelAtPeriodEnd: true` | | `ACTIVE`, já cancelada | Nada muda — chamar de novo é seguro. | `200`, a mesma linha | | `PAYMENT_PENDING`, `SUSPENDED` | **Devolvida à operadora imediatamente — IRREVERSÍVEL.** Não resta período pago. | `200`, `status: "RETURNED"` | | `RETURNED`, `CANCELED` | A chamada é recusada — a linha já está encerrada. | `409 NOT_CANCELABLE` | **Um número devolvido deixa de ser seu**: nada desfaz uma devolução, e **não há garantia de que ele possa ser comprado de volta** — ele volta para o estoque da operadora, onde qualquer pessoa pode alugá-lo. A conta do WhatsApp ativada nele continua vinculada a esse número. O histórico de códigos da linha — códigos e gravações das ligações — é apagado. Cancelar uma linha em atraso faz isso **na hora**, sem período de carência. Desfazer um cancelamento agendado de uma linha `ACTIVE` só é possível no painel (Proprietário). Se a devolução da mesma linha em atraso já estiver em andamento (execução horária do faturamento, ou o **Escolher quais linhas manter** do painel), a chamada responde `200` com a linha como ela está — possivelmente ainda `PAYMENT_PENDING` ou `SUSPENDED` — e esse processo conclui a devolução. Eventos: `phone_line.canceled` quando uma linha cancelada no fim do período passa a `CANCELED`; `phone_line.returned` com `reason: "canceled_by_customer"` na hora, para uma linha em atraso devolvida por esta chamada. Permissões: com um token OAuth / MCP, só o **Proprietário** do workspace pode cancelar (`phone_lines:cancel`) — caso contrário, `403 PERMISSION_DENIED`. Todo endpoint `/v1/phone-lines` aceita só uma chave **com escopo de tenant**: a linha pertence ao workspace, não a um número de WhatsApp, então uma chave com escopo de número (ou uma concessão OAuth por número) recebe `403 NUMBER_SCOPE_NOT_ALLOWED` antes de qualquer verificação de papel. Um `403 PERMISSION_DENIED` / `WORKSPACE_MEMBERSHIP_REQUIRED` é enviado com `Cache-Control: no-store`. **Requer uma chave com escopo de tenant.** > [!WARNING] > > **Isto cancela a linha de verdade.** Uma linha `ACTIVE` é cancelada no fim do período, sem reembolso. Uma linha em atraso (`PAYMENT_PENDING`, `SUSPENDED`) é **devolvida à operadora na hora**, sem garantia de que possa ser comprada de volta, e o histórico de códigos é apagado. Veja [Cancelar uma linha](https://docs.pilotstatus.com.br/pt-BR/api/phone-lines/cancel.md). ## OpenAPI ````yaml openapi.pt.json DELETE /v1/phone-lines/{id} 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}: delete: tags: - Phone Lines summary: Cancelar uma linha telefônica description: >- ⚠️ **Efeito colateral real — NÃO é uma simulação, inclusive pelo playground.** Cancela a linha e responde com a linha **como ela fica depois**. O que acontece depende do `status`: | `status` antes | Resultado | Resposta | | --- | --- | --- | | `ACTIVE` | **Cancelada no fim do período, sem estorno.** A linha continua `ACTIVE` e totalmente utilizável — inclusive para códigos de ativação — até `currentPeriodEnd`; ela não é renovada e passa a `CANCELED` quando o período termina. | `200`, `status: "ACTIVE"`, `cancelAtPeriodEnd: true` | | `ACTIVE`, já cancelada | Nada muda — chamar de novo é seguro. | `200`, a mesma linha | | `PAYMENT_PENDING`, `SUSPENDED` | **Devolvida à operadora imediatamente — IRREVERSÍVEL.** Não resta período pago. | `200`, `status: "RETURNED"` | | `RETURNED`, `CANCELED` | A chamada é recusada — a linha já está encerrada. | `409 NOT_CANCELABLE` | **Um número devolvido deixa de ser seu**: nada desfaz uma devolução, e **não há garantia de que ele possa ser comprado de volta** — ele volta para o estoque da operadora, onde qualquer pessoa pode alugá-lo. A conta do WhatsApp ativada nele continua vinculada a esse número. O histórico de códigos da linha — códigos e gravações das ligações — é apagado. Cancelar uma linha em atraso faz isso **na hora**, sem período de carência. Desfazer um cancelamento agendado de uma linha `ACTIVE` só é possível no painel (Proprietário). Se a devolução da mesma linha em atraso já estiver em andamento (execução horária do faturamento, ou o **Escolher quais linhas manter** do painel), a chamada responde `200` com a linha como ela está — possivelmente ainda `PAYMENT_PENDING` ou `SUSPENDED` — e esse processo conclui a devolução. Eventos: `phone_line.canceled` quando uma linha cancelada no fim do período passa a `CANCELED`; `phone_line.returned` com `reason: "canceled_by_customer"` na hora, para uma linha em atraso devolvida por esta chamada. Permissões: com um token OAuth / MCP, só o **Proprietário** do workspace pode cancelar (`phone_lines:cancel`) — caso contrário, `403 PERMISSION_DENIED`. Todo endpoint `/v1/phone-lines` aceita só uma chave **com escopo de tenant**: a linha pertence ao workspace, não a um número de WhatsApp, então uma chave com escopo de número (ou uma concessão OAuth por número) recebe `403 NUMBER_SCOPE_NOT_ALLOWED` antes de qualquer verificação de papel. Um `403 PERMISSION_DENIED` / `WORKSPACE_MEMBERSHIP_REQUIRED` é enviado com `Cache-Control: no-store`. **Requer uma chave com escopo de tenant.** operationId: delete_phone_lines_id parameters: - name: id in: path required: true schema: type: string example: cmg5k2l1n0001pl8example9x description: >- O `id` da linha (de `GET /v1/phone-lines`, ou `lineId` no resultado da compra) — não o número de telefone. responses: '200': description: A linha como ela fica depois da chamada content: application/json: schema: type: object properties: line: type: object properties: id: type: string description: >- O id da linha. Use-o em todo caminho `/v1/phone-lines/{id}`. example: cmg5k2l1n0001pl8example9x name: type: string description: >- O nome que sua equipe deu à linha no painel, com até 60 caracteres. **Nunca vem vazio:** uma linha sem nome retorna o número formatado, igual a `display` — e toda linha é comprada sem nome. Não pode ser definido nem alterado pela API. É um rótulo: identifique a linha pelo `id`. example: Suporte SP number: type: string description: >- Dígitos E.164 **sem** o `+`, por exemplo `551148637200`. example: '551148637200' display: type: string description: >- O número formatado para leitura humana: `(11) 4863-7200`. example: (11) 4863-7200 ddd: type: string description: O DDD, com dois dígitos. example: '11' status: type: string description: >- `ACTIVE`, `PAYMENT_PENDING`, `SUSPENDED`, `RETURNED` ou `CANCELED`. É o campo em que a sua lógica deve se basear. example: ACTIVE enum: - ACTIVE - PAYMENT_PENDING - SUSPENDED - RETURNED - CANCELED price: type: number description: >- Quanto **esta** linha custa por mês — o preço da próxima renovação (por exemplo, `33.9`): o preço de compra, ou o preço próprio da linha do workspace quando a equipe da Pilot Status definiu um (vale também para linhas compradas antes). example: 33.9 currency: type: string description: '`BRL` ou `USD` — a moeda em que o `price` é cobrado.' example: BRL enum: - BRL - USD purchasedAt: type: string description: >- ISO 8601 — quando a linha foi comprada. As renovações contam a partir desta data. example: '2026-10-01T14:03:11.000Z' format: date-time currentPeriodEnd: type: string description: >- ISO 8601 — fim do período pago. A próxima renovação é tentada na primeira execução horária do faturamento depois dele. Para uma linha cancelada no fim do período, é quando ela passa a `CANCELED`. Não muda enquanto uma renovação está em atraso. example: '2026-11-01T14:03:11.000Z' format: date-time cancelAtPeriodEnd: type: boolean description: >- `true` depois de um `DELETE` em uma linha `ACTIVE`: ela não será renovada e passa a `CANCELED` em `currentPeriodEnd`. example: false paymentPendingSince: type: - string - 'null' description: >- ISO 8601 — quando a cobrança da renovação falhou. A linha é suspensa 2 dias depois disso. Volta a ser `null` quando uma renovação é bem-sucedida. example: null format: date-time suspendedAt: type: - string - 'null' description: >- ISO 8601 — quando a linha foi suspensa. Ela é devolvida 1 dia depois disso. Volta a ser `null` quando uma renovação é bem-sucedida. example: null format: date-time returnedAt: type: - string - 'null' description: >- ISO 8601 — quando o número foi devolvido à operadora (`RETURNED`). example: null format: date-time canceledAt: type: - string - 'null' description: >- ISO 8601 — quando uma linha cancelada no fim do período passou a `CANCELED`. example: null format: date-time activationCount: type: integer description: >- Quantos pedidos de código foram abertos nesta linha até agora. Um `POST …/activations` que respondeu `503` não é contado. example: 1 amountDue: type: - number - 'null' description: >- Numa linha `PAYMENT_PENDING` ou `SUSPENDED`, quanto pagá-la agora cobra — o valor do período em atraso, fixado na primeira cobrança daquele período. `null` em qualquer outra linha. example: null examples: paidLine: summary: 'Linha paga: cancelada no fim do período' value: line: id: cmg5k2l1n0001pl8example9x name: Suporte SP number: '551148637200' display: (11) 4863-7200 ddd: '11' status: ACTIVE price: 33.9 currency: BRL purchasedAt: '2026-10-01T14:03:11.000Z' currentPeriodEnd: '2026-11-01T14:03:11.000Z' cancelAtPeriodEnd: true paymentPendingSince: null suspendedAt: null returnedAt: null canceledAt: null activationCount: 1 amountDue: null unpaidLine: summary: 'Linha em atraso: devolvida agora' value: line: id: cmg5k2l1n0001pl8example9x name: Suporte SP number: '551148637200' display: (11) 4863-7200 ddd: '11' status: RETURNED price: 33.9 currency: BRL purchasedAt: '2026-10-01T14:03:11.000Z' currentPeriodEnd: '2026-11-01T14:03:11.000Z' cancelAtPeriodEnd: false paymentPendingSince: '2026-11-01T14:17:02.000Z' suspendedAt: null returnedAt: '2026-11-02T09:41:27.000Z' canceledAt: null activationCount: 1 amountDue: null '401': description: >- Credencial ausente ou inválida (`x-api-key`, `x-api-key-id` ou `Authorization: Bearer`). O corpo traz só `error`, sem `code`. content: application/json: schema: type: object properties: error: type: string code: type: string examples: missing: summary: Sem credencial value: error: >- Missing x-api-key, x-api-key-id or Authorization Bearer token invalid: summary: API key inválida value: error: Invalid API key '403': description: >- Chave com escopo de número (`NUMBER_SCOPE_NOT_ALLOWED`), token OAuth/MCP de um usuário que não é o Proprietário do workspace (`PERMISSION_DENIED`) ou que não é mais membro ativo (`WORKSPACE_MEMBERSHIP_REQUIRED`), ou workspace arquivado (`WORKSPACE_ARCHIVED`). `TENANT_REQUIRED`: credencial sem workspace content: application/json: schema: type: object properties: error: type: string code: type: string examples: numberScope: summary: Chave com escopo de número value: error: This endpoint requires a tenant-scoped API key code: NUMBER_SCOPE_NOT_ALLOWED permissionDenied: summary: Usuário OAuth/MCP que não é o Proprietário value: error: >- Your workspace role does not allow this action (phone_lines:cancel). code: PERMISSION_DENIED notMember: summary: Usuário OAuth/MCP que não é mais membro value: error: >- The user behind this token is not an active member of this workspace. code: WORKSPACE_MEMBERSHIP_REQUIRED 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: >- Essa linha não existe no seu workspace (`LINE_NOT_FOUND`) — uma linha de outro workspace recebe a mesma resposta e não é alterada content: application/json: schema: type: object properties: error: type: string code: type: string examples: lineNotFound: summary: Essa linha não existe no seu workspace value: error: Line not found. | Linha não encontrada. code: LINE_NOT_FOUND numberHeader: summary: '`x-whatsapp-number-id` não indica nenhum número' value: error: >- x-whatsapp-number-id does not name a WhatsApp number of this account | x-whatsapp-number-id não indica um número de WhatsApp desta conta code: NUMBER_NOT_FOUND '409': description: A linha já está `RETURNED` ou `CANCELED` (`NOT_CANCELABLE`) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- This line cannot be cancelled now. | Esta linha não pode ser cancelada agora. code: NOT_CANCELABLE '500': description: Falha inesperada (`INTERNAL_ERROR`). content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unexpected error. | Erro inesperado. code: INTERNAL_ERROR '503': description: >- Só para linha em atraso: a operadora não confirmou a devolução (`SUPPLIER_UNAVAILABLE`). **Esta chamada não alterou a linha** — tente de novo em alguns minutos. 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.