Borkol Docs startpagina

Configurator

Configuratieschema

Haal het volledige configuratieschema van een configureerbaar product op.

Bekijk als Markdown

Het schema-endpoint retourneert alles wat een storefront nodig heeft om voor één product een configurator-UI te renderen: dimensies met hun bereikconstraints per keuze, de prijsmatrices van het product (als hint welke matrix van toepassing is), en de optiegroepen met hun keuzes, prijsdelta's, regels tussen keuzes, afbeeldingen en requires_quote-vlaggen. Zie de hoofdstukintroductie voor hoe deze concepten samenhangen.

GET /v1/api/commerce/configurator/products/{id}/schema

Retourneert het volledige configuratieschema voor één actief configureerbaar product. Alles in de response is teruggesnoeid tot de op dat moment beschikbare keuzes: een keuze verschijnt alleen als die actief is, niet verwijderd, en elke requires-doelgroep nog minstens één beschikbare keuze bevat (het snoeien werkt door, dus een keuze die een niet-beschikbare keuze vereist verdwijnt ook). Dimensieconstraints en requires- en excludes-lijsten verwijzen uitsluitend naar die beschikbare keuze-ID's, en een prijsmatrix met een condition op een niet-beschikbare keuze wordt volledig uit price_matrices weggelaten. Retourneert 404 voor elk product dat niet zowel status = active als capability = made_to_measure heeft.

Path-parameters

NaamTypeVerplichtBeschrijving
idstring (uuid)JaProduct-ID. Moet een actief product met capability made_to_measure zijn.

Responsevelden

Het data-object heeft drie keys.

data.dimensions (array, in positievolgorde; de volgorde bepaalt de afbeelding op de prijsmatrix-assen dim1 en dim2):

NaamTypeVerplichtBeschrijving
keystringaltijdRequest-key om voor deze dimensie te gebruiken in quote-calls.
labelstringaltijdWeergavelabel.
unitstringaltijdWeergave-eenheid als string, bijvoorbeeld "cm".
minintegeraltijdMinimaal toegestane waarde vóór aanscherping door constraints.
maxintegeraltijdMaximaal toegestane waarde vóór aanscherping door constraints.
constraintsarrayaltijdBereikaanscherpingen per keuze; lege array wanneer er geen zijn. Elk item: choice_id (uuid), min (integer of null), max (integer of null). Wanneer die keuze geselecteerd is, verhoogt een niet-null min het effectieve minimum en verlaagt een niet-null max het effectieve maximum.

data.price_matrices (array, in aanmaakvolgorde):

NaamTypeVerplichtBeschrijving
idstring (uuid)altijdMatrix-ID. Wordt door het quote-endpoint teruggegeven als matrix.id wanneer deze matrix de basisprijs leverde.
namestringaltijdMatrixnaam.
conditionsarray of string (uuid)altijdKeuze-ID's die allemaal geselecteerd moeten zijn om de matrix in aanmerking te laten komen. Een lege array betekent altijd in aanmerking. Van de matrices die in aanmerking komen wint die met de meeste conditions. Matrices met een condition op een niet-beschikbare keuze worden helemaal niet vermeld, dus deze array wordt nooit ingekort ten opzichte van wat de engine vereist.

data.option_groups (array, in positievolgorde):

NaamTypeVerplichtBeschrijving
idstring (uuid)altijdGroep-ID.
namestringaltijdGroepsnaam. Wordt ook gebruikt als prefix van de labels in de quote-uitsplitsing ("Group: Choice").
typestringaltijdsingle (maximaal één keuze selecteerbaar) of multi (elk aantal).
requiredbooleanaltijdOf er minstens één keuze uit deze groep geselecteerd moet zijn.
choicesarrayaltijdKeuzes in positievolgorde, zie hieronder.

data.option_groups[].choices[]:

