Borkol Docs ana sayfası

Sepetler ve Checkout

Checkout

Sepet politikası uygulaması, fiyat kayması ve stok çakışmaları, teklif tetikleyicileri ve idempotent tekrar ile aktif bir sepeti siparişe dönüştürme.

Markdown olarak görüntüle

Checkout, active bir sepeti pending_payment durumunda bir siparişe dönüştürür. Sepet akışındaki en katı endpoint'tir: her satırı yeniden doğrular, her fiyatı yeniden çözümler, stoku ve indirim kullanım limitlerini yeniden kontrol eder ve mağazanın sepet politikası ile teklif tetikleyicilerini uygular. Başarılı bir checkout sepeti converted olarak işaretler ve bir sipariş onay e-postasını kuyruğa alır.

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

commerce:write gerektirir. Olanlar, sırasıyla:

  1. Sahiplik. Zaten dönüştürülmüş bir sepetin idempotent tekrarının muaf tutulabilmesi için middleware yerine satır içinde uygulanır: misafir olmayan bir müşteriye bağlı active bir sepet, eşleşen X-Customer-Token'ı gerektirir; aksi halde 403 {"message": "This cart belongs to a customer."}. Misafire bağlı sepetler (e-posta yakalamadan gelen) açık kalır.
  2. Doğrulama. Adresler ve geçerli olduğunda kargo yöntemi doğrulanır (body tablosuna bakın).
  3. Müşteri token'ı. X-Customer-Token mevcutsa çözümlenmesi gerekir; aksi halde 401 {"message": "Invalid customer token."}. Geçerli bir token, ortaya çıkan siparişi o müşteriye bağlar.
  4. Teklif tetikleyicileri. Mağazada sales modülü etkin ve teklif talepleri açıksa ve sepet bir tetikleyiciye takılırsa, checkout 409 {"code": "QUOTE_REQUIRED", "reasons": [...]} ile reddeder. Sepetin bunun yerine teklif isteği akışından geçmesi gerekir. Sepet response'undaki requires_quote ve quote_reasons alanları bunu önceden ortaya koyar.
  5. Sepet politikası. Tenant'ın sepet politikası doğrulanır; ihlaller, makine tarafından okunabilir bir code içeren 422'dir (hatalara bakın).
  6. Stok. Stok yeniden kontrol edilir ve checkout başlangıcında en fazla 60 dakikalığına bir stok rezervi tutulur; başarı durumunda bu rezerv gerçek bir düşüme dönüştürülür.
  7. Yeniden fiyatlandırma. Her satır yeniden doğrulanır (ürün aktif, capability hâlâ aktif, varyant aktif, yapılandırma hâlâ geçerli) ve yeniden fiyatlandırılır. Herhangi bir kayma veya kullanılamazlık, 409 sepet çakışmasıyla işlemi durdurur; storefront'un yeniden render edip tekrar deneyebilmesi için yenilenen fiyatlar sepete kalıcı olarak yazılır.
  8. İndirimler. Kullanım limitleri bir kilit altında yeniden kontrol edilir; tükenmiş bir indirim, discount_unavailable taşıyan bir 409 sepet çakışmasıyla işlemi durdurur.
  9. Sipariş oluşturma. Sipariş, mağaza başına ardışık bir tamsayı number ile oluşturulur, sepet converted olur, checkout hunisi olayları kaydedilir ve bir onay e-postası kuyruğa alınır.

Kargo zorunluluğu. shipping_method_id yalnızca iki koşul birden geçerli olduğunda zorunludur: sepette ürünü requires_shipping: true olan en az bir satır var ve mağazada en az bir aktif kargo yöntemi var. Aksi halde alan opsiyoneldir ve yok sayılır. Yalnızca kargo gerektirmeyen ürünlerden (indirmeler, lisanslar, hizmetler) oluşan sepetler bunu hiçbir zaman gerektirmez.

