Integração via API

Início rápido da API

Após a aprovação da conta, a equipe comercial atribui os preços e habilita o acesso à API. Crie uma chave no painel do parceiro. Chaves somente leitura não podem fazer pedidos. As compras também precisam estar habilitadas na conta.

Use uma chave bearer no servidor em todas as requisições. Não inclua a chave no código do navegador nem em URLs. Você pode revogá-la no painel do parceiro.

Criar pedido

Envie um UUID como Idempotency-Key. Reutilize o mesmo UUID após um tempo limite ou falha de conexão. Envie o preço confirmado pelo cliente e confirme que o aparelho de destino aceita eSIM e está desbloqueado para operadoras. Mudanças de preço em tempo real retornam 409 PRICE_CHANGED. Esta é uma API de produção: compras aceitas usam fundos reais da carteira.

POST /api/partner/v1/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 83c77d9f-395f-4ff0-8ed6-c461bda46559

{"productId":"PRODUCT_ID_FROM_CATALOG","expectedPrice":"2.25","deviceConfirmed":true}

Uma resposta 201 contém orderId e esim; verifique esim.status e esim.failure. Consulte o pedido a cada 10 segundos. Os fundos são reservados primeiro e cobrados após a entrega verificada. Uma repetição também pode retornar um pedido que falhou. Se o resultado do fornecedor for incerto, a reserva permanece enquanto o pedido original é conciliado. Os dados de instalação são privados e só aparecem após a entrega verificada.

Os valores são strings decimais em USD. As listas retornam items e nextCursor; continue até nextCursor ser null. Limites: 120 requisições por chave por minuto e 10 tentativas de compra por usuário por minuto. Respeite Retry-After no erro 429. Erros comuns: 401 chave inválida, 403 sem permissão, 402 saldo insuficiente, 404 pedido inacessível, 409 conflito de preço ou idempotência, 503 serviço indisponível. Consulte o pedido original antes de tentar outra compra.