Borkol Docs ana sayfası

Sepetler ve Checkout

Sepet satırları

Varyant, made-to-measure ürün ve ondalıklı adet kuralları dahil olmak üzere sepete ürün ekleme, satır adetlerini değiştirme ve satırları kaldırma.

Markdown olarak görüntüle

Sepet satırları, sepetteki ürünleri tutar. Her satır, ekleme anında ürün adının ve SKU'nun anlık görüntüsünü alır, çözümlenen birim fiyatı minör birim cinsinden saklar ve made-to-measure ürünlerde tam bir yapılandırma anlık görüntüsü tutar. Üç endpoint'in tümü commerce:write scope'u ve active bir sepet gerektirir ve sepet sahipliği kontrolünden geçer (Sepetler sayfasına bakın). Her endpoint, GET /v1/api/commerce/carts/{id} ile aynı şekle sahip tam sepet zarfını döndürür.

Capability kuralları

Bir ürünün nasıl ekleneceği capability değerine bağlıdır (bkz. Ürünler):

  • Aktif varyantı olan standard ürünler: variant_id zorunludur ve ürünün aktif bir varyantı olmalıdır.
  • Varyantı olmayan standard ürünler: variant_id gönderilmemelidir.
  • made_to_measure ürünler: configuration zorunludur ve variant_id yasaktır. Yapılandırma, configurator motoru tarafından fiyatlandırılan {"dimensions": {...}, "choices": ["choice_id", ...]} şeklinde bir nesnedir; boyutlar tam sayıdır. Satır, bir config_hash ile birlikte attributes.configuration altında tam bir anlık görüntü saklar (boyutlar, seçimler, fiyat dökümü, bileşen listesi, matris hücresi). Bileşen stoku, configurator bileşeni başına rezerve edilir.
  • standard ürünler için configuration yasaktır.
  • capability_active değeri false olan bir ürün eklenemez: standard ürünleri commerce modülü, made_to_measure ürünleri configurator modülü satar.

Adetler

quantity, sıfırdan büyük, en fazla 8 tam sayı basamağı ve en fazla 3 ondalık basamağı olan bir JSON sayısıdır (en fazla 99999999.999). JSON sayısı olarak veya noktalı düz bir ondalık string olarak ("0.75") gönderin; ondalık virgül veya üs içeren bir string ("0,75", "1e3") reddedilir. unit değeri piece olan bir ürün yalnızca tam sayı kabul eder (2 veya 2.0, asla 2.5); diğer birimlerdeki bir ürün (kg, m2, hour, ...) en fazla üç ondalık basamak kabul eder, örneğin 0.75. Adetler JSON sayısı olarak döner (0.75, 12). Satır toplamı, birim fiyat çarpı adettir ve yarım yukarı yuvarlanarak tam küçük birime getirilir.

Ret kodları

Bir satır eklenemediğinde 422 gövdesi, message ve errors alanlarının yanında en üst düzeyde makine tarafından okunabilir bir code taşır:

codeAnlamı
CAPABILITY_INACTIVEÜrünün capability'si şu anda satılamaz (capability_active false): onu satan modül mağaza için devre dışı. errors.product_id üzerinde bildirilir.
INVALID_CONFIGURATIONVaryant veya yapılandırma ürüne uymuyor: varyant eksik, bilinmiyor veya izinli değil; yapılandırma eksik veya bir standard ürün için gönderilmiş; ya da configurator motoru yapılandırmayı reddetti (hata anahtarları, örneğin dimensions.width, aynen aktarılır).
NOT_PURCHASABLEÜrün satılamaz, örneğin çözümlenebilir bir fiyatı yok. errors.product_id üzerinde bildirilir.
Response (422, line refusal)
{
  "message": "Width must be a whole number.",
  "errors": {
    "dimensions.width": ["Width must be a whole number."]
  },
  "code": "INVALID_CONFIGURATION"
}

Düz girdi doğrulaması (eksik veya hatalı product_id ya da quantity, bilinmeyen veya pasif bir ürün, piece ürün için ondalıklı adet) code olmadan standart 422 zarfını kullanır. code varsa ona göre dallanın, yoksa errors alanına dönün.

Satırlar; ürün, varyant ve yapılandırma hash'i kombinasyonu üzerinden tekilleştirilir: aynı kombinasyonu tekrar eklemek mevcut satırla birleşir, adetleri toplar ve birim fiyatı yeni adet kademesinde yeniden çözümler.

Birim fiyatlar, request'in fiyatlandırma bağlamına göre çözümlenir: varsa X-Customer-Token ile tanımlanan müşteri, yoksa sepetin bağlı müşterisi, o da yoksa misafir fiyatlandırması.

POST /v1/api/commerce/carts/{id}/lines

Sepete bir ürün ekler veya mevcut özdeş bir satırla birleştirir. Tam sepeti 201 durumuyla döndürür.

Parametreler

