Temettüler

BIST hisseleri ve ABD'de işlem gören enstrümanlar için nakit temettüler — tek bir sembolün geçmişi ya da bütün bir piyasanın bir tarih aralığındaki temettüleri (temettü kesim takvimi, geçen çeyreğin tüm ödemeleri); sembol başına bir çağrı yerine tek çağrıda.

Uç noktalar

Uç nokta	Kapsam	Açıklama
GET/v1/dividends?market=bist\|us&from=&to=&date_field=&status=&symbols=&limit=&cursor=	history	Bir piyasanın bir tarih aralığındaki temettüleri, eskiden yeniye, sayfalı — toplu liste
GET/v1/stocks/bist:{SYM}/dividends?limit=	history	Bir BIST hissesinin temettü geçmişi, en yeni önce (limit varsayılan 50, en çok 200)
GET/v1/stocks/us:{SYM}/dividends?limit=	history	Bir ABD enstrümanının temettü geçmişi, en yeni önce (limit varsayılan 50, en çok 200)

Deneme Alanı'nda deneyin →

Sembol bazında mı, toplu mu?

Tek bir enstrümanın tüm geçmişi gerekiyorsa /v1/stocks/{id}/dividends kullanın. Soru bir piyasa genelinde bir tarih aralığıyla ilgiliyse /v1/dividends kullanın: bu ay hangi hisselerin hak kullanım tarihi var, 100 sembole kadar bir izleme listesi için yaklaşan ödemeler takvimi, 3. çeyrekteki tüm BIST ödemeleri. İkisi de aynı satır biçimini döndürür; toplu satırlara instrument_id eklenir.

Kapsam: market=bist yalnızca Borsa İstanbul hisselerini listeler — BYF'lerin (ETF) temettü satırı yoktur. market=us, PortGate ABD kataloğundaki enstrümanları (hisseler, ETF'ler ve ADR'ler) listeler.

Sorgu parametreleri (/v1/dividends)

