# Bildirim Kuyruğu

https://dev.wisecp.com/tr/bildirim-kuyrugu

Gönderilmeyi bekleyen e-posta ve mesajları izleyen, kurtaran ve temizleyen dokuz uç.

## Genel Bakış

E-posta ve kısa mesajlar doğrudan gönderilmez; önce **kuyruğa** alınır ve arka planda sırayla işlenir. Bu dokuz uç o kuyruğu izler, takılanları kurtarır ve birikeni temizler.

Mesajın kendisi şifreli saklanır ve **hiçbir uçtan dönmez**: burada konu, alıcı ve durum vardır. Gönderilmiş bir metni okumak istiyorsanız yeri kayıt defterleridir.

Yapı modül kuyruğuyla neredeyse aynıdır ama iki uçta ayrılır: burada yeniden deneme bekleyen öğeleri de kabul eder, hemen gönderme ise **yalnız** bekleyenleri.

## Referans

### Kuyruğu Listeleme

get/api/v1/admin/tools/notification-queue

`Tools/GetNotificationQueue` admin mesaj hiç dönmez

Gönderilmeyi bekleyen e-posta ve kısa mesajları döndürür.

Sorgu parametreleri 5

statusstringDuruma göre süzer.

channelstringKanala göre süzer: e-posta ya da kısa mesaj.

pageintVarsayılan 1.

limitintVarsayılan 25, en çok 100.

searchstringKayıtlarda arar.

Dönen alanlar data[] — 17

idintKuyruk öğesinin kimliği.

channelstring`mail` ya da `sms`.

recipientstringAlıcının adresi ya da numarası.

recipient_ccstringNumaradan ayrı saklandığında SMS alıcısının ülke kodu (`90` → `+90 5551112233`). E-postada ve `+` önekini kendisi taşıyan numarada boştur.

recipient_namestringAlıcının adı.

subjectstringBildirimin konusu.

statusstring`pending` sırada, `processing` gönderiliyor, `sent` gitti, `failed` düştü, `cancelled` gönderilmeden durduruldu (sebebi işlem günlüğünde).

priorityintGönderim önceliği.

user_idintİlgili müşterinin kimliği.

user_full_namestring | nullMüşterinin adı.

attemptsintKaç kez denendiği.

max_attemptsintEn çok kaç kez deneneceği.

batch_idstring | nullToplu gönderim kimliği. Aynı gönderimden çıkan bildirimleri birbirine bağlar.

created_atstring | nullKuyruğa girdiği zaman.

scheduled_atstring | nullGönderilmesi planlanan zaman.

processed_atstring | nullİşlendiği zaman.

next_retrystring | nullBir sonraki denemenin zamanı.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -G 'https://panel.ornek.com/api/v1/admin/tools/notification-queue' \
  -H "Authorization: Bearer $API_KEY" \
  -d status=failed \
  -d channel=mail
```

```javascript
const url = new URL('https://panel.ornek.com/api/v1/admin/tools/notification-queue');
url.searchParams.set('status', 'failed');
url.searchParams.set('channel', 'mail');

