# Kara listeye numara ekleme (Sandbox)

> Hesabın kara listesine numara ekler.

- **İstek:** `POST https://ext-sandbox.netgsm.com.tr/sms/v3/blacklist`
- **Sandbox:** `https://ext-sandbox.netgsm.com.tr/sms/v3`
- **Kimlik doğrulama:** `Authorization: Bearer <token>`
- **HTML sayfası:** https://api-docs.netgsm.com.tr/sandbox/blacklist/add-to-blacklist/
- **OpenAPI tanımı:** https://api-docs.netgsm.com.tr/openapi/sandbox-v3.yaml (operationId: `addToBlacklist`)

## Açıklama

Hesabın kara listesine numara ekler. Bir istekte en fazla 100 numara gönderilebilir.

**Numara biçimi.** Kara liste yalnızca yurt içi numara tutar. Her numara E.164 biçiminde, `+90`
ve on rakam olarak yazılır (`+905XXXXXXXXX`). Artısız yazımlar (`905XXXXXXXXX`, `5XXXXXXXXX`) ve
başka ülke kodlu numaralar kabul edilmez. Numaralardan biri bile kurala uymuyorsa istek bütünüyle
400 ile reddedilir ve hiçbir numara eklenmez.

**Zaten listede olan numaralar.** Kara listede olan bir numara ikinci kez eklenmez. En az bir
numara eklendiyse yanıt 200'dür; istenen her numara `addedNumbers` ya da `existingNumbers`
listelerinden birinde yer alır (1 numara eklenip 99'u zaten listedeyse yanıt yine 200'dür).
Hiçbir numara eklenmediyse, yani istenen numaraların hepsi zaten listedeyse, yanıt 409 olur.

**İstek sınırı.** Hesap başına dakikada 60 istek. Süre penceresi ilk istekle başlar ve sabittir.
Aşıldığında 429 `Retry-After` başlığıyla döner.

**Yeniden deneme.** İsteği yeniden göndermek her zaman güvenlidir: ilk istekte eklenen numaralar
ikinci kez eklenmez; ikinci istekte `existingNumbers` içinde döner ya da hepsi eklenmişse yanıt
409 olur.

## İstek

### Gövde (`application/json`, zorunlu)

- `numbers` (array<string>, zorunlu, en az kayıt 1, en fazla kayıt 100): Kara listeye eklenecek numaralar; en az 1, en fazla 100. Her biri E.164 biçiminde ve yurt içi, `+90` ve on rakam. Aynı numara birden fazla yazılırsa bir kez eklenir.

Örnek gövde:

```json
{
  "numbers": [
    "+905XXXXXXXXX",
    "+905yyyyyyyyy"
  ]
}
```

## Örnek istek

```bash
curl -X POST 'https://ext-sandbox.netgsm.com.tr/sms/v3/blacklist' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "numbers": [
    "+905XXXXXXXXX",
    "+905yyyyyyyyy"
  ]
}'
```

## Yanıtlar

### 200 — En az bir numara eklendi; eklenenler ve zaten listede olanlar ayrı ayrı döner.

Gövde (`application/json`):

- `added` (integer, zorunlu, en az 1): Eklenen numara sayısı; en az 1.
- `existing` (integer, zorunlu): Zaten kara listede olduğu için eklenmeyen numara sayısı.
- `addedNumbers` (array<string>, zorunlu, en fazla kayıt 100): Eklenen numaralar, E.164 biçiminde.
- `existingNumbers` (array<string>, zorunlu, en fazla kayıt 100): Zaten kara listede olan numaralar, E.164 biçiminde.

Örnek:

```json
{
  "added": 1,
  "existing": 1,
  "addedNumbers": [
    "+905XXXXXXXXX"
  ],
  "existingNumbers": [
    "+905yyyyyyyyy"
  ]
}
```

### 400 — INVALID_REQUEST. Hiçbir numara eklenmez. `message`:

| `message` | Ne zaman |
|---|---|
| `numbers must not be empty` | `numbers` yok ya da boş. |
| `at most 100 numbers may be added at once` | 100'den fazla numara gönderildi. |
| `number must be in +90XXXXXXXXXX format` | Bir numara `+90` ve on rakam değil (artısız ya da yurt dışı). |
| `request body could not be read as json` | Gövde JSON değil. |

Gövde (`application/json`):

