# Dövizler (SBX-FX)

TCMB gösterge kurları (2005'ten beri, alış/satış, efektif) ve ECB euro referans kurları (1999'dan beri); çeviri ve geçmiş.

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/fx/...?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": ["fx"]}` 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/fx/conversions

**Convert an amount**

`amount` of `from` in `to` at the official rate on `date` (default: latest). TCMB is used when it publishes both currencies (TRY included), else ECB (EUR included). With TCMB, `rateType` picks the rate each currency is valued at in TRY: `mid` (default, the forex buying/selling midpoint), `buying` or `selling`.

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `from` | query | string | evet | ISO 4217 code. |
| `to` | query | string | evet | ISO 4217 code. |
| `amount` | query | number | hayır | Default 1. |
| `date` | query | string | hayır | YYYY-MM-DD. Default: the latest bulletin. |
| `source` | query | string (`tcmb`, `ecb`) | hayır | Force `tcmb` or `ecb`. |
| `rateType` | query | string (`mid`, `buying`, `selling`) | hayır | TCMB only: `mid`, `buying` or `selling`. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/fx/conversions?from=<from>&to=<to>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/fx/currencies

**List currencies**

Every currency TCMB or ECB publishes, with the first and latest date each has. Free.

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

Parametre yok.

**Örnek**

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

### GET /v1/fx/rates

**Rates on a date**

Every currency's official rate on `date` (default: the latest bulletin). TCMB: the indicative forex and banknote buying/selling rates in TRY, published at 15:30 Istanbul time on business days. ECB: the euro reference rates, published around 16:00 CET. A date without a bulletin (weekend, holiday) answers the latest one before it; `meta.date` says which.

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `source` | query | string (`tcmb`, `ecb`) | hayır | `tcmb` (default: Turkish central bank, TRY rates since 2005) or `ecb` (European Central Bank, EUR rates since 1999). |
| `date` | query | string | hayır | YYYY-MM-DD. Default: the latest bulletin. |
| `currencies` | query | string | hayır | Comma-separated ISO 4217 codes to include, e.g. USD,EUR. |

**Örnek**

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

### GET /v1/fx/rates/{code}

**One currency over time**

One currency's rate on every bulletin between `start` and `end` (default: the last 30 days; at most 366 days).

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `code` | path | string | evet | ISO 4217 code, e.g. USD. |
| `source` | query | string (`tcmb`, `ecb`) | hayır | `tcmb` (default: Turkish central bank, TRY rates since 2005) or `ecb` (European Central Bank, EUR rates since 1999). |
| `start` | query | string | hayır | YYYY-MM-DD. |
| `end` | query | string | hayır | YYYY-MM-DD. Default: today. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/fx/rates/<code>" \
  -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/fx/openapi.json
- Fiyatlandırma: https://servicebox.io/pricing?api=SBX-FX
- API sayfası: https://servicebox.io/apis/fx