API belgeleri

Başlangıç

Ayarlar > Geliştirici sayfasından bir anahtar oluşturun (bk_…). Anahtar yalnızca oluşturulurken bir kez gösterilir; parola gibi saklayın. Her istekte Authorization başlığıyla gönderin:

curl -H "Authorization: Bearer bk_ANAHTARINIZ" \
  "https://SİTE/api/public/v1/summary"

• Anahtarlar salt okunur (read) ya da okuma + yazma (write) yetkili olabilir. Yazma yetkisi yalnızca işlem eklemek içindir.
• Anahtarlar yalnızca kendi portföylerinize erişir; başkasının sizinle paylaştığı (ortak) portföyler dahil değildir. Hesap silme, şifre gibi işlemlere erişemez.
• Para birimi: ?currency=TRY|USD|XAU (varsayılan: hesabınızın görünüm para birimi). Sayılar ham değerdir; biçimlendirme yapılmaz.
• Tüm liste uçları ?format=csv (virgül ayraç, nokta ondalık, UTF-8, ISO tarih) destekler.
• Sürümlüdür (v1): yeni alanlar eklenebilir, var olan alanlar değişmez ya da kalkmaz.

Önemli: Anahtarı tarayıcıdaki (herkese açık) kodda kullanmayın. GET isteklerinde ?key= parametresi yalnızca E-Tablolar’daki IMPORTDATA gibi başlık gönderemeyen araçlar için vardır; adresler günlüklere ve tablo geçmişine yazılabilir, o yüzden bu iş için ayrı, salt okunur bir anahtar kullanın.

Uç noktalar

Temel adres: https://SİTE/api/public/v1

{ "name": "Ayşe Yılmaz", "plan": "PRO", "baseCurrency": "TRY", "key": { "name": "E-Tablolar", "scopes": ["read"] } }

{ "summary": { "currency": "TRY", "totalValue": 412350.5, "totalCost": 350000, "pnl": 62350.5, "pnlPct": 17.81, "dayChange": 1520.4, "dayChangePct": 0.37, "holdingsCount": 9, "asOf": "2026-10-20T12:00:00.000Z" } }

{ "currency": "TRY", "portfolios": [ { "id": "cm…", "name": "Ana Portföy", "totalValue": 412350.5, "pnlPct": 17.81, "holdingsCount": 9 } ] }

{ "currency": "TRY", "portfolio": { … }, "holdings": [ { "symbol": "THYAO.IS", "quantity": 100, "value": 35120, "pnlPct": 12.4, "weightPct": 8.5 } ] }

{ "currency": "TRY", "holdings": [ { "portfolio": "Ana Portföy", "symbol": "THYAO.IS", "name": "Türk Hava Yolları", "quantity": 100, "value": 35120 } ] }

{ "currency": "TRY", "holdings": [ … ] }

{ "total": 42, "transactions": [ { "id": "cm…", "date": "2026-09-03", "type": "BUY", "symbol": "THYAO.IS", "quantity": 100, "price": 351.2, "fee": 2.5, "currency": "TRY", "note": "Uzun vade" } ] }

{ "symbol": "THYAO.IS", "type": "BUY", "quantity": 10, "price": 351.2, "fee": 0, "date": "2026-10-20", "note": "Aylık birikim" }

{ "transaction": { "id": "cm…", "symbol": "THYAO.IS", "type": "BUY", … } }

{ "quotes": [ { "symbol": "THYAO.IS", "price": 351.2, "changePct": 0.8, "currency": "TRY", "stale": false } ] }

Google E-Tablolar ve Excel

En hızlı yol, Ayarlar > Geliştirici sayfasındaki hazır örnekler (anahtarınız otomatik doldurulur):

• E-Tablolar, tek formül: =IMPORTDATA("…/holdings?format=csv&key=…"; ","; "en_US")
• Apps Script: anahtarı betik özelliklerinde gizli tutar, saatlik tetikleyiciyle tabloyu günceller.
• Excel Power Query: Web.Contents ile anahtar üstbilgide gider; Veri > Tümünü Yenile ile güncellenir.

