SelfIYS API Dokumantasyonu

Genel Bilgi

SelfIYS API, firmanizin IYS (Ileti Yonetim Sistemi) islemlerini programatik olarak yonetmenizi saglayan bir REST API hizmetidir.

Base URL

https://api.selfiys.com/api/v1

Temel Ozellikler

Protokol	HTTPS (zorunlu)
Format	JSON (Content-Type: application/json)
Kimlik Dogrulama	Bearer Token (1 saat gecerli)
Rate Limit	Dakikada 60 istek
Karakter Kodlamasi	UTF-8

Tum Endpointler

Method	Endpoint	Aciklama	Yetki
POST	`/api/v1/token`	Token olusturma	api_key + api_secret
GET	`/api/v1/me`	Hesap bilgileri	Bearer Token
POST	`/api/v1/firma`	IYS firma kodu tanimlama	Bearer Token
GET	`/api/v1/firma`	Tanimli firmalari listeleme	Bearer Token
GET	`/api/v1/marka`	Marka yetki sorgulama (IYS + API kayit durumu)	Bearer Token
POST	`/api/v1/izin`	Izin ekleme (asenkron)	Bearer Token
GET	`/api/v1/izin`	Izin durum sorgulama / listeleme	Bearer Token
POST	`/api/v1/izin-gecmis`	Izin gecmisi sorgulama (asenkron)	Bearer Token
GET	`/api/v1/izin-gecmis`	Izin gecmisi sonuc alma	Bearer Token
POST	`/api/v1/izin-sorgula`	Tekil izin durumu sorgulama (asenkron)	Bearer Token
GET	`/api/v1/izin-sorgula`	Tekil izin durumu sonuc alma	Bearer Token
POST	`/api/v1/izin-detay`	Tekil izin detay sorgulama (senkron)	Bearer Token
POST	`/api/v1/izin-toplu`	Coklu izin durumu sorgulama (asenkron, batch API, max 1000)	Bearer Token

Kullanim Akisi

Token Al — POST /api/v1/token ile api_key ve api_secret gondererek 1 saatlik token alin.

Firma Tanimla — POST /api/v1/firma ile IYS firma kodunuzu (iysCode) sisteme kaydedin.

Marka Yetki Sorgula — GET /api/v1/marka?brandCode=XXX ile markanin IYS'de tanimli olup olmadigini ve firmanizin API'de kayitli olup olmadigini ayni anda kontrol edin.

Izin Ekle — POST /api/v1/izin ile izin kaydi olusturun. Kayit kuyruga eklenir.

Durum Takip Et — GET /api/v1/izin?guid=XXX ile izin kaydinin IYS'ye iletilme durumunu takip edin.

Onemli: Izin ekleme islemleri asenkron calismaktadir. Istekler kuyruga eklenir, arka plan servisi IYS'ye iletir. Sonuclari ilgili GET endpointleri ile takip edin. Marka sorgulama ise senkron (DB'den anlik) calisir.

1. Kimlik Dogrulama

POST /api/v1/token

API erisim token'i olusturur. Token 1 saat gecerlidir. Suresi dolan token ile yapilan istekler 401 hatasi alir.

Request Body

Alan	Tip	Zorunlu	Aciklama
`api_key`	string	Evet	Size verilen API anahtari (UUID formatinda)
`api_secret`	string	Evet	Size verilen API gizli anahtari

Ornek Istek

curl -X POST https://api.selfiys.com/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "f2ee2f9f-2c72-11f1-899d-52e18006e243",
    "api_secret": "899d11f12c7252e18006e243fd933061"
  }'

Basarili Yanit (200)

{
    "token": "dfd767e0b6701f727d50ddf82978b7a41d4946861c09b4d276a4cde963d2cc9d",
    "expires_at": "2026-03-31 00:07:43",
    "created_at": "2026-03-30 23:07:43"
}

Token Kullanimi: Alinan token, diger tum endpointlerde Authorization: Bearer <token> header'i ile gonderilmelidir.

2. Firma Yonetimi

POST /api/v1/firma

IYS firma kodunuzu (iysCode) sisteme tanimlar. Bu islem, marka sorgulama ve izin ekleme islemleri icin on kosuldur.

Request Body

Alan	Tip	Zorunlu	Aciklama
`iysFirmaKodu`	string	Evet	IYS tarafindan firmaniza atanan tekil numara

Ornek Istek

curl -X POST https://api.selfiys.com/api/v1/firma \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "iysFirmaKodu": "631866"
  }'

Basarili Yanit (201)

{
    "message": "Firma basariyla eklendi",
    "id": 1,
    "iysFirmaKodu": "631866"
}

GET /api/v1/firma

Hesabiniza tanimli IYS firma kodlarini listeler.

Ornek Yanit (200)

