Giriş

Matriks’in finansal veri yayın ağı olan Analist Servisleri Doküman Portalı’na hoş geldiniz.

Bu dokümanda, Matriks Analist altyapısında sunulan tüm veri setlerine ait REST ve MQTT servislerinin kullanım detayları yer almaktadır. Amacımız, bu servislerle sağlıklı bağlantılar kurarak veri alım sürecinizi doğru ve güvenilir şekilde gerçekleştirebilmeniz için yol göstermektir.

JWT Token Kullanımı

Tüm Analist servislerine erişim, JWT token aracılığıyla sağlanır. İlgili token, tarafınıza iletilen CRM servisleri üzerinden temin edilebilir veya test süreçlerinde kullanmak üzere sabit bir token kullanılabilir. Token kullanımı aşağıdaki şekilde olmalıdır.

Headers

Key	Value
Authorization	jwt (token)

REST ve MQTT servislerine yapılan bağlantılar sonrasında karşılaşılabilecek olası durum kodları aşağıdaki gibidir:

HTTP Codes

HTTP Code	Description
200	İşlem başarılı
400	Geçersiz istek (Bad Request)
401	Yetkisiz erişim (Unauthorized) – JWT token geçersiz veya eksik
404	Bulunamadı (Not Found)
500	Sunucu hatası (Internal Server Error)
503	Servis kullanılamıyor (Service Unavailable)
504	İstek Zaman Aşımı (Request Time-out)

MQTT Codes

Code	Description
0	Başarılı (Connection Accepted / Publish Success)
1	Hatalı protokol sürümü (Unacceptable Protocol Version)
2	Yetkisiz erişim (Identifier Rejected)
3	Sunucu mevcut değil (Server Unavailable)
4	Kullanıcı adı veya şifre hatalı (Bad User Name or Password)
5	Yetki yok (Not Authorized)
128+	Yayın / Subscribe hataları (Application-specific)

MQTT Veri Akış

Bu akış, finansal sembol verilerine MQTT protokolü üzerinden erişim sağlama sürecini detaylandırmaktadır. Örnek olarak USDTRY sembolü kullanılmıştır.

1. Token Oluşturma → CRM Servisi
2. Endpoint Belirleme → Discovery Servisi
3. Meta Verilerin Oluşturulması → Meta Veriler
4. Topic Belirleme → Topach Servisi
5. Bağlantı Kurma → MQTT Connection ve Topic Subscription
6. Veri Akışı → Protobuf ile Mesaj Çözümleme

1. Kimlik Doğrulama

CRM servisinden alınan bilgiler kullanılarak authentication token oluşturulur.

2. Servis Keşfi (Discovery)

Disco servisine public erişim sağlanır (token gerektirmez) ve aşağıdaki endpoint bilgileri alınır:

• Symbols Servisi (https://analistdocs.matriksdata.com/Meta%20Veriler/Meta-Veriler#symbols)
• Topach Servisi (https://analistdocs.matriksdata.com/Topach)

Örnek Disco Servisi Yanıtı:

{
  "metaDataV4": {
    "symbols": {
      "url": "https://apitest.matriksdata.com/dumrul/v4/meta/symbols",
      "parameters": [
        "marketCode",
        "exchangeId", 
        "modifiedAt",
        "deleted",
        "allSymbols"
      ],
      "gzAvailable": true
    },
    "topach": {
      "url": "https://apitest.matriksdata.com/dumrul/v2/topach",
      "parameters": [],
      "gzAvailable": true
    }
  }
}

3. Meta ve Topach Alma

Oluşturulan token ve disco servisinden alınan adres bilgileri kullanılarak: Symbols Servisi: Sembol bilgileri alınır. Topach Servisi: Connect olunacak adres bilgisi için prefix, subscribe olunacak topic için topic bilgisi alınır.

4. Sembol Bilgileri

Symbols servisinden hedef sembol için gerekli bilgiler alınır:

{
  "sC": "USDTRY",    // symbolCode
  "sT": "X"          // symbolType
}

5. Topach Kullanımı

Topach servisinden symbolType ("X") bazında MQTT bağlantı bilgileri alınır. QoS değerine göre uygun endpoint seçimi yapılmalıdır (rt: real-time, dl: delayed). Kullanıcı lisansına göre bu bilgi dinamik olarak servisten dönmektedir.

{
  "topic": "mx/symbol/%s@lvl2",
  "qos": "rt",
  "prefix": "mx/symbol"
}

6. Bağlantı Endpoint'leri

Disco servisinden prefix ("mx/symbol") için kullanılabilir bağlantı adresleri alınır:

{
  "mx/symbol": {
    "qos": {
      "dl": "wss://dltest.radix.matriksdata.com:443/market",
      "rt": "wss://rttest.radix.matriksdata.com/market",
      "ws": {
        "dl": "ws://dltest.radix.matriksdata.com/market",
        "rt": "ws://rttest.radix.matriksdata.com/market"
      },
      "wss": {
        "dl": "wss://dltest.radix.matriksdata.com:443/market",
        "rt": "wss://rttest.radix.matriksdata.com/market"
      },
      "tcp": {
        "dl": "tcp://dltest.radix.matriksdata.com",
        "rt": "tcp://rttest.radix.matriksdata.com"
      }
    }
  }
}

7. MQTT Bağlantısı ve Subscription

QoS bilgisine göre uygun protokol seçilir. Örnek TCP bağlantısı: Bağlantı: tcp://rttest.radix.matriksdata.com
Subscription: mx/symbol/USDTRY@lvl2

8. Veri Akışı ve Mesaj İşleme

Bağlantı kurulduktan sonra veri akışı başlar. Gelen mesajlar ilgili protobuf şeması kullanılarak çözümlenir. Bağlantı kurulacak yayın adresleri için proto dosyaları tarafınıza iletilmektedir. mx/symbol prefix'i için: Symbol.proto mx/derivative prefix'i için: Derivative.proto