geliştirici belgeleri

Uygulama API'si

Kurulum ve kimlik doğrulama, /api/v1 kaynakları ve izinleri, faturalandırma, sayfalama, hatalar ve çağrı sınırı.

Bir uygulama mağazaya OAuth 2.0 yetki kodu akışıyla kurulur, bir erişim jetonu alır ve o jetonla mağazanın /api/v1 adreslerini çağırır. Go ile yazıyorsanız bunların hepsini Go SDK yapar.

Kurulum

  1. Başlangıç. Mağaza sahibi yönetim panelinde uygulamayı kurmaya başlar. Platform uygulamanın application_url adresini imzalı bir sorguyla açar: store (mağazanın ana makine adı), store_id (mağazanın sayısal kimliği) ve signature.

  2. Yetki isteği. Uygulama rastgele bir state üretir, saklar (örneğin bir çerezde) ve tarayıcıyı mağazaya gönderir:

    https://<mağaza>/oauth/authorize?client_id=…&scope=…&redirect_uri=…&state=…
    

    state her zaman uygulamanındır. redirect_uri, yapılandırmadaki auth.redirect_urls adreslerinden biriyle birebir aynı olmalıdır.

  3. Onay. İzin ekranı istenen izinleri listeler ve mağaza sahibi onaylar. Uygulama istediği bütün izinlerle zaten kuruluysa ekran atlanır.

  4. Geri dönüş. Platform redirect_uri adresine code, store, state ve signature ile döner. Uygulama önce imzayı, sonra state değerinin kendi sakladığı değer olduğunu denetler.

  5. Takas. Uygulama kodu jetona çevirir:

    POST /oauth/access_token HTTP/1.1
    Host: <mağaza>
    Content-Type: application/x-www-form-urlencoded
    
    client_id=…&client_secret=…&code=…
    
    { "access_token": "bt_app_…", "scope": "…", "store_id": 1000000000001 }
    

    Kod bir kez çalışır ve 60 saniye sonra geçersiz olur. Hatalar: 401 invalid_client, 400 invalid_grant, 400 invalid_request.

Jeton uygulama kaldırılana kadar geçerlidir. Her takas yeni bir jeton verir ve kurulumun önceki jetonunu hemen iptal eder: her takastan gelen jetonu kaydedin ve her çağrıda kayıtlı olanı okuyun.

Verinizi store_id ile anahtarlayın. Mağazanın alan adı değişebilir, sayısal kimliği değişmez.

Uygulamayı açmak. Yönetim panelindeki Aç düğmesi application_url adresini 1. adımdaki imzalı sorguyla açar. İmzalı sorgu bağlantıyı platformun ürettiğini kanıtlar, bağlantıyı kimin tuttuğunu değil (5 dakika geçerlidir ve sızabilir); bu yüzden yalnızca ona bakarak kimseyi oturuma almayın. Mağaza için oturumunuz yoksa 2. adımdan OAuth'u çalıştırın: uygulama kurulu olduğu için platform doğrudan geri döner.

İmzalar

Platformun uygulamaya gönderdiği her şey uygulamanın gizli anahtarıyla (client secret) imzalıdır.

Çağrılar

GET /api/v1/shop HTTP/1.1
Host: <mağaza>
Authorization: Bearer bt_app_…

Jetonun mağazası, isteğin gittiği mağaza olmalıdır. Yanıtlar { "data": … } biçimindedir. Kimlikler JSON sayısıdır, para kuruş cinsindendir (…_cents), zamanlar RFC 3339'dur. Gövdeli istekler Content-Type: application/json ile gönderilir.

Kaynaklar

Her adres /api/v1 altındadır. Bir yazma izni, aynı kaynağın okuma iznini de içerir (write_orders siparişleri okur). İzinlerin açıklamaları: İzinler. Koddan üretilen tam liste, hangi yolların sayfalı olduğuyla: Uygulama API'si yolları.

