# Kara listeyi öğrenme > Hesabın kara listesindeki numaraları döndürür. - **İstek:** `GET https://ext-api.netgsm.com.tr/sms/v3/blacklist` - **Canlı ortam:** `https://ext-api.netgsm.com.tr/sms/v3` - **Kimlik doğrulama:** `Authorization: Bearer ` - **HTML sayfası:** https://api-docs.netgsm.com.tr/read-blacklist/ - **OpenAPI tanımı:** https://api-docs.netgsm.com.tr/openapi/sms-v3.yaml (operationId: `readBlacklist`) ## Açıklama Hesabın kara listesindeki numaraları döndürür. İki kullanımı vardır: - **Liste:** `number` verilmezse kara liste sayfa sayfa döner. Her sayfada en fazla 200 numara bulunur, en son eklenen önce gelir. İlk sayfa 0'dır. - **Tek numara sorgusu:** `number` verilirse yalnızca o numaraya bakılır. Numara kara listedeyse `count` 0'dan büyüktür ve numara `numbers` içinde yer alır; değilse `count` 0 ve `numbers` boştur. Kara listede numara olmaması ya da listenin sonunu geçen bir sayfanın istenmesi hata değildir; yanıt `count` 0 ve boş `numbers` ile başarılı döner. ## İstek ### Parametreler - `page` (sorgu, integer, isteğe bağlı, en az 0): İstenen sayfa, 0'dan başlar. Tek numara sorgusunda yanıtı etkilemez. Varsayılan: `0`. - `number` (sorgu, string, isteğe bağlı, desen `^[0-9]{1,15}$`): Sorgulanacak tek numara; bir alıcı için 90 ve on rakam. Yalnızca rakam, en fazla 15; başka her şey 400 alır. Baştaki ve sondaki boşluklar kırpılır; boş bir değer `number` hiç gönderilmemiş gibi değerlendirilir. Örnek: `905xxxxxxxxx`. ## Örnek istek ```bash curl -X GET 'https://ext-api.netgsm.com.tr/sms/v3/blacklist?number=905xxxxxxxxx' \ -H 'Authorization: Bearer ' ``` ## Yanıtlar ### 200 — Bir sayfa ya da tek bir numara hakkındaki yanıt. Gövde (`application/json`): - `count` (integer, zorunlu): `numbers` içindeki numara sayısı. Tek numara sorgusunda 0, numaranın kara listede olmadığını gösterir. - `page` (integer, null olabilir, zorunlu): Döndürülen, sıfırdan başlayan sayfa. Tek numara sorgusunda `null`. - `number` (string, null olabilir, zorunlu): Sorgulanan numara, aynen geri döndürülür. Sayfa isteğinde `null`. - `numbers` (array, zorunlu): Engellenen numaralar saklandığı biçimde, en yenisi önce. Örnek: page ```json { "count": 1, "page": 0, "number": null, "numbers": [ "905xxxxxxxxx" ] } ``` Örnek: lookup ```json { "count": 1, "page": null, "number": "905xxxxxxxxx", "numbers": [ "905xxxxxxxxx" ] } ``` ### 400 — INVALID_REQUEST. `page` sayı değil ya da negatif veya `number` 1 ile 15 rakam arasında değil; `message` parametreyi belirtir. 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, 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, 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. 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 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 } ``` ### 429 — RATE_LIMITED. Hesap dakikada 60 istek sınırını aştı ya da aynı sorgu (aynı `page` ve `number` değerleri) son 10 dakika içinde yanıtlandı; `message` hangisi olduğunu belirtir. Hatayla sonuçlanan bir sorgu beklemeden tekrar gönderilebilir. Başlıklar: - `Retry-After` (integer): Engelleyen sayacın süresi dolana kadar kalan 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 } ```