---
title: "Numara Engelle API (add-blacklist)"
description: "SMS gönderilmesini istemediğiniz bir cep numarasını kara listeye ekleyin. Idempotent: aynı numara tekrar eklenirse 200 döner."
slug: /docs/api/add-blacklist
locale: tr
audience: developer
last_updated: 2026-04-29
endpoint:
  method: POST
  path: /v1/add-blacklist/json
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [get-blacklist, delete-blacklist, authentication, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/add-blacklist
  en: https://www.iletimerkezi.com/en/docs/api/add-blacklist
  toplusmsapi: https://toplusmsapi.com/numara-engelle/ekle/json
  a2psmsapi: https://a2psmsapi.com/en/numara-engelle/ekle/json
---

# Numara Engelle API (add-blacklist)

`add-blacklist` endpoint'i, SMS gönderilmesini istemediğiniz bir cep telefonu numarasını hesabınızın kara listesine ekler. Bu listedeki numaralara `send-sms` çağrılarında mesaj iletilmez. **Idempotent**: aynı numarayı ikinci kez eklemek hata değil, 200 döndürür. İstek başına yalnızca **bir** numara eklenir.

## Ö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)

## Endpoint

| Alan | Değer |
|---|---|
| Method | `POST` |
| URL | `https://api.iletimerkezi.com/v1/add-blacklist/json` |
| Content-Type | `application/json` |
| Auth | API Key + Hash (`request.authentication`) |

## Request

### Şema

```
request
├─ authentication
│  ├─ key (string, zorunlu)
│  └─ hash (string, zorunlu)
└─ blacklist
   └─ number (string, zorunlu) — tek numara, 905XXXXXXXXX / +905XXXXXXXXX / 5XXXXXXXXX
```

### Tam örnek

```json
{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "blacklist": {
      "number": "905XXXXXXXXX"
    }
  }
}
```

## Response

### Başarılı (200)

```json
{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    }
  }
}
```

Numara hesaba ait kara listeye eklendi. Aynı numarayı ikinci kez eklemek de aynı 200 yanıtını döndürür.

### Hata yanıtları

#### 401 — Üyelik bilgileri hatalı

Detay: [authentication.md](./authentication.md).

#### 466 — Hatalı numara

Numara format olarak Türkiye operatör prefix'lerine uymuyor (50/53/54/55 vb.). `+905330000099` gibi geçerli bir numara verin. Test sırasında uyduruk prefix (`905999XXXXXXX` gibi) reddedilir.

#### 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/add-blacklist/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      },
      "blacklist": { "number": "905XXXXXXXXX" }
    }
  }'
```


## Common Pitfalls

- **Idempotent davranış.** Aynı numarayı tekrar eklemek hata değildir, 200 döner. `try/except 466` gibi guard'a gerek yok; "zaten engellenmiş mi?" diye `get-blacklist` ile ön kontrol gereksiz.
- **Tek numara, istek başına.** `blacklist.number` dizi değildir — tek string. Toplu engelleme için her numara için ayrı istek atın (rate limit'e dikkat).
- **466 = geçersiz Türkiye operatör prefix'i.** `+905330000099` çalışır, `+905999000000` reddedilir. Yabancı numaralar (örn. `+49...`) MDX'te örnek var; canlı kabul davranışı operatör tarafına bağlıdır, kritik akışta kendi sisteminizden test edin.
- **Numara format esnek, dönüş `+90` prefix'li.** `905...`, `+905...`, `5...` kabul edilir; `get-blacklist` yanıtında numara `+905XXXXXXXXX` olarak döner.


## Related

- [Engellenmiş liste (get-blacklist)](./get-blacklist.md)
- [Engelleme kaldır (delete-blacklist)](./delete-blacklist.md)
- [Kimlik doğrulama (authentication)](./authentication.md)
- [Hata kodları tablosu](./error-codes.md)