Hisse Tarama

Anlık Tarama

Description

Hisselerin temel ve market verilerine göre anlık tarama yapar. Tarama sonucunda eşleşen semboller ve condition'daki metriklerin anlık değerleri döner. Bu endpoint kayıt oluşturmaz — sadece tarama çalıştırır.

Endpoint

HTTP POST Endpoint https://apitest.matriksdata.com/dumrul/v1/stock-explorer

Request Body Parameters

Parameter	Type	Required	Description
condition	string	true	Taramanın koşulları. Metrik key'leri kullanılır (ör: last_price>50&&daily_volume>10000000).
symbol_group	string	true	Taramanın çalıştırılacağı hisse grubu.

Sample Request-Response

Request Body:

{
    "symbol_group": "XU100",
    "condition": "last_price>50&&daily_volume>10000000"
}

Response:

{
    "symbol_group": "XU100",
    "condition": "last_price>50&&daily_volume>10000000",
    "symbols": [
        { "code": "GARAN", "last_price": 52.4, "daily_volume": 12500000 },
        { "code": "AKBNK", "last_price": 61.8, "daily_volume": 18200000 },
        { "code": "THYAO", "last_price": 310.5, "daily_volume": 45200000 }
    ]
}

Not: symbol_group ve condition request'ten olduğu gibi response'a yansıtılır. symbols dizisindeki her öğede code alanı ve condition'da kullanılan metrik key'lerinin hesaplanmış değerleri yer alır.

---

Tarama Kaydetme

Description

Tarama kriterlerini kaydeder. UUID ile benzersiz id üretir. Tarama çalıştırmaz, sonuç döndürmez. Kullanıcı başına en fazla 5 tarama kaydedilebilir. Kaydedilen taramalardan en fazla 5 tanesi periyodik olarak çalıştırılabilir.

Endpoint

HTTP POST Endpoint https://apitest.matriksdata.com/dumrul/v1/stock-explorer/save

Request Body Parameters

Parameter	Type	Required	Description
name	string	true	Taramanın ismi.
condition	string	true	Taramanın koşulları. Metrik key'leri kullanılır.
symbol_group	string	true	Taramanın çalıştırılacağı hisse grubu.
periodic_explorer	object	false	Periyodik tarama ayarları. Gönderilmezse periyodik tarama pasif olur.
periodic_explorer.period	string	conditional	Taramanın ne sıklıkla çalışacağı. 5min, 30min, 60min, 240min, 1day verilebilir. periodic_explorer gönderiliyorsa zorunlu.
periodic_explorer.explore_until	double	conditional	Taramanın hangi zamana kadar çalışacağı (epoch ms). Gelecekte bir zaman olmalı, en fazla 90 gün sonrasına kadar verilebilir. periodic_explorer gönderiliyorsa zorunlu.
periodic_explorer.email	string	conditional	Tarama sonucunda değişiklik olduğunda mail gönderilir. push veya email'den en az biri dolu olmalı.
periodic_explorer.push	boolean	conditional	Tarama sonucunda değişiklik olduğunda push bildirim gönderilir. push veya email'den en az biri dolu olmalı.

Sample Request-Response

Request Body:

{
    "name": "BIST100 Filtre",
    "symbol_group": "XU100",
    "condition": "last_price>50&&daily_volume>10000000",
    "periodic_explorer": {
        "period": "60min",
        "explore_until": 1780000000000,
        "push": true,
        "email": "user@matriksdata.com"
    }
}

Response:

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "BIST100 Filtre",
    "symbol_group": "XU100",
    "condition": "last_price>50&&daily_volume>10000000",
    "created_at": 1780000001234,
    "periodic_explorer": {
        "period": "60min",
        "explore_until": 1780000000000,
        "push": true,
        "email": "user@matriksdata.com"
    }
}

Periyodik tarama olmadan kayıt (pasif kayıt):

{
    "name": "Sadece Kayıt",
    "symbol_group": "XU100",
    "condition": "last_price>100"
}

Response:

{
    "id": "661f8500-a39c-42e5-b827-557766551111",
    "name": "Sadece Kayıt",
    "symbol_group": "XU100",
    "condition": "last_price>100",
    "created_at": 1780000005678
}

