Ana içeriğe geç

İ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

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

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

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

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

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.

Kod örnekleri

cURL

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). İ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

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