---
title: "Bakiye Sorgulama API (get-balance)"
description: "Hesabınızdaki TL bakiyesini ve gönderilebilir SMS adedini tek istekle alın. Yan etkisiz, kontör harcamaz."
slug: /docs/api/get-balance
locale: tr
audience: developer
last_updated: 2026-04-29
endpoint:
  method: POST
  path: /v1/get-balance/json
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [authentication, send-sms, get-report, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/get-balance
  en: https://www.iletimerkezi.com/en/docs/api/get-balance
  toplusmsapi: https://toplusmsapi.com/account/balance/json
  a2psmsapi: https://a2psmsapi.com/en/account/balance/json
---

# 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](./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

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

## Response

### Başarılı (200)

```json
{
  "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`](https://github.com/iletimerkezi/apidocs-website/issues/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](./authentication.md).

#### Diğer hata kodları

`400, 404` için tablo: [error-codes.md](./error-codes.md).

## Kod örnekleri

### cURL

```bash
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`](./get-report.md) `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.


## Related

- [Kimlik doğrulama (authentication)](./authentication.md)
- [SMS gönderme (send-sms)](./send-sms.md)
- [Sipariş raporu (get-report)](./get-report.md)
- [Hata kodları tablosu](./error-codes.md)