Not: Response'ta symbols alanı dönmez — kayıt sırasında tarama çalıştırılmaz. id alanı UUID v4 formatındadır.

---

Tarama Güncelleme

Description

Kayıtlı taramayı günceller. Full replace semantiği ile çalışır — gönderilmeyen her alan silinmiş kabul edilir. Tarama çalıştırmaz, sonuç döndürmez. Client kaydı önce GET ile çekip, kullanıcıya gösterip, düzenlenmiş haliyle komple göndermelidir.

Endpoint

HTTP PUT Endpoint https://apitest.matriksdata.com/dumrul/v1/stock-explorer/save

Query Parameters

Parameter	Type	Required	Description
id	string	true	Güncellenecek kaydın UUID'si.

Request Body Parameters

Parameter	Type	Required	Description
name	string	true	Taramanın ismi.
condition	string	true	Taramanın koşulları.
symbol_group	string	true	Hisse grubu.
periodic_explorer	object	false	Gönderilmezse periyodik tarama pasife alınır (null yazılır).
periodic_explorer.period	string	conditional	Periyod. periodic_explorer gönderiliyorsa zorunlu.
periodic_explorer.explore_until	double	conditional	Bitiş zamanı (epoch ms). Gelecekte bir zaman olmalı, en fazla 90 gün sonrasına kadar verilebilir. periodic_explorer gönderiliyorsa zorunlu.
periodic_explorer.email	string	conditional	Mail bildirimi. push veya email'den en az biri dolu olmalı.
periodic_explorer.push	boolean	conditional	Push bildirimi. push veya email'den en az biri dolu olmalı.

Sample Request-Response

Senaryo A: Periyodik taramayı güncelle (email kapat, push kalsın) PUT /save?id=550e8400-e29b-41d4-a716-446655440000

Request Body:

{
    "name": "BIST100 Filtre",
    "condition": "last_price>60&&daily_volume>15000000",
    "symbol_group": "XU100",
    "periodic_explorer": {
        "period": "60min",
        "explore_until": 1780000000000,
        "push": true
    }
}

Response:

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "BIST100 Filtre",
    "symbol_group": "XU100",
    "condition": "last_price>60&&daily_volume>15000000",
    "created_at": 1780000001234,
    "updated_at": 1780001009999,
    "periodic_explorer": {
        "period": "60min",
        "explore_until": 1780000000000,
        "push": true
    }
}

Senaryo B: Periyodik taramayı tamamen kapat

{
    "name": "BIST100 Filtre",
    "condition": "last_price>60&&daily_volume>15000000",
    "symbol_group": "XU100"
}

Not: periodic_explorer gönderilmezse Cassandra'ya null yazılır, periyodik tarama pasife alınır. Response'ta symbols alanı dönmez.

---

Kayıtlı Taramalar

Description

Kullanıcının kayıtlı taramalarının listesini döner. Sadece metadata döner, tarama çalıştırmaz.

Endpoint

HTTP GET Endpoint https://apitest.matriksdata.com/dumrul/v1/stock-explorer

Sample Request-Response

https://apitest.matriksdata.com/dumrul/v1/stock-explorer

[
    {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "BIST100 Filtre",
        "symbol_group": "XU100",
        "condition": "last_price>50&&daily_volume>10000000",
        "created_at": 1780000001234,
        "periodic_explorer": {
            "period": "60min",
            "explore_until": 1780000000000,
            "push": true,
            "email": "user@matriksdata.com"
        }
    },
    {
        "id": "661f8500-a39c-42e5-b827-557766551111",
        "name": "Düşük PD/DD",
        "symbol_group": "XU100",
        "condition": "pd_dd<10&&roe>20",
        "created_at": 1780000005678
    }
]

Not: Liste response'unda symbols alanı yer almaz (metadata only). periodic_explorer null veya undefined ise periyodik tarama pasiftir.

---

Kayıtlı Tarama Detayı + Anlık Tarama

Description

Belirli bir kaydın detayını döner ve anlık tarama (fresh scan) çalıştırır. Condition'daki metriklerin hesaplanmış değerleri symbols dizisinde yer alır.

Endpoint

HTTP GET Endpoint https://apitest.matriksdata.com/dumrul/v1/stock-explorer

