--- title: "İYS İzin Kaydı API (iys-register)" description: "Ticari mesaj göndereceğiniz alıcılar için İYS (İleti Yönetim Sistemi) izin kayıtlarını tek istekte oluşturun. Tek istekte 5000 alıcıya kadar batch." slug: /docs/api/iys-register locale: tr audience: developer last_updated: 2026-04-30 endpoint: method: POST path: /v1/consent/create/json base_url: https://api.iletimerkezi.com auth: api-key-and-hash related: [iys-check, send-sms, authentication, error-codes] alternates: tr: https://www.iletimerkezi.com/docs/api/iys-register en: https://www.iletimerkezi.com/en/docs/api/iys-register toplusmsapi: https://toplusmsapi.com/izin/ekle/json a2psmsapi: https://a2psmsapi.com/en/izin/ekle/json --- # İYS İzin Kaydı API (iys-register) `iys-register` endpoint'i, Türkiye'de ticari elektronik ileti gönderimi için yasal zorunluluk olan **İYS (İleti Yönetim Sistemi)** izin kayıtlarını oluşturur. Web formu, ıslak imzalı sözleşme, çağrı merkezi onayı vb. yollarla aldığınız izinleri (veya retleri) bu endpoint ile iletiMerkezi üzerinden ulusal İYS sistemine işleyebilirsiniz. Tek istekte **en fazla 5000 alıcı** kaydedilir. ## Ö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. Marka kodu, panel üzerinden marka kayıt başvurusu sonrası tanımlanı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/create/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 └─ list[] (array, zorunlu) — 1-5000 izin kaydı ├─ recipient (string, zorunlu) — cep numarası veya e-posta ├─ recipientType (string, zorunlu) — "BIREYSEL" veya "TACIR" ├─ type (string, zorunlu) — "MESAJ", "EPOSTA" veya "ARAMA" ├─ status (string, zorunlu) — "ONAY" veya "RET" ├─ source (string, zorunlu) — izin alınma kaynağı (aşağıdaki tabloya bakın) └─ consentDate (string, zorunlu) — izin alınma anı, format "YYYY-MM-DD HH:MM:SS" ``` > **`consentDate` 3 günden eski olamaz.** İYS regülasyonu izin kayıtlarının fiilen alındıkları zamanlamadan en geç 3 gün içinde sisteme işlenmesini zorunlu kılar; daha eski tarih `422 — İstekte gönderilen bazı değerler doğrulanamadı` ile reddedilir. ### `source` değerleri İzin alınma kaynağına göre aşağıdaki sabit değerlerden biri kullanılır: | Kod | Anlam | |---|---| | `HS_FIZIKSEL_ORTAM` | Fiziksel ortam (matbu form, broşür ile alınan onay) | | `HS_ISLAK_IMZA` | Islak imzalı sözleşme | | `HS_ETKINLIK` | Etkinlik / fuar / stand | | `HS_EORTAM` | Elektronik ortam (genel) | | `HS_WEB` | Web formu, web sitesi onay kutusu | | `HS_MOBIL` | Mobil uygulama | | `HS_MESAJ` | SMS ile alınan onay | | `HS_EPOSTA` | E-posta ile alınan onay | | `HS_CAGRI_MERKEZI` | Çağrı merkezi sesli onay | | `HS_SOSYAL_MEDYA` | Sosyal medya | | `HS_ATM` | ATM ekranı üzerinden onay | | `HS_KARAR` | İdari karar / yargı kararı kapsamında verilen izin | ### Tam örnek Tek alıcı için ONAY kaydı: ```json { "request": { "authentication": { "key": "API_KEY", "hash": "API_HASH" }, "consent": { "brandCode": 1234, "list": [ { "recipient": "+905XXXXXXXXX", "recipientType": "BIREYSEL", "type": "MESAJ", "status": "ONAY", "source": "HS_WEB", "consentDate": "2026-04-30 09:15:42" } ] } } } ``` Birden çok alıcı tek istekte: ```json "list": [ { "recipient": "+905XXXXXXXX1", "recipientType": "BIREYSEL", "type": "MESAJ", "status": "ONAY", "source": "HS_WEB", "consentDate": "2026-04-30 09:15:42" }, { "recipient": "+905XXXXXXXX2", "recipientType": "BIREYSEL", "type": "MESAJ", "status": "ONAY", "source": "HS_WEB", "consentDate": "2026-04-30 09:16:08" }, { "recipient": "+905XXXXXXXX3", "recipientType": "BIREYSEL", "type": "MESAJ", "status": "RET", "source": "HS_MESAJ","consentDate": "2026-04-30 09:18:27" } ] ``` ## Response ### Başarılı (200) ```json { "response": { "status": { "code": 200, "message": "İşlem başarılı" } } } ``` İstekteki tüm izin kayıtları başarıyla iletiMerkezi'ne işlenmiş ve ulusal İYS sistemine senkronize sıraya alınmıştır. Yanıt minimal — kayıt başına ID veya ayrıştırılmış sonuç döndürülmez; **batch atomic** kabul edilir, herhangi bir kayıt validasyondan düşerse istek 422 ile düşer ve hiçbiri kaydedilmez. ### 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. Çözüm: panel üzerinden İYS marka kayıt başvurusunu başlatın. #### 405 — Kota aşıldı Aboneliğinizin aylık kayıt kotası dolmuş. Panel üzerinden plan yükseltmesi yapın veya iletiMerkezi destek ekibiyle iletişime geçin. #### 422 — İstekte gönderilen bazı değerler doğrulanamadı Yaygın nedenler: 1. `consentDate` 3 günden eski. 2. `recipient` formatı geçersiz (cep numarası veya e-posta deseninde değil). 3. `recipientType`, `type`, `status` veya `source` enum değerlerinin dışında bir değer gönderildi. 4. `brandCode` hesabınıza ait değil ya da hiç tanımlı değil. Hata batch atomic — listedeki **bir kayıt** doğrulanamazsa **tüm istek** düşer. #### 475 — Alıcı sayısı 5000 kişiyi geçemez `consent.list` dizisinde 5000'den fazla eleman var. Listeyi 5000'lik dilimlere bölüp ardışık çağrılarla gönderin. #### 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/create/json' \ -H 'Content-Type: application/json' \ -d '{ "request": { "authentication": { "key": "'"$ILETIMERKEZI_API_KEY"'", "hash": "'"$ILETIMERKEZI_API_HASH"'" }, "consent": { "brandCode": 1234, "list": [ { "recipient": "+905XXXXXXXXX", "recipientType": "BIREYSEL", "type": "MESAJ", "status": "ONAY", "source": "HS_WEB", "consentDate": "2026-04-30 09:15:42" } ] } } }' ``` ## Common Pitfalls - **Batch atomic — 1 kayıt patlarsa hepsi patlar.** `consent.list` içindeki tek bir kayıt 422'ye düşerse listedeki diğer kayıtlar **kaydedilmez**. Toplu yüklemelerde önce küçük bir dilimle (10-50 kayıt) test edin, sonra tam batch'e geçin. Hatayı izole etmek için listede kim olduğunu kendi tarafınızda log'layın. - **`consentDate` UTC değil, Türkiye yerel saati.** Format `YYYY-MM-DD HH:MM:SS`, saat dilimi Türkiye (UTC+3). UTC zaman damgalarını gönderirseniz yan etkisiz görünür ama gerçek izin anıyla 3 saatlik kayma oluşur — denetimde sorun. - **3 gün kuralı geriye işler.** İzin akışınızda kayıt için API çağrısı geciktirmeyin. Web formundan onay alındığı an `consentDate` o anki sunucu saatinizdir; kayıt 3 gün içinde gönderilmezse 422 döner ve İYS sistemine işlenmez. - **`source` enum dışı değer = 422.** `HS_WEB` yerine `web` yazmak veya `HS_FORM` gibi varolmayan bir kod uydurmak istek düşürür. Yukarıdaki tablodaki sabit değerlerin dışına çıkmayın. - **RET kaydı pozitif bir aksiyondur.** Müşteri çıkış (opt-out) talep ettiğinde kaydı silmek değil, `status: "RET"` ile bir izin kaydı **eklemek** gerekir; İYS denetiminde kullanıcının ret beyanı bu kayıt üzerinden ispatlanır. - **`type` ile `send-sms`'in `iys` alanı arasındaki fark.** `iys-register` İYS'ye **kayıt eklemek** içindir; `send-sms`'in `iys: "1"` + `iysList` parametresi ise gönderim anında İYS sorgulamasını **tetiklemek** içindir (bkz. [send-sms](./send-sms.md)). İki ayrı işlem; `iys-register` ile kaydı önceden işlemek `send-sms`'in 468/469/470 hatalarına düşmesini engeller. - **iletiMerkezi paneli ile API senkron çalışır.** Panel üzerinden manuel girilen izin kayıtları da aynı `brandCode`'a düşer; API ile çift kayıt yaratmamak için panel ↔ API hangisinin "yazıcı" olduğuna baştan karar verin. ## Related - [İYS izin sorgulama (iys-check)](./iys-check.md) — kayıt sonrası durum doğrulama - [SMS gönderme (send-sms)](./send-sms.md) — `iys` + `iysList` ticari gönderim parametreleri - [Kimlik doğrulama (authentication)](./authentication.md) - [Hata kodları tablosu](./error-codes.md)