OAuth Akışı
Uygulamanız mağaza verisine yalnız mağaza sahibinin panelde onayladığı izinlerle erişir. Kurulumda size bir kez kullanılabilen bir kurulum kodu gelir; sunucunuz bu kodu takas ederek mağazayı kaydeder. Token'ı her mağaza için aynı uygulama kimliğiyle, mağazayı belirterek alırsınız; mağaza başına sır saklamazsınız.
Başlamadan önce
Uygulama kaydınız için T-SOFT'a şunları iletin:
| Alan | Açıklama |
|---|---|
redirect_uri | Kurulumdan sonra mağaza sahibinin yönlendirileceği https:// adresi |
app_url | Uygulamanız panel içinde açılacaksa iframe'e yüklenecek adres (Panele Gömülü Uygulamalar) |
uninstall_url | Uygulama kaldırıldığında bildirim alacağınız adres (Webhooks) |
privacy_url | Mağaza ya da müşteri verisini silmeniz gerektiğinde bildirim alacağınız adres (Gizlilik webhook'ları) |
| Kapsamlar | İstediğiniz izinler ve her birinin gerekçesi (Kapsamlar) |
Karşılığında uygulama sırrı (client_secret) alırsınız. client_id uygulamanızın prefix'idir (örn. app.ornek). Bu iki değer kod takasında da token alırken de kullanılan tek kimliğinizdir.
Mağaza sahibi onaylar
Mağaza sahibi markette Yükle'ye basar. Panel, istediğiniz izinleri listeleyen onay ekranını açar. Onaydan sonra mağaza sahibi redirect_uri adresinize yönlendirilir:
https://uygulamaniz.com/callback?code=…&store=…&domain=…
app_url tanımlıysa yönlendirme yapılmaz; uygulamanız panel içinde açılır ve code iframe adresine eklenir.
Kodu takas edin
curl -X POST https://api.tsoftapps.com/api/integration/v3/install/app/credentials \
-H "Content-Type: application/json" \
-d '{"client_id": "app.ornek", "client_secret": "<uygulama sırrı>", "code": "<code>"}'
Yanıt, kurulumun yapıldığı mağazayı ve onaylanan kapsamları söyler:
{
"client_id": "app.ornek",
"store_id": "8c1f…",
"store_domain": "magaza.com",
"scopes": ["read_orders", "read_products"],
"shared": true
}
Kod 10 dakika geçerlidir ve bir kez kullanılabilir. Yanlış uygulama sırrı 401 invalid_client, geçersiz ya da kullanılmış kod 400 invalid_grant döner.
Mağazayı kaydedin
store_id, store_domain ve scopes değerlerini saklayın. Mağaza adresi olarak sorgudaki domain değerine değil, yanıttaki store_domain değerine güvenin.
client_secret alanı da geliyorsa (shared yok), uygulamanız henüz eski, mağazaya özel kimlik modelindedir: bu client_id ve client_secret değerlerini o mağaza için şifreli saklayın ve token'ı store göndermeden bu ikisiyle alın. Uygulama sırrınız yenilendiğinde sonraki kurulumlar tek kimliğe geçer.Token alın
curl -X POST https://login.tsoft360.com/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "app.ornek",
"client_secret": "<uygulama sırrı>",
"store": "<store_id>",
"scope": "read_orders read_products"
}'
Token yalnız store ile belirttiğiniz mağazada geçerlidir. Uygulamanız o mağazada kurulu değilse ya da kaldırıldıysa 400 invalid_grant, store gönderilmezse 400 invalid_request döner. scope vermezseniz mağazanın onayladığı kapsamların tamamı gelir. Token kısa ömürlüdür; süresi dolunca aynı istekle yenisini alın.
Admin API'yi çağırın
curl https://magaza.com/api/v3/admin/2026-01/order/orders \
-H "Authorization: Bearer <access_token>" \
-H "Accept: application/vnd.api+json"
Admin API JSON:API biçimindedir; Accept: application/json gönderirseniz 406 döner. Onaylanmamış bir kapsamın ucunu çağırırsanız 403 alırsınız.
İzinler değiştiğinde
Yeni bir kapsam istediğinizde uygulama sürümünüz yükselir. Mağaza sahibi Uygulamalarım ekranında İzinleri onayla bağlantısını görür; onayladığında akış baştan işler ve size yeni bir kurulum kodu gelir; yeni kapsamlar takas yanıtının scopes alanındadır.
Kaldırma
Mağaza uygulamayı kaldırdığında o mağazadaki erişiminiz kapanır ve o mağaza için token istekleri başarısız olur. uninstall_url verdiyseniz imzalı bir bildirim alırsınız; ayrıntı Webhooks sayfasında. privacy_url verdiyseniz 48 saat sonra o mağazanın verisini silmeniz için shop.redact gelir.