Ana içeriğe geç

İYS İzin Sorgulama API (iys-check)

iys-check endpoint'i, belirli bir alıcı için İYS (İleti Yönetim Sistemi) kaydındaki güncel izin durumunu döner. iys-register ile yüklediğiniz kaydın işlendiğini doğrulamak, ticari gönderim öncesi alıcının ONAY/RET durumunu kontrol etmek veya audit raporu üretmek için kullanılır. Yan etkisiz, kontör harcamaz.

Ö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

Marka kodu ön koşulu. Hesabınızda iletiMerkezi tarafından sağlanmış aktif bir İYS marka kodu (brandCode) bulunmalıdır. Aktif İYS aboneliği yoksa istek 403 — Aktif abonelik bulunamadı ile döner.

Endpoint

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

Request

Şema

request
├─ authentication
│  ├─ key (string, zorunlu)
│  └─ hash (string, zorunlu)
└─ consent
   ├─ brandCode (string|integer, zorunlu) — hesabınızdaki aktif İYS marka kodu
   ├─ recipient (string, zorunlu)         — sorgulanacak cep numarası veya e-posta
   ├─ recipientType (string, zorunlu)     — "BIREYSEL" veya "TACIR"
   └─ type (string, zorunlu)              — "MESAJ", "EPOSTA" veya "ARAMA"

Sorgulama tek alıcılıdır — iys-register'in aksine bir liste alınmaz. Toplu sorgu için her alıcı için ayrı istek atın.

Tam örnek

{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "consent": {
      "brandCode": 1234,
      "recipient": "+905XXXXXXXXX",
      "recipientType": "BIREYSEL",
      "type": "MESAJ"
    }
  }
}

Response

Başarılı (200)

{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "consent": {
      "brandCode": 1234,
      "recipient": "+905XXXXXXXXX",
      "recipientType": "BIREYSEL",
      "type": "MESAJ",
      "status": "ONAY",
      "source": "HS_WEB",
      "consentDate": "2026-04-30 09:15:42"
    }
  }
}

Alanlar:

  • response.consent.brandCode (integer): Sorgulamada kullanılan marka kodu.
  • response.consent.recipient (string): Alıcı (cep numarası veya e-posta), +90 prefix'i ile döner.
  • response.consent.recipientType (string): BIREYSEL veya TACIR.
  • response.consent.type (string): İletişim kanalı tipi — MESAJ, EPOSTA, ARAMA.
  • response.consent.status (string): Kayıtlı izin durumu — ONAY (rıza var) veya RET (rıza yok / iptal edildi).
  • response.consent.source (string): İznin alındığı kanal kodu (örn. HS_WEB); iys-register'deki source enum değerlerinden biri.
  • response.consent.consentDate (string): İznin alındığı an, format YYYY-MM-DD HH:MM:SS, Türkiye yerel saati.

Aynı recipient + recipientType + type kombinasyonu için iletiMerkezi her zaman en son kaydı döner. Müşteri önce ONAY sonra RET verdiyse status: "RET" döner; bu bağlayıcıdır, ticari gönderim yapılamaz.

Hata yanıtları

401 — Üyelik bilgileri hatalı

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

403 — Aktif abonelik bulunamadı

Hesabınızda aktif bir İYS aboneliği yok. Marka kodu (brandCode) tanımlı değil veya İYS hizmeti pasif.

422 — İstekte gönderilen bazı değerler doğrulanamadı

Yaygın nedenler:

  1. recipient formatı geçersiz (cep numarası veya e-posta deseninde değil).
  2. recipientType veya type enum değerlerinin dışında bir değer.
  3. brandCode boş veya hesabınıza ait değil.
  4. Alıcı için bu marka + tip kombinasyonunda kayıtlı bir izin yok (kayıtsız alıcı).

"Kayıtsız" durum farklı bir 4XX kodu değil, 422 ile döner; mesaj string'inden tipi kestirmek yerine dönen consent.status alanının olup olmadığını kontrol edin.

Diğer hata kodları

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

Kod örnekleri

cURL

curl -X POST 'https://api.iletimerkezi.com/v1/consent/show/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      },
      "consent": {
        "brandCode": 1234,
        "recipient": "+905XXXXXXXXX",
        "recipientType": "BIREYSEL",
        "type": "MESAJ"
      }
    }
  }'

Common Pitfalls

  • status: "ONAY" "yasal olarak gönderebilirsin" demektir, "her zaman gönder" demek değildir. iys-check size yalnızca İYS kaydındaki son durumu söyler; uygulamanızın kendi opt-out, kara liste, frekans kontrolü, KVKK aydınlatma gibi katmanları da bağımsız çalışmalıdır.
  • status: "RET" bağlayıcıdır. RET dönen alıcıya ticari mesaj göndermek hem send-sms tarafından (468/469/470 ile) reddedilir hem de İYS tarafından şikayet konusu yapılabilir. RET'i istemci tarafında da cache'leyip blocking guard ekleyin.
  • Tek alıcılı endpoint — toplu sorguda dikkat. Büyük müşteri listelerinde her kayıt için ayrı HTTP isteği atmak yavaş ve maliyetlidir. Pratik pattern: kayıtları iys-register ile siz tutuyor olun, iys-check'i sadece audit veya tek kullanıcı kontrolü için çağırın.
  • Cache ile dikkatli olun. Müşteri panelden veya farklı kanaldan RET verebilir; uzun TTL'li cache yasal risk yaratır. 1 saatten fazla cache tutmayın veya RET callback'i ile invalidate edin.
  • recipient format hassasiyeti. Cep için +905XXXXXXXXX, 905XXXXXXXXX, 5XXXXXXXXX formatları kabul edilebilir; e-posta için tam adres. Yanlış format 422 döner; dönüşte +90 prefix gelir.
  • type ile send-sms'in yolu kesişir. send-sms ticari gönderimde iys: "1" + iysList ile İYS'yi kendisi sorgular; ön kontrol yapmak istemiyorsan iys-check opsiyoneldir. Sadece audit, dashboard veya hata öncesi durum doğrulaması için kullan.

Related

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