Borkol Docs ana sayfası

Başlarken

Giriş

Borkol storefront API'sinin ne olduğu, base URL'i ve sürümlemesi ile üç adımlık bir hızlı başlangıç.

Markdown olarak görüntüle

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:

text
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ülBağ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 sayfasına bakın.

Tek satırda kimlik doğrulama

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

text
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 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 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.

Request
curl https://api.borkol.com/v1/ping
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.

Request
curl https://api.borkol.com/v1/api/me \
  -H "Authorization: Bearer {api_key}"
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.

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: API anahtarları, scope'lar, /v1/api/me endpoint'i ve tenant askıya alınması.
  • Hatalar ve rate limit'ler: tüm hata zarfları, 422 doğrulama şekli, rate limiting ve sayfalama zarfı.
  • Webhook'lar: siparişler ve stok değişiklikleri için olay tabanlı bildirimler.