Remoção de números extras

Remova números extras que não são mais necessários para liberar vagas no seu plano e encerrar a cobrança correspondente. Você pode remover um número a qualquer momento, esteja ele conectado ou não. Desconectar um número não encerra a cobrança; só a remoção encerra.

O que acontece no celular

Quando a remoção é concluída (na hora ou na data agendada), o Turbo Notify desconecta o número do WhatsApp e apaga da sua conta os dados de acesso desse número. No celular do número, a entrada em Dispositivos conectados pode continuar na lista como Desconectado, e ela ainda conta entre os aparelhos que o WhatsApp deixa conectar (até 4). Para tirar a entrada, quem tem o celular abre Dispositivos conectados, toca nela e escolhe Remover dispositivo. Se você revende números, passe esse aviso ao seu cliente.

Cobrança

O efeito na fatura depende de qual dos dois caminhos de remoção foi tomado:

• Remoção imediata: remover um número extra logo depois de adicioná-lo, antes de usá-lo, pode excluí-lo na hora e reembolsar automaticamente a cobrança pro-rata feita na ativação. Ele não entra na fatura do período seguinte.
• Remoção agendada: nos demais casos, o número é removido no fim do período já pago (veja scheduled_deletion_at na resposta) e não há reembolso. Até essa data ele continua funcionando normalmente: mantém o status que tinha, envia e recebe mensagens, e você pode conectá-lo e desconectá-lo como de costume. Ele não entra na fatura do período seguinte: a cobrança para com a remoção. Um número apenas desconectado, ao contrário, continua sendo cobrado. Até a data, você pode cancelar a exclusão e manter o número.

A resposta do DELETE diz o que aconteceu, em refund_eligible, refund_amount_cents, refund_status e scheduled_deletion_at. Dúvidas sobre um reembolso: escreva para billing@turbonotify.com. Para mais detalhes, consulte Cobrança de números extras.

Remover pelo dashboard

Acesse a página de Números (abre em nova aba) no dashboard, abra o número desejado e clique em Remover número. Antes de confirmar, o dashboard mostra o que vai acontecer: a remoção imediata, com o valor da ativação que será reembolsado quando houver (botão Remover), ou a exclusão agendada para o fim do período já pago, sem reembolso (botão Agendar exclusão). Enquanto a exclusão não chega, o número aparece com o status de conexão de sempre, mais o aviso “Exclusão em” seguido da data e o botão Manter número.

Remover via API

cURL

turbo-notify.sh

curl -X DELETE \
  https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO \
  -H "Authorization: Bearer SUA_CHAVE"

Node

turbo-notify.js

const response = await fetch('https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer SUA_CHAVE'
  }
});

const result = await response.json();
console.log(result);

Python

turbo_notify.py

import requests

url = "https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO"
headers = {
    "Authorization": "Bearer SUA_CHAVE"
}

response = requests.delete(url, headers=headers)
result = response.json()
print(result)

Go

turbo_notify.go

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO", nil)
    req.Header.Set("Authorization", "Bearer SUA_CHAVE")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

PHP

turbo-notify.php

<?php
$url = 'https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO';

