Revenda: como a cobrança funciona e o que o seu sistema precisa controlar

Se você revende conexões de WhatsApp ou linhas telefônicas para os seus clientes, a Pilot Status cobra você, e você cobra os seus clientes. Esta página explica quando cada cobrança acontece do nosso lado e o que o seu sistema precisa registrar para que as duas pontas fechem: cobrar o seu cliente antes de a gente cobrar você e parar de pagar por quem já saiu. Os detalhes completos de cada regra estão em Números extras e On Demand, Preço e cobrança das linhas e Planos. Para automatizar, veja Tipos de chave, Criar workspaces, Carteira e cartão pela API e Webhooks do workspace.

​

Um workspace por cliente final

Mantenha cada cliente seu num workspace próprio. Cobrança, suspensão e carteira funcionam por workspace. Se todos os clientes dividem o seu workspace, uma renovação recusada para todos de uma vez; com um workspace por cliente, uma renovação recusada suspende só os números daquele cliente, e os outros continuam enviando.

• Crie os workspaces pela API com uma chave de conta (ps_account_, em Perfil → API): POST /v1/workspaces. Você é o Proprietário de cada um, e a resposta traz a chave principal do workspace. Depois, aja em qualquer um deles com a mesma chave de conta e o cabeçalho x-workspace-id.
• Depois que a equipe da Pilot Status marca você como revendedor, todo workspace que você criar já nasce no Pay As You Go, cobrado pela carteira, com os seus preços de revenda: o preço por número do seu contrato e o seu preço de linha. Nada é cobrado na criação.
• Cada workspace tem a sua carteira, o seu cartão salvo e a sua data de renovação (um mês depois de criado). Abasteça cada um com Pix ou cartão pela API, ou vincule o seu cartão compartilhado (abaixo).
• Por padrão, você pode ser dono de até 10 workspaces. Acima disso, POST /v1/workspaces responde 409 WORKSPACE_LIMIT_REACHED com o limit. Peça um teto maior à equipe da Pilot Status.
• Os workspaces que você já tinha mantêm o plano. Levar um cliente existente para um workspace próprio significa conectar os números dele lá: um número não muda de workspace.

​

Cartão compartilhado

O seu cartão compartilhado (ou cartão de reserva) é o seu cartão — o cartão salvo num dos seus workspaces — cobrindo os workspaces dos seus clientes. Você decide, workspace por workspace, quais clientes ele cobre:

• A equipe da Pilot Status configura qual dos seus workspaces guarda o seu cartão de reserva. Essa configuração é o que permite compartilhá-lo, e é a origem para a qual todo vínculo aponta. Sem ela, compartilhar responde 409 SHARED_CARD_NOT_CONFIGURED.
• Na criação: envie "shareCard": true no POST /v1/workspaces. Com shareCard ausente (ou false), o workspace não é compartilhado. No painel (Perfil → Membros → Criar outro workspace), a mesma escolha é a caixa Usar meu cartão reserva, que vem desmarcada.
• Depois: o PUT /v1/workspaces/{id}/shared-card vincula um workspace e o DELETE /v1/workspaces/{id}/shared-card o desvincula. O GET /v1/workspaces mostra o sharedCard de cada workspace.
• Desvincular faz o seu cartão deixar de pagar as renovações daquele cliente. Use quando um cliente parar de pagar você: a partir daí, uma renovação recusada suspende só o workspace desse cliente.

O cartão compartilhado é uma reserva, não a forma de pagamento principal:

• Ele paga só o que a plataforma cobra: a renovação mensal, números extras, compras e renovações de linhas telefônicas.
• Ele só é usado quando a carteira do workspace não cobre a cobrança e o workspace não tem cartão próprio. Um cartão salvo no workspace do cliente sempre vem primeiro.
• Ele nunca paga uma recarga. Ninguém no workspace do cliente consegue gastá-lo quando quiser: recargas são pagas com Pix, com a página hospedada ou com um cartão digitado na hora.
• O vínculo fica registrado no Histórico do workspace como Cartão de reserva vinculado / Cartão de reserva desvinculado.

Se você quer que a inadimplência de um cliente suspenda só esse cliente, não vincule o cartão compartilhado a ele — ou desvincule: enquanto o vínculo existir, as renovações dele são cobradas de você.

​

Conexões de WhatsApp (números)

​

Quando cobramos