{
    "firmalar": [
        {
            "id": 1,
            "iysFirmaKodu": "631866",
            "aktif": 1,
            "created_at": "2026-03-30 23:12:10"
        }
    ]
}

3. Marka Sorgulama

Iki kaynaktan kontrol: Endpoint, sorgulanan kodu iki ayri tabloda kontrol eder ve tek yanitta birlestirir:

iys bloğu — iysMarkalar tablosu: entegratorun IYS'de bu markaya yetkisi var mi?
api bloğu — api_marka tablosu: token sahibi firma bu markayi API'de kayit altina almis mi?

Sorgulanan kod, her iki tabloda hem brandCode/markaKodu hem de iysCode/iysFirmaKodu alanlariyla eslestirilir (master markalarda iki kod ayni olabildigi icin).

GET /api/v1/marka?brandCode={brandCode}

Belirtilen kodun IYS yetkisi ve firmanizin API'deki kayit durumunu doner. Marka hicbir tabloda bulunmasa bile 200 doner; her blok kendi kayitli alani ile durumu bildirir.

Query Parametreleri

Parametre	Tip	Zorunlu	Varsayilan	Aciklama
`brandCode`	integer	Evet	-	Sorgulanacak marka/iys kodu

Ornek Istek

curl "https://api.selfiys.com/api/v1/marka?brandCode=631866" \
  -H "Authorization: Bearer <token>"

Basarili Yanit (200) — Her iki tabloda da kayitli

{
    "brandCode": 631866,
    "iys": {
        "kayitli": true,
        "brandCode": 631866,
        "iysCode": 631866,
        "name": "Ana Marka",
        "title": "Ornek Sirket A.S.",
        "master": true,
        "agreementControl": 1,
        "MESAJ": 1,
        "ARAMA": 1,
        "EPOSTA": 1,
        "viaControl": 1
    },
    "api": {
        "kayitli": true,
        "firma_kodu": "FIRMA001",
        "iysFirmaKodu": "631866",
        "markaKodu": 631866,
        "markaAdi": "Ana Marka",
        "master": true,
        "created_at": "2026-03-30 23:15:00"
    }
}

Yanit (200) — IYS'de var ama API'de henuz kayitli degil

{
    "brandCode": 631866,
    "iys": {
        "kayitli": true,
        "brandCode": 631866,
        "iysCode": 631866,
        "name": "Ana Marka",
        "title": "Ornek Sirket A.S.",
        "master": true,
        "agreementControl": 1,
        "MESAJ": 1,
        "ARAMA": 1,
        "EPOSTA": 1,
        "viaControl": 1
    },
    "api": {
        "kayitli": false
    }
}

Yanit (200) — Hicbir kaynakta bulunamadi

{
    "brandCode": 999999,
    "iys": { "kayitli": false },
    "api": { "kayitli": false }
}

4. Izin Yonetimi

POST /api/v1/izin

IYS'ye izin kaydi ekler. Islem asenkron calismaktadir: kayit kuyruga alinir, arka plan servisi IYS API'ye iletir. Sonucu GET /api/v1/izin?guid=XXX ile takip edin.

Request Body

Alan	Tip	Zorunlu	Aciklama
`iysCode`	integer	Evet	IYS firma kodu
`brandCode`	integer	Evet	IYS marka kodu (marka sorgulama ile alinir)
`recipient`	string	Evet	Telefon (`+905XXXXXXXXX` E.164 formati) veya e-posta (max 265 karakter)
`type`	string (enum)	Evet	Iletisim kanali. Asagidaki type Degerleri tablosuna bakin.
`source`	string (enum)	Evet*	Izin kaynagi. BIREYSEL icin zorunlu, TACIR icin opsiyonel. Asagidaki source Degerleri tablosuna bakin.
`status`	string (enum)	Evet	Izin durumu. Asagidaki status Degerleri tablosuna bakin.
`consentDate`	string	Evet	Iznin alindigi tarih. Format: `YYYY-MM-DD HH:mm:ss` (Turkiye saati). TACIR icin opsiyonel.
`recipientType`	string (enum)	Hayir	Alici tipi. Asagidaki recipientType Degerleri tablosuna bakin. Varsayilan: `BIREYSEL`
`retailerCode`	integer	Hayir	Bayi IYS numarasi (max 8 hane)
`retailerAccess`	integer[]	Hayir	Izne erisi olan bayi IYS numaralari (max 3000 adet)

type Degerleri

Deger	Aciklama
`ARAMA`	Telefon aramasi kanali
`MESAJ`	SMS / kisa mesaj kanali
`EPOSTA`	E-posta kanali

source Degerleri

Not: recipientType = TACIR ise source alani zorunlu degildir. Ancak TACIR tipli izinlerin guncellemesinde source alani istek icerisinde yer almalidir.