Adres İzin
GET /shop Yok
GET /products, GET /products/{id}, GET /products/{id}/variants read_products
POST /products, PUT /products/{id}, PUT /variants/{id}/cost write_products
GET /collections, GET /collections/{id} read_products
PUT /variants/{id}/inventory write_inventory
GET /locations read_locations
GET /inventory_levels, GET /inventory_levels/history read_inventory
PUT /inventory_levels, POST /inventory_levels/adjust, POST /inventory_levels/move write_inventory
GET /orders, GET /orders/{id}, GET /orders/{id}/refunds read_orders
PUT /orders/{id}, POST /orders/{id}/cancel, POST /orders/{id}/refunds write_orders
POST /orders/{id}/fulfillments, PUT /orders/{id}/fulfillments/{fulfillmentID}, POST /orders/{id}/fulfillments/{fulfillmentID}/cancel, POST /orders/{id}/fulfillments/{fulfillmentID}/events write_fulfillments
POST /orders/{id}/capture write_payments
GET /customers, GET /customers/{id} read_customers
GET /customer_segments, GET /customer_segments/{id}, GET /customer_segments/{id}/customers read_customers
PUT /customers/{id} write_customers
GET /marketing/audience read_marketing_audience
POST /customers/{id}/marketing_consent write_marketing_consent
GET, POST /discount_codes; GET, PUT, DELETE /discount_codes/{id} write_discounts
GET /gift_cards, GET /gift_cards/{id} read_gift_cards
POST /gift_cards, PUT /gift_cards/{id}, POST /gift_cards/{id}/disable write_gift_cards
GET /draft_orders, GET /draft_orders/{id} read_draft_orders
POST /draft_orders; PUT, DELETE /draft_orders/{id}; POST /draft_orders/{id}/complete, POST /draft_orders/{id}/send_invoice write_draft_orders
GET /companies, GET /companies/{id} read_companies
POST /companies; PUT, DELETE /companies/{id}; POST /companies/{id}/locations; PUT, DELETE /companies/{id}/locations/{locationID}; POST /companies/{id}/contacts; PUT, DELETE /companies/{id}/contacts/{customerID} write_companies
POST /channels; GET /channels/{id}/products; PUT, DELETE /channels/{id}/products/{productID}; POST /channels/{id}/orders write_channels
GET /metaobject_definitions, GET /metaobject_definitions/{id}, GET /metaobjects, GET /metaobjects/{id} read_metaobjects
POST /metaobject_definitions; PUT, DELETE /metaobject_definitions/{id}; POST /metaobjects; PUT, DELETE /metaobjects/{id} write_metaobjects
GET /translations read_translations
PUT /translations write_translations
GET, PUT /pixels/{pixelID}/settings write_pixels
POST /sms, POST /sms/{id}/status write_sms
GET, PUT, DELETE /metafields Yok (aşağıda)
GET /webhook_deliveries, POST /webhook_deliveries/{id}/replay Yok
GET /function_runs Yok
GET /billing/plans; GET, POST /billing/subscriptions; GET /billing/subscriptions/{id}; POST /billing/subscriptions/{id}/cancel; POST /billing/subscriptions/{id}/usage_records; GET, POST /billing/credits Yok

Faturalandırma

Uygulama mağazadan kendi ücretlendirmesini ister; izin gerekmez ve uygulama yalnızca kendi ücretlendirmelerini görür. Fiyatlar KDV hariç ve kuruş cinsindendir; KDV'yi Biticaret'in faturası ekler. Adresler yalnızca herkese açık (public) uygulamalar içindir; özel bir uygulamaya 403 billing_not_available döner.

  1. POST /billing/subscriptions gövdesi name, price_cents (aylık fiyat), return_url ve isteğe bağlı trial_days, test alır. Kullanıma göre ücret için capped_amount_cents (aylık üst sınır) ve usage_terms ekleyin; ikisinden (aylık fiyat veya kullanım satırı) en az biri gerekir. test ücretlendirme hiç faturalanmaz.
  2. Yanıttaki confirmation_url adresine satıcının tarayıcısını gönderin; satıcı yönetim panelinde onaylar veya reddeder, tarayıcı return_url?charge_id=<id> adresine döner.
  3. Durum değişiklikleri app_subscriptions/update webhook'uyla gelir: pending, active, declined, cancelled, frozen (mağazanın faturası ödenmedi veya uygulama askıya alındı; sonra yeniden active), expired (satıcı 2 gün içinde karar vermedi) ve scheduled (yıllık bir planın yılı bitince başlayacak plan, starts_at).
  4. POST /billing/subscriptions/{id}/usage_records {description, price_cents, idempotency_key} ile kullanım ücreti yazar; ay içindeki toplam capped_amount_cents değerini aşamaz. balance_used_cents bu ayki kullanımdır.

