Borkol Docs ana sayfası

Siparişler ve Teklifler

Siparişler

Tek bir siparişi okuma, bir müşterinin sipariş geçmişini listeleme ve sipariş durum makinesi.

Markdown olarak görüntüle

Bir sipariş, checkout ile (veya bir teklifin kabul edilmesiyle) pending_payment durumunda oluşturulur. Storefront API tarafında siparişler salt okunurdur: tüm durum değişiklikleri (ödeme, kargo, iadeler) satıcı tarafında, dashboard üzerinden yapılır. Her iki endpoint de commerce:read scope'unu ve commerce modülünü gerektirir.

Sipariş durumu

DurumAnlamıGeçebileceği durumlar
pending_paymentOluşturuldu, ödeme bekleniyor.paid, cancelled
paidÖdeme alındı.shipped, cancelled, refunded
shippedTaşıyıcıya teslim edildi; takip alanları ayarlanmış olabilir.completed, refunded
completedSipariş karşılandı.refunded
cancelledKarşılanmadan önce iptal edildi. Envanter stoğa geri eklenir.terminal
refundedİade edildi. Envanter stoğa geri eklenir.terminal

Enum'u açık uçlu kabul edin: bir istemci, bilmediği gelecekteki bir durumu hata vermek yerine nötr şekilde göstermelidir.

Sipariş response yapısı

Her iki endpoint de siparişleri aynı şekilde serileştirir (tekil siparişler {"data": {...}} içine sarılır, geçmiş kayıtları sayfalanmış bir data dizisinin öğeleri olarak döner). Tüm para değerleri, amount alanı minör birim cinsinden olmak üzere {"amount": int, "currency": "EUR"} nesneleridir. Tarihler ISO-8601 dizeleridir.

AdTürZorunluAçıklama
idstring (UUID)her zamanSipariş id'si.
numberintegerher zamanMağaza başına bir sayaçtan gelen, kullanıcıya gösterilen sipariş numarası. UUID değil, düz tamsayıdır.
statusstringher zamanYukarıdaki durum tablosuna bakın.
emailstringher zamanCheckout sırasında verilen e-posta.
billing_addressobjecther zamanGönderildiği haliyle fatura adresi (name, street, postal_code, city, country).
shipping_addressobject or nullher zamanTeslimat adresi; fatura adresine gönderim yapıldığında null.
currencystringher zamanEUR.
linesarrayher zamanSipariş satırları, aşağıya bakın.
subtotalmoneyher zamanVergi hariç ürün toplamı.
tax_totalmoneyher zamanKargo vergisi dahil toplam vergi.
totalmoneyher zamanKargo dahil genel toplam.
tax_breakdownarrayher zamanOran bazında döküm, her biri {"rate": float, "base": int, "tax": int}.
discount_totalmoneyher zamanÖdeme sırasında uygulanan toplam ürün indirimi; varsa ücretsiz kargo indirimi hariçtir. İndirim uygulanmadığında amount 0 olur.
discount_breakdownarray or nullher zamanUygulanan her indirim için bir kayıt, her biri {"discount_id": uuid, "name": string, "code": string or null, "kind": "order" / "products" / "bogo" / "shipping", "amount": int}. İndirim uygulanmadığında null. Bir shipping kaydının amount değeri, alınmayan kargo ücretidir.
shipping_method_namestring or nullher zamanSeçilen kargo yönteminin ad snapshot'ı; kargo uygulanmadığında null.
shippingmoneyher zamanVergi hariç kargo ücreti. Kargo uygulanmadığında amount null olur.
shipping_taxmoneyher zamanKargo vergisi. Kargo uygulanmadığında amount null olur.
tracking_carrierstring or nullher zamanKargolama sırasında satıcı tarafından ayarlanır.
tracking_numberstring or nullher zamanKargolama sırasında satıcı tarafından ayarlanır.
invoice_numberinteger or nullher zamanMağaza başına fatura sayacı; satıcı siparişi faturaladığında ayarlanır.
invoiced_atstring (ISO-8601) or nullher zamanSiparişin faturalandığı zaman.
customer_idstring (UUID) or nullher zamanSiparişin bağlı olduğu kişi; misafir siparişlerinde null.
contact_idstring (UUID) or nullher zamancustomer_id ile aynı değer; bundan sonraki kanonik ad.
placed_atstring (ISO-8601) or nullher zamanSiparişin verildiği zaman.
created_atstring (ISO-8601) or nullher zamanSatırın oluşturulma zamanı.
invoice_idstring (UUID) or nullher zamanBu siparişten oluşturulan sales faturası, varsa. Fatura yoksa veya mağaza sales modülünü kullanmıyorsa null.