Alan	Tür	Notlar
market	bist \| us	Zorunlu. bist ya da us — her çağrıda tek piyasa.
from	date (YYYY-MM-DD)	Pencere başlangıcı, YYYY-MM-DD, dahil; date_field'a uygulanır. Varsayılan: bugün − 30 gün. Yalnızca to verilirse: to − 120 gün.
to	date (YYYY-MM-DD)	Pencere sonu, YYYY-MM-DD, dahil. Varsayılan: bugün + 90 gün. Yalnızca from verilirse: from + 120 gün. Pencere en fazla 366 gün olabilir (daha genişi → 422); from, to'dan sonraysa → 422.
date_field	ex \| pay	Pencerenin, status'ün ve sıralamanın hangi tarihe göre çalışacağı: ex = hak kullanım tarihi (temettüyü almak için hisseye bu günden önce sahip olun), pay = ödeme tarihi. Varsayılan ex.
status	paid \| upcoming	İsteğe bağlı, tarihe dayalı: upcoming = date_field bugün ya da sonrası, paid = bugünden önce; bugün, piyasanın kendi saat diliminde (bist için Europe/Istanbul, us için America/New_York). Pencereyi daraltır, asla genişletmez — ve satırın kendi status alanı değildir.
symbols	string (≤100, comma)	İsteğe bağlı, virgülle ayrılmış filtre, en çok 100: bu piyasanın kanonik kimlikleri (bist:THYAO) ya da yalın semboller (THYAO). Piyasanın temettüye uygun bir enstrümanı olmayan girdiler (bilinmeyen ya da bir BIST BYF'si) çağrıyı düşürmez, not_found içinde döner.
limit	int 1–1000	Sayfa başına satır, 1–1000. Varsayılan 100.
cursor	string	Önceki sayfanın next_cursor değeri. Opaktır — olduğu gibi geri gönderin.

Bilinmeyen sorgu parametreleri, kabul edilenleri listeleyen bir 400'dür (sık yapılan hatalara ipucu verilir: symbol → symbols kullanın, date → from/to kullanın, type → date_field kullanın).

Pencere, sıralama ve sayfalar

Satırlar date_field'a, ardından instrument_id'ye göre artan sıradadır — en eski önce; en-yeni-önce bir görünüm için sayfaları dolaşıp ters çevirin. Seçilen tarihi olmayan bir satır o date_field için listelenmez (birkaç ABD satırının henüz ödeme tarihi yoktur; bunlar yalnızca date_field=ex ile görünür). Yanıt etkin filtreyi geri yansıtır — market, date_field, from, to (varsayılanlar doldurulmuş) ve status — böylece ne aldığınızı her zaman bilirsiniz.

count bu sayfadaki satır sayısı, total ise filtreye uyan tüm sayfalardaki satır sayısıdır. next_cursor null olmadığı sürece aynı isteği cursor=next_cursor ile tekrarlayın. Bir cursor, kendi market ve date_field değerine bağlıdır: onu farklı bir değerle yeniden kullanmak (ya da bozuk bir cursor göndermek) 400 invalid cursor'dır.

Ardışık sayfalar, veriyi birbirinden bağımsız yeniden yükleyen farklı API süreçlerinden yanıtlanabilir; bu yüzden tek bir dolaşımın sayfaları arasında total ve as_of biraz farklı olabilir. Cursor ise hiçbir satırı atlamaz ya da tekrarlamaz — total kadar satır toplayana kadar değil, next_cursor null olana kadar döngüye devam edin.

Örnek — Eylül–Ekim BIST hak kullanım tarihleri

Beş BIST hissesi, 2026-09-01 ile 2026-10-31 arasındaki hak kullanım tarihleri; dolaşım görünsün diye sayfa başına üç satır. Bütün piyasa için symbols'ü kaldırın.

scope: history

curl -H "X-API-Key: $PORTGATE_KEY" \
  "https://api.theportfoy.com/portgate/v1/dividends?market=bist&from=2026-09-01&to=2026-10-31&symbols=TBORG,TUPRS,ASTOR,EBEBK,MCARD&limit=3"

yanıt — 1. sayfa

{
  "market": "bist",
  "date_field": "ex",
  "from": "2026-09-01",
  "to": "2026-10-31",
  "status": null,
  "dividends": [
    {"instrument_id": "bist:TBORG",
     "declaration_date": null, "ex_dividend_date": "2026-09-02", "pay_date": "2026-09-04",
     "cash_amount": "8.09", "gross_amount": "9.52", "currency": "TRY",
     "frequency": null, "distribution_type": null, "yield_pct": "7.53",
     "installment": "Peşin", "status": "paid", "finalized": true,
     "note": "Genel Kurul Tarafından Onaylandı."},
    {"instrument_id": "bist:TUPRS",
     "declaration_date": null, "ex_dividend_date": "2026-09-30", "pay_date": "2026-10-02",
     "cash_amount": "5.73", "gross_amount": "6.75", "currency": "TRY",
     "frequency": 2, "distribution_type": null, "yield_pct": "1.79",
     "installment": "2/2", "status": "paid", "finalized": true,
     "note": "Genel Kurul Tarafından Onaylandı."},
    {"instrument_id": "bist:ASTOR",
     "declaration_date": null, "ex_dividend_date": "2026-10-15", "pay_date": "2026-10-19",
     "cash_amount": "1.86", "gross_amount": "2.19", "currency": "TRY",
     "frequency": null, "distribution_type": null, "yield_pct": null,
     "installment": "Peşin", "status": "pending", "finalized": true,
     "note": "Genel Kurul Tarafından Onaylandı."}
  ],
  "count": 3,
  "total": 5,
  "next_cursor": "WyJiaXN0IiwiZXgiLCIyMDI2LTEwLTE1IiwiYmlzdDpBU1RPUiIsIjIwMjYtMTAtMTkiLCIyMDI2LTEwLTE1Il0",
  "not_found": [],
  "as_of": "2026-10-04T08:00:02.257000Z",
  "refreshed_at": "2026-10-04T08:41:10.120000Z"
}

2. sayfa aynı istek artı cursor'dır; next_cursor null olduğu için dolaşım biter:

curl — page 2

curl -H "X-API-Key: $PORTGATE_KEY" \
  "https://api.theportfoy.com/portgate/v1/dividends?market=bist&from=2026-09-01&to=2026-10-31&symbols=TBORG,TUPRS,ASTOR,EBEBK,MCARD&limit=3&cursor=WyJiaXN0IiwiZXgiLCIyMDI2LTEwLTE1IiwiYmlzdDpBU1RPUiIsIjIwMjYtMTAtMTkiLCIyMDI2LTEwLTE1Il0"

response — page 2 (abridged)

{
  "market": "bist", "date_field": "ex", "from": "2026-09-01", "to": "2026-10-31", "status": null,
  "dividends": [
    {"instrument_id": "bist:EBEBK", "ex_dividend_date": "2026-10-15", "pay_date": "2026-10-19",
     "cash_amount": "0.53", "gross_amount": "0.62", "frequency": 2, "installment": "1/2",
     "status": "pending", "finalized": true, …},
    {"instrument_id": "bist:MCARD", "ex_dividend_date": "2026-10-23", "pay_date": "2026-10-27",
     "cash_amount": "2.19", "gross_amount": "2.57", "frequency": null, "installment": "Peşin",
     "status": "pending", "finalized": false, …}
  ],
  "count": 2,
  "total": 5,
  "next_cursor": null,
  …
}

Örnek — bir izleme listesi için yaklaşan ABD ödemeleri

status=upcoming ile date_field=pay: varsayılan pencere içinde (ödeme tarihine göre bugün − 30 gün ile bugün + 90 gün arası) bugün ya da sonrasındaki (New York saati) ödemeler. 2026-10-04'te çağrıldığında:

curl

curl -H "X-API-Key: $PORTGATE_KEY" \
  "https://api.theportfoy.com/portgate/v1/dividends?market=us&date_field=pay&status=upcoming&symbols=CM,KO,MSFT"

response (abridged)

{
  "market": "us",
  "date_field": "pay",
  "from": "2026-09-04",
  "to": "2027-01-02",
  "status": "upcoming",
  "dividends": [
    {"instrument_id": "us:CM",
     "declaration_date": "2026-08-26", "ex_dividend_date": "2026-09-28", "pay_date": "2026-10-28",
     "cash_amount": "1.07", "currency": "CAD", "frequency": 4,
     "distribution_type": "recurring", "yield_pct": null,
     "gross_amount": null, "installment": null, "status": null, "finalized": null, "note": null},
    {"instrument_id": "us:CM",
     "declaration_date": "2026-08-27", "ex_dividend_date": "2026-09-28", "pay_date": "2026-10-28",
     "cash_amount": "1.07", "currency": "CAD", "frequency": 4,
     "distribution_type": "recurring", "yield_pct": null, …},
    {"instrument_id": "us:MSFT",
     "declaration_date": "2026-09-14", "ex_dividend_date": "2026-11-19", "pay_date": "2026-12-10",
     "cash_amount": "0.98", "currency": "USD", "frequency": 4,
     "distribution_type": "recurring", "yield_pct": "0.19394", …}
  ],
  "count": 3,
  "total": 3,
  "next_cursor": null,
  "not_found": [],
  "as_of": "2026-10-04T06:12:40.512000Z",
  "refreshed_at": "2026-10-04T06:12:40.512000Z"
}

Satırlar kaynağın satırlarıdır, tekilleştirilmez: kaynakta iki kez duyurulan bir dağıtım iki kez görünür; buradaki us:CM gibi (2026-08-26 ve 2026-08-27'de ilan edilmiş, tarihler ve tutar aynı). Ödeme başına tek satır gerekiyorsa instrument_id + ex_dividend_date + pay_date + cash_amount üzerinden tekilleştirin.

currency satır bazındadır: ABD'de işlem gören yabancı bir ihraççı kendi para biriminde ilan edebilir — us:CM CAD öder. market=us için USD varsaymayın.

Satır alanları

İki uç nokta da aynı Dividend satırını döndürür; /v1/dividends buna instrument_id ekler. İki piyasa biçimi paylaşır ama her anlamı değil — sayıları piyasalar arasında karşılaştırmadan önce piyasa bazlı notları okuyun.

Alan	Tür	Notlar
instrument_id	string	Kanonik kimlik, ör. bist:TBORG. Yalnızca toplu satırlarda.
ex_dividend_date	date	Hak kullanım tarihi (ex-dividend date): temettüyü almak için hisseyi bu günden önce alın.
pay_date	date \| null	Ödeme tarihi. us: yeni ilan edilmiş bir dağıtımda ara sıra null.
declaration_date	date \| null	us: ilan tarihi, her zaman dolu. bist: her zaman null (kaynak vermiyor).
cash_amount	string (decimal)	Hisse başına tutar, tam ondalık metin. bist: stopaj sonrası NET tutar (hissedarın eline geçen); us: ilan edilen tutar. 0 gerçek bir "sıfır ödendi" taksitidir, eksik veri değil.
gross_amount	string \| null	bist: hisse başına brüt tutar (stopaj öncesi). us satırlarında null.
currency	string	Ödeme para birimi — bist satırlarında TRY; us satırlarında genellikle USD ama her zaman değil (us:CM → CAD).
frequency	int \| null	us: yıllık ödeme sayısı (4 = üç aylık). bist: TEK bir ilanın taksit sayısı (installment'ın paydası). Piyasalar arasında karşılaştırılamaz.
distribution_type	string \| null	us: ör. recurring. bist satırlarında null.
yield_pct	string \| null	us: ilan anındaki tek-ödeme verimi. bist: kaynağın kendi gösterim sayısı — brüt tutarın GÜNCEL fiyata oranı, her gün yeniden yazılır — "kaynak bugün ne gösteriyor" için uygundur, tarihsel verim için yanlıştır; null olabilir. Kendi veriminizi cash_amount / gross_amount ile tarihli bir fiyattan hesaplayın.
installment	string \| null	Yalnızca bist: taksit etiketi, ör. 2/2 (iki taksitin ikincisi) ya da Peşin (tek seferde ödeme).
status	string \| null	Yalnızca bist: ödeme durumu, paid ya da pending (tanınmayan bir kaynak etiketi olduğu gibi geçer).
finalized	boolean \| null	Yalnızca bist: hak kullanım tarihi kesinleşmişse true; false, hâlâ değişebilecek önerilmiş bir tarih demektir — satırı tahmin niteliğinde değerlendirin.
note	string \| null	Yalnızca bist: kaynağın notu, ör. Genel Kurul Tarafından Onaylandı.

Yanıt zarfı (/v1/dividends)

Alan	Tür	Notlar
market	bist \| us	İstediğiniz piyasa.
date_field	ex \| pay	Geçerli date_field (ex ya da pay).
from / to	date	Etkin pencere, varsayılanlar doldurulmuş.
status	paid \| upcoming \| null	Uygulanan status filtresi ya da null.
dividends	array	Bu sayfanın satırları, date_field'a, ardından instrument_id'ye göre artan.
count	int	Bu sayfadaki satır sayısı.
total	int	Filtreye uyan, tüm sayfalardaki satır sayısı.
next_cursor	string \| null	Sonraki sayfa için cursor olarak gönderin; son sayfada null.
not_found	string[]	Bu piyasanın temettüye uygun enstrümanı olmayan symbols girdileri.
as_of	datetime \| null	Verinin tazeliği. bist: kaynağın en son günlük senkron damgası. us: PortGate'in veriyi en son okuduğu an (ABD satırlarının kendi senkron damgası yoktur).
refreshed_at	datetime \| null	PortGate'in bu piyasanın temettü verisini en son yüklediği an (UTC).

Tazelik

BIST kaynağı günde bir kez güncellenir; PortGate BIST temettülerini saatte bir yeniden yükler, böylece yeni günün satırları o güncellemeden sonraki bir saat içinde görünür. ABD temettüleri 6 saatte bir yeniden yüklenir. Her yanıttaki as_of ve refreshed_at, sayfanın ne kadar taze olduğunu tam olarak söyler.

Kapsam ve ölçümleme

İki uç nokta da, iki piyasa için de history kapsamını ister. /v1/dividends, enstrüman kataloğu gibi ölçülür: dönen her başlanmış 100 satır için 1 birim, en az 1 — 250 satırlık bir sayfa 3 birim, boş bir sayfa 1 birimdir.

Test anahtarları

Toplu liste test anahtarlarına açıktır, test evreniyle sınırlanmış olarak: market=bist'te dört test hissesinin (GARAN, ASELS, AKBNK, THYAO) satırlarını, 30 günlük sınır olmadan alırsınız; market=us boş liste döner. symbols içinde evren dışı bir sembol belirtmek her zamanki trial_key_universe 403'üdür. Sembol bazındaki /v1/stocks/{id}/dividends test anahtarlarına kapalı kalır (not_in_plan). Ayrıntılar için test anahtarı hızlı başlangıcı.

Hatalar

Durum	Ne zaman
400	Bilinmeyen sorgu parametresi ya da geçersiz cursor (bozuk ya da başka bir market/date_field için üretilmiş).
403	Anahtarda history kapsamı yok; test anahtarı evren dışı bir sembol belirtti (trial_key_universe).
422	Geçersiz değer: bist/us dışında bir market, bozuk tarih ya da sembol, diğer piyasanın sembolü, 100'den fazla sembol, to'dan sonra gelen from, 366 günden geniş pencere ya da örtük pencereyi takvimin dışına taşıyan uç bir tarih.
503	Piyasanın temettü verisi henüz yüklenmedi (yeni başlamış bir süreç ve kaynağa ulaşılamıyor). Retry-After saniye sonra yeniden deneyin.

Tüm hatalar RFC 7807 problem gövdesini kullanır — bkz. Hatalar ve hız sınırları.