Query Parameters

Parameter	Type	Required	Description
id	string	true	Kaydın UUID'si.

Sample Request-Response

https://apitest.matriksdata.com/dumrul/v1/stock-explorer?id=550e8400-e29b-41d4-a716-446655440000

Response:

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "BIST100 Filtre",
    "symbol_group": "XU100",
    "condition": "last_price>50&&daily_volume>10000000",
    "created_at": 1780000001234,
    "updated_at": 1780001009999,
    "symbols": [
        { "code": "GARAN", "last_price": 52.4, "daily_volume": 12500000 },
        { "code": "AKBNK", "last_price": 61.8, "daily_volume": 18200000 }
    ],
    "periodic_explorer": {
        "period": "60min",
        "explore_until": 1780000000000,
        "push": true,
        "email": "user@matriksdata.com"
    }
}

Not: Fresh scan sonucu yalnızca response'a eklenir, Cassandra'ya kaydedilmez.

---

Tarama Silme

Description

Kaydedilmiş taramalar silinir. Silinen taramalar geri alınamaz. Silme işlemi yapıldığında elde kalan kayıtlı taramalar response olarak döner.

Endpoint

HTTP DELETE Endpoint https://apitest.matriksdata.com/dumrul/v1/stock-explorer

Query Parameters

Parameter	Type	Required	Description
id	string	true	Silinecek taramanın UUID'si.

Sample Request-Response

https://apitest.matriksdata.com/dumrul/v1/stock-explorer?id=550e8400-e29b-41d4-a716-446655440000

Response: (kalan kayıtların listesi)

[
    {
        "id": "661f8500-a39c-42e5-b827-557766551111",
        "name": "Düşük PD/DD",
        "symbol_group": "XU100",
        "condition": "pd_dd<10&&roe>20",
        "created_at": 1780000005678
    }
]

---

Response Alanları

Endpoint'lerin response'unda dönebilecek tüm alanların açıklamaları. Hangi alanların döneceği çağrılan endpoint'e göre değişir (ör. symbols yalnızca tarama çalıştıran endpoint'lerde döner, updated_at yalnızca güncelleme sonrası döner). Zaman alanları Unix epoch, milisaniye cinsindendir (ör. 1780000001234).

Üst Seviye Alanlar

Alan (Key)	Tip	Açıklama
id	string	Kaydın benzersiz kimliği (UUID v4). Kayıt oluşturma, güncelleme, liste, detay ve silme response'larında döner. Anlık taramada (POST /stock-explorer) dönmez.
name	string	Taramaya kullanıcının verdiği isim.
symbol_group	string	Taramanın çalıştırıldığı hisse grubu. Request'ten olduğu gibi response'a yansıtılır.
condition	string	Taramanın filtre koşulu. Request'ten olduğu gibi response'a yansıtılır.
created_at	number (epoch ms)	Kaydın ilk oluşturulma zamanı.
updated_at	number (epoch ms)	Kaydın son güncellenme zamanı. Yalnızca güncelleme (PUT) sonrası dönen kayıtlarda bulunur; ilk oluşturmada dönmez.
symbols	array	Condition ile eşleşen hisselerin listesi. Yalnızca tarama çalıştıran endpoint'lerde (anlık tarama ve detay + fresh scan) döner; kayıt / güncelleme / liste response'larında bulunmaz.
periodic_explorer	object	Periyodik tarama ayarları. null veya alan yoksa periyodik tarama pasiftir.

symbols Dizisi Öğeleri

Alan (Key)	Tip	Açıklama
code	string	Eşleşen hissenin sembol kodu (ör. GARAN, AKBNK, THYAO).
<metrik_key>	number	Condition'da kullanılan her metrik key'inin o hisse için hesaplanmış anlık değeri (ör. last_price, daily_volume). Buradaki alan adları sabit değildir — condition'da hangi metrikler kullanıldıysa yalnızca onlar döner. Tüm metrik key'lerinin listesi ve formülleri için aşağıdaki "condition Sözdizimi → Metrik Key'leri" bölümüne bakınız.

periodic_explorer Nesnesi Alanları