$options = [
    'http' => [
        'header' => [
            'Authorization: Bearer SUA_CHAVE'
        ],
        'method' => 'DELETE'
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);
var_dump($response);
?>

C#

TurboNotify.cs

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer SUA_CHAVE");

var response = await client.DeleteAsync(
    "https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO"
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Java

TurboNotify.java

import java.net.http.*;
import java.net.URI;

public class TurboNotify {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .DELETE()
            .build();

        var response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Status HTTP: 200

{
  "scheduled_deletion_at": "2025-07-16T10:00:00Z",
  "refund_eligible": true,
  "refund_amount_cents": 2252,
  "refund_status": "succeeded"
}

Escopo obrigatório: numbers:write

A resposta descreve o resultado da exclusão, não o número em si:

Campo	Tipo	Descrição
scheduled_deletion_at	string	Timestamp ISO 8601 de quando o número é removido da conta.
refund_eligible	boolean	true quando a remoção foi imediata e a cobrança de ativação é reembolsada; nesse caso scheduled_deletion_at é o momento atual. false quando a exclusão foi agendada; nesse caso scheduled_deletion_at fica no fim do período já pago e o número continua funcionando até lá.
refund_amount_cents	integer	Valor reembolsado em centavos: o mesmo valor da cobrança pro-rata feita na ativação deste número. 0 quando refund_eligible é false, ou quando refund_status é not_applicable ou failed (veja abaixo).
refund_status	string | null	O resultado da tentativa de reembolso: succeeded (reembolso processado; refund_amount_cents traz o valor reembolsado), not_applicable (nada a reembolsar nesta resposta: não havia cobrança de ativação para este número, ou outra requisição simultânea para o mesmo número já está cuidando do reembolso; não é um erro) ou failed (havia uma cobrança e o reembolso não pôde ser processado; a exclusão do número não é bloqueada por isso. Escreva para billing@turbonotify.com para receber o reembolso). null quando refund_eligible é false (nenhum reembolso foi tentado).

A chamada é idempotente: repetir a requisição para um número já agendado para exclusão retorna o mesmo agendamento (sem gerar um novo reembolso).

Cancelar exclusão agendada

Enquanto a exclusão não for executada (o número tem scheduled_deletion_at preenchido), você pode cancelá-la e manter o número. Esta é a única forma de mantê-lo: conectar ou desconectar o número não altera a exclusão agendada.

Pode gerar cobrança

Cancelar a exclusão só gera cobrança quando a fatura do próximo período já foi emitida sem o número. Nesse caso você paga o valor proporcional do que falta do período já pago. A cobrança vem primeiro: se for recusada ou o processador de pagamento falhar, a exclusão continua agendada. Veja Cobrança de números extras.

cURL

turbo-notify.sh

curl -X POST \
  https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO/cancel-deletion \
  -H "Authorization: Bearer SUA_CHAVE"

Node

turbo-notify.js

const response = await fetch('https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO/cancel-deletion', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer SUA_CHAVE' }
});

const result = await response.json();
console.log(result);

Python

turbo_notify.py

import requests

url = "https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO/cancel-deletion"
headers = {"Authorization": "Bearer SUA_CHAVE"}

response = requests.post(url, headers=headers)
result = response.json()
print(result)

Go

turbo_notify.go

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO/cancel-deletion", nil)
    req.Header.Set("Authorization", "Bearer SUA_CHAVE")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

PHP

turbo-notify.php

<?php
$url = 'https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO/cancel-deletion';

$options = [
    'http' => [
        'header' => ['Authorization: Bearer SUA_CHAVE'],
        'method' => 'POST'
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);
var_dump($response);
?>

C#

TurboNotify.cs

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer SUA_CHAVE");

var response = await client.PostAsync(
    "https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO/cancel-deletion",
    null
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Java

TurboNotify.java

import java.net.http.*;
import java.net.URI;

public class TurboNotify {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/numbers/ALIAS_DO_NUMERO/cancel-deletion"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .POST(HttpRequest.BodyPublishers.noBody())
            .build();

        var response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Status HTTP: 200

{
  "status": "connected",
  "at": "2025-07-16T10:05:00Z"
}

A resposta traz o status de conexão do número (um dos valores da Tabela de status) e o momento em que ele entrou nesse status em at (null quando não há registro). Como a exclusão agendada não altera o número, o status é o mesmo de antes do cancelamento. Para acompanhar o status depois, consulte o Status dos números extras.

Erros possíveis

Remover (DELETE /v1/numbers/{ref})

Status	Código de erro	Descrição
402	feature_not_available	O plano atual não suporta números extras.
401	not_authenticated	A chave de API está inválida ou ausente.
403	insufficient_scope	A chave de API não possui o escopo numbers:write (resposta inclui required_scope).
404	number_not_found	O alias ou id informado não foi encontrado na conta.
500	internal_error	Erro interno inesperado no servidor.

Cancelar exclusão (POST /v1/numbers/{ref}/cancel-deletion)

Status	Código de erro	Descrição
400	not_pending_deletion	O número não está com exclusão agendada.
400	no_payment_method	O cancelamento exige cobrança do restante do período pago, mas a organização não tem forma de pagamento cadastrada. A exclusão continua agendada.
402	feature_not_available	O plano atual não suporta números extras.
402	payment_declined	A cobrança do restante do período pago foi recusada. A exclusão continua agendada.
402	payment_requires_authentication	A forma de pagamento exige reautenticação (3DS). A exclusão continua agendada.
401	not_authenticated	A chave de API está inválida ou ausente.
403	insufficient_scope	A chave de API não possui o escopo numbers:write (resposta inclui required_scope).
404	number_not_found	O alias ou id informado não foi encontrado na conta.
500	internal_error	Erro interno inesperado no servidor.
503	payment_gateway_unavailable	A cobrança do restante do período pago não pôde ser confirmada a tempo. Tente novamente.