T-SOFT/Admin API/Mağazaya özel entegrasyon

Mağazaya özel entegrasyon

Kendi mağazanızı bir muhasebe, ERP ya da depo programına uygulama yazmadan bağlayabilirsiniz. Mağaza panelinde bir API anahtarı açarsınız; programınız bu anahtarla 24 saat geçerli bir token alır ve Admin API'yi yalnız sizin sunucularınızdan çağırır.

Bu yol tek bir mağaza içindir. Programınızı birden çok mağazaya sunacaksanız uygulama olarak geliştirin; her mağaza sahibi kurulumda kapsamları onaylar, token OAuth akışı ile alınır.

Anahtarı açın

Panelde Ayarlar → Kullanıcılar ve İzinler → API Erişimi sayfasında yeni bir anahtar oluşturun. Aynı anahtar hem Storefront API hem Admin API için kullanılır. client_id ve client_secret bir kez gösterilir; sırrı programınızın sunucusunda saklayın.

Ağ kısıtını ekleyin

Anahtarın sayfasındaki Ağ kısıtı kartına programınızın çalıştığı sunucunun IP adresini ya da aralığını ekleyin. Program Cloudflare, AWS, Google Cloud ya da Microsoft Azure üzerinde çalışıyorsa sağlayıcı kartını seçebilirsiniz. Sağlayıcı kartı o sağlayıcının bütün müşterilerini kapsar; sabit çıkış IP adresiniz varsa IP listesini tercih edin. Ayrıntılar Ağ izin listesi sayfasındadır.

Ağ kısıtı olmayan anahtara Admin API kapsamı verilmez: panel kaydı engeller, API 422 döner.

Kapsamları seçin

Aynı sayfadaki Yönetim API kartında bir hazır paket seçin ya da tabloda kaynak başına okuma ve yazma izni verin. Anahtara yalnız uygulamaların kullandığı kapsamlar verilebilir; tema, izleme kodu ve webhook kapsamları mağazaya özel anahtarda yoktur. Yalnız kendi hesabınızda olan yetkileri anahtara verebilirsiniz; örneğin rolünüzde sipariş görüntüleme yoksa read_orders kapsamını veremezsiniz.

PaketKapsamlarNe yapar
Muhaseberead_orders, read_returns, read_customers, read_productsSiparişleri, iadeleri, müşterileri ve ürünleri okur
Stok / ERPread_products, write_products, read_inventory, write_inventory, read_product_prices, write_product_pricesÜrünleri okur; ürünü, stoğu ve fiyatları günceller. Ürün silemez

write kapsamları aynı kaynağın read erişimini de içerir. write_products stok ve fiyatı değiştirmez; stok için write_inventory, fiyat için write_product_prices gerekir. Programınız ürün adını ya da açıklamasını değiştirmeyecekse write_products vermeyin; stoğu depo stok uçlarından güncelleyin.

Eskiden anahtara admin: ile başlayan iç yetkiler de verilebiliyordu. Bu yetkiler kayıtlı anahtarlarda çalışmaya devam eder ama artık yeni verilemez; kaydederken 422 döner.

Token alın

Programınız anahtarla token ister. İstek ağ kısıtındaki bir adresten gelmelidir.

POST /auth/client-tokens
curl -X POST 'https://<domain>/api/v3/admin/2026-01/auth/client-tokens' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "client-tokens",
      "attributes": {
        "clientId": "<client_id>",
        "clientSecret": "<client_secret>"
      }
    }
  }'

201 ile token döner. expiresIn token'ın kalan süresidir, saniye cinsinden.

{
  "jsonapi": { "version": "1.0" },
  "data": {
    "type": "client-tokens",
    "id": "1842",
    "attributes": {
      "accessToken": "1842|Zq8YtR2mXvK7pLw3NcB9sHdF4gJ6aUe1",
      "tokenType": "Bearer",
      "expiresIn": 86400
    }
  }
}

Admin API'yi çağırın

accessToken değerini Authorization başlığında gönderin.

GET /order/orders
curl 'https://<domain>/api/v3/admin/2026-01/order/orders?page[size]=50' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json'

Uç noktalar, sorgu parametreleri ve hata biçimi uygulamalarla aynıdır. Kaynakların tamamı Siparişler, Ürünler ve Müşteriler sayfalarındadır.

Token süresi

Token 24 saat geçerlidir ve yenileme token'ı yoktur. Süre dolmadan aynı istekle yeni token alın. Token'ı expiresIn süresince saklayın; token uç noktasının hız sınırı dakikada 10 istektir. Süresi dolmuş token'la istekler 401 döner; yeni token alıp isteği bir kez tekrarlayın.

Token'lar şu durumlarda süresinden önce geçersiz olur:

DurumEtkisi
Anahtarın kapsamları değiştiAnahtarla alınmış Admin API token'ları silinir; yeni token yeni kapsamları taşır
Sır yenilendiAnahtarın bütün token'ları silinir
Anahtar pasife alındı ya da silindiToken'lar çalışmaz, yeni token alınamaz

Ağ kısıtı her istekte

Ağ kısıtı yalnız token isteğinde değil, her Admin API isteğinde uygulanır. Token sızsa bile başka bir ağdan kullanılamaz.

Hatalar

Durum koduSebep
401clientId ya da clientSecret yanlış, anahtar pasif, token süresi dolmuş ya da iptal edilmiş
403İstek ağ kısıtında olmayan bir adresten geldi, anahtarda Admin API kapsamı var ama ağ kısıtı boş ya da token'da uç noktanın istediği kapsam yok
422Panelde ya da API'de ağ kısıtı olmayan anahtara Admin API kapsamı verilmek istendi ya da hesabınızda olmayan bir kapsam seçildi
429Token uç noktasına dakikada 10'dan fazla istek

Hata gövdesinin biçimi Hatalar sayfasındadır.

client_secret değerini yalnız sunucuda tutun. Tarayıcıya, masaüstü programının kurulum paketine, mobil uygulamaya ya da loga yazmayın. Sırrın sızdığından şüphelenirseniz panelden yenileyin; bütün token'lar hemen geçersiz olur.

Sonraki adımlar