Alan (Key)	Tip	Açıklama
period	string	Periyodik taramanın çalışma sıklığı: 5min, 30min, 60min, 240min veya 1day.
explore_until	number (epoch ms)	Periyodik taramanın çalışacağı son zaman. Bu zamandan sonra tarama atlanır.
push	boolean	true ise, tarama sonucunda değişiklik olduğunda push bildirimi gönderilir.
email	string	Doluysa, tarama sonucunda değişiklik olduğunda bu adrese mail gönderilir.

---

symbol_group Tipleri

indexes: XUTUM, XU100, XU050, XU030, XBANK, XKTUM
markets: Z (yıldız pazar), N (ana pazar), T (alt pazar), S (piyasa öncesi), W (yakın izleme)
sektörler: sektör kodları (endeks ağırlık dosyasından yüklenir)

---

condition Sözdizimi

condition alanı sunucu tarafında tanımlı metrik key'lerini kullanır. Operatörler ve 4 işlem desteklenir.

Operatörler

"<": küçüktür
">": büyüktür
"==": eşittir
"<=": küçük eşittir
">=": büyük eşittir
"||": veya
"&&": ve
"()": parantez
"+ - * /": dört işlem

Metrik Key'leri

Fiyat ve Piyasa Verileri

Key	Açıklama	Formül	Birim
market_value	Piyasa Değeri	marketValue	TL
capital	Sermaye	capital	TL
equity	Özsermaye	equity	TL
circulation_share_per	Dolaşımdaki Pay Oranı	circulationSharePer	%
circulation_share	Dolaşımdaki Pay Miktarı	circulationShare	—
last_price	Son Fiyat	last	TL

Değişim Metrikleri

Key	Açıklama	Formül	Birim
daily_change	Günlük Değişim	(last/dayClose-1)*100	%
weekly_change	Haftalık Değişim	(last/weekClose-1)*100	%
monthly_change	Aylık Değişim	(last/monthClose-1)*100	%
three_month_change	3 Aylık Değişim	(last/threeMonthClose-1)*100	%
six_month_change	6 Aylık Değişim	(last/sixMonthClose-1)*100	%
yearly_change	Yıllık Değişim	(last/yearClose-1)*100	%
ytd_change	Yılbaşından Değişim	(last/prevYearClose-1)*100	%

Hacim ve Volatilite

Key	Açıklama	Formül	Birim
daily_volume	Günlük İşlem Hacmi	dailyVolume	TL
daily_quantity	Günlük İşlem Adedi	dailyQuantity	—
intraday_volatility	Gün İçi Volatilite	(dailyHigh-dailyLow)/dayClose*100	%
spread_percentage	Spread %	((ask-bid)/bid)*100	%
daily_turnover_rate	Günlük Devir Hızı	(dailyQuantity/circulationShare)*100	%

52 Hafta ve Ortalama Uzaklıkları

Key	Açıklama	Formül	Birim
week_52_high_distance	52 Hafta Yüksek Uzaklığı	(last/yearHigh-1)*100	%
week_52_low_distance	52 Hafta Düşük Uzaklığı	(last/yearLow-1)*100	%
daily_average_distance	Günlük Ortalamaya Uzaklık	(last/priceMean-1)*100	%

Temel Analiz Çarpanları

Key	Açıklama	Formül	Birim
pd_dd	PD/DD	marketValue/netProceeds	—
fk_dd	FK/DD	marketValue/equity	—
pd_favok	PD/FAVÖK	marketValue/shiftedEbitda	—
fd_hasilat	FD/Hasılat	marketValue/shiftedReturn	—

Finansal Veriler

Key	Açıklama	Formül	Birim
net_proceeds	Net Kar	netProceeds	TL
revenue	Hasılat	return	TL
ebitda	FAVÖK	ebitda	TL
shifted_net_proceeds	Kaydırılmış Net Kar	shiftedNetProceeds	TL
shifted_return	Kaydırılmış Hasılat	shiftedReturn	TL
shifted_ebitda	Kaydırılmış FAVÖK	shiftedEbitda	TL

Hisse Bazlı ve Borçluluk