- `code` (string, zorunlu): Değerler: `INVALID_REQUEST`.
- `message` (string, zorunlu): Okunabilir ayrıntı. `UNAUTHENTICATED` için `no bearer token` ya da `invalid or expired token`. `REJECTED_HEADER` için ret adıdır; yalnızca rakamlardan oluşan bir göndericide ` (subscriber number headers were not offered)` ekini taşıyabilir. `RATE_LIMITED` için sınırı belirtir; `FORBIDDEN` ve `REJECTED_IYS` için sabit bir cümledir. `SERVICE_UNAVAILABLE` ve `INTERNAL_ERROR` genel bir cümle taşır; bildirirken `requestId` değerini paylaşmanız gerekir.
- `requestId` (string, zorunlu): İsteğe özgü kimlik, 32 onaltılık karakter. Bir sorun bildirirken bu değeri paylaşmanız, isteğin kayıtlarda bulunmasını sağlar.
- `timestamp` (string, date-time, zorunlu)
- `violations` (array<object>, null olabilir, zorunlu): Yalnızca gövde doğrulamasından gelen INVALID_REQUEST için dolu, aksi halde `null`.
- `violations[].field` (string, isteğe bağlı)
- `violations[].message` (string, isteğe bağlı)
- `rejectedItems` (array<object>, isteğe bağlı, en fazla kayıt 100): Yalnızca `NO_DELIVERABLE_MESSAGES` yanıtında bulunur; diğer hatalarda alan hiç yer almaz. Reddedilen kayıtlar, `index` sırasıyla ilk 100 tanesi; 202 yanıtındaki `rejectedItems` ile aynıdır.
- `rejectedItems[].index` (integer, zorunlu): Kaydın istekteki `messages` dizisindeki sırası, sıfırdan başlar.
- `rejectedItems[].recipient` (string, null olabilir, zorunlu): Kayıttaki alıcı. Kayıt `null` ise ya da alıcısı yoksa `null`.
- `rejectedItems[].reason` (string, zorunlu): Değerler: `INVALID_RECIPIENT`, `INVALID_MESSAGE`, `MESSAGE_TOO_LONG`, `MALFORMED_ENTRY`, `DUPLICATE_RECIPIENT`, `NO_INTERNATIONAL_PERMISSION`.

  | Değer | Ne zaman |
  |---|---|
  | `INVALID_RECIPIENT` | Numara eksik ya da biçimi yanlış; bkz. `recipient`. |
  | `INVALID_MESSAGE` | Metin eksik ya da boş. |
  | `MESSAGE_TOO_LONG` | Metin, `encoding` ve gönderici türüne göre sınırı aşıyor; bkz. `encoding`. |
  | `MALFORMED_ENTRY` | Kayıt `null`. |
  | `DUPLICATE_RECIPIENT` | Aynı alıcı istekte daha sonra yeniden geçiyor. Yalnızca son geçen kayıt gönderilir, öncekiler bu nedenle reddedilir; son kayıt başka bir nedenle reddedilse bile. Aynı numaranın iki yazımı (`+905XXXXXXXXX` ile `905XXXXXXXXX`) aynı alıcıdır; bunun dışında numaralar yazıldığı gibi karşılaştırılır. Mükerrer gönderime izin verilen hesaplarda uygulanmaz. |
  | `NO_INTERNATIONAL_PERMISSION` | Numara yurt dışı (`-` ile ya da `+90` dışında bir `+` ülke koduyla başlıyor) ve hesabın yurt dışı gönderim izni yok. İzin için destek ekibiyle iletişime geçmelisiniz. Yalnızca başka bir hatası olmayan kayıtlarda bildirilir. |

  Bir kayıt birden fazla nedenle hatalıysa tek neden bildirilir; öncelik: `DUPLICATE_RECIPIENT`,
  `MALFORMED_ENTRY`, `MESSAGE_TOO_LONG`, `INVALID_RECIPIENT`, `INVALID_MESSAGE`,
  `NO_INTERNATIONAL_PERMISSION`.

- `rejectedItemsTruncated` (boolean, isteğe bağlı): Yalnızca `rejectedItems` ile birlikte bulunur. 100'den fazla kayıt reddedildiğinde true.

Örnek (şemadan üretildi):

```json
{
  "code": "INVALID_REQUEST",
  "message": "string",
  "requestId": "string",
  "timestamp": "2026-01-01T10:00:00+03:00",
  "violations": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "rejectedItems": [
    {
      "index": 0,
      "recipient": "string",
      "reason": "INVALID_RECIPIENT"
    }
  ],
  "rejectedItemsTruncated": true
}
```

