API dokümantasyonu

Her istek API anahtarınızı içermelidir:

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternatif başlık biçimi: X-API-Key: jm_xxx…

Anahtarları /account/api-keys üzerinden oluşturup iptal edin. Her kullanıcı en fazla 10 aktif anahtar tutabilir. Tam token yalnızca oluşturma anında bir kez gösterilir — güvenli bir yerde saklayın.

Tüm hatalar JSON döner:

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

Hız limitleri: Kullanıcı başına (tüm API anahtarların ortak kotayı paylaşır), kayan 60s pencere. Yazma uç noktaları (orders, cancel, next-sms) 10 req/min; okuma uç noktaları (account, services, prices, list) 60 req/min. Daha fazla anahtar oluşturmak kotanı artırmaz.

Mevcut bakiyenizi ve temel profil bilgilerinizi alın.

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

Stoklu hizmetleri listeleyin. Sunucu tarafında ~5 dk önbelleğe alınır.

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

Sipariş oluştururken service alanı olarak code (veya kullanıcı dostu slug) kullanın.

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

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

id, üst kaynaktaki sayısal ülke kimliğidir; slug ise SEO kısa kodudur (örn. "my" / "us"). country alanı için her iki biçim de geçerlidir.

Belirli bir hizmet için ülke bazlı fiyat ve stok. Fiyatlar, operasyon tarafından yapılandırılan ek ücret/indirimi içerir.

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

Bir SMS doğrulama siparişi oluşturun. Sistem üst kaynaktan bir numara rezerve eder ve ücreti bakiyenizden düşer.

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

service / country dışında isteğe bağlı alan yok.

Yaygın hata kodları: INSUFFICIENT (bakiye yetersiz), NO_NUMBERS, BAD_SERVICE, BAD_COUNTRY.

status değeri RECEIVED olana ve smsBody boş olmayana kadar yoklayın.

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

Durumlar: WAITING (numara aktif, SMS bekleniyor) · RECEIVED (kod geldi) · COMPLETED / FAILED / CANCELLED son durumlardır.

Önerilen yoklama: her 3–5 saniyede bir. Üst kaynak senkronizasyonu bu uç nokta içinde çalışır, dolayısıyla arka plan işçisi meşgul olsa bile yoklama durumu ilerletir.

Henüz kod almamış bir siparişi iptal edin. Tutar bakiyenize tam olarak iade edilir.

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

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

Numara herhangi bir SMS aldıysa CODE_RECEIVED ile, durum eş zamanlı değiştiyse ALREADY_CHANGED ile reddedilir.

RECEIVED sonrasında, üst kaynaktan numarayı aktif tutmasını ve başka bir SMS beklemesini isteyin (aktif pencere içinde ek ücret yok).

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

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

Son siparişlerinizin imleç tabanlı sayfalanmış listesi.

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

İsteğe bağlı sorgu: status · limit 1–100 (varsayılan 20) · cursor = önceki sayfanın nextCursor değeri.

1. Web arayüzünden bakiye yükleyin → bakiyeyi doğrulamak için GET /v1/account.
2. Bir hizmet seçin: GET /v1/services ve GET /v1/prices?service=tg.
3. Sipariş oluşturun: service + country ile POST /v1/orders.
4. data.phone değerini okuyun ve üst kaynak SMS'ini istemcinizden tetikleyin (örn. Telegram kayıt akışına yapıştırın).
5. Her 3–5s'de bir GET /v1/orders/:id yoklayın. status === "RECEIVED" olduğunda smsBody değerini okuyun.
6. Yanlış SMS geldiyse veya ikinci bir kod istiyorsanız: POST /v1/orders/:id/next-sms → tekrar WAITING.
7. Bitti. Herhangi bir SMS gelmeden iptal ederseniz: tam iade için POST /v1/orders/:id/cancel.