Objecten

De Objecten-module is het generieke contentmodel van het platform. Een merchant definieert objecttypes (contenttypes zoals "FAQ", "Pagina" of "Winkellocatie") in het client-dashboard, elk met een geordende lijst van getypeerde properties. Contentredacteuren maken vervolgens records (items) van die types. Je storefront leest beide via de publieke API: de typedefinities vertellen je welke vorm je kunt verwachten, de records bevatten de content.

Dat maakt de module een natuurlijke match voor LLM-gedreven en headless storefronts: haal /v1/api/objects/types één keer op om het schema te leren kennen, en render records daarna generiek.

Alle vier de endpoints leven onder /v1/api/objects, zijn read-only, vereisen de scope objects:read op je API-key, en vereisen dat de objects-module is ingeschakeld (anders 403 {"error":"Module not enabled: objects"}).

Objecttypes en properties#

Een objecttype heeft een key (een unieke slug die in URL's wordt gebruikt; de waarden types, records, properties en bulk zijn gereserveerd en komen nooit voor), een enkelvoudige name, een plural_name en settings die zeggen of de records worden gepubliceerd en hoe ze een adres krijgen. Elk type heeft automatisch een verplichte name-textproperty; de merchant voegt de rest toe.

Het settings-object van het type:

Een propertydefinitie heeft:

Propertytypes en de waarde die elk oplevert binnen values. Dezelfde soorten zijn beschikbaar voor velden binnen secties en repeaterrijen.

Properties kunnen in het dashboard gearchiveerd worden. Gearchiveerde properties zijn onzichtbaar op de publieke API: ze worden weggelaten uit de propertylijst van het type en hun keys worden uit record-values verwijderd.

Records#

Een record is {id, values, published_at, created_at}, plus slugs wanneer het type adressen heeft. values is een JSON-object met propertykeys als sleutel. Properties zonder waarde ontbreken simpelweg in values (null-waarden worden bij het opslaan weggelaten), dus behandel ontbrekende keys altijd als "geen waarde". De enige uitzondering is een media-waarde die naar een ontbrekend of privé-item wijst: die key is aanwezig met de waarde null. published_at en created_at zijn ISO 8601-timestamps; published_at is het moment waarop het record live ging (voor een type zonder publicatiestap is het de aanmaaktijd).

slugs koppelt een taaltag aan het adres van het record in die taal, bijvoorbeeld {"en": "kitchen-fitting", "nl": "keukenmontage"}. De slug is het laatste padsegment: het volledige pad op je storefront is het voorvoegsel van het type voor die taal (uit settings.slug.prefixes) plus / plus de slug. Alleen ingeschakelde contenttalen verschijnen. Zoek een record op adres op met GET /v1/api/objects/types/{key}/records/by-slug/{slug} (zie Records).

Publiceren en zichtbaarheid#

De publieke API levert alleen content die een merchant heeft gepubliceerd.

• Op een type met settings.publishable: true is een record zichtbaar wanneer het gepubliceerd is en zijn published_at nu of in het verleden ligt. Concepten en records die zijn ingepland voor een toekomstige published_at ontbreken in de lijst en geven 404 op beide endpoints voor één record. Een ingepland record verschijnt vanzelf wanneer zijn tijd komt; op dat moment gaat er geen webhook af.
• Op een type zonder publicatiestap hebben records geen conceptstap en zijn ze zichtbaar zodra ze zijn aangemaakt. (Concepten die zijn blijven staan nadat Publiceren is uitgezet, blijven verborgen.)
• De zichtbaarheid is op elk endpoint gelijk. filter[status] bestaat niet op de publieke API (het geeft 422), omdat elk record dat je kunt lezen al gepubliceerd is.

Gelokaliseerde waarden#

Een property of sectieveld met de vlag localized slaat één waarde per contenttaal op. De waarde in values is een map van taaltag naar waarde, {"en": "Hello", "nl": "Hallo"}, met tags passend op /^[a-z]{2}(-[A-Z]{2})?$/. De API snijdt de map terug tot de talen die op dat moment voor de winkel zijn ingeschakeld, zodat een taal die de merchant inmiddels heeft uitgezet nooit lekt. Een taal die de merchant leeg liet, ontbreekt gewoon in de map: val terug op de standaardtaal van de winkel, die altijd de eerste ingeschakelde taal is en altijd is ingevuld wanneer de property verplicht is. Een waarde die niet verplicht is mag geen waarde voor de standaardtaal hebben, bijvoorbeeld {"nl": "Hallo"} bij een winkel met standaard en; blijft er geen ingeschakelde taal over in de map, dan is de waarde null.

Een property die niet localized is, geeft altijd een kale waarde, welke soort ook. Number, money, boolean, date, datetime, customer, color, media_list, recordverwijzingen, repeater en sections kunnen niet gelokaliseerd worden (de velden binnen een repeaterrij of een sectie wel). Ondersteun beide vormen voor dezelfde soort, want een merchant kan een property later alsnog lokaliseren.

Mediawaarden#

media- en media_list-waarden worden voor je opgelost, zodat een storefront geen tweede request nodig heeft:

{
  "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "url": "https://cdn.borkol.com/t/abc/hero.webp",
  "alt": "Oak table in a sunny room",
  "width": 1600,
  "height": 900,
  "mime_type": "image/webp"
}

Een media-waarde is dit object, of null wanneer het item niet meer bestaat of privé is. Een media_list-waarde is een lijst van deze objecten, elk met een extra caption (string, een locale-map of null); een item kan een eigen alt hebben die die van de bibliotheek vervangt (een string of een locale-map). Items die ontbreken of privé zijn, vallen uit de lijst, dus de lijst kan korter zijn dan wat de merchant koos. Alleen publieke media wordt ooit getoond; privébestanden verschijnen nooit.

Sections-waarden#

Een property van type sections bevat page-builder-content: de waarde is een lijst van sectie-instanties. Een opgeslagen lege sections-waarde geeft []. Elke instantie heeft deze vorm:

{
  "_key": "sec_a1b2c3d4e5f60718293a4b5c",
  "type": "hero",
  "look": "default",
  "v": 1,
  "visible": true,
  "data": { "title": { "en": "Welcome" }, "cta": { "url": "/products", "label": "Shop now" } }
}

Sectie-instanties worden bij het schrijven gevalideerd tegen de sectietypedefinities van de winkel (key, naam, icoon, looks, schemaversie, velden, itemlabelveld), die in het client-dashboard worden beheerd. De publieke API stelt de sectietypedefinities niet beschikbaar; je storefront en de merchant spreken het sectievocabulaire buiten de API om af.

Elke veldsoort uit de propertytabel hierboven kan binnen data voorkomen, met dezelfde waardevorm en dezelfde publieke serialisatie: media- en media_list-waarden zijn mediaobjecten, gelokaliseerde velden zijn locale-maps die zijn teruggesneden tot de ingeschakelde talen, en repeaterrijen behouden hun _key. Een sectie waarvan het type niet meer in de winkel bestaat, valt uit de lijst. Secties met visible: false worden wel teruggegeven; sla ze over bij het renderen.

Limieten. Een sectie heeft maximaal 40 velden. Een sections-property bevat maximaal 100 secties (of het geconfigureerde maximum van de property) en maximaal 256KB aan JSON.

Conventies#

• Alle id's zijn UUID's. Alle data is impliciet beperkt tot jouw winkel via de API-key.
• Geld is altijd integer centen. Datums in date-velden en bereikfilters zijn YYYY-MM-DD-strings. created_at- en published_at-timestamps zijn ISO 8601.
• Alleen het recordlijst-endpoint is gepagineerd; de typeslijst retourneert een kale data-array.

Endpoints#