Planlar. Uygulama planlarını iş ortağı portalında tanımlarsa (yönetilen fiyatlandırma) satıcı planını uygulamanın plan sayfasında seçer; GET /billing/plans fiyatlandırma biçimini ve mağazanın seçebileceği planları verir. Bir plan aylık (interval monthly, ay sonunda faturalanır) ya da yıllık (annual, her plan yılının başında faturalanır) olabilir ve bir kullanım satırı taşıyabilir. Plandan gelen ücretlendirmede plan alanı doludur; uygulamanın kendi oluşturduğu ücretlendirme her zaman aylıktır. Yönetilen fiyatlandırmadaki bir uygulamanın POST /billing/subscriptions çağrısı 409 managed_pricing döner. GET, POST /billing/credits uygulamanın mağazaya verdiği alacakları okur ve yazar.

Sayfalama

Liste adresleri limit alır (1 ile 100 arası, varsayılan 25) ve en yeniden eskiye döner. Yanıt bir sonraki sayfanın imlecini hem gövdede hem Link başlığında taşır:

Link: <…?limit=25&page_info=…>; rel="next"
{ "data": [], "page_info": { "next": "…", "previous": null } }

Sonraki sayfa için page_info değerini olduğu gibi geri gönderin; imleç opaktır.

Hatalar

Hatalar HTTP durumu ve şu gövdeyle gelir:

{ "error": { "code": "…", "message": "…" } }

code sabittir ve kod içindir; message insanlar içindir ve değişebilir.

Durum Kod Ne zaman
400 invalid_json Gövde beklenen biçimde JSON değil veya application/json olarak gönderilmedi.
401 invalid_token Jeton yok, bilinmiyor, iptal edilmiş veya başka bir mağazanın.
403 missing_scope Jetonda adresin istediği izin yok.
404 not_found Bu mağazada bu uygulama için böyle bir kaynak yok.
403 customer_data_not_approved Adres veya alan, uygulamanın onaylanmış müşteri verisi düzeyinden yükseğini istiyor.
409 conflict ve adrese özgü kodlar İstek kaynağın şimdiki haliyle çelişiyor (inventory_changed, insufficient_stock, consent_superseded gibi).
422 invalid_request Biçimi doğru ama platformun kabul etmediği bir istek.
422 idempotency_key_reused Aynı Idempotency-Key başka bir istekle kullanıldı.
423 store_suspended Mağaza askıya alındı; açık ödeme oturumlarının sonuçları dışında her çağrı reddedilir.
429 rate_limited Çağrı sınırı doldu; Retry-After kadar bekleyin.
503 store_moving Mağaza birkaç dakikalığına başka bir sunucuya taşınıyor: okumalar çalışır, yazmalar ve kod takası Retry-After kadar sonra yeniden denenmelidir.
5xx internal_error Platform başarısız oldu; aynı çağrı sonra başarılı olabilir.

400, 409 ve 422 isteğin kendisini reddeder: yeniden göndermek aynı yanıtı verir.

Çağrı sınırı

Her kurulumun bir kovası vardır: her çağrı bir ekler, kova saniyede 2 boşalır ve 40 çağrı alır. Bilinen bir jetona verilen her yanıt kovanın durumunu söyler:

X-Biticaret-Api-Call-Limit: 14/40

Kova doluyken yanıt 429 rate_limited ve saniye cinsinden Retry-After olur.