> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flextell.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerçek Zamanlı Bildirimler API

> İstemcilerin (frontend / mobil) güvenli (private) bir WebSocket kanalına abone olabilmesi için gerekli yetkilendirme (handshake) endpoint'i.

**Base URL:** `/broadcasting/auth`

<Note>
  Bu API, istemcilerin **yeni bir kayıt oluşturması veya veri çekmesi için kullanılmaz**. Bu endpoint, istemcinin güvenli (private) bir WebSocket kanalına abone olabilmesi (`subscribe`) için gerekli olan yetkilendirme (handshake) işlemini yapar. İstemciler kanala bağlandıktan sonra sadece gelen olayları (`events`) **dinlerler**.
</Note>

## Endpoint özeti

| Metot  | Endpoint             | Açıklama                                                                | Gerekli Header  |
| ------ | -------------------- | ----------------------------------------------------------------------- | --------------- |
| `POST` | `/broadcasting/auth` | WebSocket kanalına abone olabilmek için yetkilendirme (handshake) yapar | `Authorization` |

## Broadcasting (soket) kavramı ve çalışma akışı

Sistemimizde, örneğin sohbetlere (`conversations`) yeni bir mesaj geldiğinde uygulamayı yenilemeden (refresh atmadan) mesajın ekrana düşmesi için **WebSocket** altyapısı kullanılır.

Güvenlik gereği, bir hastanın veya kliniğin mesajlarının başkaları tarafından dinlenmesini engellemek için tüm kanallar **Private (özel)** olarak yapılandırılmıştır.

İstemci tarafındaki genel akış:

<Steps>
  <Step title="Bearer token al">
    İstemci sisteme giriş yapar ve standart API Bearer Token'ını alır.
  </Step>

  <Step title="Kanalı belirt">
    İstemci (örn. Laravel Echo veya Pusher kütüphanesi) dinlemek istediği kanalı belirtir.
  </Step>

  <Step title="Otomatik yetkilendirme">
    Kütüphane arka planda otomatik olarak `POST /broadcasting/auth` endpoint'ine elindeki token ile istek atar.
  </Step>

  <Step title="Sunucu onayı">
    Sunucu kullanıcının bu kanalı dinlemeye yetkisi olup olmadığını kontrol eder. Yetkisi varsa soket bağlantısına onay verir.
  </Step>
</Steps>

## Dinlenebilir kanallar

Sistemde şu an için dışarıya açık ve dinlenebilir tek bir ana kanal yapısı bulunmaktadır.

| Kanal adı             | Açıklama                                                                             | Örnek                                               |
| --------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `chat-log.{tenantId}` | Belirtilen tenant'a (kliniğe) ait canlı sohbet loglarını ve yeni mesajları yayınlar. | `chat-log.5` (ID'si 5 olan tenant'ın sohbet kanalı) |

### Erişim kontrolü (katı iş kuralları)

* Bu kanala abone olmak isteyen kullanıcının **geçerli bir API token'ı** olmalıdır.
* Kullanıcının, kanal adında geçen `{tenantId}` numaralı tenant'a sistem üzerinden erişim yetkisi **olmak zorundadır**.

<Warning>
  Başka bir kliniğe (tenant'a) ait olan kanalı dinleme isteği reddedilir ve sunucu `403 Forbidden` hatası döner.
</Warning>

## Yetkilendirme endpoint'i kullanımı

```http theme={null}
POST /broadcasting/auth
```

<Note>
  Bu endpoint genellikle **manuel olarak çağrılmaz**; kullandığınız WebSocket istemci kütüphanesi (Pusher JS, Laravel Echo vb.) tarafından otomatik olarak tetiklenir.
</Note>

### Zorunlu header

<ParamField header="Authorization" type="string" required>
  `Bearer {access_token}` formatında geçerli bir access token.
</ParamField>

### Body

Kütüphanenin gönderdiği `channel_name` (örn. `private-chat-log.5`) ve `socket_id` bilgilerini içerir.

## İstemci (frontend / mobil) entegrasyon örneği

Bu API'yi kullanacak olan arayüz geliştiricisinin yapması gereken örnek konfigürasyon (JavaScript / Laravel Echo):

```javascript theme={null}
import Echo from 'laravel-echo';

// 1. WebSocket kütüphanesine, yetkilendirme için kullanılacak Token'ı verin
window.axios.defaults.headers.common['Authorization'] = `Bearer ${accessToken}`;

// 2. Echo nesnesini yapılandırın
const echo = new Echo({
  broadcaster: 'pusher', // veya projenizin kullandığı sağlayıcı
  key: 'your-socket-key',
  cluster: 'your-cluster',
  authEndpoint: '/broadcasting/auth' // Auth endpoint'inin adresi
});

const tenantId = 5; // Kullanıcının aktif çalıştığı tenant ID'si

// 3. Kanala abone olun ve olayları dinlemeye başlayın
echo.private(`chat-log.${tenantId}`)
   .listen('.NewChatMessageEvent', (eventPayload) => {
       console.log('Yeni mesaj geldi!', eventPayload);
       // Arayüzdeki sohbet kutusuna yeni mesajı ekle...
   });
```

<Tip>
  Dinlenecek tam olay (event) adları uygulamanızın yayınladığı isimlere göre `.NewChatMessageEvent` veya benzeri bir formatta olacaktır.
</Tip>

## Yetkilendirme ve kısıtlamalar özeti

| Konu                        | Kural                                                                                                    |
| --------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Token zorunluluğu**       | Standart `auth:api` kuralları geçerlidir.                                                                |
| **Multi-tenant izolasyonu** | Soket kanalları da REST API'ler gibi katı bir tenant izolasyonuna tabidir.                               |
| **Yön**                     | Tek yönlüdür (Server → Client). API tüketicisi WebSocket kanalı üzerinden sunucuya mesaj **gönderemez**. |

<Note>
  Mesaj göndermek için **REST endpoint**'i kullanılmalıdır: `POST /conversations/{id}/messages`. WebSocket kanalı sadece gelen olayları dinlemek (`subscribe`) içindir.
</Note>