Uni Mobile
POWERED BYsynthron

API Uni Mobile

Venda, ative e entregue linhas e eSIM de forma automática, direto do seu site ou sistema. Versão 1.

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).

1Seu site ou sistema lista os planos
2Envia os dados do cliente e cria o pedido
3A plataforma escolhe o número pelo CEP e ativa a linha
4O eSIM (QR Code e código) volta pela API e por aviso
QuemChavePagamento
Sites (navegador)upk_… públicaO 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_… secretaAtivaçã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.

statusSignificado
aguardando_pagamentoPedido criado, esperando a confirmação do pagamento.
aguardando_chipPago; a equipe vai separar e ativar o chip físico (pedidos de chip feitos pelo site).
processandoAtivando a linha na operadora.
ativoLinha ativa. Para eSIM, o campo esim traz o QR Code e o código.
falhouNão foi possível ativar; o motivo vem em erro. Nossa equipe pode tentar de novo pela intranet.
canceladoCancelado 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
PrefixoUso
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.
Segurança: a chave secreta (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

GET/v1/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)

POST/v1/pedidos

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" }
}'
CampoObrigatórioDescrição
plano_idsimId de /v1/planos.
tiponãoesim (padrão) ou chip.
iccidpara chipICCID 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.tiponãoPF (padrão) ou PJ. Para PJ, envie razao_social e o CNPJ em documento.
cliente.nascimentoPFAAAA-MM-DD.
enderecosimO número da linha é escolhido pela cidade do CEP.
portabilidadenã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_externanãoSeu identificador; dá para buscar por ele.
aguardar_pagamentonãotrue para só ativar depois de confirmar o pagamento.

Resposta 202: o pedido com status: "processando".

Consultar pedido

GET/v1/pedidos/{id}
{
  "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.

GET/v1/pedidos?ref_externa=venda-10293&status=ativo&pagina=1

Lista os pedidos (50 por página), do mais novo para o mais antigo.

POST/v1/pedidos/{id}/cancelar

Cancela um pedido que ainda aguarda pagamento.

Confirmar pagamento

POST/v1/pedidos/{id}/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.

POST/v1/checkout

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.

GET/v1/checkout/{id}?token=…

Consulte a cada 5 segundos. Quando status for ativo, mostre o QR Code de esim.qrcode_svg.

POST/v1/checkout/{id}/simular-pagamento?token=…

Só com chave de teste: finge que o cliente pagou, para você testar o site do começo ao fim.

Consultar linha

GET/v1/linhas/{numero}
{ "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:

EventoQuando
pedido.ativadoLinha ativa; o eSIM vem em dados.esim.
pedido.falhouA ativação não foi possível.
pedido.pagamento_confirmadoPagamento confirmado; a ativação começou.
pedido.canceladoO 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." } } }
HTTPcodigo
401chave_invalida
403origem_nao_permitida, chave_secreta_no_navegador
404nao_encontrado, rota_desconhecida
409status_invalido
422dados_invalidos (detalhes em campos)
429limite

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>