# Giriş

Borkol storefront API'si, Borkol ticaret platformunun herkese açık HTTP API'sidir. Tek bir mağazaya (bir tenant'a) programatik okuma ve yazma erişimi sağlar: ürün kataloğu, stok seviyeleri, müşteriler, siparişler ve özel nesneler. Bu API'yi bir Borkol mağazasına karşı özel storefront'lar, headless frontend'ler, mobil uygulamalar ve sunucu tarafı entegrasyonlar geliştirmek için kullanırsınız.

API, alışılagelmiş bir JSON-üzerinden-HTTPS API'sidir. Her request ve response body JSON'dır. Kimlik doğrulama, bearer token olarak gönderilen bir tenant API anahtarıyla yapılır. Storefront API'sinde cookie, oturum veya OAuth akışı yoktur.

## Base URL

Tüm istekler şu adrese gider:

```
https://api.borkol.com
```

API, URL yolunda sürümlenir. Geçerli ve tek sürüm `v1` olduğundan bu dokümantasyondaki her rota `/v1` ile başlar. Kimlik doğrulaması gerektiren storefront rotaları `/v1/api/...` altında yaşar; kimlik doğrulaması gerektirmeyen tek rota, `/v1/ping` adresindeki sağlık kontrolüdür.

Modül yüzeyleri `/v1/api/{module}` altına bağlanır:

| Modül | Bağlanma noktası |
| --- | --- |
| Commerce | `/v1/api/commerce` (ayrıca `/v1/api/commerce/configurator`) |
| Stock | `/v1/api/stock` |
| Customers | `/v1/api/customers` |
| Objects | `/v1/api/objects` |
| Forms | `/v1/api/forms` |

Bir modül yüzeyine yalnızca o modül mağazanız için etkinleştirildiğinde erişilebilir. Devre dışı bir modülün rotasını çağırmak `403 {"error": "Module not enabled: {key}"}` döndürür. Hataların tam kataloğu için [Hatalar ve rate limit'ler](./errors-and-rate-limits) sayfasına bakın.

## Tek satırda kimlik doğrulama

Her `/v1/api` isteği, bearer token olarak bir tenant API anahtarı taşır:

```
Authorization: Bearer {api_key}
```

Anahtar mağazayı tanımladığından başka bir tenant header'ına gerek yoktur. Merchant'lar anahtarları client dashboard'da (app.borkol.com) Settings > API keys altında oluşturur. Her anahtar, hangi endpoint'leri çağırabileceğini belirleyen bir scope kümesi taşır (örneğin `commerce:read`). Tüm ayrıntılar [Kimlik Doğrulama](./authentication) sayfasındadır.

## Kurallar

Şunlar API'nin tamamında geçerlidir:

- Kaynak ID'leri UUID string'leridir (yalnızca merchant dashboard akışında görünen API anahtarı ID'leri integer'dır).
- Para değerleri, ayrı bir ISO 4217 `currency` alanıyla birlikte küçük birim (kuruş/cent) cinsinden integer'lardır. `"currency": "EUR"` ile `15900`, 159,00 EUR anlamına gelir.
- Zaman damgaları ISO 8601 string'leridir.
- Liste endpoint'leri, [Hatalar ve rate limit'ler](./errors-and-rate-limits) sayfasında bir kez belgelenen sayfalama zarfını kullanır. Bu sayfalardaki temel endpoint'ler (`/v1/ping`, `/v1/api/me`) sarmalayıcı olmadan düz JSON nesneleri döndürür.

## Hızlı başlangıç

Üç istekle sıfırdan ilk katalog çağrınıza ulaşırsınız.

**1. adım: bağlantıyı doğrulayın.** `/v1/ping` kimlik bilgisi gerektirmez ve base URL ile API sürümünün erişilebilir olduğunu doğrular.

```bash title="Request"
curl https://api.borkol.com/v1/ping
```

```json title="Response"
{
  "status": "ok",
  "version": "v1"
}
```

**2. adım: API anahtarınızı doğrulayın.** Client dashboard'da (Settings > API keys) en az `commerce:read` scope'una sahip bir anahtar oluşturun, ardından `/v1/api/me` endpoint'ini çağırın. Bu çağrı, anahtarın ait olduğu mağazayı ve anahtarın taşıdığı scope'ları döndürür. Bu endpoint scope gerektirmez; yalnızca geçerli bir anahtar yeterlidir.

```bash title="Request"
curl https://api.borkol.com/v1/api/me \
  -H "Authorization: Bearer {api_key}"
```

```json title="Response"
{
  "tenant": {
    "id": "9c4e7f0a-2b31-4d6e-8f0a-1d2c3b4a5e6f",
    "name": "Example Store",
    "slug": "example-store"
  },
  "scopes": ["tenant:read", "commerce:read"]
}
```

**3. adım: kataloğu çekin.** `commerce:read` scope'unu taşıyan bir anahtarla commerce modülündeki ürünleri listeleyin. Bu istek, commerce modülü mağaza için etkin değilse `403 {"error": "Module not enabled: commerce"}` ile, anahtar `commerce:read` scope'undan yoksunsa `403 {"message": "Invalid ability provided."}` ile başarısız olur.

```bash title="Request"
curl https://api.borkol.com/v1/api/commerce/products \
  -H "Authorization: Bearer {api_key}"
```

Yanıt, sayfalanmış bir ürün listesidir; ürün endpoint'leri Commerce bölümünde belgelenmiştir.

## Sonraki adımlar

- [Kimlik Doğrulama](./authentication): API anahtarları, scope'lar, `/v1/api/me` endpoint'i ve tenant askıya alınması.
- [Hatalar ve rate limit'ler](./errors-and-rate-limits): tüm hata zarfları, 422 doğrulama şekli, rate limiting ve sayfalama zarfı.
- [Webhook'lar](/tr/webhooks/index): siparişler ve stok değişiklikleri için olay tabanlı bildirimler.