Path

AdTürZorunluAçıklama
idstring (UUID)evetSepet id'si. active bir sepet olmalıdır.

Body

AdTürZorunluAçıklama
product_idstring (UUID)evetEklenecek ürün. Mağazanın aktif bir ürünü olmalıdır.
variant_idstring (UUID) veya nullkoşulluÜrünün aktif varyantları varsa zorunludur; aksi halde yasaktır ve made_to_measure ürünler için her zaman yasaktır.
quantitynumberevetSıfırdan büyük, en fazla 3 ondalık basamak; piece ürün için tam sayı (yukarıdaki Adetler bölümüne bakın). Birleştirilmiş satır adedi, politikanın max_quantity_per_line değerini aşamaz.
configurationobjectkoşullumade_to_measure ürünler için zorunlu, diğerleri için yasaktır. Şekil: {"dimensions": {...}, "choices": [choice_ids]}, boyutlar tam sayı olarak. Configurator motoru tarafından doğrulanır.

Header'lar

AdTürZorunluAçıklama
X-Customer-TokenstringhayırFiyatlandırma bağlamını seçer; sepet misafir olmayan bir müşteriye bağlıysa zorunludur.
Request
curl -X POST https://api.borkol.com/v1/api/commerce/carts/9d3f2a10-6b7c-4e6d-9f21-8a54c1d2e3f4/lines \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "variant_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "quantity": 2
  }'
Request (JS)
const res = await fetch(
  `https://api.borkol.com/v1/api/commerce/carts/${cartId}/lines`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      product_id: "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      variant_id: "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      quantity: 2,
    }),
  }
);
const { data: cart } = await res.json();
Response
{
  "data": {
    "id": "9d3f2a10-6b7c-4e6d-9f21-8a54c1d2e3f4",
    "status": "active",
    "lines": [
      {
        "id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
        "product_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "variant_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "name": "Garden Chair",
        "sku": "CHAIR-GRN-M",
        "quantity": 2,
        "unit_price_amount": 2250,
        "unit_price": { "amount": 2250, "currency": "EUR" },
        "line_total": { "amount": 4500, "currency": "EUR" },
        "attributes": null
      }
    ],
    "...": "same cart shape as GET /v1/api/commerce/carts/{id}"
  }
}

Bir made_to_measure ürün için oluşturulan satır, yapılandırma anlık görüntüsünü taşır. components[].qty, yapılandırılmış birim başına kesin bir ondalık string'dir (rezerve edilen stok için satır adediyle çarpın):

Response (made-to-measure line excerpt)
{
  "attributes": {
    "configuration": {
      "dimensions": { "width": 120, "depth": 180 },
      "choices": ["c1d2e3f4-..."],
      "breakdown": [
        { "label": "Base", "amount": 18900 },
        { "label": "Motor: Motorised", "amount": 7500 }
      ],
      "components": [{ "product_id": "...", "qty": "2.16" }],
      "matrix": { "id": "...", "name": "Fabric blinds" }
    }
  }
}

Hatalar

Satır retleri, mesajın errors içinde ilgili alana eklendiği ve en üst düzeyde bir code taşıyan 422 hatalarıdır (yukarıdaki Ret kodları bölümüne bakın):

DurumGövdeNe zaman
422errors.product_id: ["Product is not available."]Ürün bilinmiyor veya aktif değil. code yok.
422errors.product_id: ["Product is not available."], code: "NOT_PURCHASABLE"Ürün mevcut ve aktif ama satılamaz, örneğin çözümlenebilir bir fiyatı yok.
422errors.product_id: ["Product is not available."], code: "CAPABILITY_INACTIVE"Ürünün capability'si mağaza için aktif değil (capability_active false).
422errors.variant_id: ["Choose a variant for this product."], code: "INVALID_CONFIGURATION"Ürünün aktif varyantları var ve variant_id gönderilmemiş.
422errors.variant_id: ["Variant is not available."], code: "INVALID_CONFIGURATION"Varyant id'si, ürünün aktif bir varyantına çözümlenmiyor.
422errors.variant_id: ["This product has no variants."], code: "INVALID_CONFIGURATION"Varyantı olmayan bir ürün için variant_id gönderilmiş.
422errors.variant_id: ["Configurable products have no variants."], code: "INVALID_CONFIGURATION"Bir made_to_measure ürün için variant_id gönderilmiş.
422errors.configuration: ["Configure this product before adding it."], code: "INVALID_CONFIGURATION"configuration olmadan gönderilen made_to_measure ürün.
422errors.configuration: ["This product is not configurable."], code: "INVALID_CONFIGURATION"Bir standard ürün için configuration gönderilmiş.
422errors.choices, errors.choices.{choiceId}, errors.dimensions.{key}, errors.configuration, code: "INVALID_CONFIGURATION"Configurator motoru hataları, teklif hata kataloğunda belgelendiği gibi kendi alan anahtarlarına eklenir; ondalıklı bir boyut için {Label} must be a whole number. dahil.
422errors.quantity: ["The quantity must be a whole number."]piece ürün için ondalıklı adet. code yok.
422errors.quantity: ["..."]Adet eksik, düz bir ondalık sayı değil (virgül, üs, 3'ten fazla ondalık basamak veya 8'den fazla tam sayı basamağı) ya da sıfırdan büyük değil. code yok.
422{"message": "Quantity exceeds the per-line maximum.", "code": "cart_constraint"}Birleştirilmiş adet, max_quantity_per_line değerini aşacaktı.
422{"message": "Cart line limit reached.", "code": "cart_constraint"}Yeni bir ayrı satır eklemek, max_lines değerini aşacaktı.
404{"message": "..."}Sepet bilinmiyor, süresi dolmuş veya active değil.
403sahiplik, scope, modül veya askıya alma gövdesiSepetler sayfasına bakın.
429{"message": "Too Many Attempts."}Rate limit aşıldı.

