Assinaturas e Cobrança

Todo canal retornado por GET /api/v1/channels traz um objeto subscription descrevendo seu estado de cobrança atual. Esta página explica o que esses estados significam e como mudam ao longo do ciclo de vida de um canal. Para os tipos dos campos, veja a Referência da API.

Um canal pode enviar e receber mensagens apenas enquanto sua assinatura estiver active. Quando não está, as chamadas de envio/recebimento são rejeitadas até que uma licença seja (re)vinculada.

O objeto subscription

"subscription": {
  "status": "active",
  "source": "paddle",
  "tier": "pro",
  "expires_at": "2025-02-15T10:30:00",
  "auto_renew": true
}

status — active, expired, canceled ou none (nenhuma licença vinculada; o canal não pode enviar/receber).
source — de onde veio o direito de uso: trial (concedido automaticamente no cadastro), paddle (assinatura paga) ou enterprise (assinatura customizada provisionada pela equipe Fiwano, por exemplo um acordo de parceria ou cobrança por fatura). null quando status é none.
tier — starter ou pro. pro é obrigatório para mensagens de mídia e CRUD/envio de modelos do WhatsApp. null quando status é none.
expires_at — timestamp ISO-8601 UTC de quando o período atual termina. Se auto_renew for true, esta é a próxima data de renovação; caso contrário, é o limite após o qual o canal para de funcionar.
auto_renew — true somente para uma assinatura Paddle ativa que será renovada em expires_at. Sempre false para trial e Enterprise.

O que as combinações significam

Assinatura Paddle ativa — {status: "active", source: "paddle", auto_renew: true, expires_at: <próxima renovação>}.
Renovação Paddle em nova tentativa — {status: "active", source: "paddle", auto_renew: true, expires_at: <há pouco no passado>}. Enquanto um pagamento de renovação é retentado, status permanece active e expires_at pode ficar ligeiramente no passado — o serviço continua durante essa breve janela de tolerância. Depois resolve para renovado (expires_at futuro) ou, se o pagamento seguir falhando, expira.
Paddle com cancelamento agendado — {status: "active", source: "paddle", auto_renew: false, expires_at: <limite>}. O cliente cancelou no Paddle; o serviço continua até expires_at, depois o canal fica órfão.
Trial — {status: "active", source: "trial", tier: "pro", auto_renew: false, expires_at: <cadastro + 7 dias>}.
Enterprise — {status: "active", source: "enterprise", auto_renew: false, expires_at: <fim do prazo acordado>}. As renovações são combinadas com a equipe Fiwano antes de expires_at.
Sem assinatura ativa — {status: "none", source: null, tier: null, expires_at: null, auto_renew: false}. Envio/recebimento falharão; vincule uma licença para restaurar o serviço.

Dica. Trate status como a única fonte de verdade para saber se um canal pode operar. Não o deduza por conta própria a partir de expires_at — durante a janela de tolerância do Paddle, um canal active pode legitimamente ter um expires_at no passado.