​

Números extras e On Demand

​

Cobrado na primeira conexão

• Criar um número não cobra nada. Gerar um link de pareamento também não.
• Um número que nunca conectou não conta na sua capacidade nem na sua cobrança mensal. Você paga só pelos números que foram de fato pareados.
• Em um plano pago, a cobrança é automática. É a mesma compra de POST /v1/subscription/extra-numbers para um número: proporcional aos dias que faltam no ciclo, primeiro os créditos da carteira, o restante no cartão salvo. O plano Free nunca compra sozinho — veja Plano Free.
• Comprar antes continua funcionando. Um número que conecta dentro da capacidade que você já pagou não é cobrado de novo.
• Em um número não oficial, a primeira conexão é a primeira vez em que o QR Code ou o código de pareamento é concluído. Em um número oficial (Meta Cloud API), é quando o número é ativado — por exemplo, quando o Embedded Signup é concluído.

​

Plano Free

• Criar um número acima da cota do plano é recusado com 402 PLAN_NUMBER_LIMIT_REACHED, mesmo quando o workspace tem saldo na carteira ou cartão salvo. Nos planos pagos, havendo saldo ou cartão a criação passa, e o extra é cobrado na primeira conexão.
• Parear um número que nunca conectou também é recusado quando a cota do plano já está cheia. GET /v1/numbers/{id}/connect, o passo de conexão de um link de pareamento remoto e POST /v1/numbers/remote-pairing para um telefone que já existe respondem 402 PLAN_NUMBER_LIMIT_REACHED. Reparear um número que já tinha conectado nunca é recusado.
• Se um segundo número conecta mesmo assim — dois pareamentos iniciados ao mesmo tempo — nada é cobrado e o plano não muda. O número continua conectado com o envio bloqueado (409 NUMBER_BLOCKED, reason: "extra_charge_unpaid"), e POST /v1/numbers/{id}/pay responde 402 PLAN_NUMBER_LIMIT_REACHED para ele. Uma recarga ou um cartão salvo não removem esse bloqueio.

​

Quando a cobrança é recusada

• POST /v1/messages/send responde 409 NUMBER_BLOCKED com reason: "extra_charge_unpaid".
• Uma mensagem que já estava na fila falha, e aparece com NUMBER_BLOCKED nos logs.
• GET /v1/numbers e GET /v1/numbers/{id} mostram extraChargeUnpaidSince no número.

{
  "error": "This number's extra-number charge is unpaid. Pay it to resume sending from this number. | A cobrança do número extra deste número está pendente. Pague para voltar a enviar por ele.",
  "code": "NUMBER_BLOCKED",
  "reason": "extra_charge_unpaid",
  "observedAt": "2026-10-10T12:00:00.000Z"
}

​

O que remove o bloqueio

​

Depois de 7 dias sem pagamento

• Um número conectado por QR Code que fica 7 dias sem pagamento é desconectado: o aparelho é deslogado e o número deixa de contar na sua capacidade. Um lembrete é enviado 2 dias antes, e o extraChargeDisconnectAt do número diz quando. Conectá-lo de novo é uma nova primeira conexão, cobrada de novo.
• Um número da Meta Cloud API nunca é desconectado. Ele fica bloqueado para envio até o pagamento.

​

GET /v1/subscription/extra-numbers — Prévia (dry-run)

curl "https://pilotstatus.com.br/v1/subscription/extra-numbers?quantity=1" \
  -H "x-api-key: ps_your_tenant_scoped_key"

{
  "plan": "FREE",
  "requiresConversion": true,
  "explanation": { "pt": "…", "en": "…" },
  "currentNumbers": 1,
  "requested": 1,
  "billedQuantity": 2,
  "currency": "BRL",
  "unitPriceMonthly": 29.9,
  "proratedUnitPrice": 14.95,
  "proratedTotal": 29.9,
  "remainingDays": 15,
  "totalDaysInCycle": 30,
  "walletBalance": 0,
  "hasSavedCard": false,
  "fundingSource": "none",
  "canFund": false,
  "unitPriceBRL": 29.9,
  "monthlyTotalBRL": 59.8
}

​

POST /v1/subscription/extra-numbers — Comprar

curl -X POST "https://pilotstatus.com.br/v1/subscription/extra-numbers" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_tenant_scoped_key" \
  -d '{ "quantity": 1, "confirm": true }'

• Conversão Free → On Demand. Se você está no plano Free, comprar um número extra move você para o On Demand: seu número atual (antes gratuito, limitado a 200 mensagens) se torna um número pago e ilimitado e o novo número também é cobrado. Portanto, comprar 1 extra estando no Free cobra você por 2 números. Como isso altera o que você paga, o POST retorna 409 CONFIRMATION_REQUIRED (com a prévia) a menos que você envie confirm: true.
• Já no On Demand / pago. Comprar incrementa sua contagem de números; as mensagens permanecem ilimitadas.
• Pagamento. O custo proporcional é cobrado na hora: primeiro da sua carteira pré-paga, e o que sobrar vai no cartão salvo (painel Plans → Cartão, ou POST /v1/billing/checkout com add_card). Uma compra bem-sucedida responde { "success": true, "charged": true, … } — creditsUsed e cardCharged mostram como a cobrança foi dividida, e paidExtraNumbers já inclui a vaga nova, então você pode criar o número com POST /v1/numbers em seguida. Esta rota nunca devolve link de checkout (não existe checkoutUrl, e charged nunca vem false): sem créditos suficientes e sem cartão salvo, ela retorna 402 INSUFFICIENT_FUNDS — nada é cobrado, e os créditos que ela chegou a usar são devolvidos. Recarregue ou salve um cartão e tente de novo.
• A recorrência mensal sai da carteira, não de uma assinatura à parte. A cada ciclo, paidExtraNumbers × preço unitário é debitado dos créditos, com o cartão salvo como reserva. Recarregue com POST /v1/billing/checkout (wallet_topup, só cartão) ou pelo painel, onde o PIX também está disponível — dá para rodar On Demand só com créditos de PIX recarregados pelo painel, sem nunca salvar um cartão.