NaamTypeVerplichtBeschrijving
idstring (uuid)altijdKeuze-ID. Stuur dit mee in de choices-array van het quote-request.
namestringaltijdKeuzenaam.
delta_typestringaltijdfixed, per_area, percent, of percent_of_total.
delta_valueintegeraltijdMinor units voor fixed; minor units per vierkante meter voor per_area; procent maal 100 voor percent en percent_of_total (1050 = 10,50 procent).
is_defaultbooleanaltijdUI-hint voor de initiële selectie.
requiresarray of string (uuid)altijdKeuze-ID's die deze keuze vereist. OR binnen één targetgroep, AND tussen targetgroepen.
excludesarray of string (uuid)altijdKeuze-ID's waarmee deze keuze niet gecombineerd kan worden.
imagesarrayaltijd[{url, alt}]; lege array wanneer de keuze geen media heeft.
requires_quotebooleanaltijdWanneer true, hoort de storefront de koper naar een handmatige offerteaanvraag te leiden in plaats van naar checkout. Informatief: het quote-endpoint prijst de configuratie nog steeds.
Request
curl "https://api.borkol.com/v1/api/commerce/configurator/products/9c2f1e6a-8b4d-4f2a-9e11-3d5a7b9c0e21/schema" \
  -H "Authorization: Bearer {api_key}" \
  -H "Accept: application/json"
Request (JS)
const res = await fetch(
  `https://api.borkol.com/v1/api/commerce/configurator/products/${productId}/schema`,
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: "application/json",
    },
  }
);
const { data } = await res.json();
Response
{
  "data": {
    "dimensions": [
      {
        "key": "width",
        "label": "Width",
        "unit": "cm",
        "min": 200,
        "max": 700,
        "constraints": [
          {
            "choice_id": "c1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
            "min": null,
            "max": 600
          }
        ]
      },
      {
        "key": "depth",
        "label": "Depth",
        "unit": "cm",
        "min": 150,
        "max": 400,
        "constraints": []
      }
    ],
    "price_matrices": [
      {
        "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a",
        "name": "Glass roof",
        "conditions": ["c1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c"]
      },
      {
        "id": "e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9",
        "name": "Base",
        "conditions": []
      }
    ],
    "option_groups": [
      {
        "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "name": "Roof type",
        "type": "single",
        "required": true,
        "choices": [
          {
            "id": "c1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
            "name": "Glass",
            "delta_type": "fixed",
            "delta_value": 0,
            "is_default": true,
            "requires": [],
            "excludes": ["f6a7b8c9-d0e1-4f2a-b3c4-d5e6f7a8b9c0"],
            "images": [
              {
                "url": "https://cdn.borkol.com/t/9c2f/glass-roof.jpg",
                "alt": "Glass roof"
              }
            ],
            "requires_quote": false
          }
        ]
      },
      {
        "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "name": "LED lighting",
        "type": "multi",
        "required": false,
        "choices": [
          {
            "id": "f6a7b8c9-d0e1-4f2a-b3c4-d5e6f7a8b9c0",
            "name": "LED set (6)",
            "delta_type": "per_area",
            "delta_value": 2500,
            "is_default": false,
            "requires": ["c1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c"],
            "excludes": [],
            "images": [],
            "requires_quote": false
          }
        ]
      }
    ]
  }
}

Fouten

StatusBodyOorzaak
401{"message":"Unauthenticated."}Ontbrekende of ongeldige API-key.
403{"message":"Invalid ability provided."}De key heeft noch de scope catalog:read noch commerce:read.
403{"error":"Module not enabled: configurator"}De tenant heeft de configurator-module niet ingeschakeld. Let op de key error in plaats van message.
403{"message":"Tenant suspended.","code":"tenant_suspended"}Het tenant-account is geschorst.
404{"message":"..."}Het product bestaat niet, is niet actief, of de capability is niet made_to_measure.
429{"message":"Too Many Attempts."}Rate limit van 120 requests per minuut overschreden.