I-automate ang SMS Verification: Kumpletong Gabay sa API

Sapat na ang website kung minsan-minsan lang mag-signup: mag-click nang ilang beses, hintayin ang isang text message. Hindi na ito sapat kapag sumusulat ka ng automated tests, bulk-signup script, CI pipeline, o bot na kailangang kumuha ng verification code nang walang taong nag-aasikaso. Hindi kayang gawin ito ng website. Kaya ito ng API. Ito ang lahat ng kailangan mong malaman para makapagsimula mula zero hanggang sa may gumaganang flow.

Hakbang 1: Kumuha ng API Key

Mag-log in at pumunta sa /account/api-keys para gumawa ng isa. Ganito ang hitsura ng mga key: jm_ na sinusundan ng random string. Ipinapakita lang ang plaintext nang isang beses — ang naka-store namin ay hash, hindi ang key mismo, kaya walang opsyong "i-recover ang key ko" kung mawala ito. I-delete lang ito at gumawa ng bago.

Gumagamit ang bawat request ng standard na Bearer auth:

Authorization: Bearer jm_your_key

Ituring ang key na parang password — huwag i-commit sa isang public repo, huwag i-paste sa chat para lang ipa-debug sa iba. Kung pinaghihinalaan mong na-leak ito, bumalik sa /account/api-keys, i-delete ito, at gumawa ng bago; agad tumitigil gumana ang luma.

Hakbang 2: Pumili ng Serbisyo at Bansa

Kailangan ng dalawang bagay para makapag-order: service (service code) at country (country id). Magsimula sa pag-list ng catalog:

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

May code field ang bawat item (ang Telegram ay tg) — ipasa mo iyon direkta sa order endpoint, mas maaasahan ito kumpara sa sariling pagbuo ng slug. Para makita ang live pricing at stock ng isang partikular na serbisyo sa iba't ibang bansa, magdagdag ng service param:

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

Bawat entry sa items ay may countryId / priceCents / count (kasalukuyang available na numero). I-check ang count bago mag-order — kung zero, mabibigo ang order, kaya huwag na lang sayangin ang isang call para lang malaman iyon nang mahirap na paraan.

Hakbang 3: I-place ang Order

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

Kapag successful ang order, makukuha mo ang isang phone number at expiry:

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

Nangyayari ang singil sa hakbang na ito — ang chargedCents ay ang aktwal na ibinawas (sa cents). Ibigay ang numerong ito sa target app para tumanggap ng verification code, tapos tuloy sa susunod na hakbang.

Hakbang 4: Mag-poll para sa Code

Walang WebSocket o webhook push — nakukuha mo ang SMS content sa pamamagitan ng pag-poll ng GET /api/v1/orders/:id hanggang hindi na null ang smsBody:

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

Magandang starting point ang bawat 5 segundo — valid ang numero nang 15 minuto, at ang limit na 60 requests kada minuto para sa queries ay may malaking allowance pa. Gumagana rin ang 3 segundo kung talagang naiinip ka; hindi mapapabilis ng pag-poll kada segundo ang pagdating ng code, ubos lang ang rate limit mo nang walang kapalit.

Mga Karaniwang Gotcha

• Per user ang rate limit, hindi per key. Ang write endpoints (order / cancel / next-sms) ay limitado sa 10/minuto kada user; ang queries ay 60/minuto. Ang paggawa ng dagdag na key ay hindi magbibigay sa'yo ng mas mataas na limit — pareho lang silang sumasalo sa parehong ceiling.
• Mag-expire ang mga numero pagkalipas ng 15 minuto. Ang hindi nagamit na numerong nag-expire nang hindi natanggap ang code ay awtomatikong ma-refund — hindi na kailangang humingi. Pero kung matagal itong itinago ng sarili mong pipeline bago talagang gamitin (halimbawa, natigil sa queue), patay na ito bago mo pa magamit.
• Isang numero, maraming code. Kung nagpapadala ang target app ng SMS sa dalawang hakbang (una, confirmation ng signup, tapos hiwalay na login code), tawagan ang POST /api/v1/orders/:id/next-sms pagkatapos dumating ng una para sabihing "tapos na ako dito, magpatuloy sa paghintay" — hindi na kailangang mag-order ulit ng bagong numero.
• Pagkatanggap ng code, hindi na gagana ang cancel. Agad na nagbabalik ng refund ang POST /api/v1/orders/:id/cancel habang naghihintay pa ang numero ng code. Pagkatapos maging non-null kailanman ang smsBody, ang parehong call ay magbabalik ng CODE_RECEIVED error sa halip — nakuha mo na ang binayaran mo, kaya hindi na ito maibabalik.
• Huwag basta i-check ang status nang isang beses lang at sumuko. Gumagalaw ang status mula WAITING patungong RECEIVED. Kung natigil ito sa WAITING hanggang mag-expire, karaniwang isyu ito sa delivery rate ng partikular na kombinasyon ng bansa/serbisyo — ang mag-order ulit sa ibang bansa ay mas mabilis na solusyon kaysa maghintay lang.

Ano ang Susunod

Sinaklaw na nito ang pangunahing flow mula order hanggang code. Ang kumpletong listahan ng field, error codes, at edge cases ng bawat endpoint ay makikita sa /api-docs. Kung malawakan ang paggamit mo nito — halimbawa, sabay-sabay na pinapanatiling live ang verification flow ng dose-dosenang account — i-time ang polling loop ng bawat order nang hiwalay. Huwag silang i-queue sa isang serial loop, kung hindi, mag-expire na ang mga unang numero habang naghihintay ka pa sa una.