# Yatırım ve emeklilik fonları (SBX-FON)

TEFAS'taki tüm yatırım, serbest, emeklilik (BES/OKS) ve borsa yatırım fonları: günlük fiyat, büyüklük, yatırımcı sayısı, getiriler, ücretler, risk ve portföy dağılımı.

Sürüm: v1.0

## Kimlik doğrulama

API anahtarınızı her istekte Bearer token olarak ya da `apikey` sorgu parametresiyle gönderin:

```
Authorization: Bearer <API_ANAHTARINIZ>
https://api.servicebox.io/v1/funds/...?apikey=<API_ANAHTARINIZ>
```

Anahtar almak için https://servicebox.io/signup adresinden kaydolun ve panelden bir anahtar oluşturun. Bir ajan `POST https://api.servicebox.io/v1/accounts` ve `{"email": "...", "apis": ["funds"]}` ile kendisi kaydolabilir: e-posta sahibi e-postadaki bağlantıyla onaylar, ajan dönen `poll_url` adresini yoklayarak kısa ömürlü bir anahtar alır.

## Temel URL

`https://api.servicebox.io`

## Uç noktalar

### GET /v1/funds

**List funds**

Every Turkish investment fund, pension fund and ETF TEFAS lists, with the latest price, size, investors, returns, fees and risk. Filter by `type`, `category`, `founder`, `codes`, a text search `q` (code or title, Turkish letters optional), `tefas` and `riskLevel`; sort by size, investors, a return period, fee, code or name. Active funds only unless `status=all`. Updated every morning from TEFAS. Use for questions about Turkish mutual funds, hedge funds, private pension (BES) funds or ETFs: finding a fund by name or company, the best performers over a period, the largest funds, or the lowest fees.

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `type` | query | string (`investment`, `pension`, `exchange-traded`) | hayır | Only this type. |
| `category` | query | string | hayır | A category id from /funds/categories, e.g. para-piyasasi-semsiye-fonu. |
| `founder` | query | string | hayır | A company code from /funds/founders, e.g. ISP. |
| `codes` | query | string | hayır | Comma-separated fund codes (up to 100), e.g. AAL,TTE. |
| `q` | query | string | hayır | Words to find at the start of words of the code or the Turkish or English title; Turkish letters optional: `altin` finds ALTIN and Altın, `tekno` TEKNOLOJİ. |
| `tefas` | query | string (`true`, `false`) | hayır | `true`: only funds traded on the TEFAS platform; `false`: only those that are not. |
| `riskLevel` | query | integer | hayır | Only this risk value, 1–7. |
| `status` | query | string (`active`, `all`) | hayır | `active` (default) or `all` (also funds no longer priced). |
| `sort` | query | string (`aum`, `investors`, `return-1m`, `return-3m`, `return-6m`, `return-ytd`, `return-1y`, `return-3y`, `return-5y`, `fee`, `code`, `name`) | hayır | Sort key. Default `aum` (fund size). |
| `order` | query | string (`asc`, `desc`) | hayır | `desc` or `asc`; default `asc` for fee, code and name, else `desc`. Funds without the sort value come last. |
| `limit` | query | integer | hayır | Items per page, 1–200. |
| `cursor` | query | string | hayır | The `next_cursor` of the previous page, with the same filters. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/funds" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/funds/categories

**List fund categories**

The categories TEFAS uses per fund type — umbrella fund types for investment funds, fund kinds for pension funds and ETFs — in English and Turkish, with how many active funds each has. Free.

**Kredi:** ücretsiz (çağrı başına 0 kredi)

Parametre yok.

**Örnek**

```bash
curl "https://api.servicebox.io/v1/funds/categories" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/funds/founders

**List fund companies**

Portfolio management and pension companies with their number of active funds and total fund value, largest first. Free.

**Kredi:** ücretsiz (çağrı başına 0 kredi)

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `type` | query | string (`investment`, `pension`, `exchange-traded`) | hayır | Only this type. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/funds/founders" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/funds/{code}

**Get a fund**

One fund: the latest price, size, investors, returns, fees and risk, and its portfolio allocation by asset class (stocks, government bonds, reverse repo, deposits, precious metals, foreign securities…). Use when the user names a fund code (e.g. TTE, AAL) or asks what a fund invests in.

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `code` | path | string | evet | A TEFAS fund code, e.g. AAL. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/funds/<code>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/funds/{code}/prices

**Daily price history**

One fund's daily price, shares, investors and size between `start` and `end` (inclusive; default the 30 days up to its latest price; at most 1,830 days per request), oldest first, with `meta.changePercent` over the range. History since October 2021. Use for a fund's price history or its change over a period.

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `code` | path | string | evet | A TEFAS fund code, e.g. AAL. |
| `start` | query | string | hayır | YYYY-MM-DD. |
| `end` | query | string | hayır | YYYY-MM-DD. Default: the fund's latest price date. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/funds/<code>/prices" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

## Hatalar

Hatalar, makinece okunabilir bir `type` taşıyan RFC 9457 `application/problem+json` gövdeleridir.

- `401` — anahtar eksik, bilinmiyor, süresi dolmuş ya da iptal edilmiş.
- `402` — kredi yetersiz: gövde `credits_required` ve `upgrade_url` (https://servicebox.io/pricing) taşır.
- `403` — anahtarın bu API'yi çağırma izni yok.
- `429` — hız sınırı: `retry_after` saniye bekleyin (`Retry-After` başlığıyla da gönderilir); `upgrade_url` daha büyük bir plana yönlendirir.

## Bağlantılar

- OpenAPI belgesi: https://api.servicebox.io/v1/funds/openapi.json
- Fiyatlandırma: https://servicebox.io/pricing?api=SBX-FON
- API sayfası: https://servicebox.io/apis/funds