# İzin sorgulama

> Bir ya da birden fazla alıcının İYS'deki izin durumunu sorgular.

- **İstek:** `GET https://ext-api.netgsm.com.tr/iys/v1/consents`
- **Canlı ortam:** `https://ext-api.netgsm.com.tr/iys/v1`
- **Kimlik doğrulama:** `Authorization: Bearer <token>`
- **HTML sayfası:** https://api-docs.netgsm.com.tr/iys/search-consents/
- **OpenAPI tanımı:** https://api-docs.netgsm.com.tr/openapi/iys-v1.yaml (operationId: `searchConsents`)

## Açıklama

Bir ya da birden fazla alıcının İYS'deki izin durumunu sorgular.

**Tekil sorgu:** `recipient`, `recipientType` ve `type` alanlarını gönderin.

**Çoklu sorgu:** Kayıtları `data` dizisiyle, en fazla 1000 kayıt olacak şekilde gönderin:

```
GET /consents?brandCode=123456&data[0][recipient]=%2B905551112233&data[0][recipientType]=BIREYSEL&data[0][type]=MESAJ&data[1][recipient]=ornek@mail.com&data[1][recipientType]=BIREYSEL&data[1][type]=EPOSTA
```

- `data` içinde tek kayıt varsa tekil sorgu yapılır; yanıt tekil sorguyla aynıdır.
- Sonuçlar gönderilen kayıtlarla aynı sırada döner. Çoklu sorguda her kaydın kendi
  `errorCode` ve `message` alanı vardır: `0` başarılı, `81` kayıt bulunamadı, `120` hatalı
  istek, `112` İYS'den geçerli yanıt alınamadı. Hatalı kayıtta sorgulanan alanlar korunur.
- İsteğin tamamını etkileyen bir hata (örneğin geçersiz `brandCode`) isteği `400` ile
  sonlandırır.
- Kayıtlar adres satırında taşındığı için çok sayıda kayıtta URL uzunluk sınırına dikkat
  etmelisiniz.

## İstek

### Parametreler

- `brandCode` (sorgu, integer, zorunlu, en az 1, en fazla 2147483647): İYS marka kodu. Örnek: `123456`.
- `path` (sorgu, string, isteğe bağlı): Gönderilmezse `SMSAPI` kabul edilir. Değerler: `SANTRAL`, `SMSAPI`, `WEBPORTAL`. Örnek: `SMSAPI`.
- `refId` (sorgu, string, isteğe bağlı, en az uzunluk 1, en fazla uzunluk 255): İsteğe eklediğiniz referans değeri. Çoklu sorguda `data[i][refId]` gönderilmeyen kayıtlar için kullanılır. Örnek: `40e6215d-b5c6-4896-987c-f30f3678f608`.
- `recipient` (sorgu, string, isteğe bağlı): Telefon numarası (`+90XXXXXXXXXX`) ya da e-posta adresi. `data` gönderilmiyorsa zorunludur. Örnek: `+905554443322`.
- `recipientType` (sorgu, string, isteğe bağlı): Alıcı tipi. `data` gönderilmiyorsa zorunludur. Değerler: `BIREYSEL`, `TACIR`. Örnek: `BIREYSEL`.
- `type` (sorgu, string, isteğe bağlı): İzin tipi. `data` gönderilmiyorsa zorunludur. Değerler: `ARAMA`, `MESAJ`, `EPOSTA`. Örnek: `MESAJ`.
- `data` (sorgu, array<object>, isteğe bağlı, en az kayıt 1, en fazla kayıt 1000): Çoklu sorgu kayıtları, en fazla 1000. Her kayıtta `recipient`, `recipientType` ve `type` zorunludur.

## Örnek istek

```bash
curl -X GET 'https://ext-api.netgsm.com.tr/iys/v1/consents?brandCode=123456&path=SMSAPI&refId=40e6215d-b5c6-4896-987c-f30f3678f608&recipient=%2B905554443322&recipientType=BIREYSEL&type=MESAJ' \
  -H 'Authorization: Bearer <token>'
```

## Yanıtlar

### 200 — Sorgu tamamlandı.

Gövde (`application/json`):