Idempotency. Zaten dönüştürülmüş bir sepet için checkout'u yeniden POST etmek, mevcut siparişi 200 durumuyla döndürür (ilk başarı 201 döner). Sepet id'si üzerindeki bir unique kısıtlama, eşzamanlı çift gönderimleri güvence altına alır. Tekrarda body, adres alanları için yine doğrulanır; ancak shipping_method_id zorunlu değildir ve sahiplik token kontrolü atlanır.

Parametreler

Path

AdTürZorunluAçıklama
idstring (UUID)evetSepet id'si.

Body

AdTürZorunluAçıklama
emailstringevetSipariş için geçerli e-posta adresi.
billing_addressobjectevetFatura adresi.
billing_address.namestringevetAd soyad.
billing_address.streetstringevetSokak ve numara.
billing_address.postal_codestringevetPosta kodu.
billing_address.citystringevetŞehir.
billing_address.countrystringevetTam olarak 2 karakter (ISO 3166-1 alpha-2).
shipping_addressobject veya nullhayırSerbest biçimli adres nesnesi; billing_address ile aynı şekil önerilir. Null veya gönderilmemesi, fatura adresine kargolama anlamına gelir.
shipping_method_idstring (UUID)koşulluSepette kargolanabilir satırlar varsa ve mağazada en az bir aktif kargo yöntemi varsa zorunludur. Aktif bir kargo yöntemi id'si olmalıdır. Aksi halde opsiyoneldir ve yok sayılır.

Header'lar

AdTürZorunluAçıklama
X-Customer-TokenstringhayırMevcutsa çözümlenmesi gerekir (aksi halde 401). Siparişi müşteriye bağlar ve 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/checkout \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "billing_address": {
      "name": "Jane Doe",
      "street": "Keizersgracht 1",
      "postal_code": "1015 CC",
      "city": "Amsterdam",
      "country": "NL"
    },
    "shipping_address": null,
    "shipping_method_id": "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a"
  }'
Request (JS)
const res = await fetch(
  `https://api.borkol.com/v1/api/commerce/carts/${cartId}/checkout`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "jane@example.com",
      billing_address: {
        name: "Jane Doe",
        street: "Keizersgracht 1",
        postal_code: "1015 CC",
        city: "Amsterdam",
        country: "NL",
      },
      shipping_address: null,
      shipping_method_id: "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
    }),
  }
);
if (res.status === 409) {
  const conflict = await res.json();
  // conflict.code === "QUOTE_REQUIRED" or conflict.message === "Cart contents changed."
}
const { data: order } = await res.json();
Response
{
  "data": {
    "id": "7f8a9b0c-1d2e-4f3a-b4c5-d6e7f8a9b0c1",
    "number": 1042,
    "status": "pending_payment",
    "email": "jane@example.com",
    "billing_address": {
      "name": "Jane Doe",
      "street": "Keizersgracht 1",
      "postal_code": "1015 CC",
      "city": "Amsterdam",
      "country": "NL"
    },
    "shipping_address": null,
    "currency": "EUR",
    "lines": [
      {
        "id": "8a9b0c1d-2e3f-4a4b-c5d6-e7f8a9b0c1d2",
        "product_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "variant_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "variant_label": "Green / M",
        "name": "Garden Chair",
        "sku": "CHAIR-GRN-M",
        "quantity": 2,
        "unit": "piece",
        "unit_price": { "amount": 2250, "currency": "EUR" },
        "line_subtotal": { "amount": 3347, "currency": "EUR" },
        "tax_rate": 21,
        "tax": { "amount": 703, "currency": "EUR" },
        "line_total": { "amount": 4050, "currency": "EUR" },
        "attributes": { "returnable": true, "lead_time_days": null }
      }
    ],
    "subtotal": { "amount": 3347, "currency": "EUR" },
    "tax_total": { "amount": 789, "currency": "EUR" },
    "total": { "amount": 4545, "currency": "EUR" },
    "tax_breakdown": [{ "rate": 21, "base": 3756, "tax": 789 }],
    "discount_total": { "amount": 0, "currency": "EUR" },
    "discount_breakdown": null,
    "shipping_method_name": "Standard",
    "shipping": { "amount": 409, "currency": "EUR" },
    "shipping_tax": { "amount": 86, "currency": "EUR" },
    "tracking_carrier": null,
    "tracking_number": null,
    "invoice_number": null,
    "invoiced_at": null,
    "customer_id": null,
    "contact_id": null,
    "placed_at": "2026-08-14T10:15:30+00:00",
    "created_at": "2026-08-14T10:15:30+00:00",
    "invoice_id": null
  }
}