Deger	Aciklama
`HS_FIZIKSEL_ORTAM`	Fiziksel ortamda alinan izin
`HS_ISLAK_IMZA`	Islak imza ile alinan izin
`HS_WEB`	Web sitesi uzerinden alinan izin
`HS_CAGRI_MERKEZI`	Cagri merkezi uzerinden alinan izin
`HS_SOSYAL_MEDYA`	Sosyal medya uzerinden alinan izin
`HS_EPOSTA`	E-posta uzerinden alinan izin
`HS_MESAJ`	SMS / mesaj uzerinden alinan izin
`HS_MOBIL`	Mobil uygulama uzerinden alinan izin
`HS_EORTAM`	Elektronik ortamda alinan izin
`HS_ETKINLIK`	Etkinlik sirasinda alinan izin
`HS_2015`	2015 oncesi alinan izin (gecis donemi)
`HS_ATM`	ATM uzerinden alinan izin
`HS_KARAR`	Karar ile alinan izin

status Degerleri

Deger	Aciklama
`ONAY`	Alici iletisim iznini onaylamistir
`RET`	Alici iletisim iznini reddetmistir

recipientType Degerleri

Deger	Aciklama
`BIREYSEL`	Bireysel alici (varsayilan). `source` ve `consentDate` zorunludur.
`TACIR`	Ticari alici. `source` ve `consentDate` ilk kayitta opsiyoneldir, guncelleme isteklerinde zorunludur. Ayni iletisim adresi hem BIREYSEL hem TACIR olarak kaydedilebilir.

Ornek Istek

curl -X POST https://api.selfiys.com/api/v1/izin \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "iysCode": 631866,
    "brandCode": 631866,
    "recipient": "+905333031510",
    "type": "MESAJ",
    "source": "HS_MESAJ",
    "status": "ONAY",
    "consentDate": "2026-03-30 12:00:00",
    "recipientType": "BIREYSEL"
  }'

Basarili Yanit (201)

{
    "message": "Izin kaydi alindi, isleme kuyruguna eklendi",
    "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "durum": "bekliyor"
}

Not: Yanittaki guid degerini saklayın. Izin durumunu sorgulamak icin bu deger kullanilir.

GET /api/v1/izin?guid={guid}

Belirli bir izin kaydinin durumunu sorgular. guid degeri izin ekleme yanitindan alinir.

Ornek Istek

curl "https://api.selfiys.com/api/v1/izin?guid=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <token>"

Basarili Yanit (200)

{
    "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "iysCode": 631866,
    "brandCode": 631866,
    "recipient": "+905333031510",
    "type": "MESAJ",
    "status": "ONAY",
    "durum": "basarili",
    "transactionId": "f9c8b7a6-d5e4-3210-fedc-ba9876543210",
    "creationDate": "2026-03-30 12:00:00",
    "hataKodu": null,
    "hataMesaj": null,
    "created_at": "2026-03-30 23:30:00"
}

Durum Degerleri

Durum	Aciklama
bekliyor	Kayit kuyrukta, henuz IYS'ye gonderilmedi
gonderiliyor	IYS API'ye gonderim islemi devam ediyor
basarili	IYS'ye basariyla iletildi. `transactionId` alaninda IYS islem numarasi yer alir
hata	Gonderim basarisiz. `hataKodu` ve `hataMesaj` alanlarina bakin

GET /api/v1/izin?tel={telefon}

Telefon numarasina ait tum izin kayitlarini listeler. Numara basa +90 eklenerek aranir.

Query Parametreleri

Parametre	Tip	Zorunlu	Varsayilan	Aciklama
`tel`	string	Evet	-	Telefon numarasi. `5333031510`, `05333031510` veya `+905333031510` formatlarini destekler
`limit`	integer	Hayir	50	Sayfa basina kayit (max 200)
`offset`	integer	Hayir	0	Atlanacak kayit sayisi

Ornek Istek

curl "https://api.selfiys.com/api/v1/izin?tel=5333031510" \
  -H "Authorization: Bearer <token>"

Basarili Yanit (200)

{
    "recipient": "+905333031510",
    "total": 3,
    "limit": 50,
    "offset": 0,
    "kayitlar": [
        {
            "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "iysCode": 631866,
            "brandCode": 631866,
            "recipient": "+905333031510",
            "type": "MESAJ",
            "source": "HS_MESAJ",
            "status": "ONAY",
            "durum": "basarili",
            "transactionId": "f9c8b7a6...",
            "hataKodu": null,
            "hataMesaj": null,
            "created_at": "2026-03-30 23:30:00"
        }
    ]
}

GET /api/v1/izin?iysCode={iysCode}&durum={durum}&limit={limit}&offset={offset}

Izin kayitlarinizi listeler. Filtreleme ve sayfalama destekler.

Query Parametreleri

