# 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](go-sdk.md) 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:

   ```http
   POST /oauth/access_token HTTP/1.1
   Host: <mağaza>
   Content-Type: application/x-www-form-urlencoded

   client_id=…&client_secret=…&code=…
   ```

   ```json
   { "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.

- **İmzalı yönlendirmeler** (1. ve 4. adım) imzayı `signature` sorgu parametresinde `t=<unix saniye>,v1=<hex>` biçiminde taşır. `v1 = hex(HMAC-SHA256(client_secret, t + "." + sorgu))`; sorgu, diğer bütün parametrelerin ada göre sıralanmış ve URL kodlanmış halidir. `store`, `store_id` veya `code` değerlerine güvenmeden önce imzayı denetleyin.
- **Gövdeli istekler** `X-Biticaret-Signature: t=…,v1=…` başlığını taşır; `v1 = hex(HMAC-SHA256(client_secret, t + "." + ham gövde))`. Webhook'ların imzası farklıdır: [Webhook'lar](webhooks.md#imza).
- İmzayı ham baytlar üzerinde, ayrıştırmadan önce ve sabit zamanlı karşılaştırmayla denetleyin; `t` değeri 5 dakikadan eskiyse reddedin.
- **Anahtar yenileme.** Gizli anahtar iş ortağı portalında yenilenir; eski anahtar seçilen süre boyunca (1 saat, 24 saat veya 7 gün) geçerli kalır. Bu sürede `X-Biticaret-Signature` her anahtar için bir `v1=` taşır ve kod takası iki anahtarı da kabul eder.

## Çağrılar

```http
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](../reference/scopes.md). Koddan üretilen tam liste, hangi yolların sayfalı olduğuyla: [Uygulama API'si yolları](../reference/api-routes.md).

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

- **Müşteri verisi düzeyi.** Müşteriye ulaşabilen bir uygulama yapılandırmasında `[customer_data]` bloğunda bir düzey ve gerekçe ister: 0 (müşteri verisi yok), 1 (ad ve iletişim bilgisi olmadan) veya 2 (ad ve iletişim bilgisiyle). Düzey sürüm incelemesinde onaylanır; aşağıdaki alanlar ve adresler hangi düzeyi istediklerini söyler. Onaylanandan yüksek düzey isteyen bir çağrı `403 customer_data_not_approved` döner.
- **Ürünler** (`/products`) seçenekleri, varyantları ve görselleriyle gelir. Bir ürün ilk 250 varyantını sırasıyla taşır; `variants_count` toplamı söyler, daha fazlası varsa `variants_truncated` `true` olur ve `GET /products/{id}/variants` hepsini sayfa sayfa verir (`products/*` webhook'ları da aynı biçimdedir). `PUT` yalnızca gönderilen alanları değiştirir; `variants` gönderilirse listenin yerini alır, `id` taşıyan varyant söylemediği alanları korur. Yeni bir varyantın `inventory_quantity` değeri `write_inventory` ister, var olanınki reddedilir (stok `/inventory_levels` ile değişir). Varyantın `image_id`, `compare_at_price_lawful` (karşılaştırma fiyatı, bugünkü fiyattan önceki 10 günün en düşük fiyatıysa ve satış fiyatından yüksekse `true`: üstü çizili "önceki fiyat" olarak yasal olarak gösterilebilir) alanları da gelir. `PUT /variants/{id}/cost` gövdesi `{"cost_cents": …}` yalnızca varyantın maliyetini yazar.
- **Mağaza** (`GET /shop`) izin istemez: `id`, `name`, `domain`, `url`, `primary_url` (mağazanın ana alan adındaki vitrin adresi; birincil özel alan adı hazırsa o, değilse `url`), `email`, `phone`, `locale`, `currency`, `logo_url`, `logo_width`, `plan` (`handle`, `name`) ve `partner_development` (geliştirme mağazasında `true`).
- **Müşteriler** (`/customers`): `id`, `email`, `first_name`, `last_name`, `phone`, `note` (satıcının müşteriye yazdığı özel not), `accepts_marketing`, `email_marketing_consent`, `sms_marketing_consent`, `tags`, `orders_count`, `total_spent_cents`, `default_address`, `created_at`, `updated_at`. Ad, e-posta, telefon, adres ve not müşteri verisi düzeyi 2 ister; düzey 1'de boş gelir. `PUT /customers/{id}` yalnızca `tags` yazar; not okunur, uygulamadan değiştirilemez.
- **Müşteri segmentleri** (`/customer_segments`) mağazanın kayıtlı müşteri süzgeçleridir: `id`, `name`, `rules`, `created_at`, `updated_at`. `GET /customer_segments/{id}/customers` segmente şu anda giren müşterileri `/customers` gibi, sayfalı verir.
- **İndirimler** (`/discount_codes`) kod ya da otomatik olabilir: `method` `code` ya da `automatic`tir ve yalnızca oluştururken verilir; otomatik indirimin `code` alanı boştur, alıcı kod yazmadan uygun her ödemede uygulanır ve sepette `title` ile görünür. `discount_type` `percentage`, `fixed_amount`, `free_shipping` ya da `buy_x_get_y`dir. X al Y kazan indiriminde `value` Y ürünlerinden düşülen yüzdedir (baz puan, 10000 bedava), `applies_to` Y tarafıdır ve `buy_x_get_y` `{buy_quantity, buys, get_quantity, uses_per_order}` X tarafını ve adetleri verir (`uses_per_order` null ise sınırsız). `combines_with` `{product, order, shipping}` indirimin hangi sınıftaki diğer indirimlerle birlikte uygulanabileceğini söyler; çakışmada alıcıya en çok kazandıran birleşim seçilir. `min_quantity` en az ürün adedidir. `buyer_eligibility` `segments` olduğunda `customer_segment_ids` müşteri segmentlerinin, `customers` olduğunda `customer_ids` seçilen müşterilerin kimlikleridir; ikisinde de yalnızca hesabıyla giriş yapmış müşteri yararlanır, misafir alıcı hiçbir segmente girmez ve hiçbir seçili müşteri sayılmaz. Müşteri verisi düzeyi 1'in altında şirket şubeleri, segmentler ve müşteriler yanıtta null gelir, gönderilirse reddedilir.
- **Pazarlama izni** yalnızca mağazada tutulur: pazarlama uygulaması kitlesini buradan okur ve her ret kararını buraya yazar, böylece bir yerde izni geri alan müşteri her yerde geri almış olur. İki adres de müşteri verisi düzeyi 2 ister; düşük düzeyde `403 customer_data_not_approved` döner.
  - `GET /marketing/audience?channel=email` yalnızca izni açık, verilerinin silinmesini istememiş ve adresi gönderimden çıkarılmamış (kalıcı olarak geri dönen veya şikâyet eden) müşterileri, mağazanın kendi kampanyalarıyla aynı süzgeçle listeler (sayfalı): `id`, `email`, `first_name`, `locale`, `consent_updated_at`, `source`. `channel=sms` SMS izni açık, izni bir Türkiye cep telefonu numarası için olan ve verilerinin silinmesini istememiş müşterileri listeler; `email` yerine `phone` (iznin verildiği numara, E.164) gelir. `read_customers` ile gelen müşteride de `email_marketing_consent` ve `sms_marketing_consent` (`state`: `subscribed`, `unsubscribed` veya `not_subscribed`; `consent_updated_at`; `source`; SMS'te izin açıkken `phone`) bulunur.
  - `POST /customers/{id}/marketing_consent` gövdesi `{"channel": "email", "state": "unsubscribed"}` izni her zaman geri alır. `"state": "subscribed"` için kanıt gerekir: `collected_at` (müşterinin onay verdiği an, RFC 3339) ve `consent_text` (onaylanan metin, en çok 2000 karakter); varsa `ip` ve `user_agent` de gönderin. Kanıtsız izin `422 invalid_request` döner. `collected_at` müşterinin son izin değişikliğinden önceyse `409 consent_superseded`, müşteri verilerinin silinmesini istediyse `409 erasure_requested` döner. Kaynak `app:<uygulama>` olarak kaydedilir; SMS sağlayıcı uygulaması İYS'de yapılan retleri `"source": "iys"` ile yazar. `channel=sms` aynı kanıtı ister; izin müşterinin telefonu için kaydedilir, telefon bir Türkiye cep telefonu numarası değilse `422 no_mobile_number` döner ve hiçbir şey yazılmaz; SMS izni zaten açıksa (hangi numara için olursa olsun) izin çağrısı bir şey değiştirmez. SMS izninin geri alınmasında isteğe bağlı `phone` gönderebilirsiniz: geri alma yalnızca bu numara hâlâ müşterinin izinli SMS numarasıysa uygulanır, değilse hiçbir şey yazılmaz ve `changed` `false` döner. Numara, izin verirken olduğu gibi E.164 biçimine çevrilir; `phone` e-posta değişikliğinde, izin verirken ya da Türkiye cep telefonu numarası değilse `422` döner. SMS izni e-posta iznine, e-posta izni SMS iznine dokunmaz. Yanıt müşterinin güncel iznidir ve `changed` bu çağrının bir şey değiştirip değiştirmediğini söyler; `Idempotency-Key` başlığıyla tekrarlanan çağrı ilk yanıtı döner.
  - Her değişiklik `customers/marketing_consent_update` webhook'u ile bildirilir ([Webhook'lar](webhooks.md)).
- **Meta alanlar** kendi izinlerini istemez: uygulama kendi ad alanlarını her zaman okur ve yazar; bir kaynağın başka ad alanları o kaynağın iznini ister.
- **Siparişler** (`/orders`) satırları, gönderimleri, iadeleri, indirim kodları ve satış kanalıyla gelir. Vergi KDV oranı başına `tax_lines` içinde (`rate_bps`, `base_cents`, `tax_cents`) siparişin kaydettiği gibidir; kargo satırı kendi `tax_cents` değerini taşır. Düzey 2'nin altında sipariş notu yazılmaz, korunur.
- **Gönderimler** `write_fulfillments` ister. `POST /orders/{id}/fulfillments` `line_items` (`line_item_id`, `quantity`; boşsa kalan her şey), takip bilgisi ve `notify_customer` alır. Kargo uygulaması bir gönderimi `…/cancel` ile iptal eder (ürünler yeniden gönderilmeyi bekler) ve ilerlemesini `…/events` ile bildirir: `{"status": "in_transit" | "delivered" | "failed", "message": "…"}`. Aynı durum ikinci kez bir şey değiştirmez, iptal edilmiş gönderime olay `409` döner; her yeni durum siparişin zaman çizelgesine uygulamanın adıyla yazılır.
- **Stok ayarlaması** (`POST /inventory_levels/adjust`) `variant_id`, `location_id`, işaretli `amount`, `deny_negative` (stok eksiye düşecekse `409 insufficient_stock`), `reason` (verilmezse `app`; `received`, `damaged`, `lost` veya `correction`) ve en çok 200 karakterlik `note` alır. `Idempotency-Key` başlığıyla tekrarlanan çağrı ilk sonucu döner.
- **Stok geçmişi** (`GET /inventory_levels/history`) bir stok seviyesindeki her değişikliği en yeniden eskiye döner; `variant_id`, `location_id` ve `created_at_min` (RFC 3339) ile daraltılır, hiçbiri verilmezse mağazanın tüm geçmişi gelir. Her satır `variant_id`, `location_id`, `delta`, `available_after`, `reason` (`manual`, `order`, `order_cancel`, `restock_refund`, `checkout_release`, `move`, `app`, `import`, `correction`, `received`, `damaged`, `lost`), `order_id` (siparişin numarası, yoksa `null`), `actor_type` (`staff`, `app` ya da `system`; kişi adı verilmez) ve `created_at` taşır. Müşteri bilgisi içermez; personelin notu yalnızca yönetim panelinde görünür.
- **Meta nesneler** (`/metaobject_definitions`, `/metaobjects`) mağazanın kendi veri türleri ve onların kayıtlarıdır. Tanım `{"metaobject_definition": {type, name, description, display_name_key, fields, web_pages, url_handle, access}}` ile yazılır; `type` yalnızca oluştururken verilir, `PUT` alanların tamamını değiştirir; bir tanım en çok 40 alan taşır. Kayıt `{"metaobject": {type, handle, status, fields}}` ile yazılır (`status` `draft` veya `active`); `PUT` yalnızca söylediği alanları değiştirir. `GET /metaobjects?type=…` bir türün kayıtlarını en yeniden eskiye verir; öteki listeler gibi sayfalanır (`limit` 1-100, varsayılan 25, `page_info` imleci ve `Link` başlığı); `type` zorunludur. **Uygulamaya ayrılmış türler:** `$app:<ad>` biçimindeki bir tür yalnızca onu oluşturan uygulamanındır: başka uygulamalar onu görmez (`404`), yalnızca sahibi değiştirir. `access.admin` (`merchant_read` veya `merchant_read_write`) satıcının yönetim panelinde kayıtları yalnızca görüp göremeyeceğini, `access.storefront` (`none` veya `public_read`) vitrinin onları okuyup okuyamayacağını söyler; verilmezse yeni tür `merchant_read` ve `none` olur.
- **Çeviriler** (`GET`, `PUT /translations`) `resource_type` olarak `product`, `product_option`, `product_option_value`, `product_variant`, `collection`, `page`, `blog`, `article`, `menu`, `metaobject` veya `legal_template` kabul eder (tema metinlerini yalnızca yönetim paneli çevirir); başka bir tür `422` ve kabul edilen türlerin listesiyle döner.
- **Hediye kartını devre dışı bırakma:** `POST /gift_cards/{id}/disable` gövde okumaz; gövdesiz ya da `{}` ile çağrılır. Gövde gönderiyorsanız `application/json` olmalıdır, değilse `400 invalid_json` döner.
- **SMS** (`write_sms`): `POST /sms` gövdesi `{"order_id": …, "body": "…"}` siparişin alıcısına tek bir işlem SMS'i gönderir. Telefonu platform siparişten alır ve SMS'i mağazanın SMS sağlayıcı uygulamasına iletir; yanıt `202` ile `{id, status, encoding, segments, …}` olur, telefon ve metin dönmez. Mağazanın SMS sağlayıcısı yoksa `409 no_sms_provider`, siparişte cep telefonu yoksa `422 no_phone` döner; `Idempotency-Key` başlığı tekrarı tek SMS yapar. SMS sağlayıcı uygulama (`sms_provider = true`) kendisine `sms/send` ile gelen SMS'in sonucunu `POST /sms/{id}/status` ile bildirir: `{"status": "sent" | "delivered" | "failed", "provider_message_id": "…", "error": "…"}`. Başka bir uygulamanın SMS'i `404` döner; durum yalnızca ileri gider.
- **Ürün maliyeti:** bir varyantın `cost_cents` alanı yalnızca `read_product_costs` ile dolar. **Vergi numarası:** şahıs şirketinin 11 haneli numarası yalnızca `read_company_tax_ids` ile açık gelir.
- **Faturalandırma:** [aşağıda](#faturalandirma).
- `POST /emails` (`write_emails`) yalnızca Biticaret'in kendi uygulamalarına açıktır.
- Ödeme uygulamalarının oturum adresleri bu sayfanın konusu değildir. Ödeme uygulamaları şimdilik yalnızca Biticaret'in kendi uygulamalarıdır; üçüncü taraf ödeme uygulaması yayımlama yolu henüz açık değildir.

## 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:

```http
Link: <…?limit=25&page_info=…>; rel="next"
```

```json
{ "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:

```json
{ "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:

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

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