### 401 — UNAUTHENTICATED. Bearer token yok ya da token geçersiz veya süresi dolmuş; `message` `no bearer token` ya da `invalid or expired token`.

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

- `code` (string, zorunlu): Değerler: `UNAUTHENTICATED`.

Örnek (şemadan üretildi):

```json
{
  "code": "UNAUTHENTICATED",
  "message": "string",
  "requestId": "string",
  "timestamp": "2026-01-01T10:00:00+03:00",
  "violations": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "rejectedItems": [
    {
      "index": 0,
      "recipient": "string",
      "reason": "INVALID_RECIPIENT"
    }
  ],
  "rejectedItemsTruncated": true
}
```

### 409 — ALREADY_EXISTS. Hiçbir numara eklenmedi çünkü istenen numaraların hepsi zaten kara listede. `message` tek numara için `number is already in the blacklist`, birden fazla numara için `all numbers are already in the blacklist`.

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

- `code` (string, zorunlu): Değerler: `ALREADY_EXISTS`.

Örnek (şemadan üretildi):

```json
{
  "code": "ALREADY_EXISTS",
  "message": "string",
  "requestId": "string",
  "timestamp": "2026-01-01T10:00:00+03:00",
  "violations": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "rejectedItems": [
    {
      "index": 0,
      "recipient": "string",
      "reason": "INVALID_RECIPIENT"
    }
  ],
  "rejectedItemsTruncated": true
}
```

### 429 — RATE_LIMITED, `message` `blacklist add rate limit exceeded`. Hesap başına dakikada 60 istek aşıldı; `Retry-After` kadar bekleyip yeniden denemelisiniz.

Başlıklar:

- `Retry-After` (integer): Yeniden denemeden önce beklenecek süre (saniye).

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

- `code` (string, zorunlu): Değerler: `RATE_LIMITED`.

Örnek (şemadan üretildi):

```json
{
  "code": "RATE_LIMITED",
  "message": "string",
  "requestId": "string",
  "timestamp": "2026-01-01T10:00:00+03:00",
  "violations": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "rejectedItems": [
    {
      "index": 0,
      "recipient": "string",
      "reason": "INVALID_RECIPIENT"
    }
  ],
  "rejectedItemsTruncated": true
}
```

### 500 — INTERNAL_ERROR, `message` `internal error`. Beklenmeyen hata; bildirirken `requestId` değerini paylaşmanız gerekir.

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

- `code` (string, zorunlu): Değerler: `INTERNAL_ERROR`.

Örnek (şemadan üretildi):

```json
{
  "code": "INTERNAL_ERROR",
  "message": "string",
  "requestId": "string",
  "timestamp": "2026-01-01T10:00:00+03:00",
  "violations": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "rejectedItems": [
    {
      "index": 0,
      "recipient": "string",
      "reason": "INVALID_RECIPIENT"
    }
  ],
  "rejectedItemsTruncated": true
}
```

### 503 — SERVICE_UNAVAILABLE. Hiçbir şey yapılmadı; yeniden denemek güvenlidir.

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

- `code` (string, zorunlu): Değerler: `SERVICE_UNAVAILABLE`.

Örnek (şemadan üretildi):

```json
{
  "code": "SERVICE_UNAVAILABLE",
  "message": "string",
  "requestId": "string",
  "timestamp": "2026-01-01T10:00:00+03:00",
  "violations": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "rejectedItems": [
    {
      "index": 0,
      "recipient": "string",
      "reason": "INVALID_RECIPIENT"
    }
  ],
  "rejectedItemsTruncated": true
}
```

### 504 — QUEUE_UNCONFIRMED. Ekleme iletildi ama yanıtı alınamadı; numaralar eklenmiş olabilir. İsteği yeniden gönderebilirsiniz: eklenmiş numaralar `existingNumbers` içinde döner, hepsi eklenmişse yanıt 409 olur.

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

- `code` (string, zorunlu): Değerler: `QUEUE_UNCONFIRMED`.

Örnek (şemadan üretildi):

```json
{
  "code": "QUEUE_UNCONFIRMED",
  "message": "string",
  "requestId": "string",
  "timestamp": "2026-01-01T10:00:00+03:00",
  "violations": [
    {
      "field": "string",
      "message": "string"
    }
  ],
  "rejectedItems": [
    {
      "index": 0,
      "recipient": "string",
      "reason": "INVALID_RECIPIENT"
    }
  ],
  "rejectedItemsTruncated": true
}
```