Parametre	Tip	Zorunlu	Varsayilan	Aciklama
`iysCode`	integer	Hayir	-	IYS firma koduna gore filtrele
`durum`	string	Hayir	-	`bekliyor` \| `gonderiliyor` \| `basarili` \| `hata`
`limit`	integer	Hayir	50	Sayfa basina kayit (max 200)
`offset`	integer	Hayir	0	Atlanacak kayit sayisi

Ornek Istek

curl "https://api.selfiys.com/api/v1/izin?iysCode=631866&durum=basarili&limit=10" \
  -H "Authorization: Bearer <token>"

Basarili Yanit (200)

{
    "total": 156,
    "limit": 10,
    "offset": 0,
    "kayitlar": [
        {
            "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "iysCode": 631866,
            "brandCode": 631866,
            "recipient": "+905333031510",
            "type": "MESAJ",
            "status": "ONAY",
            "durum": "basarili",
            "transactionId": "f9c8b7a6...",
            "hataKodu": null,
            "hataMesaj": null,
            "created_at": "2026-03-30 23:30:00"
        }
    ]
}

5. Izin Gecmisi Sorgulama

Asenkron Islem: Izin gecmisi sorgulama iki asamalidir. Once POST /api/v1/izin-gecmis ile sorgu olusturun, donen guid ile GET /api/v1/izin-gecmis?guid=XXX uzerinden sonucu takip edin. IYS sorgulamasi arka plan servisi tarafindan gerceklestirilir.

Toplu Sorgu: recipient alani gonderilmezse, api_izin tablosundaki ilgili iysCode/brandCode icin kayitli tum numaralar otomatik olarak bulunur ve her biri icin IYS'ye ayri ayri sorgu atilir. Sonuclar tek bir yanit altinda birlestirilir. Cok sayida numara icin islem süresi uzayabilir; ilerlemeyi sorgulanan / toplamNumara alanlari ile takip edebilirsiniz.

POST /api/v1/izin-gecmis

Belirli bir alici icin IYS'deki izin gecmisini sorgular. Sonuclar consentDate alanina gore yeniden eskiye siralanir. Islem asenkron calismaktadir.

Request Body

Alan	Tip	Zorunlu	Aciklama
`iysCode`	integer	Evet	IYS firma kodu
`brandCode`	integer	Evet	IYS marka kodu
`recipient`	string	Hayir	Telefon (`+905XXXXXXXXX`) veya e-posta adresi. Gonderilmezse daha once izin eklenen tum numaralar icin toplu sorgu yapilir.
`type`	string (enum)	Evet	`ARAMA` \| `MESAJ` \| `EPOSTA`
`recipientType`	string (enum)	Hayir	`BIREYSEL` (varsayilan) \| `TACIR`
`limit`	integer	Hayir	Sayfa basina kayit sayisi. Varsayilan: `100`, Maksimum: `100`
`offset`	integer	Hayir	Sayfalama baslangic indeksi. Varsayilan: `0`

Ornek Istek — Toplu Sorgu (Tum Numaralar)

curl -X POST https://api.selfiys.com/api/v1/izin-gecmis \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "iysCode": 631866,
    "brandCode": 631866,
    "type": "MESAJ",
    "recipientType": "BIREYSEL"
  }'

Basarili Yanit — Toplu (201)

{
    "message": "Toplu izin gecmisi sorgusu alindi (48 numara), isleme kuyruguna eklendi",
    "guid": "d5e6f7a8-b9c0-1234-def5-6789abcdef01",
    "durum": "bekliyor",
    "toplamNumara": 48
}

Ornek Istek — Telefon (MESAJ)

curl -X POST https://api.selfiys.com/api/v1/izin-gecmis \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "iysCode": 631866,
    "brandCode": 631866,
    "recipient": "+905333031510",
    "type": "MESAJ",
    "recipientType": "BIREYSEL"
  }'

Ornek Istek — E-posta (EPOSTA)

curl -X POST https://api.selfiys.com/api/v1/izin-gecmis \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "iysCode": 631866,
    "brandCode": 631866,
    "recipient": "ornek@firma.com",
    "type": "EPOSTA",
    "recipientType": "BIREYSEL",
    "limit": 50,
    "offset": 0
  }'

Basarili Yanit (201)

{
    "message": "Izin gecmisi sorgusu alindi, isleme kuyruguna eklendi",
    "guid": "c4d5e6f7-a8b9-0123-cdef-456789abcdef",
    "durum": "bekliyor"
}

Not: Yanittaki guid degerini saklayın. Sorgu sonucunu almak icin bu deger kullanilir.

GET /api/v1/izin-gecmis?guid={guid}

Izin gecmisi sorgusunun sonucunu dondurur. durum alani tamamlandi oldugunda sonuc alaninda IYS'den donen izin gecmisi yer alir.

Query Parametreleri