Key	Açıklama	Formül	Birim
eps	Hisse Başı Kazanç	netProceeds/circulationShare	TL
equity_per_share	Hisse Başı Özsermaye	equity/circulationShare	TL
net_debt	Net Borç	netDebt	TL
net_debt_ebitda	Net Borç/FAVÖK	netDebt/shiftedEbitda	—
debt_equity	Borç/Özsermaye	netDebt/equity	—
cash_ratio	Nakit Oranı	cashRatio	—

Getiri ve Karlılık

Key	Açıklama	Formül	Birim
dividend_yield	Temettü Verimi	cashNetDividend/last*100	%
roe	ROE	(netProceeds/equity)*100	%
net_profit_margin	Net Kar Marjı	(netProceeds/shiftedReturn)*100	%
ebitda_margin	FAVÖK Marjı	(shiftedEbitda/shiftedReturn)*100	%
earnings_yield	Kazanç Verimi	(netProceeds/marketValue)*100	%

Emir Defteri ve Limit Verileri

Key	Açıklama	Formül	Birim
bid_size	Alış Adedi	bidSize	—
ask_size	Satış Adedi	askSize	—
open_price	Açılış Fiyatı	open	TL
daily_low	Günlük En Düşük	dailyLow	TL
daily_high	Günlük En Yüksek	dailyHigh	TL
limit_up	Tavan Fiyat	limitUp	TL
limit_down	Taban Fiyat	limitDown	TL
distance_to_limit_up	Tavana Uzaklık	(limitUp-last)/last*100	%
distance_to_limit_down	Tabana Uzaklık	(last-limitDown)/last*100	%

Condition Örnekleri

"last_price>50&&daily_volume>10000000"         → Son fiyatı 50 TL üstü ve günlük hacmi 10M üstü
"pd_dd<15&&fk_dd<3"                            → PD/DD 15 altı ve FK/DD 3 altı
"roe>20&&net_profit_margin>10"                 → ROE %20 üstü ve net kar marjı %10 üstü
"dividend_yield>5&&debt_equity<1"              → Temettü verimi %5 üstü ve borç/özsermaye 1 altı
"distance_to_limit_up<3||distance_to_limit_down<3" → Tavana veya tabana %3'ten yakın
"last_price>10&&daily_volume>5000000&&pd_dd<20&&roe>15&&dividend_yield>3" → Çoklu filtre

---

Hata Kodları

HTTP	Kod	Durum
400	INVALID_ERROR	Geçersiz parametre, bilinmeyen metrik key, geçersiz condition, geçersiz symbol_group, eksik zorunlu alan, geçersiz period, explore_until geçmişte
401	EACCES	Yetkilendirme hatası — geçersiz veya eksik token, lisans yetersiz
404	NOT_FOUND	Kayıt bulunamadı (GET /?id, PUT /save?id, DELETE /?id)

---

Endpoint Özet Tablosu

Metod	Endpoint	Açıklama	Tarama Çalıştırır	Kayıt Yapar
POST	/stock-explorer	Anlık tarama	✅	❌
POST	/stock-explorer/save	Yeni kayıt oluştur	❌	✅
PUT	/stock-explorer/save?id=uuid	Kayıt güncelle	❌	✅
GET	/stock-explorer	Kayıtlı tarama listesi	❌	❌
GET	/stock-explorer?id=uuid	Kayıt detayı + fresh scan	✅	❌
DELETE	/stock-explorer?id=uuid	Kayıt sil	❌	❌

---

Periyodik Tarama Davranışı

Periyodik tarama periodic_explorer nesnesinin varlığına göre belirlenir:

• periodic_explorer doluysa → Periyodik tarama aktif. processJob belirtilen period aralığında taramayı çalıştırır.
• periodic_explorer null/yoksa → Periyodik tarama pasif. processJob bu kaydı atlar.
• İlk tarama → Baseline oluşturulur, bildirim gönderilmez.
• Sonraki taramalar → Hash karşılaştırılır, değişiklik varsa bildirim gönderilir (email ve/veya push).
• explore_until süresi dolmuşsa → processJob bu kaydı atlar.

Bildirim Kanalları

• email: periodic_explorer.email doluysa, değişiklik tespit edildiğinde mail gönderilir.
• push: periodic_explorer.push = true ise, değişiklik tespit edildiğinde push bildirim gönderilir (Redis PubSub → stock-notification kanalı).