API dokümantasyonu

jiema.my hizmetine toplu / otomatik erişim için REST API. SMS doğrulamayı kendi servislerinize entegre etmek için kullanın. Tüm uç noktalar JSON döner.

İlk API anahtarınızı oluşturmak için giriş yapın.

İçindekiler

Kimlik doğrulama
Hatalar ve hız limitleri
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
Tipik iş akışı

Kimlik doğrulama

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.

Hatalar ve hız limitleri

Tüm hatalar JSON döner:

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

HTTP	kod	anlamı
401	AUTH_MISSING / AUTH_INVALID	Anahtar yok veya iptal edilmiş
403	FORBIDDEN	Yasaklı veya erişim yok
400	BAD_REQUEST / INSUFFICIENT / NO_NUMBERS / …	Doğrulama veya iş kuralı hatası
404	NOT_FOUND	Sipariş yok (veya size ait değil)
429	RATE_LIMITED	Anahtar başına hız sınırlaması
500	INTERNAL	Sunucu hatası (otomatik raporlanır)

Hız limitleri: Anahtar başına, kayan 60s pencere. Yazma uç noktaları (orders, cancel, next-sms) 10 req/min; okuma uç noktaları (account, services, prices, list) 60 req/min.

GET /v1/account

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

GET /v1/services

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.

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, ü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.

GET /v1/prices?service=tg

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

POST /v1/orders

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.

GET /v1/orders/:id

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.

POST /v1/orders/:id/cancel

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.

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

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

GET /v1/orders

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.

Tipik iş akışı

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

jiema.my