Integre a API de eSIM

Use a API de eSIM para comprar pacotes de dados e entregar detalhes de instalação a partir da sua aplicação. Você precisa de um espaço de trabalho, uma chave API e saldo na carteira da organização para compras em produção. Siga a autenticação e use a região API correspondente à sua chave.

Dê à chave esim:read para inspecionar ofertas e recursos, e esim:write para comprar ou gerenciar serviço. Credenciais de instalação têm permissões separadas: esim_credentials:read para recuperá-las e esim_credentials:write para criar ou enviar links de instalação. Mantenha a chave API na sua aplicação de servidor.

1. Escolha uma oferta

Liste as ofertas para o destino e então obtenha a oferta selecionada. Verifique zone.countries, a franquia e a validade em pricing, termos de velocidade e qualquer serviço telefônico incluído. Para um eSIM existente, use Listar ofertas compatíveis; a disponibilidade no catálogo geral não estabelece compatibilidade de recarga.

Obtenha os requisitos de identificação da oferta antes de coletar informações do assinante. A resposta contém um Schema JSON para cada país de cobertura, exigindo nome, sobrenome e email, além de quaisquer campos adicionais. Habilite validação de formato de email e data. Você coleta e valida essas informações; a API de eSIM não recebe nem verifica as respostas, e uma validação bem-sucedida não autoriza uma compra.

Para um novo eSIM, obtenha as opções de checkout. Exiba o preço avulso retornado ou a cotação recorrente disponível antes de aceitar a compra. Os preços do checkout são antes de impostos. A renovação tem seu próprio preço e cadência; siga pacotes recorrentes quando o cliente escolher essa opção.

Para o exemplo avulso abaixo, instale curl e jq. Defina BIRD_API_URL como sua URL base regional, BIRD_API_KEY como sua chave e ESIM_OFFER_ID como o ID da oferta selecionada:

Exemplo de código

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/offers/$ESIM_OFFER_ID/checkout" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  > esim-checkout.json

jq '.one_time' esim-checkout.json

Revise o preço e os termos da oferta antes de continuar. A cotação não reserva disponibilidade.

2. Crie a compra

Crie um pedido com offer_id. Omita esim_id para um novo perfil; inclua-o para uma recarga. Para uma compra avulsa, envie offer_revision e expected_price da cotação aceita. Esses campos rejeitam termos alterados com 409 antes da cobrança; busque e revise uma cotação atualizada antes de aceitar um preço alterado.

Defina ESIM_ORDER_KEY como um valor único para esta compra e salve-o com a solicitação. Este exemplo compra um eSIM novo, não atribuído, e copia o preço publicado sem alterar o valor ou a moeda:

Exemplo de código

jq '{offer_id, offer_revision: .one_time.offer_revision, expected_price: .one_time.price}' \
  esim-checkout.json > esim-order.json

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/orders" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ESIM_ORDER_KEY" \
  --data-binary @esim-order.json

Para atribuir um novo perfil quando a entrega for concluída, inclua um subscriber_id do espaço de trabalho; siga configuração de assinante. Uma recarga mantém a atribuição existente, então omita subscriber_id ao enviar esim_id. Envie os detalhes de instalação separadamente após a entrega.

Armazene o ID do pedido retornado. Inspecione status mesmo após HTTP 201, que pode conter um pedido concluído ou com falha. HTTP 202 significa que o processamento continua. Obtenha o pedido até que esteja completed ou failed. Um pedido concluído identifica esim_id e package_id; a instalação no dispositivo continua sendo uma etapa separada.

3. Forneça os detalhes de instalação

Após a compra, leia as credenciais de instalação, crie um link de instalação hospedado ou envie um link por email ou SMS. Mantenha detalhes de ativação e links de instalação fora de análises e logs públicos.

Para um link enviado, salve o ID de entrega e verifique o histórico de entregas. Uma resposta 202 confirma a aceitação para envio; delivered confirma a entrega da mensagem, e a instalação no dispositivo precisa de sua própria verificação. Siga o guia de instalação para métodos suportados, expiração do link e recuperação.

4. Recupere uma compra interrompida

Se a resposta de criação foi perdida ou retornou 503, repita a solicitação salva com o Idempotency-Key original; veja solicitações idempotentes. Se você tem o ID do pedido, leia esse pedido primeiro. Criar outra compra enquanto o resultado é incerto pode causar outra cobrança.

Para um pedido em charging, inspecione funding e o saldo da sua carteira. funding.required_amount é o saldo total necessário, incluindo impostos; compare-o com os fundos existentes antes de adicionar dinheiro. Pedidos avulsos tentam novamente o financiamento automaticamente. Após uma compra recorrente inicial ser recusada por fundos insuficientes, adicione fundos e tente novamente explicitamente a mesma solicitação de criação com sua chave original.

Verifique o status atual do pedido mesmo após funding.lapses_at: esse timestamp não garante o cancelamento. Um pedido ainda pode ser concluído se receber fundos antes que uma nova tentativa por fundos insuficientes o falhe.

Para interromper uma compra não financiada indesejada, cancele o pedido. Um cancelamento não financiado bem-sucedido retorna status: failed e failure_code: canceled. Um pedido avulso já financiado retorna 409 e continua. Para uma compra recorrente inicial, o pagamento recuperado durante o cancelamento pode deixar a compra paga em andamento enquanto a renovação futura é interrompida. Inspecione o pedido e a assinatura retornados antes de reportar o cancelamento ou um reembolso.

Para uma compra com falha, inspecione failure_code e failure_reason. Qualquer cobrança é creditada automaticamente; refund_transaction_id identifica um crédito emitido. Guarde o ID do pedido para suporte se o pagamento, a entrega ou o crédito permanecer sem resolução.

5. Exiba saldos e estado do serviço

Obtenha o eSIM para status, estado de instalação, pacotes e available_actions. Exiba a franquia, o consumo e a data e hora da medição do pacote usando o guia de uso. Consumo desconhecido deve permanecer desconhecido na sua aplicação.

Verifique novamente a disponibilidade da ação quando o cliente agir; a operação verifica permissões e estado outra vez. Use o guia de operações para investigar compras incompletas, problemas de instalação ou falhas de conectividade.

Próximos passos

Continue com a documentação, guias e exemplos sobre este tópico.

Obtenha um resumo de implementação