Documentação da API

API REST para acesso em lote / automatizado ao jiema.my. Use-a para integrar a verificação por SMS aos seus próprios serviços. Todos os endpoints retornam JSON.

Entrar para criar sua primeira API key.

Conteúdo

Autenticação
Erros e limites de taxa
GET /v1/account
GET /v1/services
GET /v1/countries
GET /v1/prices
POST /v1/orders
GET /v1/orders/:id
POST /v1/orders/:id/cancel
POST /v1/orders/:id/next-sms
GET /v1/orders
Fluxo de trabalho típico

Autenticação

Cada requisição deve incluir sua API key:

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Forma alternativa do cabeçalho: X-API-Key: jm_xxx…

Crie e revogue chaves em /account/api-keys. Cada usuário pode manter até 10 chaves ativas. O token completo é exibido apenas uma vez na criação — guarde-o com segurança.

Erros e limites de taxa

Todos os erros retornam JSON:

{ "ok": false, "code": "RATE_LIMITED", "message": "..." }

HTTP	code	significado
401	AUTH_MISSING / AUTH_INVALID	Sem chave ou revogada
403	FORBIDDEN	Banido ou sem acesso
400	BAD_REQUEST / INSUFFICIENT / NO_NUMBERS / …	Erro de validação ou de negócio
404	NOT_FOUND	O pedido não existe (ou não é seu)
429	RATE_LIMITED	Limitação por chave
500	INTERNAL	Erro do servidor (reportado automaticamente)

Limites de taxa: Por chave, janela deslizante de 60s. Endpoints de escrita (orders, cancel, next-sms) 10 req/min; endpoints de leitura (account, services, prices, list) 60 req/min.

GET /v1/account

Obtenha seu saldo atual e o perfil básico.

curl https://jiema.my/api/v1/account \
  -H "Authorization: Bearer jm_xxx"

# 200 OK
{ "ok": true, "data": {
  "id": "clxxxxxxxxxxx",
  "balanceCents": "1200",       // string to preserve precision; $12.00
  "referralCode": "abc123",
  "displayName": "Alice",
  "lang": "en"
}}

GET /v1/services

Lista os serviços com estoque. Cache no servidor por ~5 min.

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

{ "ok": true, "data": { "items": [
  { "code": "tg", "slug": "telegram", "name": "Telegram",
    "minCostUsd": 0.18, "totalCount": 1234, "countryCount": 24 },
  ...
] }}

Use code (ou o slug amigável) como campo service ao criar um pedido.

GET /v1/countries

curl https://jiema.my/api/v1/countries -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "items": [
  { "id": 7, "slug": "my", "name": "Malaysia" },
  ...
] }}

id é o identificador numérico de país do provedor; slug é o código curto de SEO (ex.: "my" / "us"). Qualquer um dos formatos funciona como campo country.

GET /v1/prices?service=tg

Preço e estoque por país para um serviço específico. Os preços já incluem a margem/desconto configurada pela operação.

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

{ "ok": true, "data": {
  "service": "tg",
  "items": [
    { "countryId": 7, "countrySlug": "my", "priceCents": "32", "count": 540 },
    ...
  ]
}}

POST /v1/orders

Cria um pedido de verificação por SMS. O sistema reserva um número de telefone no provedor e desconta o valor cobrado do seu saldo.

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_xxx" \
  -H "content-type: application/json" \
  -d '{ "service": "tg", "country": 7 }'

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "WAITING",
  "service": "tg",
  "country": "7",
  "phone": "+60123456789",
  "expiresAt": "2026-05-22T08:30:00.000Z",
  "chargedCents": "32"
}}

Não há campos opcionais além de service / country.

Códigos de erro comuns: INSUFFICIENT (recarga necessária), NO_NUMBERS, BAD_SERVICE, BAD_COUNTRY.

GET /v1/orders/:id

Faça polling até que status seja RECEIVED e smsBody não seja null.

curl https://jiema.my/api/v1/orders/ckxxxxx -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "RECEIVED",
  "phone": "+60123456789",
  "smsBody": "Your verification code is 123456",
  "smsHistory": [
    { "body": "Your verification code is 123456", "receivedAt": "..." }
  ],
  "smsReceivedAt": "2026-05-22T08:12:34.000Z",
  ...
}}

Status: WAITING (número ativo, aguardando SMS) · RECEIVED (código chegou) · COMPLETED / FAILED / CANCELLED são finais.

Intervalo de polling sugerido: a cada 3–5 segundos. A sincronização com o provedor é executada dentro deste endpoint, então fazer polling nele avança o estado mesmo que o worker em segundo plano esteja ocupado.

POST /v1/orders/:id/cancel

Cancela um pedido que ainda não recebeu código. Estorno total ao seu saldo.

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/cancel \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "CANCELLED" }}

Rejeitado com CODE_RECEIVED se o número já recebeu algum SMS, ou ALREADY_CHANGED se o status mudou de forma concorrente.

POST /v1/orders/:id/next-sms

Após RECEIVED, solicita ao provedor que mantenha o número ativo e aguarde outro SMS (sem cobrança adicional dentro da janela ativa).

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/next-sms \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "WAITING" }}

GET /v1/orders

Lista paginada por cursor dos seus pedidos recentes.

curl "https://jiema.my/api/v1/orders?limit=20" -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "items": [ { "id": "ck...", "status": "RECEIVED", "service": "tg", ... }, ... ],
  "nextCursor": "ck..." | null
}}

Query opcional: status · limit 1–100 (padrão 20) · cursor = nextCursor da página anterior.

Fluxo de trabalho típico

Recarregue pela interface web → GET /v1/account para confirmar o saldo.
Escolha um serviço: GET /v1/services e GET /v1/prices?service=tg.
Crie um pedido: POST /v1/orders com service + country.
Leia data.phone e dispare o SMS do provedor a partir do seu cliente (ex.: cole no cadastro do Telegram).
Faça polling em GET /v1/orders/:id a cada 3–5s. Quando status === "RECEIVED", leia smsBody.
Se o SMS estiver errado ou você quiser um segundo código: POST /v1/orders/:id/next-sms → volta para WAITING.
Pronto. Se você cancelar antes de qualquer SMS chegar: POST /v1/orders/:id/cancel para estorno total.

jiema.my