Consultar uso e adicionar uma recarga
Use este guia para adicionar dados a um eSIM existente. Você precisa de permissão para ler o eSIM e comprar um pacote, além de saldo suficiente na carteira. A disponibilidade de recarga depende do perfil, dos pacotes existentes e da oferta selecionada.
1. Consultar os pacotes ativos
Abra o perfil em eSIMs e revise Data packages. Com a API, liste os pacotes do eSIM e verifique o status, a validade e o saldo.
balance.total_bytes é a franquia adquirida. used_bytes, remaining_bytes ou used_percent nulo significa que nenhuma medição está disponível. Mantenha esses valores como desconhecidos na sua aplicação.
Leia o campo balance_reporting do eSIM para decidir o que exibir. Se for unavailable, mostre a franquia adquirida sem apresentá-la como dados restantes medidos. Se for available, o consumo ainda pode ser desconhecido até que um relatório chegue. O histórico de uso diário é separado e não está disponível no momento.
Use balance.as_of para o horário da última atualização de saldo; antes de o consumo ser reportado, esse valor pode ser o horário de entrega do pacote. balance.observed_at é o horário de medição da rede, quando fornecido. Exiba o timestamp junto com o uso medido para que o cliente reconheça um relatório atrasado.
2. Listar ofertas compatíveis
Selecione Top up no eSIM ou chame Listar ofertas compatíveis para esse perfil. Use uma oferta retornada em vez de escolher do catálogo geral. Cobertura no mesmo país não estabelece compatibilidade.
Se uma recarga não estiver disponível, leia available_actions no eSIM para saber o motivo. Um pedido inacabado ou o limite de pacotes pode impedir outra compra. Resolva o pedido existente antes de tentar novamente. Atualize as ofertas compatíveis antes de enviar: uma oferta pode ficar indisponível entre a seleção e a compra.
Um eSIM em expired está inativo e pode retornar a active após a conclusão de uma recarga compatível. Verifique a ação disponível e as ofertas compatíveis antes de decidir que o perfil instalado precisa ser substituído.
3. Revisar os termos efetivos
Exiba a franquia, a cobertura, o preço publicado com moeda e a validade da oferta selecionada. Compare a validade do novo pacote com o limite de serviço active_until do eSIM, quando presente. Se esse limite encurtar a validade adquirida, o pedido retorna 409 com a validade efetiva. Exiba o período mais curto e obtenha a aceitação antes de definir acknowledge_shortened_validity: true.
Uma recarga cria outro pacote. Ela não altera o saldo de um pacote existente nem estende a validade desse pacote. Verifique a ativação e a validade do novo pacote após a entrega.
4. Aprovar e acompanhar o pedido
Confirme a compra no dashboard. Com a API, crie um pedido usando o esim_id existente, o offer_id selecionado, o revision da oferta como offer_revision e o pricing.price dela como expected_price. Omita subscriber_id; uma recarga mantém a atribuição existente. Salve o ID do pedido e um Idempotency-Key para novas tentativas.
Se o preço aceito ou a revisão mudou, busque a oferta atual e confirme os novos termos antes de enviar outra compra. Copie o valor e a moeda do preço retornado sem conversão ou arredondamento.
Acompanhe o pedido em Orders ou obtenha o pedido pela API. Inspecione status após as respostas de 201 e 202. Se a resposta for perdida, repita a mesma solicitação com a mesma chave; não crie uma compra substituta enquanto o resultado for incerto.
5. Verificar o pacote resultante
Quando o pedido estiver completed, use o package_id dele para obter o novo pacote. Confirme que o eSIM de destino, a cobertura e a franquia correspondem à compra. A recarga usa o perfil instalado; você não precisa instalar um novo eSIM. Um pacote aguardando o primeiro uso pode ainda não ter timestamp de ativação ou expiração.
Solução de problemas
Se o pedido estiver concluído mas o saldo permanecer desconhecido, compare o status do pacote e os timestamps dos relatórios. O relatório pode ficar atrasado em relação ao uso no dispositivo; comprar novamente não resolve esse atraso. Se uma compra falhar, inspecione os detalhes da falha e qualquer referência de crédito antes de tentar novamente.
Próximos passos
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.