Borkol Docs startpagina

Aan de slag

Redirects en sitemap

Hernoemde paden naar hun nieuwe adres omzetten, en elk live pad van de ingeschakelde modules oplijsten voor een sitemap.

Bekijk als Markdown

Deze twee endpoints helpen een storefront zijn zoekpositie te houden wanneer de merchant iets hernoemt. Ze horen bij het platform, niet bij één module: elke module die content een adres geeft, draagt eraan bij. Catalogus-content gebruikt paden van een vaste vorm: een product staat op /products/{slug} en een categorie op /categories/{slug}. Contentrecords (Objecten) staan op het adresvoorvoegsel van het type voor de taal plus de recordslug, bijvoorbeeld /diensten/keukenmontage. Gebruikt je storefront andere URL's, map deze paden dan op je eigen routes.

De catalogus levert sitemap-items voor producten en categorieën, en Objecten levert één item per gepubliceerd recordadres (zie GET /v1/api/sitemap). Wanneer de merchant de slug van een product, categorie of record wijzigt, legt Borkol een permanente redirect vast van het oude pad naar het nieuwe; voor een record gebeurt dat alleen als het type voor die taal een niet-leeg adresvoorvoegsel heeft. Ketens worden samengevouwen: a hernoemen naar b en daarna b naar c laat zowel /products/a als /products/b rechtstreeks naar /products/c wijzen. Een pad dat weer live wordt (een nieuw product neemt de oude slug) stopt met redirecten.

Beide endpoints nemen een tenant-API-key met één van de scopes catalog:read, commerce:read, tenant:read of objects:read, meegestuurd als Authorization: Bearer {api_key}. Ze vereisen de catalog-module niet: een winkel die alleen Objecten gebruikt kan ze ook aanroepen. De gedeelde tenant-rate-limit van 120 requests per minuut geldt.

GET /v1/api/redirects

Zoekt de redirect op voor één storefront-pad. Roep het aan wanneer een product-, categorie- of recordrequest op je storefront anders een 404 zou geven, en stuur de bezoeker door met de teruggegeven status-code.

De lookup haalt één afsluitende slash weg (/products/old-chair/ matcht /products/old-chair; het rootpad / blijft ongemoeid) en is hoofdlettergevoelig. Alleen exacte paden matchen: querystrings horen niet bij het pad.

Queryparameters

NaamTypeVerplichtBeschrijving
pathstringJaHet storefront-pad om op te zoeken, bijvoorbeeld /products/old-chair of /diensten/oude-slug. Maximaal 512 tekens.
Request
curl "https://api.borkol.com/v1/api/redirects?path=%2Fproducts%2Fold-chair" \
  -H "Authorization: Bearer {api_key}" \
  -H "Accept: application/json"
Request (JS)
const res = await fetch(
  "https://api.borkol.com/v1/api/redirects?" +
    new URLSearchParams({ path: "/products/old-chair" }),
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: "application/json",
    },
  }
);
if (res.status === 404) {
  // No redirect: render your own not-found page.
} else {
  const { data } = await res.json();
  // Redirect the visitor to data.to_path with data.status.
}
Response
{
  "data": {
    "from_path": "/products/old-chair",
    "to_path": "/products/oak-dining-chair",
    "status": 301
  }
}

Responsevelden

NaamTypeVerplichtBeschrijving
from_pathstringaltijdHet opgeslagen oude pad (zonder afsluitende slash).
to_pathstringaltijdHet pad waarheen je de bezoeker stuurt. Redirects worden vastgelegd ongeacht de status van het product, de categorie of het record, en archiveren of depubliceren verwijdert er geen, dus to_path kan zelf onbeschikbaar zijn; controleer het voordat je doorstuurt.
statusintegeraltijdHTTP-status om mee te redirecten. Op dit moment altijd 301 (permanent).

Fouten

StatusBodyOorzaak
401{"message":"Unauthenticated."}Ontbrekende of ongeldige API-key.
403{"message":"Invalid ability provided."}Key heeft geen van de scopes catalog:read, commerce:read, tenant:read of objects:read.
403{"message":"Tenant suspended.","code":"tenant_suspended"}Tenant-account is opgeschort.
404{"message":"..."}Er bestaat geen redirect voor dit pad.
422{"message":"...","errors":{"path":["..."]}}path ontbreekt, is geen string of is langer dan 512 tekens.
429{"message":"Too Many Attempts."}Rate-limit van 120 requests per minuut overschreden.

GET /v1/api/sitemap

Lijst elk live pad van de voor de winkel ingeschakelde modules op, klaar om als sitemap.xml te renderen. Een uitgeschakelde module draagt niets bij, dus een winkel zonder catalog-module krijgt geen product- of categorie-items (de respons is dan een lege data-array, geen fout). De catalog-module levert alle producten met status active en alle actieve categorieën, eerst de producten, dan de categorieën, elke groep gesorteerd op slug. De Objects-module levert één item per publiek zichtbaar record, taal en adres, voor objecttypes met een niet-leeg adresvoorvoegsel voor die taal; types zonder voorvoegsels hebben geen publieke pagina's en blijven weg, net als concepten en ingeplande records. De respons is niet gepagineerd.

Parameters

Geen.

Request
curl "https://api.borkol.com/v1/api/sitemap" \
  -H "Authorization: Bearer {api_key}" \
  -H "Accept: application/json"
Response
{
  "data": [
    {
      "type": "product",
      "path": "/products/oak-dining-chair",
      "lastmod": "2026-10-11T09:14:33+00:00"
    },
    {
      "type": "category",
      "path": "/categories/chairs",
      "lastmod": "2026-10-02T15:20:11+00:00"
    },
    {
      "type": "object_record",
      "object_type": "service",
      "locale": "nl",
      "path": "/diensten/keukenmontage",
      "lastmod": "2026-10-09T12:41:07+00:00",
      "alternates": {
        "en": "/services/kitchen-fitting",
        "nl": "/diensten/keukenmontage"
      }
    }
  ]
}

Responsevelden

Elk item in data:

NaamTypeVerplichtBeschrijving
typestringaltijdproduct, category of object_record.
pathstringaltijdStorefront-pad: /products/{slug}, /categories/{slug}, of voor een record het adresvoorvoegsel van het type voor de taal plus het adres van het record, bijvoorbeeld /services/kitchen-fitting.
lastmodstring (ISO 8601) of nullaltijdWanneer het product, de categorie of het record voor het laatst is gewijzigd.
object_typestringalleen object_recordSleutel van het objecttype van het record.
localestringalleen object_recordDe taal van het adres van dit item.
alternatesobjectalleen object_recordTaaltag naar pad, voor elke ingeschakelde taal waarin het record een openbaar adres heeft (inclusief dat van dit item zelf). Gebruik het voor hreflang-links.

Fouten

StatusBodyOorzaak
401{"message":"Unauthenticated."}Ontbrekende of ongeldige API-key.
403{"message":"Invalid ability provided."}Key heeft geen van de scopes catalog:read, commerce:read, tenant:read of objects:read.
403{"message":"Tenant suspended.","code":"tenant_suspended"}Tenant-account is opgeschort.
429{"message":"Too Many Attempts."}Rate-limit van 120 requests per minuut overschreden.