Webhook

Ayarlar > Geliştirici sayfasından bir https:// adresi ekleyin. Olay olunca adresinize POST ile JSON gövdeli bir istek gelir:

{ "id": "evt_9c1f…", "type": "transaction.created", "createdAt": "2026-10-20T12:00:00.000Z", "data": { … } }

• alert.triggeredAlarm tetiklendi (fiyat, günlük % değişim, 52 haftalık zirve/dip, hacim patlaması ya da temettü duyurusu). condition: ABOVE | BELOW | DAY_UP | DAY_DOWN | HIGH_52W | LOW_52W | VOLUME_SPIKE | DIVIDEND; targetPrice koşula göre eşiktir (fiyat, yüzde ya da hacim katı); value gözlenen değer, note kısa açıklamadır.

  { "alert": { "id": "…", "symbol": "THYAO.IS", "condition": "ABOVE", "targetPrice": 360, "triggerPrice": 361.2, "value": 361.2, "note": "hedef fiyatın üstüne çıktı (hedef ₺360,00)", "triggeredAt": "…" } }

• transaction.createdİşlem eklendi (uygulamadan, içe aktarmadan ya da API'den)

  { "portfolioId": "…", "transaction": { "id": "…", "symbol": "THYAO.IS", "type": "BUY", "quantity": 10, "price": 351.2, "date": "…" } }

• transaction.updatedİşlem güncellendi

  { "portfolioId": "…", "transaction": { … } }

• transaction.deletedİşlem silindi

  { "portfolioId": "…", "transaction": { "id": "…", "symbol": "THYAO.IS" } }

İmza doğrulama

Her istek HMAC-SHA256 ile imzalanır. X-Birikimli-Timestamp (unix saniye) ve X-Birikimli-Signature (v1=<hex>) başlıklarını kullanın; imzalanan metin <zaman damgası>.<ham gövde>’dir. Zaman damgası 5 dakikadan eskiyse isteği reddedin (tekrar saldırısına karşı). Ham gövdeyi ayrıştırmadan önce doğrulayın.

import { createHmac, timingSafeEqual } from "node:crypto";

// gövde: ham istek gövdesi (string), başlıklar: gelen HTTP başlıkları
export function dogrula(govde, basliklar, gizliAnahtar) {
  const zaman = Number(basliklar["x-birikimli-timestamp"]);
  if (!zaman || Math.abs(Date.now() / 1000 - zaman) > 300) return false; // 5 dakikadan eski: reddet
  const beklenen = "v1=" + createHmac("sha256", gizliAnahtar).update(`${zaman}.${govde}`).digest("hex");
  const gelen = basliklar["x-birikimli-signature"] ?? "";
  return gelen.length === beklenen.length && timingSafeEqual(Buffer.from(gelen), Buffer.from(beklenen));
}

• Başarı = herhangi bir 2xx yanıt (8 saniye içinde). Yönlendirmeler izlenmez.
• Başarısız teslimat 1 dk, 5 dk, 30 dk, 2 sa ve 6 sa arayla yeniden denenir (toplam 6 deneme). Aynı olay tekrar gelebilir; id alanıyla tekilleştirin.
• Art arda 10 teslimat başarısız olursa uç nokta otomatik kapatılır; 410 Gone yanıtı uç noktayı hemen kapatır.
• Güvenlik için yalnızca https:// ve genel (iç ağ olmayan) adresler kabul edilir.
• Toplu içe aktarmada en çok 25 işlem olayı gönderilir.

Sınırlar ve hatalar

• Anahtar başına dakikada 60 istek (aşılırsa 429). Pro planda 5 etkin anahtar ve 5 webhook.
• Fiyatlar gecikmeli ve gayriresmî olabilir; stale/simulated alanları durumu bildirir. Veriler yatırım tavsiyesi değildir.

{ "error": "API anahtarı geçersiz, iptal edilmiş ya da süresi dolmuş", "code": "INVALID_API_KEY" }