lines[]

AdTürZorunluAçıklama
idstring (UUID)her zamanSipariş satırı id'si.
product_idstring (UUID)her zamanÜrün.
variant_idstring (UUID) or nullher zamanVarsa varyant.
variant_labelstring or nullher zamanOkunabilir varyant etiketi snapshot'ı, örneğin "Green / M".
namestringher zamanÜrün adı snapshot'ı.
skustring or nullher zamanSKU snapshot'ı.
quantitynumberher zamanSipariş edilen adet: piece ürün için tam sayı, diğer tüm birimler için en fazla üç ondalık basamak (örneğin 0.75).
unitstringher zamanSipariş anında ürünün birimi: piece, kg, g, l, m, m2, m3 veya hour.
unit_pricemoneyher zamanBirim fiyat.
line_subtotalmoneyher zamanVergi hariç satır toplamı.
tax_ratenumberher zamanSatıra uygulanan vergi oranı yüzdesi.
taxmoneyher zamanSatırın vergisi.
line_totalmoneyher zamanVergi dahil satır toplamı.
attributesobject or nullher zamanSipariş verildiğinde kaydedilen satır anlık görüntüsü, aşağıya bakın.

lines[].attributes

AdTürZorunluAçıklama
returnablebooleankoşulluSatırın iade edilip edilemeyeceği. made_to_measure ürün için her zaman false; aksi halde sipariş anında ürünün returnable değeri. Ürünü olmayan bir satır (özel bir teklif satırı veya teklif kabul edilmeden önce silinmiş bir ürün) true olur ve lead_time_days null olur.
lead_time_daysinteger or nullkoşulluSipariş anında ürünün gün cinsinden teslim süresi; yoksa null.
configurationobjectkoşulluYalnızca made-to-measure satırlar: sepet satırındaki gibi yapılandırma anlık görüntüsü (boyutlar, seçimler, döküm, bileşenler, matris). components[].qty kesin bir ondalık string'dir.

returnable ve lead_time_days, 2026-10-11 tarihinden itibaren checkout, satıcının manuel siparişi veya kabul edilen bir teklif üzerinden verilen siparişlerin her satırına kaydedilir. Daha önceki siparişlerde attributes null olabilir veya bu anahtarları içermeyebilir: eksik bir değeri bilinmiyor olarak değerlendirin.

GET /v1/api/commerce/orders/{id}

Tek bir siparişi, satırlarıyla birlikte id ile getirir. Bu endpoint'te müşteri sahipliği denetimi yoktur: yetkilendirme yalnızca sunucu tarafında saklanan bir sır olan tenant API anahtarıyla yapılır. Endpoint storefront sunucusu içindir; örneğin checkout'tan hemen sonra sipariş onay sayfasını render etmek için. Sunucunuz önce kendi sahiplik denetimini yapmadıkça, istemciden gelen bir sipariş id'siyle bu endpoint'i asla tarayıcılara proxy'lemeyin.

Parametreler

Path

AdTürZorunluAçıklama
idstring (UUID)evetSipariş id'si.
Request
curl https://api.borkol.com/v1/api/commerce/orders/7f8a9b0c-1d2e-4f3a-b4c5-d6e7f8a9b0c1 \
  -H "Authorization: Bearer {api_key}"
Response
{
  "data": {
    "id": "7f8a9b0c-1d2e-4f3a-b4c5-d6e7f8a9b0c1",
    "number": 1042,
    "status": "paid",
    "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": "PostNL",
    "tracking_number": "3STEST123456",
    "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
  }
}

