Como funciona
Endereço base: https://api.exemplo.com.br. Todas as respostas são JSON, em UTF-8. Valores em dinheiro vêm em centavos (preco_centavos).
| Quem | Chave | Pagamento |
|---|---|---|
| Sites (navegador) | upk_… pública | O pedido já volta com o Pix e o link de pagamento (Asaas). Quando o pagamento é aprovado, a linha é ativada sozinha. |
| Sistemas de parceiros (servidor) | uk_… secreta | Ativação imediata; cobrança na fatura do mês. Se preferir cobrar do cliente antes, envie "aguardar_pagamento": true: o pedido volta com o Pix e o link de pagamento. |
A ativação leva normalmente de alguns segundos a poucos minutos. Acompanhe pelo status do pedido ou receba o aviso por webhook.
| status | Significado |
|---|---|
aguardando_pagamento | Pedido criado, esperando a confirmação do pagamento. |
aguardando_chip | Pago; a equipe vai separar e ativar o chip físico (pedidos de chip feitos pelo site). |
processando | Ativando a linha na operadora. |
ativo | Linha ativa. Para eSIM, o campo esim traz o QR Code e o código. |
falhou | Não foi possível ativar; o motivo vem em erro. Nossa equipe pode tentar de novo pela intranet. |
cancelado | Cancelado antes da ativação. |
Chaves e ambientes
As chaves são criadas pelo administrador da Uni Mobile em Intranet › Integrações. Envie a chave no cabeçalho:
Authorization: Bearer uk_live_xxxxxxxxxxxxxxxxxxxxxxxx
| Prefixo | Uso |
|---|---|
| uk_test_ upk_test_ | Teste: tudo funciona igual, mas nenhuma linha é ativada de verdade. O eSIM devolvido é fictício. Use para integrar. |
| uk_live_ upk_live_ | Produção: ativa linhas reais. |
uk_) nunca pode ir para o navegador. Se uma requisição com chave secreta vier de um navegador, ela é recusada. A chave pública (upk_) só funciona nos endereços de site cadastrados e só cria pedidos que aguardam pagamento.Limites: 300 requisições por minuto por chave secreta; na chave pública, 60 por minuto para cada visitante do site.
Planos
curl https://api.exemplo.com.br/v1/planos -H "Authorization: Bearer uk_test_..."
{ "dados": [
{ "id": "7f1c…", "nome": "Plano 10GB", "descricao": "WhatsApp ilimitado", "preco_centavos": 3990,
"preco": "39.90", "dados_gb": 10, "tipo": "Nacional", "dias": null } ] }
Criar pedido (chave secreta)
Envie o cabeçalho Idempotency-Key com um valor único por venda (por exemplo, o número do seu pedido). Se a mesma chave for repetida, a API devolve o mesmo pedido e não ativa duas linhas.
curl -X POST https://api.exemplo.com.br/v1/pedidos \
-H "Authorization: Bearer uk_test_..." -H "Content-Type: application/json" \
-H "Idempotency-Key: venda-10293" \
-d '{
"plano_id": "7f1c…",
"tipo": "esim",
"ref_externa": "venda-10293",
"cliente": { "tipo": "PF", "nome": "Maria Silva", "documento": "12345678909",
"nascimento": "1990-05-20", "email": "maria@email.com", "telefone": "11987654321" },
"endereco": { "cep": "13049900", "rua": "Av. Antonio Artioli", "numero": "570",
"complemento": "", "bairro": "Swiss Park", "cidade": "Campinas", "uf": "SP" }
}'
| Campo | Obrigatório | Descrição |
|---|---|---|
plano_id | sim | Id de /v1/planos. |
tipo | não | esim (padrão) ou chip. |
iccid | para chip | ICCID do chip físico (19 ou 20 dígitos). No checkout de sites pode ficar vazio: a equipe separa o chip depois do pagamento. |
cliente.tipo | não | PF (padrão) ou PJ. Para PJ, envie razao_social e o CNPJ em documento. |
cliente.nascimento | PF | AAAA-MM-DD. |
endereco | sim | O número da linha é escolhido pela cidade do CEP. |
portabilidade | não | { "numero": "11987654321", "operadora": "Vivo" } para trazer o número. A linha nasce com um número provisório e a portabilidade é concluída pela equipe. |
ref_externa | não | Seu identificador; dá para buscar por ele. |
aguardar_pagamento | não | true para só ativar depois de confirmar o pagamento. |
Resposta 202: o pedido com status: "processando".
Consultar pedido
{
"id": "c5b1…", "status": "ativo", "ambiente": "producao", "ref_externa": "venda-10293",
"plano": "Plano 10GB", "preco_centavos": 3990, "tipo": "esim", "numero": "19991234567",
"esim": {
"lpa": "LPA:1$smdp.exemplo.com$ABC123DEF456",
"smdp": "smdp.exemplo.com",
"codigo_ativacao": "ABC123DEF456",
"qrcode_url": "/v1/pedidos/c5b1…/qrcode.svg",
"qrcode_svg": "data:image/svg+xml;base64,PHN2Zy…",
"link_iphone": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=…"
},
"criado_em": "2026-11-18T12:00:00.000Z", "ativado_em": "2026-11-18T12:00:41.000Z"
}
qrcode_svg pode ser usado direto numa tag <img src="…"> ou num e-mail. link_iphone instala o eSIM com um toque em iPhones com iOS 17.4 ou mais novo.
Lista os pedidos (50 por página), do mais novo para o mais antigo.
Cancela um pedido que ainda aguarda pagamento.
Confirmar pagamento
Normalmente você não precisa chamar isto: os pedidos com cobrança no Asaas são confirmados sozinhos quando o Pix, o cartão ou o boleto é aprovado. Use só se você recebeu o pagamento por outro meio (chave secreta). A equipe da Uni Mobile também pode confirmar na intranet.
Checkout para sites (chave pública)
Para sites sem servidor próprio. A chave pública vai no código do site e só funciona no endereço cadastrado.
Mesmo corpo de /v1/pedidos. Resposta 201 com id, token, status: "aguardando_pagamento" e a cobrança. Guarde o token: ele é a senha do cliente para ver o próprio pedido.
{ "id": "c5b1…", "token": "Qm9…", "status": "aguardando_pagamento", "preco_centavos": 3990,
"pagamento": {
"status": "pendente",
"link": "https://www.asaas.com/i/…", // página para pagar com Pix, cartão ou boleto
"pix_qrcode": "data:image/png;base64,iVBOR…", // mostre numa <img>
"pix_copia_e_cola": "00020126…",
"vencimento": "2026-11-19" } }
Se o vencimento passar sem pagamento, o pedido vira cancelado.
Consulte a cada 5 segundos. Quando status for ativo, mostre o QR Code de esim.qrcode_svg.
Só com chave de teste: finge que o cliente pagou, para você testar o site do começo ao fim.
Consultar linha
{ "numero": "19991234567", "status": "ativa", "plano": "Plano 10GB", "tipo": "esim",
"ativada_em": "2026-11-18T12:00:41.000Z", "pedido_id": "c5b1…" }
Webhooks (avisos automáticos)
Ao criar a chave secreta, cadastre um endereço https://. Enviamos um POST nestes eventos:
| Evento | Quando |
|---|---|
pedido.ativado | Linha ativa; o eSIM vem em dados.esim. |
pedido.falhou | A ativação não foi possível. |
pedido.pagamento_confirmado | Pagamento confirmado; a ativação começou. |
pedido.cancelado | O pagamento venceu ou a cobrança foi apagada. |
POST https://seu-sistema.com/avisos
X-Evento: pedido.ativado
X-Assinatura: t=1763467241,v1=5f2b…
{ "id": "evt_9a…", "evento": "pedido.ativado", "criado_em": "…", "dados": { …mesmo formato de /v1/pedidos/{id}… } }
Responda com qualquer código 2xx. Se falhar, tentamos de novo após 1 min, 5 min, 30 min, 2 h, 6 h e 24 h. Confira a assinatura com o segredo whsec_… (Node.js):
import crypto from 'node:crypto';
function avisoValido(corpoBruto, cabecalho, segredo) {
const { t, v1 } = Object.fromEntries(cabecalho.split(',').map(p => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // aviso velho
const esperado = crypto.createHmac('sha256', segredo).update(t + '.' + corpoBruto).digest('hex');
return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(v1));
}
Erros
{ "erro": { "codigo": "dados_invalidos", "mensagem": "Confira os campos indicados.",
"campos": { "cliente.documento": "CPF inválido." } } }
| HTTP | codigo |
|---|---|
| 401 | chave_invalida |
| 403 | origem_nao_permitida, chave_secreta_no_navegador |
| 404 | nao_encontrado, rota_desconhecida |
| 409 | status_invalido |
| 422 | dados_invalidos (detalhes em campos) |
| 429 | limite |
Exemplo para um site (HTML puro)
O cliente preenche os dados, vê o Pix na tela e paga. Quando o Asaas aprova, a linha é ativada e a mesma tela mostra o eSIM, sem o cliente sair do site.
<script>
const API = 'https://api.exemplo.com.br/v1';
const CHAVE = 'upk_live_...'; // chave pública do site
const h = { 'Content-Type': 'application/json', 'X-Chave-Publica': CHAVE };
async function comprar(dados) { // dados = { plano_id, cliente, endereco }
const r = await fetch(API + '/checkout', { method: 'POST', headers: h, body: JSON.stringify(dados) });
const p = await r.json();
if (!r.ok) throw new Error(p.erro.mensagem);
localStorage.setItem('pedido', JSON.stringify({ id: p.id, token: p.token }));
document.querySelector('#pix').src = p.pagamento.pix_qrcode; // QR Code do Pix
document.querySelector('#copia').value = p.pagamento.pix_copia_e_cola; // Pix copia e cola
document.querySelector('#cartao').href = p.pagamento.link; // pagar com cartão ou boleto
acompanhar(p.id, p.token);
}
async function acompanhar(id, token) {
const r = await fetch(`${API}/checkout/${id}?token=${encodeURIComponent(token)}`, { headers: h });
const p = await r.json();
if (p.status === 'ativo') {
document.querySelector('#qr').src = p.esim.qrcode_svg;
document.querySelector('#codigo').textContent = p.esim.lpa;
document.querySelector('#iphone').href = p.esim.link_iphone;
} else if (p.status !== 'falhou' && p.status !== 'cancelado') {
setTimeout(() => acompanhar(id, token), 5000);
}
}
</script>