Ana içeriğe geç

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

{
  "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:

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

send-sms için message alanı eklenir; detaylar 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.

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):

{
  "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ı

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

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

  • 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

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