​

Números extras e On Demand

​

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 sai primeiro da sua carteira pré-paga e o que sobrar vai no cartão salvo (painel Plans → Cartão). Sem nenhum dos dois, a resposta é { "success": true, "charged": false, "checkoutUrl": "https://…" } — abra-a para pagar o valor proporcional; o cartão usado ali fica salvo para a cobrança recorrente. Após o pagamento, o slot é desbloqueado (webhook) e você pode criar o número com POST /v1/numbers.
• 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), que aceita PIX — dá para rodar On Demand só com créditos de PIX, sem nunca salvar um cartão.

​

Quando o pagamento não passa

​

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 passa a ser utilizável, prorata pelos dias restantes do ciclo. 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" }'

• purpose: "wallet_topup" — recarrega a carteira pré-paga.
• purpose: "add_card" — salva um cartão para futuras cobranças On Demand.