Parametre	Tip	Zorunlu	Aciklama
`guid`	string	Evet	Sorgu olusturma yanitindaki guid degeri

Ornek Istek

curl "https://api.selfiys.com/api/v1/izin-gecmis?guid=c4d5e6f7-a8b9-0123-cdef-456789abcdef" \
  -H "Authorization: Bearer <token>"

Basarili Yanit — Tamamlandi (200)

{
    "guid": "c4d5e6f7-a8b9-0123-cdef-456789abcdef",
    "iysCode": 631866,
    "brandCode": 631866,
    "recipient": "+905333031510",
    "recipientType": "BIREYSEL",
    "type": "MESAJ",
    "limit": 100,
    "offset": 0,
    "durum": "tamamlandi",
    "totalCount": 2,
    "sonuc": {
        "list": [
            {
                "consentDate": "2026-03-15 14:30:00",
                "source": "HS_WEB",
                "recipient": "+905333031510",
                "recipientType": "BIREYSEL",
                "status": "ONAY",
                "type": "MESAJ",
                "creationDate": "2026-03-15 14:32:10",
                "transactionId": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567"
            },
            {
                "consentDate": "2025-11-20 09:15:00",
                "source": "HS_CAGRI_MERKEZI",
                "recipient": "+905333031510",
                "recipientType": "BIREYSEL",
                "status": "RET",
                "type": "MESAJ",
                "creationDate": "2025-11-20 09:18:45",
                "transactionId": "zzz999yyy888xxx777www666vvv555uuu444ttt333sss222rrr111"
            }
        ],
        "pagination": {
            "totalCount": 2,
            "pageSize": 2,
            "offset": 0
        }
    },
    "hataKodu": null,
    "hataMesaj": null,
    "created_at": "2026-03-31 10:00:00",
    "updated_at": "2026-03-31 10:00:08"
}

Basarili Yanit — Toplu Sorgu Tamamlandi (200)

{
    "guid": "d5e6f7a8-b9c0-1234-def5-6789abcdef01",
    "iysCode": 631866,
    "brandCode": 631866,
    "recipient": null,
    "durum": "tamamlandi",
    "totalCount": 5,
    "toplamNumara": 3,
    "sorgulanan": 3,
    "sonuc": {
        "list": [
            {
                "consentDate": "2026-03-15 14:30:00",
                "source": "HS_WEB",
                "recipient": "+905333031510",
                "recipientType": "BIREYSEL",
                "status": "ONAY",
                "type": "MESAJ",
                "creationDate": "2026-03-15 14:32:10",
                "transactionId": "abc123..."
            },
            {
                "consentDate": "2026-02-10 09:00:00",
                "source": "HS_MESAJ",
                "recipient": "+905441234567",
                "recipientType": "BIREYSEL",
                "status": "ONAY",
                "type": "MESAJ",
                "creationDate": "2026-02-10 09:01:15",
                "transactionId": "def456..."
            },
            // ... diger numaralara ait kayitlar
        ],
        "summary": {
            "toplamNumara": 3,
            "sorgulanan": 3,
            "hatali": 0,
            "toplamKayit": 5
        }
    },
    "hataKodu": null,
    "hataMesaj": null,
    "created_at": "2026-03-31 10:00:00",
    "updated_at": "2026-03-31 10:00:45"
}

Basarili Yanit — Henuz Isleniyor (200)

{
    "guid": "c4d5e6f7-a8b9-0123-cdef-456789abcdef",
    "durum": "sorguluyor",
    "sonuc": null,
    "totalCount": null,
    "toplamNumara": 48,
    "sorgulanan": 12,
    // ... toplu sorguda ilerleme: 48 numaradan 12'si sorgulandi
}

Durum Degerleri

Durum	Aciklama
bekliyor	Sorgu kuyrukta, henuz IYS'ye gonderilmedi
sorguluyor	IYS API'ye sorgu gonderildi, yanit bekleniyor
tamamlandi	IYS'den yanit alindi. `sonuc` alaninda izin gecmisi yer alir
hata	Sorgulama basarisiz. `hataKodu` ve `hataMesaj` alanlarina bakin

sonuc.list Alanlari (IYS Yaniti)

Alan	Tip	Aciklama
`consentDate`	string	Iznin verildigi tarih (`YYYY-MM-DD HH:mm:ss`)
`source`	string	Izin kaynagi (HS_WEB, HS_CAGRI_MERKEZI vb.)
`recipient`	string	Telefon veya e-posta adresi
`recipientType`	string	`BIREYSEL` veya `TACIR`
`status`	string	`ONAY` (onaylanmis) veya `RET` (reddedilmis)
`type`	string	`ARAMA` \| `MESAJ` \| `EPOSTA`
`creationDate`	string	Iznin IYS'ye ilk kaydedildigi tarih
`transactionId`	string	IYS islem numarasi

