---
title: "iletiMerkezi API Kimlik Doğrulama"
description: "API Anahtarı + Hash ile iletiMerkezi API'sine giriş. Panel ön koşulu, istek formatı, 401 hatası ve dil bazlı örnekler."
slug: /docs/api/authentication
locale: tr
audience: developer
last_updated: 2026-04-29
endpoint:
  method: POST
  path: /v1/* (tüm endpoint'lerde aynı pattern)
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [overview, send-sms, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/authentication
  en: https://www.iletimerkezi.com/en/docs/api/authentication
  toplusmsapi: https://toplusmsapi.com/giris/genel-bilgiler
  a2psmsapi: https://a2psmsapi.com/en/giris/genel-bilgiler
---

# iletiMerkezi API Kimlik Doğrulama

iletiMerkezi REST API'si **API Anahtarı + Hash** ikilisi ile kimlik doğrular. İki değer de panelden alınır, runtime'da hesaplanmaz. Her istekte JSON gövdesinin `request.authentication` alanında gönderilir; ayrı bir HTTP header gerekmez.

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

> İlk istekten ö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. Bu, anahtarınızın yanlış olduğu anlamına gelmez; sadece izin kapalıdır. API ile tanışan geliştiricilerin %90'ından fazlası ilk denemede bu hatayı alır.

## Anahtarlarınızı nereden alırsınız

1. `panel.iletimerkezi.com` → **Ayarlar → Güvenlik → API Erişimi** bölümüne gidin.
2. **API Anahtarı** ve **API Hash** alanlarını panelden kopyalayın. İkisi de hex string formatındadır.
3. Bu iki değeri uygulamanızın environment variable'larına yazın:

```bash
ILETIMERKEZI_API_KEY=...
ILETIMERKEZI_API_HASH=...
```

> **Hash kendiniz üretmeyin.** iletiMerkezi paneli hash'i hazır verir; SDK'lar ve doğrudan HTTP istemcileri bu değeri olduğu gibi kullanır. Runtime'da MD5 / SHA / HMAC hesaplaması yapmanıza gerek yoktur.

## İstek formatı

Tüm endpoint'ler `POST` metoduyla çağırılır ve aşağıdaki gövde yapısını paylaşır:

| Alan | Değer |
|---|---|
| Method | `POST` |
| URL | `https://api.iletimerkezi.com/v1/{endpoint}/json` |
| Content-Type | `application/json` |
| Auth alanı | `request.authentication.{key, hash}` |

### Auth bloğu

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

Her endpoint kendi alanlarını bu bloğun yanına ekler. Örneğin `get-balance` için ek alan yoktur:

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

`send-sms` için `message` alanı eklenir; detaylar [send-sms.md](./send-sms.md) içinde.

## Doğrulama isteği

Anahtarlarınızın çalıştığını test etmenin en hızlı yolu `get-balance` endpoint'ini çağırmaktır. Yan etki üretmez, kontör harcamaz, dakikada birden fazla denenebilir.

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

Başarılı yanıt (HTTP 200):

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

Bu yanıt geliyorsa kimlik doğrulama başarılı; diğer endpoint'leri çağırmaya hazırsınız.

## Hata yanıtları

### 401 — Üyelik bilgileri hatalı

```json
{
  "response": {
    "status": {
      "code": 401,
      "message": "Üyelik bilgileri hatalı"
    }
  }
}
```

**En yaygın sebepler (öncelik sırasıyla):**

1. **Panel'de "API kullanımına izin ver" toggle'ı kapalı.** İlk denemede 401 alanların büyük çoğunluğu bu sebepten alır. Mesaj genel ("Üyelik bilgileri hatalı") olduğu için yanıltıcıdır.
2. **API Anahtarı veya Hash yanlış kopyalanmış.** Panel ekranındaki değerlerle environment variable'larınızı tekrar karşılaştırın; sondaki / baştaki boşluk dahil.
3. **IP kısıtlaması aktif ama isteğin geldiği IP whitelist dışı.** Panel'de **Ayarlar → Güvenlik → Sabit IP** altında API erişimi için tanımlı IP listesi varsa, bu listenin dışından gelen istekler 401 alır. Sunucunuzun çıkış IP'sini whitelist'e ekleyin ya da kısıtlamayı kaldırın.
4. **Anahtar rotate edilmiş veya disable edilmiş.** Panelden yeni bir anahtar üretip değiştirin.

Hata kodlarının tam tablosu: [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

- **Panel toggle kapalı 401.** En yaygın ilk-deneme hatası. Mesaj "Üyelik bilgileri hatalı" der ama gerçek sebep izin kapalı olmasıdır. Panele bakmadan saatlerce anahtar değiştirmeyin.
- **Hash'i kendiniz üretmeyin.** Bazı eski örneklerde MD5 / SHA hesaplama akışı görülür; iletiMerkezi'de hash panelden hazır gelir. Runtime hesaplama anahtarınızı çalıştırmaz, hatalı hash üretir.
- **Anahtarları repository'ye commit etmeyin.** API Anahtarı ve Hash, hesabınıza tam yetkiyle bağlıdır. `.env` dosyası ve gizli yapılandırma yöneticileri (Vault, AWS Secrets Manager, GitHub Actions secrets) standart yoldur.
- **Dakikada bir kontör test etmeyin.** Doğrulama için `get-balance` çağırın; `send-sms` her başarılı çağrıda kontör harcar ve hedef numaraya gerçek SMS gönderir.
- **Test ortamı için aynı kimlikleri kullanın.** iletiMerkezi'de ayrı sandbox anahtarı yoktur; aynı anahtar hem geliştirme hem production'da çalışır. Yeni hesaplara test ve değerlendirme amaçlı **100 SMS ücretsiz kredi** otomatik tanımlanır, ilk entegrasyonu ek maliyet olmadan denemenize yeter. Standart pattern: mesaj içeriğine "TEST" prefix'i + kendi numaranız.


## Related

- [API genel bakış](./overview.md)
- [SMS gönderme (send-sms)](./send-sms.md)
- [Bakiye sorgulama (get-balance)](./get-balance.md)
- [Hata kodları tablosu](./error-codes.md)