Dokumentasyon ng API

Bawat kahilingan ay dapat may API key mo:

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternatibong anyo ng header: X-API-Key: jm_xxx…

Lumikha at bawiin ang mga key sa /account/api-keys. Bawat user ay maaaring magtago ng hanggang 10 aktibong key. Ang buong token ay ipinapakita nang isang beses lamang sa paglikha — itago itong ligtas.

Lahat ng error ay nagbabalik ng JSON:

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

Mga rate limit: Kada key, sliding window na 60s. Mga endpoint para sumulat (orders, cancel, next-sms) 10 req/min; mga endpoint para magbasa (account, services, prices, list) 60 req/min.

Kunin ang iyong kasalukuyang balanse at pangunahing profile.

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

Listahan ng mga service na may stock. Naka-cache sa server-side nang ~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 },
  ...
] }}

Gamitin ang code (o ang madaling slug) bilang field na service kapag gumagawa ng order.

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

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

Ang id ay ang upstream numeric country id; ang slug ay ang maikling SEO code (hal. "my" / "us"). Pareho ay tumatakbo bilang field na country.

Presyo bawat bansa at stock para sa isang naibigay na service. Ang presyo ay may kasama nang markup/diskwento na na-configure ng ops.

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 },
    ...
  ]
}}

Gumawa ng order ng SMS verification. Ire-reserve ng system ang isang numero ng telepono mula sa upstream at ibabawas ang sinisingil mula sa balanse mo.

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

Walang opsyonal na field maliban sa service / country.

Mga karaniwang error code: INSUFFICIENT (kailangang mag-top up), NO_NUMBERS, BAD_SERVICE, BAD_COUNTRY.

Mag-poll hanggang maging RECEIVED ang status at hindi null ang smsBody.

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",
  ...
}}

Mga status: WAITING (aktibo ang numero, naghihintay ng SMS) · RECEIVED (dumating na ang code) · COMPLETED / FAILED / CANCELLED ay mga terminal.

Mungkahing polling: bawat 3–5 segundo. Ang upstream sync ay tumatakbo sa loob ng endpoint na ito kaya ang polling ay nagpapatuloy sa state kahit abala ang background worker.

Kanselahin ang order na hindi pa nakatatanggap ng code. Buong refund sa iyong balanse.

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

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

Tatanggihan ng CODE_RECEIVED kung ang numero ay nakatanggap na ng anumang SMS, o ALREADY_CHANGED kung nagbago ang status nang sabay.

Pagkatapos ng RECEIVED, hilingin sa upstream na panatilihing aktibo ang numero at maghintay ng panibagong SMS (walang dagdag na bayad sa loob ng aktibong window).

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

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

Listahan na may cursor-pagination ng iyong mga kamakailang order.

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

Opsyonal na query: status · limit 1–100 (default 20) · cursor = nextCursor ng nakaraang pahina.

1. Mag-top up sa pamamagitan ng web UI → GET /v1/account upang kumpirmahin ang balanse.
2. Pumili ng service: GET /v1/services at GET /v1/prices?service=tg.
3. Gumawa ng order: POST /v1/orders na may service + country.
4. Basahin ang data.phone at i-trigger ang upstream SMS mula sa iyong client (hal. i-paste sa pag-rehistro sa Telegram).
5. Mag-poll ng GET /v1/orders/:id bawat 3–5s. Kapag status === "RECEIVED", basahin ang smsBody.
6. Kung mali ang SMS o gusto ng pangalawang code: POST /v1/orders/:id/next-sms → babalik sa WAITING.
7. Tapos na. Kung kakanselahin mo bago dumating ang anumang SMS: POST /v1/orders/:id/cancel para sa buong refund.