Yeni bir siparişte durum 201, idempotent tekrarda 200'dür. Tam sipariş alan referansı Siparişler sayfasındadır; buradaki şekil birebir aynıdır.

409 sepet çakışması response'u

Yeniden fiyatlandırma bir kayma tespit ettiğinde, bir satır kullanılamaz hale geldiğinde, stok yetersiz olduğunda veya bir indirimin kullanım limiti tükendiğinde, checkout 409 durumuyla işlemi durdurur:

Response (409 cart conflict)
{
  "message": "Cart contents changed.",
  "cart": {
    "id": "9d3f2a10-6b7c-4e6d-9f21-8a54c1d2e3f4",
    "lines": [
      {
        "id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
        "unavailable": false,
        "...": "same line shape as GET /v1/api/commerce/carts/{id}"
      }
    ],
    "...": "same cart shape as GET /v1/api/commerce/carts/{id}"
  },
  "out_of_stock": [
    {
      "product_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "variant_id": null,
      "requested": 2,
      "available": 1
    }
  ],
  "discount_unavailable": [
    {
      "discount_id": "71c9e0aa-2f4b-4d31-9a77-0b1c2d3e4f5a",
      "name": "Welcome 10%",
      "code": "WELCOME10"
    }
  ]
}

cart, yenilenmiş (zaten kalıcı olarak yazılmış) fiyatlarla tam sepet kaynağıdır ve her satırda fazladan bir boolean unavailable alanı bulunur. Bir satır artık çözümlenemediğinde kullanılamaz olur: ürün geri çekilmiş, varyant devre dışı bırakılmış, yapılandırma artık geçerli değil veya capability artık aktif değil. out_of_stock[].requested ve .available JSON sayılarıdır ve ağırlık, uzunluk, alan veya hacimle satılan ürünlerde ondalıklı olabilir. out_of_stock ve discount_unavailable yalnızca geçerli olduklarında bulunur. Doğru istemci tepkisi, sepeti cart üzerinden yeniden render etmek, alışverişçinin onayını almak ve checkout'u yeniden POST etmektir.

Hatalar

DurumGövdeNe zaman
422{"message": "...", "errors": {...}}Adres veya e-posta doğrulama hatası; ayrıca Cart is empty. ve Choose a valid shipping method.
422{"message": "Log in to complete this order.", "code": "login_required"}Sepet politikası ihlali. Diğer kodlar: guest_only, b2b_approval_required, b2c_only, min_order_value.
401{"message": "Invalid customer token."}X-Customer-Token mevcut ama çözümlenemiyor.
403{"message": "This cart belongs to a customer."}Sahibinin token'ı olmadan, müşteriye bağlı aktif sepet.
409{"code": "QUOTE_REQUIRED", "reasons": ["product_purchasability"]}Sepetin teklif isteği akışından geçmesi gerekiyor. Nedenler: cart_threshold, configurator_choice, customer_group, product_purchasability. Yalnızca mağazada sales modülü etkin ve teklif talepleri açıkken.
409{"message": "Cart contents changed.", "cart": {...}, ...}Fiyat kayması, kullanılamayan satır, stok yetersizliği veya tükenmiş indirim (yukarıya bakın).
404{"message": "..."}Bilinmeyen sepet id'si veya başka bir mağazanın sepeti.
403scope, modül veya askıya alma gövdesiSepetler sayfasına bakın.
429{"message": "Too Many Attempts."}Rate limit aşıldı.