Automatizza la verifica SMS: la guida completa all'API

Il sito va benissimo per una registrazione occasionale: qualche clic e una breve attesa per un SMS. Non basta più quando stai scrivendo test automatizzati, uno script di registrazione in massa, una pipeline CI o un bot che deve recuperare il codice di verifica senza nessuno a controllare. Questo il sito non lo può fare. L'API sì. Qui trovi tutto quello che serve per partire da zero e arrivare a un flusso funzionante.

Passo 1: ottieni una chiave API

Accedi e vai su /account/api-keys per crearne una. Le chiavi hanno la forma jm_ seguito da una stringa casuale. Il testo in chiaro viene mostrato una sola volta — conserviamo solo un hash, non la chiave stessa, quindi non esiste un modo per «recuperare la chiave» se la perdi. In quel caso, non resta che eliminarla e crearne una nuova.

Ogni richiesta usa l'autenticazione Bearer standard:

Authorization: Bearer jm_your_key

Trattala come una password — non fare commit in un repository pubblico, non incollarla in una chat per farla debuggare a qualcun altro. Se sospetti che sia stata compromessa, torna su /account/api-keys, eliminala e creane una nuova; quella vecchia smette di funzionare immediatamente.

Passo 2: scegli un servizio e un paese

Per creare un ordine servono due cose: service (il codice del servizio) e country (l'id del paese). Comincia elencando il catalogo:

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

Ogni elemento ha un campo code (per Telegram è tg) — passalo direttamente all'endpoint dell'ordine, è più affidabile che ricostruire uno slug da solo. Per vedere prezzo e disponibilità in tempo reale di un servizio specifico nei vari paesi, aggiungi il parametro service:

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

Ogni voce in items ha countryId / priceCents / count (i numeri disponibili in questo momento). Controlla count prima di ordinare — se è zero l'ordine fallirà di sicuro, quindi non sprecare una chiamata solo per scoprirlo a tue spese.

Passo 3: crea l'ordine

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"}'

Un ordine andato a buon fine restituisce un numero di telefono e una scadenza:

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

L'addebito avviene in questo passaggio — chargedCents è l'importo effettivamente detratto (in centesimi). Passa questo numero all'app di destinazione per ricevere il codice di verifica, poi vai al passaggio successivo.

Passo 4: fai polling per il codice

Non c'è nessun WebSocket né push via webhook — il contenuto dell'SMS si ottiene facendo polling su GET /api/v1/orders/:id finché smsBody non smette di essere 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

Cinque secondi sono un buon punto di partenza — il numero resta valido 15 minuti, e il limite di 60 richieste al minuto per le query lascia ampio margine. Vanno bene anche tre secondi se non hai pazienza; fare polling ogni secondo non fa arrivare il codice più in fretta, consuma solo il tuo limite di frequenza più velocemente.

Insidie

• I limiti di frequenza sono per utente, non per chiave. Gli endpoint di scrittura (order / cancel / next-sms) sono limitati a 10 al minuto per utente; le query a 60 al minuto. Creare altre chiavi non alza il tetto — lo condividono tutte.
• I numeri scadono dopo 15 minuti. Un numero non usato che scade senza aver ricevuto un codice viene rimborsato automaticamente — non serve chiedere nulla. Ma se la tua pipeline impiega troppo tempo a usare davvero il numero (bloccato in una coda, per esempio), sarà già morto quando arriverà il suo turno.
• Un numero può ricevere più di un codice. Se l'app di destinazione manda l'SMS in due passaggi (una conferma di registrazione, poi un codice di accesso separato), chiama POST /api/v1/orders/:id/next-sms dopo l'arrivo del primo per dirci «ho finito con questo, continua ad aspettare» — senza bisogno di creare un nuovo ordine per ottenere un altro numero.
• Una volta arrivato un codice, l'annullamento smette di funzionare. POST /api/v1/orders/:id/cancel rimborsa all'istante mentre il numero è ancora in attesa di un codice. Da quando smsBody è diventato non nullo, la stessa chiamata restituisce invece un errore CODE_RECEIVED — hai già ottenuto ciò per cui hai pagato, quindi non si torna indietro.
• Non controllare lo status una sola volta e arrenderti. Lo status passa da WAITING a RECEIVED. Se resta fermo su WAITING fino alla scadenza, di solito è un problema di tasso di consegna di quella specifica combinazione paese/servizio — creare un nuovo ordine in un altro paese di solito risolve più in fretta che aspettare.

Prossimi passi

Questo copre il flusso principale, dall'ordine al codice. L'elenco completo dei campi, i codici di errore e i casi limite di ogni endpoint si trovano su /api-docs. Se lo usi su scala — per esempio mantenendo attivi i flussi di verifica di decine di account contemporaneamente — gestisci il polling di ogni ordine con un tempismo indipendente. Non metterli in coda in un unico ciclo seriale, altrimenti i numeri più vecchi scadranno mentre aspetti ancora il primo.