- `success` (boolean, isteğe bağlı): Örnek: `true`.
- `errorCode` (integer, isteğe bağlı): Örnek: `0`.
- `message` (string, isteğe bağlı): Örnek: `success`.
- `data` (array<object>, isteğe bağlı)
- `data[].type` (string, null olabilir, isteğe bağlı): Örnek: `MESAJ`.
- `data[].source` (string, null olabilir, isteğe bağlı): Örnek: `HS_MESAJ`.
- `data[].recipient` (string, isteğe bağlı): Örnek: `+905555555555`.
- `data[].status` (string, null olabilir, isteğe bağlı): Örnek: `ONAY`.
- `data[].consentDate` (string, null olabilir, isteğe bağlı): Örnek: `2020-07-09 17:20:00`.
- `data[].recipientType` (string, isteğe bağlı): Örnek: `BIREYSEL`.
- `data[].creationDate` (string, null olabilir, isteğe bağlı)
- `data[].queryStatus` (string, null olabilir, isteğe bağlı): Örnek: `failure`.
- `data[].retailerAccessCount` (integer, null olabilir, isteğe bağlı): Yalnızca çoklu sorguda.
- `data[].errorCode` (integer, isteğe bağlı): Yalnızca çoklu sorguda: `0` başarılı, `81` kayıt bulunamadı, `120` hatalı istek, `112` İYS'den geçerli yanıt alınamadı. Örnek: `0`.
- `data[].message` (string, null olabilir, isteğe bağlı): Yalnızca çoklu sorguda, kaydın hata mesajı.

Örnek: Tekil sorgu

```json
{
  "success": true,
  "errorCode": 0,
  "message": "success",
  "data": [
    {
      "type": "MESAJ",
      "source": "HS_MESAJ",
      "recipient": "+905555555555",
      "status": "ONAY",
      "consentDate": "2020-07-09 17:20:00",
      "recipientType": "BIREYSEL",
      "creationDate": null,
      "queryStatus": "failure"
    }
  ]
}
```

Örnek: Çoklu sorgu

```json
{
  "success": true,
  "errorCode": 0,
  "message": "success",
  "data": [
    {
      "type": "MESAJ",
      "source": "HS_WEB",
      "recipient": "+905551112233",
      "status": "ONAY",
      "consentDate": "2026-01-01 10:00:00",
      "recipientType": "BIREYSEL",
      "creationDate": null,
      "queryStatus": null,
      "retailerAccessCount": null,
      "errorCode": 0,
      "message": null
    },
    {
      "type": "EPOSTA",
      "source": null,
      "recipient": "ornek@mail.com",
      "status": null,
      "consentDate": null,
      "recipientType": "BIREYSEL",
      "creationDate": null,
      "queryStatus": null,
      "retailerAccessCount": null,
      "errorCode": 81,
      "message": "Resource not found"
    }
  ]
}
```

### 400 — Hatalı istek.

Gövde (`application/json`):

- `success` (boolean, isteğe bağlı): Örnek: `false`.
- `errorCode` (integer, isteğe bağlı): Hata kodu (bkz. Hata kodları). Örnek: `120`.
- `message` (string, isteğe bağlı): Örnek: `Bad request`.
- `data` (array<any> | object, isteğe bağlı): Hata ayrıntıları. Çoğu hatada boş dizidir; doğrulama hatasında `errors` nesnesini taşır.
- `data` oneOf → **seçenek 1**
- `data` oneOf → **seçenek 2**

Örnek:

```json
{
  "success": false,
  "errorCode": 120,
  "message": "Bad request",
  "data": []
}
```

### 401 — Token yok, geçersiz ya da süresi dolmuş.

Gövde (`application/json`): alanlar 400 yanıtıyla aynı.

Örnek: Token'ın süresi dolmuş

```json
{
  "success": false,
  "errorCode": 53,
  "message": "Token has expired",
  "data": []
}
```

Örnek: Token bulunamadı

```json
{
  "success": false,
  "errorCode": 51,
  "message": "Token not found",
  "data": []
}
```

### 403 — Yetkisiz erişim ya da hesapta İYS hizmeti aktif değil.

Gövde (`application/json`): alanlar 400 yanıtıyla aynı.

Örnek:

```json
{
  "success": false,
  "errorCode": 60,
  "message": "Unauthorized access",
  "data": []
}
```

### 422 — İstekteki bir alan kurallara uymuyor.

Gövde (`application/json`): alanlar 400 yanıtıyla aynı.

Örnek:

```json
{
  "success": false,
  "errorCode": 70,
  "message": "Validation failed",
  "data": {
    "errors": {
      "brandCode": "The brand code field is required."
    }
  }
}
```

### 424 — İYS'den geçerli bir yanıt alınamadı.

Gövde (`application/json`): alanlar 400 yanıtıyla aynı.

Örnek:

```json
{
  "success": false,
  "errorCode": 112,
  "message": "Api Error",
  "data": []
}
```

### 429 — Çok fazla istek gönderildi.

Gövde (`application/json`): alanlar 400 yanıtıyla aynı.

Örnek:

```json
{
  "success": false,
  "errorCode": 150,
  "message": "Too many requests.",
  "data": []
}
```

### 500 — Beklenmeyen bir hata oluştu.

Gövde (`application/json`): alanlar 400 yanıtıyla aynı.

Örnek:

```json
{
  "success": false,
  "errorCode": 110,
  "message": "Server Error",
  "data": []
}
```