const res  = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```

```php
$url = 'https://panel.ornek.com/api/v1/admin/tools/notification-queue?' . http_build_query([
    'status'  => 'failed',
    'channel' => 'mail',
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Mesajin kendisi hicbir uctan DONMEZ; konu ve alici disinda icerik gormezsiniz.
$failed = Api::Tools()->GetNotificationQueue([], ['status' => 'failed'])['data'];
```

### Kuyruk Sayaçları

get/api/v1/admin/tools/notification-queue/stats

`Tools/GetNotificationQueueStats` admin

Bekleyen ve gitmiş bildirimlerin sayısını döndürür.

Dönen alanlar data — 5

totalintKuyruktaki toplam bildirim.

pendingintSırada bekleyen bildirim sayısı.

processingintŞu an gönderilen bildirim sayısı.

sentintGönderilmiş bildirim sayısı.

failedintDüşmüş bildirim sayısı.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/tools/notification-queue/stats' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/tools/notification-queue/stats', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/notification-queue/stats');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Bekleyen sayisinin surekli buyumesi gonderim hattinin durdugunu gosterir.
$stats = Api::Tools()->GetNotificationQueueStats()['data'];
```

### Öğe Detayı

get/api/v1/admin/tools/notification-queue/{id}

`Tools/GetNotificationQueueItem` admin adım kayıtları

Tek bir bildirimi, gönderim denemelerinin kaydıyla birlikte döndürür.

Dönen alanlar data — 18

idintKuyruk öğesinin kimliği.

channelstring`mail` ya da `sms`.

recipientstringAlıcının adresi ya da numarası.

recipient_ccstringNumaradan ayrı saklandığında SMS alıcısının ülke kodu (`90` → `+90 5551112233`). E-postada ve `+` önekini kendisi taşıyan numarada boştur.

recipient_namestringAlıcının adı.

subjectstringBildirimin konusu.

statusstring`pending` sırada, `processing` gönderiliyor, `sent` gitti, `failed` düştü, `cancelled` gönderilmeden durduruldu (sebebi işlem günlüğünde).

priorityintGönderim önceliği.

user_idintİlgili müşterinin kimliği.

user_full_namestring | nullMüşterinin adı.

attemptsintKaç kez denendiği.

max_attemptsintEn çok kaç kez deneneceği.

batch_idstring | nullToplu gönderim kimliği. Aynı gönderimden çıkan bildirimleri birbirine bağlar.

created_atstring | nullKuyruğa girdiği zaman.

scheduled_atstring | nullGönderilmesi planlanan zaman.

processed_atstring | nullİşlendiği zaman.

next_retrystring | nullBir sonraki denemenin zamanı.

process_logsarrayGönderim denemelerinin adım kaydı. Bir bildirimin neden gitmediği burada yazar.

Hatalar 3

invalid_id422Kimlik geçerli değil.

not_found404Kuyruk öğesi bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/tools/notification-queue/201' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/tools/notification-queue/201', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/notification-queue/201');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Detay bile mesaj govdesini TASIMAZ: gonderilmis bir metni gormek icin kayit defterine bakin.
$item = Api::Tools()->GetNotificationQueueItem(['id' => 201])['data'];
$why  = end($item['process_logs']);
```

### Öğeyi Yeniden Deneme

post/api/v1/admin/tools/notification-queue/{id}/retry

`Tools/RetryNotificationQueueItem` admin

Bir bildirimi tekrar gönderim sırasına alır.

Gövde —

——Gövde gerekmez. Bildirim, path parametresiyle belirlenir; boş gövde gönderin.

Dönen alanlar data

dataobjectBildirimin sıfırlama sonrası hâli. Öğe detayı ucuyla aynı şekildedir.

Hatalar 3

not_found404Kuyruk öğesi bulunamadı.

not_retryable422Yalnız düşmüş ya da bekleyen bildirimler yeniden denenebilir. Gitmiş bir bildirim buradan tekrar gönderilemez.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/tools/notification-queue/201/retry' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tools/notification-queue/201/retry', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/notification-queue/201/retry');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Yeniden deneme BEKLEYEN ogeleri de kabul eder; bu, sirasini one almanin yoludur.
Api::Tools()->RetryNotificationQueueItem(['id' => 201]);
```

### Öğeyi Hemen Gönderme

post/api/v1/admin/tools/notification-queue/{id}/run

`Tools/RunNotificationQueueItem` admin anında gider

Bildirimi arka planı beklemeden o anda gönderir ve sonucunu döndürür.

Gövde —

——Gövde gerekmez. Bildirim, path parametresiyle belirlenir; boş gövde gönderin.

Dönen alanlar data — 3

task_successboolGönderim başarılı oldu mu.

task_messagestringDüştüyse hata mesajı.

itemobjectBildirimin gönderim sonrası hâli.

Hatalar 3

not_found404Kuyruk öğesi bulunamadı.

not_pending422Yalnız sırada bekleyen bildirimler gönderilebilir. Düşmüş bir bildirimi önce yeniden denemeye almanız gerekir.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/tools/notification-queue/201/run' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tools/notification-queue/201/run', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/notification-queue/201/run');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Dusmus bir bildirim dogrudan gonderilemez: once yeniden denemeye alin, sonra calistirin.
Api::Tools()->RetryNotificationQueueItem(['id' => 201]);
$result = Api::Tools()->RunNotificationQueueItem(['id' => 201])['data'];

if (!$result['task_success']) {
    $why = $result['task_message'];
}
```

### Öğeyi Silme

delete/api/v1/admin/tools/notification-queue/{id}

`Tools/DeleteNotificationQueueItem` admin

Bir bildirimi kuyruktan çıkarır. Gönderilmemiş bildirim hiç gitmez.

Dönen alanlar data — 2

deletedboolSilme başarılı mı.

idintSilinen öğenin kimliği.

Hatalar 2

not_found404Kuyruk öğesi bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X DELETE 'https://panel.ornek.com/api/v1/admin/tools/notification-queue/201' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tools/notification-queue/201', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/notification-queue/201');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Gonderilmekte olan bir bildirim SILINEMEZ; islem bitene kadar bekleyin.
Api::Tools()->DeleteNotificationQueueItem(['id' => 201]);
```

### Toplu Silme

post/api/v1/admin/tools/notification-queue/bulk-delete

`Tools/BulkDeleteNotificationQueue` admin

Birden çok bildirimi kuyruktan çıkarır.

Gövde 1

idsint[]zorunluSilinecek bildirimlerin kimlikleri.

Dönen alanlar data — 2

deletedboolSilme çalıştı mı.

countintSilinen bildirim sayısı. Gönderilmekte olanlar atlandığı için gönderdiğinizden az olabilir.

Hatalar 2

ids_required422Hiç kimlik verilmedi.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/tools/notification-queue/bulk-delete' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"ids":[201,202]}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tools/notification-queue/bulk-delete', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ ids: [201, 202] }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/notification-queue/bulk-delete');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['ids' => [201, 202]]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Gonderilmekte olanlar sessizce atlanir: silinen sayiyi gonderdiginizle karsilastirin.
$ids      = [201, 202];
$response = Api::Tools()->BulkDeleteNotificationQueue(['ids' => $ids]);

$skipped = count($ids) - $response['data']['count'];
```

### Tüm Düşenleri Yeniden Deneme

post/api/v1/admin/tools/notification-queue/retry-all-failed

`Tools/RetryAllFailedNotificationQueue` admin kuyruğun tamamı

Kuyruktaki bütün düşmüş bildirimleri tekrar sıraya alır.

Gövde —

——Gövde gerekmez. İşlem kuyruğun tamamını kapsar ve daraltılamaz; boş gövde gönderin.

Dönen alanlar data — 1

retriedintTekrar sıraya alınan bildirim sayısı.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/tools/notification-queue/retry-all-failed' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tools/notification-queue/retry-all-failed', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/notification-queue/retry-all-failed');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Modul kuyrugunun aksine bu uc SAYIYI dondurur.
$count = Api::Tools()->RetryAllFailedNotificationQueue()['data']['retried'];
```

### Gönderilenleri Temizleme

post/api/v1/admin/tools/notification-queue/clear-sent

`Tools/ClearSentNotificationQueue` admin

Gönderilmiş bildirimleri kuyruktan siler.

Gövde —

——Gövde gerekmez. İşlem kuyruğun tamamını kapsar ve daraltılamaz; boş gövde gönderin.

Dönen alanlar data — 1

clearedboolTemizlik çalıştı mı.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/tools/notification-queue/clear-sent' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/tools/notification-queue/clear-sent', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/tools/notification-queue/clear-sent');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Kuyrugu temizlemek GONDERIM KAYDINI silmez: ne gonderildigi kayit defterinde durur.
Api::Tools()->ClearSentNotificationQueue();
```

## Tuzaklar

> **Mesajın kendisi hiçbir uçtan dönmez**
> 
> Kuyruk uçları konu, alıcı ve durumu verir; gövde şifreli saklanır ve **detayda bile** yer almaz. Bir müşteriye ne gönderildiğini görmek istiyorsanız kuyruğa değil, kayıt defterlerine bakmanız gerekir.

> **İki uç farklı durumları kabul eder**
> 
> Yeniden deneme hem düşmüş hem bekleyen bildirimleri alır; hemen gönderme ise **yalnız bekleyenleri**. Yani düşmüş bir bildirimi hemen göndermek isterseniz önce yeniden denemeye alıp sonra çalıştırmanız gerekir. Tek adım denemek `not_pending` ile döner.

> **Gönderilmekte olan öğe silinemez**
> 
> Şu an gönderilen bir bildirim silinemez ve toplu silmede **sessizce atlanır**. Gönderdiğiniz kimlik sayısıyla dönen sayının farkı, atlanan öğeleri gösterir; farkı kontrol etmezseniz sildiğinizi sandığınız bildirim yola çıkmış olabilir.

> **İki kuyruk toplu uçlarda ayrışır**
> 
> Bildirim kuyruğunda tüm düşenleri yeniden deneme ucu kaç bildirimin sıraya alındığını **döndürür**; modül kuyruğunun aynı ucu döndürmez. İki kuyruk için ortak bir yardımcı yazıyorsanız bu farkı gözetin.

> **Kuyruğu temizlemek gönderim kaydını silmez**
> 
> Gönderilenleri temizlemek yalnız kuyruk satırlarını kaldırır. Neyin gönderildiği kayıt defterlerinde durmaya devam eder, yani geçmişi kaybetmezsiniz. İki yeri karıştırmak, silinmemiş bir veriyi silinmiş sanmaya yol açar.

## İlgili Makaleler

- [Modül Kuyruğu](https://dev.wisecp.com/tr/modul-kuyrugu)
- [Kayıt Defterleri](https://dev.wisecp.com/tr/kayit-defterleri)
- [Toplu Bildirim](https://dev.wisecp.com/tr/toplu-bildirim)