6. Tekil Izin Durumu Sorgulama

Asenkron Islem: Tekil izin durumu sorgulama iki asamalidir. Once POST /api/v1/izin-sorgula ile sorgu olusturun, donen guid ile GET /api/v1/izin-sorgula?guid=XXX uzerinden sonucu takip edin.

Rate Limit: IYS API bu endpoint icin saatte IP basina maksimum 1000 istek kabul etmektedir.

POST /api/v1/izin-sorgula

Belirli bir alici icin IYS'deki guncel izin durumunu sorgular. Izin gecmisinden farkli olarak sadece son/aktif izin kaydini dondurur.

Request Body

Alan	Tip	Zorunlu	Aciklama
`iysCode`	integer	Evet	IYS firma kodu
`brandCode`	integer	Evet	IYS marka kodu
`type`	string (enum)	Evet	`ARAMA` \| `MESAJ` \| `EPOSTA`
`recipient`	string	Hayir	Telefon (`+905XXXXXXXXX`) veya e-posta. Gonderilmezse tum kayitli numaralar icin toplu sorgu yapilir.
`recipientType`	string (enum)	Hayir	`BIREYSEL` (varsayilan) \| `TACIR`

Ornek Istek — Toplu (Tum Numaralar)

curl -X POST https://api.selfiys.com/api/v1/izin-sorgula \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "iysCode": 631866,
    "brandCode": 631866,
    "type": "MESAJ",
    "recipientType": "BIREYSEL"
  }'

Ornek Istek — Tekil Telefon

curl -X POST https://api.selfiys.com/api/v1/izin-sorgula \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "iysCode": 631866,
    "brandCode": 631866,
    "recipient": "+905333031510",
    "type": "MESAJ",
    "recipientType": "BIREYSEL"
  }'

Ornek Istek — Tekil E-posta

curl -X POST https://api.selfiys.com/api/v1/izin-sorgula \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "iysCode": 631866,
    "brandCode": 631866,
    "recipient": "ornek@firma.com",
    "type": "EPOSTA",
    "recipientType": "BIREYSEL"
  }'

Basarili Yanit (201)

{
    "message": "Izin durumu sorgusu alindi, isleme kuyruguna eklendi",
    "guid": "e6f7a8b9-c0d1-2345-ef67-89abcdef0123",
    "durum": "bekliyor"
}

GET /api/v1/izin-sorgula?guid={guid}

Izin durumu sorgusunun sonucunu dondurur.

Basarili Yanit — Tekil, Tamamlandi (200)

{
    "guid": "e6f7a8b9-c0d1-2345-ef67-89abcdef0123",
    "iysCode": 631866,
    "brandCode": 631866,
    "recipient": "+905333031510",
    "recipientType": "BIREYSEL",
    "type": "MESAJ",
    "durum": "tamamlandi",
    "sonuc": {
        "consentDate": "2026-03-15 14:30:00",
        "source": "HS_WEB",
        "recipient": "+905333031510",
        "recipientType": "BIREYSEL",
        "status": "ONAY",
        "type": "MESAJ",
        "creationDate": "2026-03-15 14:32:10",
        "transactionId": "abc623z3cq4bhac9b88dadd49b767a232...",
        "retailerCode": 55550127,
        "retailerTitle": "XYZ TICARET",
        "retailerAccessCount": 3
    },
    "hataKodu": null,
    "hataMesaj": null,
    "created_at": "2026-03-31 12:00:00",
    "updated_at": "2026-03-31 12:00:06"
}

Basarili Yanit — Toplu, Tamamlandi (200)

{
    "guid": "f7a8b9c0-d1e2-3456-f789-abcdef012345",
    "recipient": null,
    "durum": "tamamlandi",
    "toplamNumara": 3,
    "sorgulanan": 3,
    "sonuc": {
        "list": [
            {
                "consentDate": "2026-03-15 14:30:00",
                "source": "HS_WEB",
                "recipient": "+905333031510",
                "recipientType": "BIREYSEL",
                "status": "ONAY",
                "type": "MESAJ",
                "transactionId": "abc123..."
            },
            {
                "consentDate": "2026-02-10 09:00:00",
                "source": "HS_MESAJ",
                "recipient": "+905441234567",
                "recipientType": "BIREYSEL",
                "status": "RET",
                "type": "MESAJ",
                "transactionId": "def456..."
            }
        ],
        "summary": {
            "toplamNumara": 3,
            "sorgulanan": 3,
            "hatali": 0
        }
    }
}

sonuc Alanlari (IYS Yaniti — Tekil)

