# Doğrulama (SBX-VAL)

IBAN (87 ülke, Türk IBAN'larında banka adı), T.C. kimlik no, vergi no ve Türkiye telefon numarası doğrulama.

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

**List Turkish banks**

The participants of the Turkish central bank's payment systems (EFT/FAST) with their codes; a Turkish IBAN's bank code is `0` followed by the participant code. From TCMB's published list. Free. Not paged: the whole list in one answer.

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

Parametre yok.

**Örnek**

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

### GET /v1/validation/ibans/lookup

**Check an IBAN**

Validates an IBAN of any of 87 countries (ISO 13616: country, length, mod-97 checksum; for Turkey also the reserved digit) and returns its electronic and print forms. A Turkish IBAN also names its bank from TCMB's payment-systems participant list. Spaces and dashes are ignored. Nothing is stored or cached.

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `iban` | query | string | evet | The IBAN, with or without spaces. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/validation/ibans/lookup?iban=<iban>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/validation/national-ids/lookup

**Check a Turkish national id (TCKN)**

Checks that an 11-digit T.C. kimlik numarası (or a foreigner's YKN, starting 99) is well formed and its two check digits hold. Only the number's form is checked — nothing is looked up, and a valid number is not proof that the person exists. Nothing is stored or cached; the number does appear in the request URL, so do not log URLs you would not log the number in.

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `id` | query | string | evet | The 11-digit number. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/validation/national-ids/lookup?id=<id>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/validation/phone-numbers/lookup

**Check a Turkish phone number**

Parses a Turkish phone number in any common spelling (`0532 123 45 67`, `+90 532…`, `0090…`) and returns its E.164 and national forms and its kind from the national numbering plan: mobile (5xx), landline (2xx–4xx), toll-free (800), shared-cost (850), single-number (444) or premium (900). Nothing is stored or cached.

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `number` | query | string | evet | The phone number. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/validation/phone-numbers/lookup?number=<number>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/validation/tax-ids/lookup

**Check a Turkish tax number (VKN)**

Checks that a 10-digit vergi kimlik numarası is well formed and its check digit holds. Only the number's form is checked — nothing is looked up. Nothing is stored or cached.

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `id` | query | string | evet | The 10-digit number. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/validation/tax-ids/lookup?id=<id>" \
  -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/validation/openapi.json
- Fiyatlandırma: https://servicebox.io/pricing?api=SBX-VAL
- API sayfası: https://servicebox.io/apis/validation