• Criar o número ou gerar o QR / link de conexão não cobra. A cobrança acontece na primeira conexão do número. Um número que nunca conectou não conta na capacidade nem na cobrança. Veja Cobrado na primeira conexão.
• Se o número conectado passar da capacidade que você já pagou, cobramos o número extra na hora: primeiro a carteira, depois o cartão salvo. A primeira cobrança é proporcional aos dias que faltam até o fim do seu ciclo.
• Sem saldo na carteira e sem cartão salvo, a criação de um número acima da capacidade é recusada.
• O número pago vale pelo ciclo inteiro. Apagar um número no meio do ciclo não gera reembolso, mas a vaga continua sua até o fim do ciclo: dá para conectar outro número nela sem pagar de novo.
• Nos números da API oficial (Meta), as conversas e os templates são cobrados pela Meta, direto na forma de pagamento da conta WhatsApp Business. Esse custo não passa pela Pilot Status e não está incluído em nenhum plano.

​

A renovação mensal

A revenda fica no plano Pay As You Go: sem mensalidade de plano, você paga por número. O preço por número é o do seu contrato, e todo workspace que você criar o herda.

• No dia da renovação, cobramos cada número que já conectou alguma vez e não foi apagado, inclusive os que estiverem desconectados nesse dia.
• Desconectar não para a cobrança. Só apagar o número para. Um número que você apagar antes da renovação não entra no ciclo seguinte.
• Não há capacidade para agendar nem para devolver. Para pagar menos, basta apagar os números que não quer mais.

Veja No Pay As You Go funciona diferente.

​

Quando o pagamento falha

• Cobrança do número extra recusada na conexão: o número continua conectado, mas o envio por ele fica bloqueado (409 NUMBER_BLOCKED, reason: "extra_charge_unpaid") e o Proprietário recebe um aviso. Recarregar a carteira ou salvar um cartão retenta a cobrança sozinho. Também dá para pagar na hora com Pagar agora, na página Números, ou com POST /v1/numbers/{id}/pay.
• 7 dias sem pagamento: o número é desconectado, e conectar de novo conta como uma nova primeira conexão, cobrada de novo. Um número da Meta Cloud API nunca é desconectado: ele fica bloqueado para envio até ser pago.
• Renovação mensal recusada: há 2 dias de carência, com nova tentativa a cada 12 horas. Depois disso, todos os números daquele workspace param de enviar ao mesmo tempo: API (422 BILLING_SUSPENDED), chat do painel, Chatwoot e as mensagens que já estavam na fila. Os números continuam conectados, receber mensagens continua e os webhooks de entrada seguem chegando. As linhas telefônicas não são afetadas: elas têm cobrança própria. Recarregar a carteira ou salvar um cartão roda a cobrança de novo e libera os envios.
  Quem é suspenso é o workspace, não um número. Se todos os seus clientes dividem um workspace e a renovação dele falha, todos param de enviar de uma vez. Mantenha um workspace por cliente final: assim, uma renovação recusada suspende só os números daquele cliente.
• 15 dias suspenso, num plano cobrado pela carteira: a assinatura é cancelada e o workspace volta para o plano Free. O Proprietário recebe um aviso por e-mail e WhatsApp. Os números não são desconectados, mas o que passar dos limites do Free fica bloqueado.

​

Reativar um número excluído (até 30 dias)

Excluir um número com DELETE /v1/numbers/{id} desconecta o aparelho na hora, mas o número fica 30 dias na lixeira. Nesse prazo, ele pode ser restaurado com POST /v1/numbers/{id}/restore (ou pelo painel), com o mesmo id, chaves de API, webhooks e histórico. No Pay As You Go:

• O número volta desconectado. Conecte de novo (GET /v1/numbers/{id}/connect, ou o fluxo da Meta para um número oficial). Essa reconexão não cobra outra vez.
• Se a cobrança não passar, a resposta é 422, nada é cobrado e o número continua excluído. Repetir o mesmo restore nunca cobra duas vezes.
• Enquanto o número está na lixeira, o mesmo telefone não pode ser criado de novo (409 NUMBER_SOFT_DELETED): restaure-o ou purgue-o.
• Depois de 30 dias, a exclusão é definitiva (404 RESTORE_WINDOW_EXPIRED). Purgar antes disso também é definitivo e, num número da Meta, descadastra o número na Meta.
• O webhook number.restored avisa quando um número volta.

Na prática: se o seu cliente atrasou, você excluiu o número antes da renovação e ele pagou depois, restaurar custa o proporcional do que falta do ciclo, e você não perde o histórico nem as configurações dele.

​

O que o seu sistema precisa registrar

