Bakiye Sorgulama API (get-balance)

get-balance endpoint'i, hesabınızda kalan TL bakiyesini ve bu bakiye ile gönderebileceğiniz SMS adedini döner. Yan etkisi yoktur, kontör harcamaz; auth doğrulaması ve kalan bütçe kontrolü için ideal başlangıç çağrısıdır.

Önemli ön koşul: Panel'de API erişimi

Bu endpoint'i çağırmadan önce panelinizde API kullanımına izin ver seçeneğinin aktif olması gerekir.
Ayar yeri: panel.iletimerkezi.com → Ayarlar → Güvenlik → Erişim İzinleri
Aktif değilse istek 401 — Üyelik bilgileri hatalı ile döner. Detay: authentication.md

Endpoint

| Alan | Değer | |---|---| | Method | POST | | URL | https://api.iletimerkezi.com/v1/get-balance/json | | Content-Type | application/json | | Auth | API Key + Hash (request.authentication) |

Request

Şema

request
└─ authentication
   ├─ key (string, zorunlu)
   └─ hash (string, zorunlu)

get-balance ek alan beklemez; sadece auth bloğu gönderilir.

Tam örnek

{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    }
  }
}

Response

Başarılı (200)

{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "balance": {
      "amount": 10.584,
      "sms": 67
    }
  }
}

Alanlar:

response.status.code (integer): HTTP durum koduna paralel iç durum kodu.
response.status.message (string): Türkçe açıklama.
response.balance.amount (number, float): Kalan bakiye, TL cinsinden. Ondalıklı.
response.balance.sms (integer): Bu bakiyeyle gönderilebilecek standart SMS adedi (sender ve operatör ortalaması üzerinden hesaplanır).

Eski apidocs-website şartnamesinde amount ve sms alanları string olarak görünebilir; canlı API bunları number / integer olarak döndürüyor. Canlı API'yi ground truth alıyoruz (drift: apidocs-website#1). TypeScript'te response.balance.amount direkt number olarak kullanılabilir.

Hata yanıtları

401 — Üyelik bilgileri hatalı

API Anahtar/Hash doğrulanamadı veya panel toggle kapalı. Detay: authentication.md.

Diğer hata kodları

400, 404 için tablo: error-codes.md.

Kod örnekleri

cURL

curl -X POST 'https://api.iletimerkezi.com/v1/get-balance/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      }
    }
  }'

Common Pitfalls

amount number'dır, string değil. Eski örneklerde "amount": "0" görebilirsiniz; canlı API amount: 10.584 (number/float) döndürür. JSON parse sırasında string'den number'a çevirme adımı eklemeyin.
sms integer'dır. "sms": "18343" gibi string örnekleri eski şartnamededir; gerçek değer integer (67).
get-balance kontör harcamaz. Auth doğrulaması ve "yeterli bakiye var mı?" kontrolü için bu endpoint'i send-sms'ten önce çağırmak güvenli. Webhook veya cron'da fazla sıklıkta sorgulamak ise gereksiz yük yaratır.
sms sayısı yaklaşıktır. Operatör paylaşımları ve uzun mesaj/UCS-2 etkileri nedeniyle gerçekte gönderilebilen SMS adedi response.balance.sms'den biraz farklı olabilir. Kritik kararlarda send sonrasında get-report price alanından gerçek tüketimi okuyun.
Bakiye düşüş anı send-sms 200 yanıtıdır. Mesaj kuyruğa girer girmez kontör düşer; teslim onayını beklemez.

Son güncelleme: 2026-04-29 · English version