Hatalar

DurumGövdeNe zaman
404{"message": "..."}Bilinmeyen veya soft-delete edilmiş sipariş id'si, ya da başka bir mağazanın siparişi.
403scope, modül veya askıya alma gövdesiAnahtar commerce:read scope'undan yoksun, modül devre dışı veya mağaza askıya alınmış.
429{"message": "Too Many Attempts."}Rate limit aşıldı.

GET /v1/api/commerce/my/orders

X-Customer-Token ile tanımlanan müşterinin, placed_at alanına göre azalan sırada (en yeni önce) sıralanmış, sayfalanmış sipariş geçmişi. Token zorunludur: bu, bir storefront'un "siparişlerim" sayfasının arkasındaki endpoint'tir. Standart Laravel sayfalama zarfını kullanır.

Parametreler

Query

AdTürZorunluAçıklama
per_pageintegerhayırSayfa boyutu, varsayılan 25, 1..100 aralığına sabitlenir.
pageintegerhayırSayfa numarası, varsayılan 1.

Headers

AdTürZorunluAçıklama
X-Customer-TokenstringevetMüşteri oturum token'ı. Eksikse veya çözümlenemezse: 401.
Request
curl "https://api.borkol.com/v1/api/commerce/my/orders?per_page=25&page=1" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: {customer_token}"
Request (JS)
const res = await fetch(
  "https://api.borkol.com/v1/api/commerce/my/orders?per_page=25",
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "X-Customer-Token": customerToken,
    },
  }
);
const { data: orders, meta } = await res.json();
Response
{
  "data": [
    {
      "id": "7f8a9b0c-1d2e-4f3a-b4c5-d6e7f8a9b0c1",
      "number": 1042,
      "status": "shipped",
      "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": null,
          "variant_label": null,
          "name": "Garden Chair",
          "sku": "CHAIR-GRN",
          "quantity": 2,
          "unit": "piece",
          "unit_price": { "amount": 2250, "currency": "EUR" },
          "line_subtotal": { "amount": 3719, "currency": "EUR" },
          "tax_rate": 21,
          "tax": { "amount": 781, "currency": "EUR" },
          "line_total": { "amount": 4500, "currency": "EUR" },
          "attributes": { "returnable": true, "lead_time_days": 3 }
        }
      ],
      "subtotal": { "amount": 3719, "currency": "EUR" },
      "tax_total": { "amount": 867, "currency": "EUR" },
      "total": { "amount": 4995, "currency": "EUR" },
      "tax_breakdown": [{ "rate": 21, "base": 4128, "tax": 867 }],
      "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": "PostNL",
      "tracking_number": "3STEST123456",
      "invoice_number": null,
      "invoiced_at": null,
      "customer_id": "0a1b2c3d-4e5f-4a6b-7c8d-9e0f1a2b3c4d",
      "contact_id": "0a1b2c3d-4e5f-4a6b-7c8d-9e0f1a2b3c4d",
      "placed_at": "2026-08-10T14:02:11+00:00",
      "created_at": "2026-08-10T14:02:11+00:00",
      "invoice_id": null
    }
  ],
  "links": {
    "first": "https://api.borkol.com/v1/api/commerce/my/orders?page=1",
    "last": "https://api.borkol.com/v1/api/commerce/my/orders?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      { "url": null, "label": "« Previous", "active": false },
      { "url": "https://api.borkol.com/v1/api/commerce/my/orders?page=1", "label": "1", "active": true },
      { "url": null, "label": "Next »", "active": false }
    ],
    "path": "https://api.borkol.com/v1/api/commerce/my/orders",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

Hatalar

DurumGövdeNe zaman
401{"message": "Invalid customer token."}X-Customer-Token eksik veya çözümlenemiyor.
403scope, modül veya askıya alma gövdesiAnahtar commerce:read scope'undan yoksun, modül devre dışı veya mağaza askıya alınmış.
429{"message": "Too Many Attempts."}Rate limit aşıldı.