​

Quando o pagamento não passa

{
  "error": "Saldo insuficiente na carteira e cartão indisponível para cobrar o número extra. Adicione créditos ou um cartão.",
  "code": "INSUFFICIENT_FUNDS",
  "proratedTotal": 29.9,
  "currency": "BRL",
  "walletReason": "NO_CARD"
}

​

O campo declineCode

• Decida pelo code: "PAYMENT_FAILED". Ele está sempre presente e sempre significa a mesma coisa.
• Use o declineCode só para refinar a mensagem quando ele existir.
• Nunca leia “sem declineCode” como “não foi recusa” — e nunca como “o cartão está bom”.

​

A capacidade paga é um direito de 30 dias

• Deletar um número não reduz sua capacidade paga. DELETE /v1/numbers/<id> libera o slot para você reconectar outro número no mesmo ciclo — sua contagem paga e sua cobrança seguem iguais até o fim do ciclo.
• Reduzir a capacidade é uma ação explícita e agendada. Você decide baixar a quantidade de slots pagos; a mudança vale no próximo ciclo, quando a cobrança cai para o novo valor. Nada é estornado do ciclo em andamento.

​

No Pay As You Go funciona diferente

• O número é cobrado quando conecta pela primeira vez, prorata pelos dias restantes do ciclo — a mesma regra de todos os planos, descrita acima. Para número não-oficial isso é a primeira conexão; para número oficial (Meta), é quando o Embedded Signup é concluído.
• O slot que você pagou vale pelo ciclo. Deletar um número e conectar outro no lugar não cobra de novo.
• O ciclo seguinte cobra só o que continuar conectado. Nada se acumula do ciclo anterior, então não há o que agendar para baixo — veja o 409 NOT_APPLICABLE_FOR_PLAN no endpoint abaixo.
• Um pareamento que você nunca concluiu não é um número e não é cobrado. A linha “Aguardando conexão”, que aparece enquanto o seu usuário final está no diálogo do Facebook, fica de fora da cobrança e da sua capacidade, e é removida automaticamente 24h depois de criada.

​

DELETE /v1/subscription/extra-numbers — Agendar uma redução

curl -X DELETE "https://pilotstatus.com.br/v1/subscription/extra-numbers" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_tenant_scoped_key" \
  -d '{ "quantity": 1 }'

• Agendado, não imediato. Este ciclo mantém a capacidade atual (sem estorno); a redução vale a partir do próximo rollover, quando os meses futuros cobram menos.
• Editável. Chamar de novo sobrescreve o alvo agendado. Cancele com DELETE …/schedule (abaixo).
• Não pode ficar abaixo dos números conectados. Se o alvo deixaria o limite abaixo dos números que você ainda tem conectados, retorna 409 NUMBER_LIMIT_EXCEEDED ({ currentNumberCount, maxNumbers }) — delete um número antes.
• Não existe no Pay As You Go. Retorna 409 NOT_APPLICABLE_FOR_PLAN. Não há capacidade paga a devolver: o Pay As You Go cobra pelos números que você tem conectados, e o próximo ciclo já cobra apenas o que continuar conectado. Para pagar menos, delete o número — não é preciso agendar nada.
• quantity tem default 1 e é limitado para nunca ficar abaixo de 0 extras pagos. Chaves de escopo de número recebem 403.

{
  "success": true,
  "charged": true,
  "plan": "ON_DEMAND",
  "paidExtraNumbers": 5,
  "scheduledPaidExtraNumbers": 4,
  "scheduledReductionEffectiveAt": "2026-08-01T00:00:00.000Z",
  "maxNumbers": 5
}

​

DELETE /v1/subscription/extra-numbers/schedule — Cancelar a redução agendada

curl -X DELETE "https://pilotstatus.com.br/v1/subscription/extra-numbers/schedule" \
  -H "x-api-key: ps_your_tenant_scoped_key"

​

POST /v1/billing/checkout — Recarga de carteira / adicionar um cartão

curl -X POST "https://pilotstatus.com.br/v1/billing/checkout" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_tenant_scoped_key" \
  -d '{ "purpose": "wallet_topup", "amount": 50 }'

• purpose: "wallet_topup" — recarrega a carteira pré-paga. Só cartão: o checkout hospedado do Stripe não oferece PIX — recarga por PIX existe só pelo painel (contas em BRL). Exige amount: um número positivo, na moeda da sua conta (a da carteira, BRL ou USD — não dá para escolher por requisição). Ausente, zero, negativo ou não numérico retorna 400 { "error": "amount must be a positive number", "code": "INVALID_AMOUNT" }.
• purpose: "add_card" — salva um cartão para futuras cobranças On Demand.

{
  "url": "https://checkout.stripe.com/c/pay/cs_test_…",
  "purpose": "wallet_topup",
  "orderId": "…",
  "amount": 50,
  "currency": "BRL"
}