Alan	Tip	Aciklama
`consentDate`	string	Iznin verildigi tarih (`YYYY-MM-DD HH:mm:ss`)
`source`	string	Izin kaynagi (HS_WEB, HS_CAGRI_MERKEZI vb.)
`recipient`	string	Telefon veya e-posta
`recipientType`	string	`BIREYSEL` veya `TACIR`
`status`	string	`ONAY` veya `RET`
`type`	string	`ARAMA` \| `MESAJ` \| `EPOSTA`
`creationDate`	string	IYS'ye ilk kaydedildigi tarih
`transactionId`	string	IYS islem numarasi
`retailerCode`	integer	Bayi IYS numarasi
`retailerTitle`	string	Bayi unvani
`retailerAccessCount`	integer	Izne erisi olan bayi sayisi

Durum Degerleri

Durum	Aciklama
bekliyor	Sorgu kuyrukta, henuz IYS'ye gonderilmedi
sorguluyor	IYS API'ye sorgu gonderildi, yanit bekleniyor
tamamlandi	IYS'den yanit alindi. `sonuc` alaninda izin durumu yer alir
hata	Sorgulama basarisiz. `hataKodu` ve `hataMesaj` alanlarina bakin

7. Izin Detay Sorgulama

Asenkron Islem: Bu endpoint api_izin_sorgula tablosuna kayit atar. IP kisitli sunucudaki izinDurumuSorgula.py worker'i kayitlari isler ve IYS'ye sorgular. Sonuclari GET /api/v1/izin-sorgula?guid=XXX ile takip edin.

Tekil & Coklu: Tek numara icin recipient, birden fazla numara icin recipients (dizi) gonderin. Tek istekte en fazla 100 recipient sorgulanabilir. Her recipient icin ayri bir guid olusturulur.

POST /api/v1/izin-detay

Belirli alicilar icin IYS'deki guncel izin detayini sorgular. Her recipient icin api_izin_sorgula tablosuna kayit atar, arka plan worker'i IYS'ye sorgulama yapar. Sonuclari GET /api/v1/izin-sorgula?guid=XXX ile alin.

Request Body

Alan	Tip	Zorunlu	Aciklama
`iysCode`	integer	Evet	IYS firma kodu
`brandCode`	integer	Evet	IYS marka kodu
`recipient`	string	Evet*	Tek numara/e-posta sorgulama. `recipients` ile birlikte kullanilamaz.
`recipients`	string[]	Evet*	Birden fazla numara/e-posta sorgulama (max 100 adet). `recipient` ile birlikte kullanilamaz.
`type`	string (enum)	Evet	`ARAMA` \| `MESAJ` \| `EPOSTA`
`recipientType`	string (enum)	Hayir	`BIREYSEL` (varsayilan) \| `TACIR`

* recipient veya recipients alanlarindan biri zorunludur.

Ornek Istek — Tekil

curl -X POST https://api.selfiys.com/api/v1/izin-detay \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "iysCode": 631866,
    "brandCode": 631866,
    "recipient": "+905333031510",
    "type": "MESAJ",
    "recipientType": "BIREYSEL"
  }'

Basarili Yanit — Tekil (201)

{
    "message": "Izin detay sorgusu alindi, isleme kuyruguna eklendi",
    "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "recipient": "+905333031510",
    "durum": "bekliyor"
}

Ornek Istek — Coklu (3 numara)

curl -X POST https://api.selfiys.com/api/v1/izin-detay \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "iysCode": 631866,
    "brandCode": 631866,
    "recipients": [
        "+905333031510",
        "+905441234567",
        "+905559876543"
    ],
    "type": "MESAJ",
    "recipientType": "BIREYSEL"
  }'

Basarili Yanit — Coklu (201)

