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.
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.
| Paket | Kapsamlar | Ne yapar |
|---|---|---|
| Muhasebe | read_orders, read_returns, read_customers, read_products | Siparişleri, iadeleri, müşterileri ve ürünleri okur |
| Stok / ERP | read_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.
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.
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.
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:
| Durum | Etkisi |
|---|---|
| Anahtarın kapsamları değişti | Anahtarla alınmış Admin API token'ları silinir; yeni token yeni kapsamları taşır |
| Sır yenilendi | Anahtarın bütün token'ları silinir |
| Anahtar pasife alındı ya da silindi | Token'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 kodu | Sebep |
|---|---|
401 | clientId 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 |
422 | Panelde 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 |
429 | Token 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.