• Qual workspace é de cada cliente (o id, de POST /v1/workspaces ou GET /v1/workspaces), e de qual cliente é cada número, com a data da primeira conexão de cada um. O webhook number.connected é o gatilho: é a partir dele que a gente cobra você, então é a partir dele que você cobra o seu cliente. number.disconnected avisa quando o número caiu.
• A data de renovação de cada workspace com a Pilot Status. Quando um cliente seu para de pagar, apague o número dele antes dessa data. Desconectar não basta. Se você não fizer nada, paga o mês seguinte desse cliente. (Fora do Pay As You Go, apague o número e agende a redução da capacidade.)
• Uma regra de cancelamento que acompanhe a nossa. A gente não reembolsa o ciclo em andamento. Se você reembolsar o seu cliente, a diferença sai do seu bolso. A vaga paga continua sua até o fim do ciclo: use-a para o próximo cliente.
• Quem paga a Meta, se os seus clientes usam a API oficial: de quem é a conta WhatsApp Business e qual forma de pagamento está cadastrada nela. Deixe isso no contrato com o seu cliente.
• Números bloqueados por falta de pagamento: leia extraChargeUnpaidSince e extraChargeDisconnectAt em GET /v1/numbers para saber o que está bloqueado e quando será desconectado. Veja Pagar número extra.

​

Linhas telefônicas

​

Quando cobramos

• R$ 33,90 por mês, por linha (US$ 33.90 em workspaces em dólar), em qualquer plano, inclusive o Free — a menos que a equipe da Pilot Status tenha definido um preço de linha próprio para você. Nesse caso, todo workspace que você criar o herda, e ele é o preço de toda compra e de toda renovação a partir da próxima. Veja Preço próprio da linha.
• A compra cobra o primeiro mês inteiro, sem valor proporcional.
• Cada linha renova no mesmo dia do mês em que foi comprada, independente do ciclo do plano e dos números. Cinco linhas compradas em dias diferentes dão cinco datas de renovação.
• As linhas usam a mesma carteira do plano e dos números. Não existe reserva de saldo por produto: a cobrança que vence primeiro usa o saldo primeiro.
• A linha não conta no limite de números. Se você ativar o WhatsApp numa linha e conectar esse número na Pilot Status, ele é cobrado como qualquer outro número, pelas regras da seção anterior.

​

Avisos e atraso

• Cerca de 48 horas antes de cada renovação, o titular e o Proprietário recebem um aviso com as linhas que renovam naquele dia e o total.
• Sem cartão salvo, há também um aviso quando o saldo da carteira não cobre as renovações dos próximos 7 dias.
• Renovação recusada: a linha fica 2 dias com pagamento pendente (nova tentativa a cada 6 horas), depois é suspensa e, 1 dia depois, devolvida à operadora. Veja Linhas em atraso.
• Cancelar uma linha em dia: ela continua funcionando até o fim do mês já pago, sem reembolso, e é devolvida nesse dia.
• Verificação do titular recusada: as linhas compradas enquanto a verificação estava em análise continuam funcionando por 3 dias e depois são devolvidas. O valor pago por elas volta como saldo na carteira.

​

O que o seu sistema precisa registrar

• De qual cliente é cada linha e a data de compra, porque a renovação é mensal nessa data.
• Cobre o seu cliente antes da data de renovação, não depois. A nossa carência é de 2 dias, e a devolução é definitiva.
• Cliente inadimplente: decida antes do aniversário da linha se vai cancelar a linha ou pagar mais um mês por ele.
• Webhooks úteis (veja Webhooks das linhas): phone_line.purchased, phone_line.renewed, phone_line.payment_failed, phone_line.suspended, phone_line.returned (com reason: unpaid, canceled_by_customer ou verification_rejected) e phone_line.canceled. Cada linha também expõe price (quanto custa a próxima renovação), amountDue (quanto pagar uma linha em atraso cobra agora), currency e currentPeriodEnd pela API das linhas. Os mesmos eventos chegam a um webhook do workspace.

​

Saldo

• Mantenha na carteira de cada workspace, pelo menos, o valor das renovações de linhas dos próximos 7 dias mais a renovação mensal dos números dele.
• Deixe um cartão salvo como reserva — no workspace, ou o seu cartão compartilhado. É ele que evita o bloqueio de envio e a devolução de linhas quando a carteira não cobre uma cobrança.
• O Proprietário recarrega a carteira em Planos → Carteira. Pela API: Pix ou página hospedada com POST /v1/billing/checkout, ou um checkout dentro do seu próprio app com Stripe Elements. O wallet.topup_paid avisa quando o dinheiro entrou, para você liberar o serviço do seu cliente do seu lado.