Introdução
API de emissão de eSIM para operadores e agências diretas.
Esta API permite emitir eSIMs de viagem de forma programática, integrando o fluxo de venda ao seu próprio sistema (ERP, e-commerce, CRM ou atendimento).
Ela atende dois perfis de integração:
- Operador — a chave pode operar várias agências abaixo do operador.
- Agência direta — a chave opera uma única agência.
O tipo de dono e as agências acessíveis são determinados pela chave de API; o mesmo conjunto de endpoints serve aos dois perfis.
Autenticação
Toda requisição usa uma chave de API no header Authorization:
Authorization: Bearer ong_sk_...Gere e gerencie suas chaves no painel administrativo. A chave é exibida uma única vez no momento da criação — guarde-a com segurança. Chaves podem ser restritas por IP.
Se o operador ou a agência dona da chave estiver desativado, as chamadas
passam a retornar 403 (Operador desativado ou Agência desativada).
Nunca exponha a chave de API em código de frontend ou em repositórios públicos. Ela concede acesso de emissão em nome da(s) sua(s) agência(s).
Como funciona a emissão
A emissão é self-service por link de ativação: o eSIM só é provisionado quando o cliente final ativa pelo link — a criação do pedido não emite o eSIM. O acompanhamento padrão é por polling; atualizações via webhook podem ser habilitadas sob demanda — fale com o time comercial.
Descubra o contexto da chave
GET /v1/whoami retorna o tipo de dono, o escopo e os agencyId que a chave
pode operar.
Liste os planos disponíveis
GET /v1/agencies/{agencyId}/plans retorna os planos com o preço de venda da
agência.
Crie (ou reutilize) o cliente
POST /v1/agencies/{agencyId}/customers cadastra o cliente final.
Crie o pedido
POST /v1/agencies/{agencyId}/orders congela o preço e dispara o link de
ativação ao cliente. O retorno inclui activationUrl, caso você prefira
enviar o link pelo seu próprio canal.
Acompanhe até a emissão
Faça polling em GET /v1/agencies/{agencyId}/orders/{id}. Quando o cliente
ativa pelo link, o pedido passa a emitido e os dados do eSIM ficam
disponíveis no pedido.
Escopo dos endpoints
Exceto GET /v1/whoami, todos os endpoints são escopados por agência sob
/v1/agencies/{agencyId}/.... Uma chave só pode operar os agencyId aos quais
tem acesso — chamadas para agências fora do escopo retornam 403.