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.

Verificando slots disponíveis

Use GET /api/v1/subscriptions quando um serviço externo precisar decidir se pode iniciar um novo fluxo de conexão de canal. O endpoint é somente leitura e retorna todas as assinaturas mais a disponibilidade agregada de slots:

curl -H "X-API-Key: $FIWANO_API_KEY" \
  https://fiwano.com/api/v1/subscriptions

{
  "available_slots": {
    "whatsapp": { "total": 0, "starter": 0, "pro": 0 },
    "instagram": { "total": 1, "starter": 0, "pro": 1 },
    "facebook": { "total": 1, "starter": 0, "pro": 1 }
  },
  "subscriptions": [
    {
      "id": "a1b2c3d4e5f67890",
      "status": "active",
      "source": "trial",
      "tier": "pro",
      "auto_renew": false,
      "assigned_channels": {
        "whatsapp": {
          "channel_id": "1111222233334444",
          "channel_type": "whatsapp",
          "name": "Acme Support",
          "is_active": false
        },
        "instagram": null,
        "facebook": null
      }
    }
  ]
}

Use available_slots.<channel_type>.total > 0 como o sinal de que um novo canal desse tipo pode ser conectado. Um canal inativo ainda pode ocupar um slot porque a Fiwano preserva o vínculo para reconexão. Em available_slots, total é a soma dos slots starter e pro atualmente livres para esse tipo de canal. Em cada assinatura, assigned_channels mostra qual canal está atribuído à assinatura para cada tipo; null significa que nenhum canal está atribuído ali.