{
    "message": "3 izin detay sorgusu kuyruga eklendi",
    "toplam": 3,
    "durum": "bekliyor",
    "sorgular": [
        {
            "recipient": "+905333031510",
            "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        },
        {
            "recipient": "+905441234567",
            "guid": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
        },
        {
            "recipient": "+905559876543",
            "guid": "c3d4e5f6-a7b8-9012-cdef-345678901234"
        }
    ]
}

Sonuc Alma

Donen guid degerleri ile sonuclari sorgulayabilirsiniz:

curl "https://api.selfiys.com/api/v1/izin-sorgula?guid=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <token>"

Yanit formati icin Tekil Izin Durumu Sorgulama bolumune bakin.

Sorgu Olustur — POST /api/v1/izin-detay ile recipient(lar) gonderin. Her biri icin guid doner.

Worker Isler — IP kisitli sunucudaki izinDurumuSorgula.py kayitlari alir, IYS'ye sorgular, sonucu DB'ye yazar.

Sonuc Al — GET /api/v1/izin-sorgula?guid=XXX ile her recipient'in sonucunu alin.

izin-sorgula vs izin-detay: izin-sorgula tek bir recipient veya toplu (tum numaralar) destekler. izin-detay ise birden fazla belirli recipient'i tek istekte kuyruga eklemenizi saglar. Her ikisi de ayni api_izin_sorgula tablosunu ve worker'i kullanir.

8. Coklu Izin Durumu Sorgulama

Asenkron & Batch API: Tum numaralar tek bir guid altinda kuyruga eklenir (sorguTipi=1). Worker, IYS batchConsentStatus API'sini kullanarak 1000'e kadar numarayi tek istekte sorgular. Bu sayede API istek kotasi verimli kullanilir (saatte 1000 istek limiti). Sadece ONAY durumundaki alicilar doner.

POST /api/v1/izin-toplu

Birden fazla alici icin tek bir IYS izin durumu sorgulama kaydi olusturur. Tek guid doner, tum sonuclar bu guid ile sorgulanir.

Request Body

Alan	Tip	Zorunlu	Aciklama
`iysCode`	integer	Evet	IYS firma kodu
`brandCode`	integer	Evet	IYS marka kodu
`recipients`	string[]	Evet	Sorgulanacak telefon/e-posta listesi (max 1000 adet)
`type`	string (enum)	Evet	`ARAMA` \| `MESAJ` \| `EPOSTA`
`recipientType`	string (enum)	Hayir	`BIREYSEL` (varsayilan) \| `TACIR`

Ornek Istek

curl -X POST https://api.selfiys.com/api/v1/izin-toplu \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "iysCode": 631866,
    "brandCode": 631866,
    "recipients": [
        "+905333031510",
        "+905441234567",
        "+905559876543"
    ],
    "type": "MESAJ",
    "recipientType": "BIREYSEL"
  }'

Basarili Yanit (201)

{
    "message": "3 numara icin izin sorgusu kuyruga eklendi",
    "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "toplam": 3,
    "durum": "bekliyor"
}

Sonuc Alma

Donen tek guid ile tum numaralarin sonucunu birlikte sorgulayabilirsiniz:

curl "https://api.selfiys.com/api/v1/izin-sorgula?guid=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <token>"

Sonuc Yaniti — Tamamlandi (200)

IYS batchConsentStatus API'si kullanilir. Sadece ONAY durumundaki alicilar listelenir:

{
    "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "durum": "tamamlandi",
    "sorguTipi": 1,
    "toplamNumara": 3,
    "sorgulanan": 3,
    "sonuc": {
        "requestIds": ["req-abc-123"],
        "sorgulanan": 3,
        "onayliSayisi": 2,
        "onaylilar": [
            "+905333031510",
            "+905441234567"
        ],
        "hataliChunk": 0
    }
}

Durum Degerleri

Durum	Aciklama
bekliyor	Sorgu kuyrukta, henuz islenmedi
sorguluyor	Worker numaralari IYS'ye sorguluyor. `sorgulanan` / `toplamNumara` ile ilerleme takip edilebilir
tamamlandi	Tum numaralar sorgulandi. `sonuc` alaninda detaylar yer alir
hata	Genel hata olustu

izin-detay vs izin-toplu:
• izin-detay: Her recipient icin ayri guid olusturur (max 100). IYS consentDetail API'si ile tek tek sorgulanir. Her numara icin detayli sonuc (ONAY/RET) doner.
• izin-toplu: Tum recipientlar icin tek guid olusturur (max 1000). IYS batchConsentStatus API'si ile tek istekte sorgulanir. Sadece ONAY durumundaki alicilar listelenir. API kota kullanimi minimumda tutulur.

9. Hata Kodlari

Tum hata yanitlari asagidaki formattadir:

{
    "error": "Hata aciklamasi",
    "code": "HATA_KODU"
}

HTTP Durum Kodlari

HTTP Kodu	Hata Kodu	Aciklama
400	`MISSING_CREDENTIALS`	api_key veya api_secret eksik
400	`MISSING_FIELD`	Zorunlu alan eksik
400	`VALIDATION_ERROR`	Girdi dogrulama hatasi. `details` alaninda detaylar yer alir
401	`INVALID_CREDENTIALS`	Gecersiz api_key veya api_secret
401	`AUTH_REQUIRED`	Authorization header eksik
401	`TOKEN_EXPIRED`	Token suresi dolmus veya gecersiz
403	`FIRMA_NOT_FOUND`	iysCode hesabiniza tanimli degil
403	`FIRMA_LIMIT_EXCEEDED`	Firma ekleme limitine ulasildi
404	`NOT_FOUND`	Kayit bulunamadi
404	`BRAND_NOT_FOUND`	brandCode firma adina API'de tanimli degil. `GET /api/v1/marka?brandCode=...` ile kontrol edip `api_marka` tablosunda kayit acin
502	`IYS_ERROR`	IYS servisi hata dondurdu
503	`IYS_UNAVAILABLE`	IYS servisi gecici olarak kullanilamiyor
503	`SERVICE_UNAVAILABLE`	Servis gecici olarak kullanilamiyor