PATCH /v1/api/commerce/carts/{id}/lines/{lineId}

Bir satırın adedini, eklemeyle aynı adet kurallarıyla değiştirir (piece ürün için tam sayı). Yapılandırılmamış ürün satırları, request'in fiyatlandırma bağlamı kullanılarak yeni adette (kademeli fiyatlandırma) yeniden fiyatlandırılır. Yapılandırılmış satırlar ve varyantı sonradan devre dışı bırakılmış satırlar, saklanan birim fiyatlarını korur; kullanılamazlık checkout'ta ortaya çıkar. Tam sepeti 200 durumuyla döndürür.

Parametreler

Path

AdTürZorunluAçıklama
idstring (UUID)evetSepet id'si. active bir sepet olmalıdır.
lineIdstring (UUID)evetSatır id'si. Bu sepete ait olmalıdır.

Body

AdTürZorunluAçıklama
quantitynumberevetSıfırdan büyük, en fazla 3 ondalık basamak, piece ürün için tam sayı; en fazla politikanın max_quantity_per_line değeri.

Header'lar

AdTürZorunluAçıklama
X-Customer-TokenstringhayırFiyatlandırma bağlamını seçer; sepet misafir olmayan bir müşteriye bağlıysa zorunludur.
Request
curl -X PATCH https://api.borkol.com/v1/api/commerce/carts/9d3f2a10-6b7c-4e6d-9f21-8a54c1d2e3f4/lines/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9 \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 3}'
Response
{
  "data": {
    "id": "9d3f2a10-6b7c-4e6d-9f21-8a54c1d2e3f4",
    "lines": [{ "id": "5e6f7a8b-...", "quantity": 3, "...": "..." }],
    "...": "same cart shape as GET /v1/api/commerce/carts/{id}"
  }
}

Hatalar

DurumGövdeNe zaman
422{"message": "...", "errors": {"quantity": ["..."]}}Adet eksik veya hatalı, sıfırdan büyük değil ya da piece ürün için ondalıklı. Bu endpoint hiçbir zaman bir ret code'u ile yanıt vermez: artık çözümlenemeyen bir satır, ödemeye kadar fiyatını korur.
422{"message": "Quantity exceeds the per-line maximum.", "code": "cart_constraint"}max_quantity_per_line değerinin üzerinde.
404{"message": "..."}Sepet bilinmiyor veya active değil ya da satır bu sepete ait değil.
403sahiplik, scope, modül veya askıya alma gövdesiSepetler sayfasına bakın.
429{"message": "Too Many Attempts."}Rate limit aşıldı.

DELETE /v1/api/commerce/carts/{id}/lines/{lineId}

Bir satırı sepetten kaldırır ve sepet için tutulan tüm stok rezervlerini serbest bırakır. Kaldırılan satır olmaksızın tam sepeti 200 durumuyla döndürür.

Parametreler

Path

AdTürZorunluAçıklama
idstring (UUID)evetSepet id'si. active bir sepet olmalıdır.
lineIdstring (UUID)evetSatır id'si. Bu sepete ait olmalıdır.

Body yok.

Request
curl -X DELETE https://api.borkol.com/v1/api/commerce/carts/9d3f2a10-6b7c-4e6d-9f21-8a54c1d2e3f4/lines/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9 \
  -H "Authorization: Bearer {api_key}"
Response
{
  "data": {
    "id": "9d3f2a10-6b7c-4e6d-9f21-8a54c1d2e3f4",
    "lines": [],
    "...": "same cart shape as GET /v1/api/commerce/carts/{id}"
  }
}

Hatalar

DurumGövdeNe zaman
404{"message": "..."}Sepet bilinmiyor veya active değil ya da satır bu sepete ait değil.
403sahiplik, scope, modül veya askıya alma gövdesiSepetler sayfasına bakın.
429{"message": "Too Many Attempts."}Rate limit aşıldı.