Automatize a verificação por SMS: guia completo da API

O site funciona bem para um cadastro ocasional: alguns cliques e uma espera curta por um SMS. Ele para de dar conta do recado quando você está escrevendo testes automatizados, um script de cadastro em massa, um pipeline de CI ou um bot que precisa buscar o código de verificação sem ninguém por perto. Isso o site não faz. A API faz. Aqui está tudo o que você precisa para sair do zero e chegar a um fluxo funcionando.

Passo 1: Consiga uma chave de API

Faça login e acesse /account/api-keys para criar uma. As chaves têm o formato jm_ seguido de uma sequência aleatória. O texto completo aparece uma única vez — guardamos apenas um hash, nunca a chave em si, então não existe a opção "recuperar minha chave" se você perdê-la. Nesse caso, é só apagar e criar outra.

Toda requisição usa autenticação Bearer padrão:

Authorization: Bearer jm_your_key

Trate a chave como uma senha — não faça commit dela em um repositório público, não cole em uma conversa para alguém te ajudar a debugar. Se suspeitar que ela foi exposta, volte em /account/api-keys, apague-a e crie outra; a antiga para de funcionar imediatamente.

Passo 2: Escolha um serviço e um país

Para criar um pedido você precisa de duas coisas: service (o código do serviço) e country (o id do país). Comece listando o catálogo:

curl https://jiema.my/api/v1/services \
  -H "Authorization: Bearer jm_your_key"

Cada item tem um campo code (o do Telegram é tg) — passe esse valor direto para o endpoint de pedido, é mais confiável do que tentar reconstruir um slug por conta própria. Para ver preço e estoque em tempo real de um serviço específico em vários países, adicione o parâmetro service:

curl "https://jiema.my/api/v1/prices?service=tg" \
  -H "Authorization: Bearer jm_your_key"

Cada entrada em items traz countryId / priceCents / count (a quantidade de números disponíveis agora). Confira o count antes de fazer o pedido — se for zero, o pedido vai falhar, então não desperdice uma chamada só para descobrir isso na prática.

Passo 3: Faça o pedido

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"6"}'

Um pedido bem-sucedido retorna um número de telefone e um prazo de validade:

{
  "ok": true,
  "data": {
    "id": "cm...",
    "status": "WAITING",
    "phone": "62812xxxxxxx",
    "expiresAt": "2026-08-01T12:15:00.000Z",
    "chargedCents": "40"
  }
}

A cobrança acontece nessa etapa — chargedCents é o valor efetivamente descontado (em centavos). Use esse número no app de destino para receber o código de verificação e siga para o próximo passo.

Passo 4: Faça polling até o código chegar

Não existe WebSocket nem push via webhook — você recebe o conteúdo do SMS fazendo polling em GET /api/v1/orders/:id até smsBody deixar de ser null:

while true; do
  RESP=$(curl -s https://jiema.my/api/v1/orders/$ORDER_ID \
    -H "Authorization: Bearer jm_your_key")
  BODY=$(echo "$RESP" | jq -r '.data.smsBody')
  if [ "$BODY" != "null" ]; then
    echo "Code received: $BODY"
    break
  fi
  sleep 5
done

Cinco segundos é um bom ponto de partida — o número vale por 15 minutos, e o limite de 60 requisições por minuto para consultas deixa bastante margem. Três segundos também funcionam se você estiver com pressa; fazer polling a cada segundo não traz o código mais rápido, só consome seu limite de taxa mais rápido.

Pegadinhas

• O limite de taxa é por usuário, não por chave. Endpoints de escrita (order / cancel / next-sms) ficam limitados a 10 por minuto por usuário; consultas, a 60 por minuto. Criar mais chaves não aumenta seu limite — todas compartilham o mesmo teto.
• Os números expiram em 15 minutos. Um número não usado que expira sem receber código é estornado automaticamente — não precisa pedir. Mas se o seu próprio pipeline demorar demais para de fato usar o número (parado numa fila, por exemplo), ele já vai estar morto quando chegar a sua vez.
• Um número pode receber mais de um código. Se o app de destino manda o SMS em duas etapas (uma confirmação de cadastro e depois um código de login separado), chame POST /api/v1/orders/:id/next-sms depois que o primeiro chegar para avisar "terminei com esse, continue esperando" — sem precisar abrir um novo pedido para ganhar outro número.
• Depois que o código chega, o cancelamento para de funcionar. POST /api/v1/orders/:id/cancel estorna instantaneamente enquanto o número ainda está esperando um código. Assim que smsBody deixa de ser nulo pela primeira vez, a mesma chamada passa a retornar um erro CODE_RECEIVED — você já recebeu o que pagou, e não tem como voltar atrás.
• Não desista depois de checar o status uma única vez. O status passa de WAITING para RECEIVED. Se ele ficar parado em WAITING até expirar, geralmente é um problema de taxa de entrega daquela combinação específica de país/serviço — abrir um novo pedido em outro país costuma resolver mais rápido do que esperar.

Próximos passos

Isso cobre o fluxo principal, do pedido ao código. A lista completa de campos, códigos de erro e casos de borda de cada endpoint está em /api-docs. Se você for operar em escala — mantendo o fluxo de verificação de dezenas de contas ao mesmo tempo, por exemplo — controle o tempo do polling de cada pedido de forma independente. Não os enfileire num único loop sequencial, ou os números mais antigos vão expirar enquanto você ainda espera pelo primeiro.