Gerenciar pacotes eSIM recorrentes

Use uma assinatura recorrente para comprar pacotes de dados em um ciclo de cobrança. Você precisa de permissão para comprar serviço eSIM, de fundos na carteira da organização e de um assinante para a pessoa que usa o eSIM. A disponibilidade depende da oferta e do perfil selecionados.

Este guia abrange novas compras e a inscrição em um eSIM existente. O API de eSIM não oferece uma operação para trocar uma assinatura ativa por outro plano.

1. Revisar os termos recorrentes

Para um eSIM novo, obtenha as opções de checkout. Ofereça renovação automática quando recurrence.available for true e use o quote correspondente como termos aceitos. Se não estiver disponível, inspecione unavailable_reason e ofereça uma opção de compra compatível.

Para um eSIM existente, liste as ofertas compatíveis com recurring_only=true e depois obtenha os termos recorrentes da oferta selecionada. A inscrição verifica a compatibilidade novamente antes de aceitar a compra.

Exiba o preço recorrente, a moeda publicada, a cadência e o modo de entrega antes da aceitação. O valor cotado é antes de impostos; o histórico de períodos registra o total cobrado e o imposto. calendar_month segue meses do calendário; fixed_days usa o número indicado de dias de 24 horas. A carteira da organização paga pelo serviço; o assinante não tem uma carteira separada.

Verifique se o pacote cobre o intervalo pago (exact_period) ou se cada renovação compra um pacote padrão (recurring_top_up). Com recargas recorrentes, a ativação e a expiração seguem os termos do pacote e podem diferir dos limites de cobrança. Não prometa dados ininterruptos apenas porque a renovação está agendada.

2. Atribuir o assinante

No painel, abra o perfil em eSIMs, abra More eSIM actions, selecione Assign person, escolha o contato e confirme Assign person. Você não pode alterar a pessoa atribuída depois.

Com o API, crie um assinante usando o contact_id de um contato no seu espaço de trabalho. Isso requer email_marketing:read para Contacts e esim:write. A resposta retorna o assinante existente quando o contato já possui um.

Criar a associação impede a exclusão do contato, inclusive após o encerramento do eSIM. Associações de assinante não podem ser removidas, desvinculadas ou anonimizadas no momento. Decida se essa retenção se adequa ao seu processo de atendimento ao cliente antes de criar uma.

Para um perfil existente, atribua o eSIM usando subscriber_id. Repetir a mesma atribuição retorna o registro existente; atribuir uma pessoa diferente retorna 409. Para um perfil novo, inclua subscriber_id na compra para que a atribuição seja concluída junto com a entrega.

A atribuição não concede acesso ao espaço de trabalho nem permissão para ler credenciais de instalação. Trate a coleta de identificação separadamente usando os requisitos da oferta e o guia de integração.

3. Inscrever e verificar a entrega

Para um eSIM existente já atribuído, no painel, abra Automatic renewal e selecione Set up renewal. Escolha um Package, selecione Check recurring price e revise o preço, a cadência e os termos de entrega do pacote. Selecione Buy first package and renew para comprar o primeiro período e ativar a renovação.

Para um novo eSIM pela API, crie um pedido com a offer_id selecionada, a subscriber_id do espaço de trabalho e estes termos de checkout aceitos:

• Defina offer_revision como recurrence.quote.offer_revision.
• Defina recurrence.recurrence_revision como recurrence.quote.recurrence_revision.
• Defina recurrence.accepted_price como o objeto recurrence.quote.price completo.

Envie um Idempotency-Key; omita esim_id e expected_price para esta compra. Salve o ID do pedido e seu recurring_subscription_id. O primeiro período de cobrança começa quando o pagamento é financiado. Acompanhe o pedido até ele ser concluído ou falhar, usando as etapas de recuperação de compra se necessário.

Para um eSIM existente já atribuído, crie uma assinatura recorrente com esim_id, offer_id, o revision da oferta como offer_revision e o revision dos termos recorrentes como recurrence_revision. Envie o price completo dos termos recorrentes como accepted_price. Um Idempotency-Key é obrigatório; reutilize-o com a mesma solicitação para recuperar a inscrição. A inscrição compra o primeiro período imediatamente; ela não espera um pacote existente se esgotar.

Obtenha a assinatura e liste seus períodos. Confirme pagamento e entrega do pacote separadamente. Para um novo eSIM, entregue os detalhes de instalação após a conclusão do pedido.

4. Monitorar a renovação

Abra Subscriptions para inspecionar os termos aceitos, o status e a próxima renovação. Na API, leia next_renewal_at, stop_reason e o histórico de períodos. Uma alteração no preço publicado exige nova aceitação; uma renovação sem fundos interrompe compras futuras.

Se status for needs_attention, inspecione o período mais recente e o pedido associado. Uma entrega não resolvida pode permanecer pagável e bloqueia uma nova inscrição substituta. Entre em contato com o suporte informando essas referências antes de comprar uma substituição.

5. Interromper a renovação futura

Na seção Automatic renewal do eSIM, selecione Cancel renewal. Revise o fim do período pago atual e confirme Cancel renewal no diálogo. Verifique a assinatura atualizada para consultar a data de cancelamento.

Com a API, cancele a assinatura e depois leia-a novamente. Verifique cancel_at_period_end, cancellation_effective_at e next_renewal_at para confirmar quando a renovação termina. Um período já confirmado permanece pagável. Os pacotes entregues mantêm sua própria validade, e o perfil instalado é preservado.

Remover o perfil do telefone não cancela a renovação. Liberar um eSIM o desativa permanentemente, perde os dados restantes e não gera reembolso. Use ações de serviço quando você pretender alterar a conectividade além da renovação.

Solução de problemas

Adicionar fundos à carteira não reinicia automaticamente uma assinatura parada. Verifique stop_reason e o estado final do serviço anterior antes de aceitar uma nova inscrição. Uma entrega paga que falhou e seu crédito têm resultados separados: inspecione order_status e refund_transaction_id no histórico de períodos.

Verifique a jornada do cliente

Confirme que o cliente consegue encontrar a franquia comprada, a validade do pacote, a próxima renovação, a data de cancelamento e o contato de suporte. Verifique a entrega do primeiro pacote e teste os dados móveis em um dispositivo compatível. Confira o pagamento e a entrega de um período subsequente separadamente da data de renovação programada.

Próximos passos

• Consultar saldos e comprar uma recarga avulsa.
• Preparar a instalação no dispositivo.
• Investigar problemas de pagamento ou entrega.