Konfigüratör
Fiyat teklifi
Yapılandırılabilir bir ürünün belirli bir yapılandırmasını fiyatlayın ve satır bazında döküm alın.
Markdown olarak görüntüleQuote endpoint'i tek bir somut yapılandırmayı fiyatlar. Canlı bir toplam göstermek için alıcının seçimindeki her değişiklikte çağırın. Salt okunurdur: sepet veya sipariş oluşturulmaz ve yalnızca bir okuma scope'u gerekir: catalog:read veya commerce:read taşıyan bir anahtar kabul edilir.
Quote endpoint'i tek bir somut yapılandırmayı fiyatlar. Canlı bir toplam göstermek için alıcının seçimindeki her değişiklikte çağırın. Salt okunurdur: sepet veya sipariş oluşturulmaz ve yalnızca bir okuma scope'u gerekir: catalog:read veya commerce:read taşıyan bir anahtar kabul edilir.
POST /v1/api/commerce/configurator/products/{id}/quote
Aktif bir made-to-measure ürünün (capability made_to_measure) belirli bir yapılandırmasını fiyatlar. Sunucu önce seçili seçimleri doğrular (varlık, kullanılabilirlik, single grup başına en fazla bir seçim, zorunlu grupların karşılanması, requires ve excludes kuralları), ardından boyutları doğrular (yapılandırılmış her boyutun mevcut olması, tam sayı olması, seçili seçimlerin kısıtlarıyla daraltıldıktan sonra min ve max sınırları içinde kalması), taban fiyatı kazanan fiyat matrisinden (veya ürünün boyutu yoksa ürün fiyatından) çözer, seçim deltalarını iki geçişte uygular (önce fixed, per_area ve percent, ardından her percent_of_total bu ara toplama karşı, bileşik etki olmadan) ve toplamı satır bazında dökümle birlikte döndürür. Algoritmanın tamamı için bölüm girişine bakın.
Yol parametreleri
| Ad | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| id | string (uuid) | Evet | Ürün ID'si. Capability değeri made_to_measure olan aktif bir ürün olmalıdır. |
Gövde parametreleri
Request body JSON'dur.
| Ad | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| dimensions | object | Koşullu | Boyut key değerlerinden (şemadan) boyutun biriminde (örneğin cm) tam sayı değere bir eşleme. Ondalıklı bir değer dimensions.{key} üzerinde 422 ile reddedilir. Ürünün boyutları olduğunda zorunludur: yapılandırılmış her boyut mevcut ve sayısal olmalıdır. Bilinmeyen anahtarlar 422 ile reddedilir. Yalnızca boyutu olmayan bir ürün için atlanabilir. |
| choices | array of string (uuid) | Hayır | Seçili seçenek seçimi ID'leri. Tekrarlar tekilleştirilir. Her öğe, bu ürünün kullanılabilir bir seçimine, yani şema endpoint'inin yayımladığı bir seçime referans veren bir UUID olmalıdır. Zorunlu gruplar karşılanmalı ve single grup başına en fazla bir seçime izin verilir. Yalnızca ürünün zorunlu grubu yoksa atlayın veya boş dizi gönderin. |
Yanıt alanları
| Ad | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| total | integer | her zaman | Küçük birim (kuruş/cent) cinsinden toplam fiyat. |
| currency | string | her zaman | Ürünün ISO para birimi kodu, örneğin "EUR". |
| breakdown | array | her zaman | Satır kalemleri. Her zaman {"label":"Base","amount":<base>} ile başlar; ardından grup ve seçim pozisyon sırasına göre, fiyatlanan her seçim için "{Group name}: {Choice name}" etiketli birer satır gelir (tüm percent_of_total satırları diğerlerinden sonra). Deltası 0 olan seçimler yine de amount: 0 ile görünür. Tüm tutarlar tamsayı küçük birimdir. |
| matrix | object or null | her zaman | Taban fiyatı sağlayan fiyat matrisinin {id, name} bilgisi. Taban, ürünün kendi fiyatından geldiğinde (boyutu olmayan bir ürün) null. |
Hatalar
Kimlik doğrulama ve altyapı hataları, diğer storefront route'larıyla aynıdır:
| Durum | Gövde | Neden |
|---|---|---|
| 401 | {"message":"Unauthenticated."} | Eksik veya geçersiz API anahtarı. |
| 403 | {"message":"Invalid ability provided."} | Anahtarda catalog:read scope'u da commerce:read scope'u da yok. |
| 403 | {"error":"Module not enabled: configurator"} | Tenant'ta configurator modülü etkin değil. message yerine error anahtarına dikkat edin. |
| 403 | {"message":"Tenant suspended.","code":"tenant_suspended"} | Tenant hesabı askıya alınmış. |
| 404 | {"message":"..."} | Ürün mevcut değil, aktif değil veya capability değeri made_to_measure değil. |
| 429 | {"message":"Too Many Attempts."} | Dakikada 120 request'lik rate limit aşıldı. |
422 doğrulama hataları
Tüm doğrulama hataları standart Laravel zarfını kullanır: {"message":"<first error>","errors":{"<field>":["<message>", ...]}}; en üst düzeyde code yoktur. Bu, aynı yapılandırma hatalarını en üst düzeyde code INVALID_CONFIGURATION ile bildiren sepete eklemeden farklıdır (bkz. Sepet satırları). İki katman vardır.
Girdi doğrulaması (request body'nin şekli): dimensions bir nesne, choices bir dizi olmalı ve her choices.* öğesi bir UUID olmalıdır. Örnek:
Alan (domain) doğrulaması (yapılandırmanın kendisi): aynı zarf; her hata anahtarı tam olarak bir mesaj taşır. Seçim hataları önce denetlenir ve kısa devre yapar: herhangi bir seçim hatası oluştuğunda, o response'ta boyutlar doğrulanmaz. Olası anahtarlar ve mesajlar:
| Hata anahtarı | Mesaj | Neden |
|---|---|---|
choices | One or more choices are not available. | Bir seçim ID'si bu üründe mevcut değil ya da seçim kullanılabilir değil: pasif, silinmiş veya karşılanabilir bir requires hedef grubu kalmamış. Mesaj bilinçli olarak geneldir ve kullanılabilir olmayan seçimin adını asla vermez. |
choices | Choose one {Group}. | single tipindeki bir grupta iki veya daha fazla seçim seçilmiş. |
choices | {Group} is required. | Zorunlu bir grupta seçili seçim yok. |
choices | Area-priced choice needs two dimensions. | Tam olarak iki boyutu olmayan bir üründe per_area bir seçim seçilmiş. |
choices.{choiceId} | {Choice} cannot be combined with {Target}. | Bir excludes kuralı ihlal edilmiş. |
choices.{choiceId} | {Choice} requires one of: {names}. | Bir requires kuralı karşılanmamış (bir hedef grubundaki hedeflerin hiçbiri seçili değil). {names} yalnızca şemanın bu ürün için yayımladığı seçimleri listeler; bu nedenle mesajdaki bir ad her zaman alıcının seçebileceği bir seçimdir. |
dimensions.{key} | {Label} is required. | Boyut request'te eksik veya değeri sayısal değil. |
dimensions.{key} | {Label} must be a whole number. | Değerin ondalık kısmı var, örneğin 120.5. |
dimensions.{key} | {Label} must be between {min} and {max} {unit}. | Değer, boyutun aralığının dışında. |
dimensions.{key} | {Label} must be between {min} and {max} {unit} when {choice names} is selected. | Değer, seçili seçimlerin kısıtlarıyla daraltıldıktan sonraki aralığın dışında. |
dimensions.{key} | {Label} has no valid range for the selected choices ({names}). | Seçili seçimlerin kısıtları aralığı geçersiz kılıyor (geçerli min, geçerli max'i aşıyor). |
dimensions.{key} | Unknown dimension. | Request, üründe yapılandırılmamış bir boyut anahtarı içeriyor. |
configuration | not_priceable | Taban fiyat çözülemedi: boyutu olmayan bir ürünün fiyatı null, seçili seçimler hiçbir fiyat matrisinin koşullarını karşılamıyor veya kazanan matriste boyut değerlerini kapsayan bir fiyat kuralı yok. Kullanılabilir olmayan bir seçime koşullanmış bir matris asla karşılanamaz, bu yüzden hiçbir zaman taban fiyat sağlamaz; şema da böyle bir matrisi listelemez. |
Örnek bir alan doğrulaması hatası:
Bir seçimdeki requires_quote bayrağının burada asla hataya yol açmadığını unutmayın: endpoint bu tür yapılandırmaları normal şekilde fiyatlar. Şemada sunulan bu bayrak, yalnızca storefront'un alıcıyı doğrudan ödeme (checkout) yerine manuel teklif talebine yönlendirmesi gerektiğini belirtir.
curl -X POST "https://api.borkol.com/v1/api/commerce/configurator/products/9c2f1e6a-8b4d-4f2a-9e11-3d5a7b9c0e21/quote" \
-H "Authorization: Bearer {api_key}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"dimensions": { "width": 420, "depth": 300 },
"choices": [
"c1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
"f6a7b8c9-d0e1-4f2a-b3c4-d5e6f7a8b9c0"
]
}'const res = await fetch(
`https://api.borkol.com/v1/api/commerce/configurator/products/${productId}/quote`,
{
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
Accept: "application/json",
"Content-Type": "application/json",
},
body: JSON.stringify({
dimensions: { width: 420, depth: 300 },
choices: [
"c1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
"f6a7b8c9-d0e1-4f2a-b3c4-d5e6f7a8b9c0",
],
}),
}
);
if (res.status === 422) {
const { errors } = await res.json();
// errors is a map of field => [message]; render per-field.
} else {
const { data } = await res.json();
}{
"data": {
"total": 561500,
"currency": "EUR",
"breakdown": [
{ "label": "Base", "amount": 530000 },
{ "label": "LED lighting: LED set (6)", "amount": 31500 }
],
"matrix": {
"id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a",
"name": "Glass roof"
}
}
}{
"message": "The choices.0 field must be a valid UUID.",
"errors": {
"choices.0": ["The choices.0 field must be a valid UUID."]
}
}{
"message": "Width must be between 200 and 600 cm when Glass is selected.",
"errors": {
"dimensions.width": [
"Width must be between 200 and 600 cm when Glass is selected."
]
}
}POST /v1/api/commerce/configurator/products/{id}/quote
Aktif bir made-to-measure ürünün (capability made_to_measure) belirli bir yapılandırmasını fiyatlar. Sunucu önce seçili seçimleri doğrular (varlık, kullanılabilirlik, single grup başına en fazla bir seçim, zorunlu grupların karşılanması, requires ve excludes kuralları), ardından boyutları doğrular (yapılandırılmış her boyutun mevcut olması, tam sayı olması, seçili seçimlerin kısıtlarıyla daraltıldıktan sonra min ve max sınırları içinde kalması), taban fiyatı kazanan fiyat matrisinden (veya ürünün boyutu yoksa ürün fiyatından) çözer, seçim deltalarını iki geçişte uygular (önce fixed, per_area ve percent, ardından her percent_of_total bu ara toplama karşı, bileşik etki olmadan) ve toplamı satır bazında dökümle birlikte döndürür. Algoritmanın tamamı için bölüm girişine bakın.
Yol parametreleri
| Ad | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| id | string (uuid) | Evet | Ürün ID'si. Capability değeri made_to_measure olan aktif bir ürün olmalıdır. |
Gövde parametreleri
Request body JSON'dur.
| Ad | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| dimensions | object | Koşullu | Boyut key değerlerinden (şemadan) boyutun biriminde (örneğin cm) tam sayı değere bir eşleme. Ondalıklı bir değer dimensions.{key} üzerinde 422 ile reddedilir. Ürünün boyutları olduğunda zorunludur: yapılandırılmış her boyut mevcut ve sayısal olmalıdır. Bilinmeyen anahtarlar 422 ile reddedilir. Yalnızca boyutu olmayan bir ürün için atlanabilir. |
| choices | array of string (uuid) | Hayır | Seçili seçenek seçimi ID'leri. Tekrarlar tekilleştirilir. Her öğe, bu ürünün kullanılabilir bir seçimine, yani şema endpoint'inin yayımladığı bir seçime referans veren bir UUID olmalıdır. Zorunlu gruplar karşılanmalı ve single grup başına en fazla bir seçime izin verilir. Yalnızca ürünün zorunlu grubu yoksa atlayın veya boş dizi gönderin. |
curl -X POST "https://api.borkol.com/v1/api/commerce/configurator/products/9c2f1e6a-8b4d-4f2a-9e11-3d5a7b9c0e21/quote" \
-H "Authorization: Bearer {api_key}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"dimensions": { "width": 420, "depth": 300 },
"choices": [
"c1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
"f6a7b8c9-d0e1-4f2a-b3c4-d5e6f7a8b9c0"
]
}'const res = await fetch(
`https://api.borkol.com/v1/api/commerce/configurator/products/${productId}/quote`,
{
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
Accept: "application/json",
"Content-Type": "application/json",
},
body: JSON.stringify({
dimensions: { width: 420, depth: 300 },
choices: [
"c1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
"f6a7b8c9-d0e1-4f2a-b3c4-d5e6f7a8b9c0",
],
}),
}
);
if (res.status === 422) {
const { errors } = await res.json();
// errors is a map of field => [message]; render per-field.
} else {
const { data } = await res.json();
}{
"data": {
"total": 561500,
"currency": "EUR",
"breakdown": [
{ "label": "Base", "amount": 530000 },
{ "label": "LED lighting: LED set (6)", "amount": 31500 }
],
"matrix": {
"id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a",
"name": "Glass roof"
}
}
}Yanıt alanları
| Ad | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| total | integer | her zaman | Küçük birim (kuruş/cent) cinsinden toplam fiyat. |
| currency | string | her zaman | Ürünün ISO para birimi kodu, örneğin "EUR". |
| breakdown | array | her zaman | Satır kalemleri. Her zaman {"label":"Base","amount":<base>} ile başlar; ardından grup ve seçim pozisyon sırasına göre, fiyatlanan her seçim için "{Group name}: {Choice name}" etiketli birer satır gelir (tüm percent_of_total satırları diğerlerinden sonra). Deltası 0 olan seçimler yine de amount: 0 ile görünür. Tüm tutarlar tamsayı küçük birimdir. |
| matrix | object or null | her zaman | Taban fiyatı sağlayan fiyat matrisinin {id, name} bilgisi. Taban, ürünün kendi fiyatından geldiğinde (boyutu olmayan bir ürün) null. |
Hatalar
Kimlik doğrulama ve altyapı hataları, diğer storefront route'larıyla aynıdır:
| Durum | Gövde | Neden |
|---|---|---|
| 401 | {"message":"Unauthenticated."} | Eksik veya geçersiz API anahtarı. |
| 403 | {"message":"Invalid ability provided."} | Anahtarda catalog:read scope'u da commerce:read scope'u da yok. |
| 403 | {"error":"Module not enabled: configurator"} | Tenant'ta configurator modülü etkin değil. message yerine error anahtarına dikkat edin. |
| 403 | {"message":"Tenant suspended.","code":"tenant_suspended"} | Tenant hesabı askıya alınmış. |
| 404 | {"message":"..."} | Ürün mevcut değil, aktif değil veya capability değeri made_to_measure değil. |
| 429 | {"message":"Too Many Attempts."} | Dakikada 120 request'lik rate limit aşıldı. |
422 doğrulama hataları
Tüm doğrulama hataları standart Laravel zarfını kullanır: {"message":"<first error>","errors":{"<field>":["<message>", ...]}}; en üst düzeyde code yoktur. Bu, aynı yapılandırma hatalarını en üst düzeyde code INVALID_CONFIGURATION ile bildiren sepete eklemeden farklıdır (bkz. Sepet satırları). İki katman vardır.
Girdi doğrulaması (request body'nin şekli): dimensions bir nesne, choices bir dizi olmalı ve her choices.* öğesi bir UUID olmalıdır. Örnek:
{
"message": "The choices.0 field must be a valid UUID.",
"errors": {
"choices.0": ["The choices.0 field must be a valid UUID."]
}
}Alan (domain) doğrulaması (yapılandırmanın kendisi): aynı zarf; her hata anahtarı tam olarak bir mesaj taşır. Seçim hataları önce denetlenir ve kısa devre yapar: herhangi bir seçim hatası oluştuğunda, o response'ta boyutlar doğrulanmaz. Olası anahtarlar ve mesajlar:
| Hata anahtarı | Mesaj | Neden |
|---|---|---|
choices | One or more choices are not available. | Bir seçim ID'si bu üründe mevcut değil ya da seçim kullanılabilir değil: pasif, silinmiş veya karşılanabilir bir requires hedef grubu kalmamış. Mesaj bilinçli olarak geneldir ve kullanılabilir olmayan seçimin adını asla vermez. |
choices | Choose one {Group}. | single tipindeki bir grupta iki veya daha fazla seçim seçilmiş. |
choices | {Group} is required. | Zorunlu bir grupta seçili seçim yok. |
choices | Area-priced choice needs two dimensions. | Tam olarak iki boyutu olmayan bir üründe per_area bir seçim seçilmiş. |
choices.{choiceId} | {Choice} cannot be combined with {Target}. | Bir excludes kuralı ihlal edilmiş. |
choices.{choiceId} | {Choice} requires one of: {names}. | Bir requires kuralı karşılanmamış (bir hedef grubundaki hedeflerin hiçbiri seçili değil). {names} yalnızca şemanın bu ürün için yayımladığı seçimleri listeler; bu nedenle mesajdaki bir ad her zaman alıcının seçebileceği bir seçimdir. |
dimensions.{key} | {Label} is required. | Boyut request'te eksik veya değeri sayısal değil. |
dimensions.{key} | {Label} must be a whole number. | Değerin ondalık kısmı var, örneğin 120.5. |
dimensions.{key} | {Label} must be between {min} and {max} {unit}. | Değer, boyutun aralığının dışında. |
dimensions.{key} | {Label} must be between {min} and {max} {unit} when {choice names} is selected. | Değer, seçili seçimlerin kısıtlarıyla daraltıldıktan sonraki aralığın dışında. |
dimensions.{key} | {Label} has no valid range for the selected choices ({names}). | Seçili seçimlerin kısıtları aralığı geçersiz kılıyor (geçerli min, geçerli max'i aşıyor). |
dimensions.{key} | Unknown dimension. | Request, üründe yapılandırılmamış bir boyut anahtarı içeriyor. |
configuration | not_priceable | Taban fiyat çözülemedi: boyutu olmayan bir ürünün fiyatı null, seçili seçimler hiçbir fiyat matrisinin koşullarını karşılamıyor veya kazanan matriste boyut değerlerini kapsayan bir fiyat kuralı yok. Kullanılabilir olmayan bir seçime koşullanmış bir matris asla karşılanamaz, bu yüzden hiçbir zaman taban fiyat sağlamaz; şema da böyle bir matrisi listelemez. |
Örnek bir alan doğrulaması hatası:
{
"message": "Width must be between 200 and 600 cm when Glass is selected.",
"errors": {
"dimensions.width": [
"Width must be between 200 and 600 cm when Glass is selected."
]
}
}Bir seçimdeki requires_quote bayrağının burada asla hataya yol açmadığını unutmayın: endpoint bu tür yapılandırmaları normal şekilde fiyatlar. Şemada sunulan bu bayrak, yalnızca storefront'un alıcıyı doğrudan ödeme (checkout) yerine manuel teklif talebine yönlendirmesi gerektiğini belirtir.