​

Linhas telefônicas

​

Endpoints

​

Credenciais e permissões

​

Antes da primeira compra: verificação do titular

​

Preço e pagamento

• R$ 33,90 por linha por mês para workspaces em BRL, US$ 33.90 para workspaces em USD. O preço é congelado em cada linha no momento da compra: price e currency da linha são o que toda renovação dessa linha cobra.
• O primeiro mês é cobrado integralmente na compra — sem cobrança proporcional.
• Cada linha tem seu próprio ciclo, ancorado na data da compra. Ela renova no mesmo dia do mês seguinte; quando esse dia não existe, no último dia do mês, e esse dia mais curto passa a valer daí em diante: comprada em 31/01 → renova em 28/02 (ou 29/02) → 28/03 → 28/04. As datas são calculadas em UTC. O currentPeriodEnd da linha é a próxima renovação.
• O pagamento sai primeiro da carteira pré-paga, e o que os créditos não cobrirem é cobrado no seu cartão salvo. Se a etapa do cartão falhar, os créditos já descontados são devolvidos. Recarregue a carteira pelo painel (cartão ou PIX), ou pela API com POST /v1/billing/checkout — wallet_topup (só cartão) ou add_card para salvar um cartão.
• As linhas estão disponíveis em todos os planos, inclusive o Free, sem limite de quantas um workspace pode ter. Um único POST compra no máximo 10.
• As linhas compartilham a carteira com o produto WhatsApp. O painel mostra o extrato agrupado por produto.

​

Ciclo de vida da linha

                 renewal fails                2 days unpaid              1 more day unpaid
   ACTIVE ─────────────────────▶ PAYMENT_PENDING ─────────────▶ SUSPENDED ───────────────▶ RETURNED
     ▲                                  │                            │                     (final)
     └──────────── a renewal charge succeeds (retried every 6 hours) ┘

   ACTIVE ── DELETE ──▶ ACTIVE + cancelAtPeriodEnd: true ── period ends ──▶ CANCELED (final)
   PAYMENT_PENDING / SUSPENDED ── DELETE ──▶ RETURNED (immediately, final)

• A renovação é tentada quando currentPeriodEnd é atingido. O faturamento roda uma vez por hora, então a cobrança — e cada transição abaixo — acontece em até cerca de uma hora depois do respectivo prazo.
• Uma renovação que falha leva a linha para PAYMENT_PENDING e é tentada de novo a cada 6 horas. Créditos ou um cartão adicionados são aproveitados na próxima tentativa; o botão Pagar tudo do painel tenta de novo na hora.
• 2 dias após a falha, a linha fica SUSPENDED; 1 dia depois, fica RETURNED. Da primeira cobrança que falhou até perder o número: cerca de 3 dias.
• Pagar com atraso mantém a data de aniversário. Quando uma renovação finalmente dá certo — mesmo em SUSPENDED — a linha volta para ACTIVE e o novo período conta a partir da data original de renovação, não da data do pagamento.
• Cada etapa envia um aviso e um evento de webhook: phone_line.payment_failed (uma vez por renovação, na primeira tentativa que falha), phone_line.suspended e phone_line.returned. Uma renovação bem-sucedida envia phone_line.renewed.

​

Cancelamento

• ACTIVE — sem estorno. A linha continua ACTIVE e utilizável (inclusive para códigos) até currentPeriodEnd, com cancelAtPeriodEnd: true; ela não é renovada e passa a CANCELED no fim do período. Desfazer um cancelamento agendado só é possível no painel.
• PAYMENT_PENDING / SUSPENDED — não resta período pago, então a linha é devolvida imediatamente (RETURNED).
• RETURNED / CANCELED — 409 NOT_CANCELABLE.

​

O fluxo do código de ativação

​

Idempotência

​

Limites

• De 1 a 10 números por requisição de compra, sem duplicados. Sem limite de linhas por workspace.
• Um pedido de código aguardando por linha.
• Histórico de códigos: limit de 1–100 por chamada (padrão 20).
• As requisições que chegam à nossa operadora — buscar, comprar, pedir um código, cancelar uma linha em atraso — consomem uma cota de requisições compartilhada por toda a plataforma. Quando ela se esgota, elas respondem 503 SUPPLIER_UNAVAILABLE (“Tente de novo em alguns minutos”), ou o SUPPLIER_UNAVAILABLE por número dentro de uma compra. Busque uma vez por DDD e reutilize o resultado, em vez de consultá-lo repetidamente.
• Não há outro limite de taxa específico para estes endpoints.

​

Erros

{
  "error": "Line not found. | Linha não encontrada.",
  "code": "LINE_NOT_FOUND"
}

​

Resultados por número de uma compra

​

Só no painel

• Verificação do titular (envio de documento e código de contato).
• Ouvir a gravação da ligação de um pedido de código.
• Desfazer um cancelamento agendado.
• Pagar tudo e Escolher quais linhas manter para linhas em atraso.
• O extrato da carteira agrupado por produto.
• Criar e gerenciar webhooks das linhas e ler o log de entregas deles.