--- title: "İYS İzin Sorgulama API (iys-check)" description: "Tek bir alıcı için İYS izin durumunu sorgulayın. Kayıtlı izin var mı, ONAY mı RET mi, hangi tarihte ve hangi kanaldan alındı?" slug: /docs/api/iys-check locale: tr audience: developer last_updated: 2026-04-30 endpoint: method: POST path: /v1/consent/show/json base_url: https://api.iletimerkezi.com auth: api-key-and-hash related: [iys-register, send-sms, authentication, error-codes] alternates: tr: https://www.iletimerkezi.com/docs/api/iys-check en: https://www.iletimerkezi.com/en/docs/api/iys-check toplusmsapi: https://toplusmsapi.com/izin/sorgula/json a2psmsapi: https://a2psmsapi.com/en/izin/sorgula/json --- # İ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](./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 ```json { "request": { "authentication": { "key": "API_KEY", "hash": "API_HASH" }, "consent": { "brandCode": 1234, "recipient": "+905XXXXXXXXX", "recipientType": "BIREYSEL", "type": "MESAJ" } } } ``` ## Response ### Başarılı (200) ```json { "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](./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](./error-codes.md). ## Kod örnekleri ### cURL ```bash 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 - [İYS izin kaydı (iys-register)](./iys-register.md) — kayıt oluşturma - [SMS gönderme (send-sms)](./send-sms.md) — `iys` + `iysList` ticari gönderim - [Kimlik doğrulama (authentication)](./authentication.md) - [Hata kodları tablosu](./error-codes.md)