Ontwikkelaars

Prijslijst-API

Haal de prijslijst van een reparatiewinkel op als JSON, voor de website van die winkel. Adres, velden, prijsregels, caching en wat je doet bij elk antwoord.

Bijgewerkt

Vragen over de API? Mail support@repairflow.eu.

Wat het is

Een reparatiewinkel die Repairflow gebruikt, kan haar prijslijst publiceren als JSON. De website van de winkel haalt die lijst op en laat er merken, toestellen, reparaties en prijzen mee zien, met bij elke reparatie een link om direct online te boeken. De lijst is openbaar en zonder sleutel op te halen, maar alleen als de winkel hem zelf aanzet.

De API wordt per winkel uitgerold. Een winkel zet hem aan onder Instellingen, Koppelingen, in de groep Op je eigen website, bij de tegel Prijslijst-API. Die tegel verschijnt binnenkort voor alle winkels. Zolang een winkel hem niet aanzet, geeft haar URL een 404 met de code PRICE_LIST_NOT_FOUND. Zolang Repairflow de API heeft gepauzeerd, geeft elke URL een 503 met de code PUBLIC_API_PAUSED, ook die van een winkel die hem wel aanzet (zie de tabel bij Wat je doet bij elk antwoord).

Het adres

Er is één URL per winkel, zonder queryparameters:

GET https://api.repairflow.eu/api/v1/shops/{slug}/price-list

De slug is de winkelnaam in de boekingslink van de winkel, het deel achter /ssp/. De tegel in Repairflow toont de volledige URL met een knop om hem te kopiëren.

Alles onder /api/v1/ is gedocumenteerd en heeft een versie. Andere paden van Repairflow zijn intern en niet bedoeld voor gebruik.

Voorbeeldantwoord

{
  "version": 1,
  "shop": { "slug": "voorbeeld-reparatie", "name": "Voorbeeld Reparatie", "bookingUrl": "https://my.repairflow.eu/ssp/voorbeeld-reparatie" },
  "currency": "EUR",
  "pricesIncludeVat": true,
  "disclaimer": { "nl": "Prijzen zijn inclusief btw en arbeid.", "en": null },
  "updatedAt": "2026-11-14T09:12:41.000Z",
  "brands": [
    {
      "name": "Apple",
      "devices": [
        {
          "id": "6650c1f2a9e3b40012ab34cd",
          "slug": "apple-iphone-15",
          "model": "iPhone 15",
          "series": "iPhone 15",
          "bookingUrl": "https://my.repairflow.eu/ssp/voorbeeld-reparatie?device=6650c1f2a9e3b40012ab34cd",
          "repairs": [
            {
              "id": "6650c1f2a9e3b40012ab34ce",
              "slug": "scherm-vervangen",
              "name": "Scherm vervangen",
              "description": "Inclusief nieuwe glasfolie",
              "price": { "type": "from", "amount": 149.0 },
              "options": [
                { "id": "6650c1f2a9e3b40012ab34d1", "label": "Kopie", "price": { "type": "fixed", "amount": 149.0 },
                  "bookingUrl": "https://my.repairflow.eu/ssp/voorbeeld-reparatie?device=6650c1f2a9e3b40012ab34cd&repair=6650c1f2a9e3b40012ab34ce&option=6650c1f2a9e3b40012ab34d1" },
                { "id": "6650c1f2a9e3b40012ab34d2", "label": "Origineel", "price": { "type": "fixed", "amount": 229.0 },
                  "bookingUrl": "https://my.repairflow.eu/ssp/voorbeeld-reparatie?device=6650c1f2a9e3b40012ab34cd&repair=6650c1f2a9e3b40012ab34ce&option=6650c1f2a9e3b40012ab34d2" }
              ],
              "bookingUrl": "https://my.repairflow.eu/ssp/voorbeeld-reparatie?device=6650c1f2a9e3b40012ab34cd&repair=6650c1f2a9e3b40012ab34ce"
            },
            {
              "id": "6650c1f2a9e3b40012ab34d0",
              "slug": "waterschade-onderzoek",
              "name": "Waterschade-onderzoek",
              "description": "",
              "price": { "type": "on_request", "amount": null },
              "options": [],
              "bookingUrl": "https://my.repairflow.eu/ssp/voorbeeld-reparatie?device=6650c1f2a9e3b40012ab34cd&repair=6650c1f2a9e3b40012ab34d0"
            }
          ]
        }
      ]
    }
  ],
  "services": [
    {
      "id": "6650c1f2a9e3b40012ab3500",
      "slug": "computerservice",
      "name": "Computerservice",
      "bookingUrl": "https://my.repairflow.eu/ssp/voorbeeld-reparatie?device=6650c1f2a9e3b40012ab3500",
      "repairs": []
    }
  ]
}

De velden

  • version is het versienummer van het contract, nu 1.
  • currency is de valuta van de winkel, standaard EUR. pricesIncludeVat is true: alle bedragen zijn inclusief btw.
  • disclaimer is de eigen tekst van de winkel, letterlijk overgenomen, per taal. Een leeg veld is null. Zijn beide talen leeg, dan is het hele object null. Toon de tekst bij de prijzen als hij er is.
  • brands bevat merken met hun toestellen. series van een toestel kan null zijn.
  • services bevat dienstengroepen, zoals computerservice. Ze zijn opgebouwd als een toestel, maar met name in plaats van model en zonder series.
  • options is altijd een array, leeg als een reparatie geen kwaliteitsopties heeft.
  • Merken, toestellen en diensten zonder actieve reparaties staan er niet in. Inactieve items staan er nooit in.
  • De volgorde is die van de boekingspagina van de winkel.
  • De lijst bevat bewust geen voorraad, beschikbaarheid, inkoopprijzen of marges. Wat hier niet staat, is niet op te halen.

Prijzen

price.type is een uitkomst, geen instelling van de winkel. Er zijn drie waarden:

Type Bedrag Betekenis
fixed getal, bijvoorbeeld 149.0 Een concreet bedrag, inclusief btw. Hoe de prijs is opgebouwd, maakt de lijst niet bekend.
from getal Alleen bij een reparatie met kwaliteitsopties: het laagste vaste bedrag van de opties.
on_request null De winkel noemt geen prijs. Toon bijvoorbeeld Prijs op aanvraag.

Een reparatie met opties is from zodra minstens één optie een vast bedrag heeft, en anders on_request. De opties zelf zijn fixed of on_request. Een prijs kan ook on_request zijn doordat de winkel bij haar boekingsinstellingen geen prijzen publiceert, en soms om andere redenen die de lijst niet noemt. Neem aan dat een prijs on_request kan worden en nog later een bedrag kan krijgen. Bedragen hebben hooguit twee decimalen.

id, slug en name

Elk toestel, elke dienstengroep en elke reparatie heeft een id en een slug. Opties hebben alleen een id. Merken hebben geen van beide.

  • id verandert nooit. Bewaar het als je een item wilt herkennen.
  • slug wordt vastgelegd bij de eerste publicatie en verandert daarna niet meer, ook niet als de winkel de naam wijzigt. Gebruik hem in je eigen URL, bijvoorbeeld voorbeeldreparatie.nl/reparatie/apple-iphone-15/. Een toestelslug bestaat uit merk en model, een reparatieslug uit de naam van de reparatie, en is uniek binnen zijn toestel. Bij twee gelijke namen krijgt de tweede een -2.
  • model, series, name, label en description zijn de teksten om te tonen. Ze kunnen veranderen, dus bouw er geen URL op.

Zo bouw je stabiele pagina’s: toon model en name, gebruik slug in het pad en sla id op als sleutel.

Maak een toestel of reparatie inactief in plaats van hem te verwijderen. Een inactief item verdwijnt uit de lijst, maar houdt zijn slug: zet je hem later weer aan, dan werkt de URL op je website weer. Verwijder je een toestel en maak je het opnieuw aan, dan krijgt het een nieuwe slug en verandert de URL op je website. Wijs de winkel hier ook op, want ze kan een toestel zelf verwijderen. Een tikfout in een slug herstellen we op verzoek met de hand. Voor je site is dat een breuk in de URL.

Boeken vanaf je website

bookingUrl staat op de winkel, op elk toestel en elke dienstengroep, op elke reparatie en op elke optie. Het is een link naar de boekingspagina van de winkel met de keuze al klaargezet:

  • ?device=<id> opent het toestel.
  • &repair=<id> zet de reparatie klaar.
  • &option=<id> zet ook de gekozen kwaliteitsoptie klaar.

Bij een reparatie met opties opent de link van de reparatie het toestel zonder vinkje, en kiest de klant zelf een optie. Wil je direct een keuze klaarzetten, gebruik dan de bookingUrl van de optie. Een link met een toestel dat niet meer bestaat of inactief is, opent de boekingspagina bij de eerste stap. Een reparatie of optie die niet meer bestaat, opent het toestel zonder vinkje. Gebruik de bookingUrl uit de lijst zoals hij er staat en bouw hem niet zelf na.

Heeft de winkel Online boeken uit staan, dan is bookingUrl overal null. De prijzen staan er dan nog wel in.

Ophalen, caching en ETag

  • De lijst is openbaar en vraagt geen sleutel of cookie. Je kunt hem aan de serverkant ophalen en ook vanuit de browser: CORS staat elke herkomst toe (Access-Control-Allow-Origin: *, alleen GET en HEAD) en de ETag is leesbaar. Er gaan geen cookies of andere inloggegevens mee. Welke manier bij je site past, staat bij Statische sites, browsers en rate limits.
  • Een 200 en een 304 hebben Cache-Control: public, max-age=60. De server van Repairflow kan de lijst zelf ook tot ongeveer 60 seconden bewaren. Een wijziging van de winkel is dus binnen ongeveer twee minuten te zien voor een client die deze caching volgt. Zet de winkel de lijst uit of pauzeert Repairflow de API, dan geldt dat direct voor elke nieuwe aanvraag.
  • De body wordt gecomprimeerd (gzip) als je Accept-Encoding: gzip meestuurt. Elke gangbare HTTP-client doet dat vanzelf.
  • Een 200 en een 304 hebben ook een zwakke ETag, zoals W/"3f9a1c0b7d2e4a58". De ETag hangt alleen af van wat de lijst toont. Stuur hem terug in If-None-Match: is er niets veranderd, dan krijg je een 304 zonder body. Dat is de goedkoopste manier om te controleren. Gebruik de ETag alleen om te zien of de lijst gelijk is gebleven. Hij zegt niets over welke versie nieuwer is, dus vergelijk of sorteer ETags niet.
  • Het antwoord heeft X-Robots-Tag: noindex. De JSON zelf hoort niet in zoekmachines, jouw pagina’s wel.
  • Onbekende velden negeer je. In versie 1 kunnen er velden bijkomen.

Wat updatedAt betekent

updatedAt is het moment waarop Repairflow de gewijzigde lijst voor het eerst heeft geleverd. De wijziging zelf gebeurde daarvoor, na de vorige levering. updatedAt is dus niet het exacte moment van de wijziging, en ook niet het moment waarop je zelf voor het laatst hebt opgehaald.

Het verandert bij elke wijziging van wat de lijst toont: een prijs, een naam, een nieuwe reparatie, de btw, de disclaimer, Online boeken aan of uit. Een wijziging die niets aan de lijst verandert, laat updatedAt en de ETag ongemoeid. Een antwoord draagt altijd de updatedAt en de ETag van de lijst die erin staat.

updatedAt loopt niet gegarandeerd op tussen twee antwoorden. Repairflow kan de lijst vanaf meer dan één server leveren, elk met een eigen cache. In de eerste minuut na een wijziging kan een client daardoor afwisselend de vorige en de nieuwe versie krijgen, en dus ook weer een eerdere updatedAt. Gebruik updatedAt om te tonen wanneer de lijst voor het laatst is veranderd. Wil je weten of er iets veranderd is, gebruik dan de ETag.

Wat je doet bij elk antwoord

Antwoord Wat het betekent Wat je doet
200 De lijst. Gebruik hem en bewaar hem met zijn ETag.
304 Niets veranderd sinds je ETag. Houd je kopie.
404 met code: PRICE_LIST_NOT_FOUND De winkel publiceert niet (meer), of de slug klopt niet. Haal de prijzen van je site.
404 met code: NOT_FOUND Het pad onder /api/v1/ bestaat niet. Controleer je URL en houd je kopie.
400 met code: BAD_REQUEST of 413 met code: REQUEST_TOO_LARGE Je aanvraag had een body. Stuur een gewone GET zonder body en houd je kopie.
429 met code: PRICE_LIST_RATE_LIMITED Je haalt te vaak op. Houd je laatste goede kopie en probeer het later opnieuw. Volg Retry-After.
503 met code: PUBLIC_API_PAUSED Tijdelijk niet beschikbaar. Houd je laatste goede kopie en probeer het later opnieuw, na Retry-After.
Een andere 5xx, een 404 zonder code, geen verbinding Een tijdelijke storing. Houd je laatste goede kopie en probeer het later opnieuw.

Alleen 404 met de code PRICE_LIST_NOT_FOUND betekent dat de prijzen weg moeten. Bij elk ander antwoord dan 200 of 304 laat je de prijzen op je site staan, ook bij een 404 met een andere code. Anders zou een storing bij ons je site zonder prijzen laten staan.

Fouten hebben de vorm { "success": false, "code": "…", "message": "…" }. Lees de code, niet de message.

Uitzetten en opgeslagen kopieën

Zet de winkel de lijst uit, dan geeft de server bij de eerstvolgende aanvraag direct een 404, ook als hij de lijst nog bewaarde. Een client of tussenliggende cache kan de lijst nog hooguit 60 seconden tonen.

Een externe site die de gegevens heeft opgeslagen of in een build heeft verwerkt, toont ze tot ze zelf opnieuw ophaalt. Repairflow kan die kopieën niet intrekken. Bouw je site daarom zo dat hij regelmatig ophaalt en bij een 404 PRICE_LIST_NOT_FOUND zijn kopie verwijdert.

Statische sites, browsers en rate limits

Een statisch gebouwde site ververst niet vanzelf. Wanneer en hoe vaak de site de lijst ophaalt of opnieuw bouwt, bepaalt de site zelf. Plan dat dus, bijvoorbeeld met een timer of een geplande build, en kies een interval van minuten tot uren, niet van seconden.

Voor SEO en voor statische sites haal je de lijst aan de serverkant op en bewaar je een kopie. Dan staan je prijzen in de HTML, en blijft je site prijzen tonen als de API even niet antwoordt.

Ophalen vanuit de browser van de bezoeker kan ook. De browser houdt zich dan zelf aan max-age=60. Houd er rekening mee dat de limiet per winkel alle bezoekers van die winkel samen telt. Een drukke site haalt de lijst daarom beter aan de serverkant op en toont zijn eigen kopie aan de bezoekers.

De limieten (ze kunnen veranderen, bouw er niet op):

  • ongeveer 120 aanvragen per minuut per IP-adres;
  • ongeveer 120 aanvragen per minuut per winkel, alle IP-adressen samen;
  • ongeveer 280 aanvragen per minuut in totaal voor de hele API.

Ook een 304, 404 en 503 tellen mee. Een site die aan de serverkant een paar keer per uur ophaalt, blijft ver onder alle grenzen. Krijg je een 429, houd dan je laatste kopie en wacht minstens zo lang als Retry-After zegt.

Een voorbeeld aan de serverkant

Dit Node-script (vanaf Node 20) haalt de lijst op met If-None-Match, bewaart de laatste goede kopie, verwijdert de prijzen bij een 404 PRICE_LIST_NOT_FOUND en laat bij elk ander antwoord de kopie staan. Draai het op een timer of voor elke build en lees price-list.json bij het bouwen van je pagina’s.

import { readFile, writeFile, rm } from 'node:fs/promises';

const URL = 'https://api.repairflow.eu/api/v1/shops/voorbeeld-reparatie/price-list';
const COPY = './price-list.json';
const ETAG = './price-list.etag';

async function read(path) {
  try { return await readFile(path, 'utf8'); } catch { return null; }
}

export async function refreshPriceList() {
  const etag = await read(ETAG);
  let res;
  try {
    res = await fetch(URL, {
      headers: etag ? { 'If-None-Match': etag } : {},
      signal: AbortSignal.timeout(10_000),
    });
  } catch {
    return 'kept'; // geen verbinding: houd de laatste kopie
  }

  if (res.status === 304) return 'unchanged';

  if (res.status === 200) {
    const body = await res.text();
    JSON.parse(body); // ongeldige JSON valt hier door de mand
    await writeFile(COPY, body);
    const next = res.headers.get('etag');
    if (next) await writeFile(ETAG, next);
    return 'updated';
  }

  if (res.status === 404) {
    const error = await res.json().catch(() => null);
    if (error?.code === 'PRICE_LIST_NOT_FOUND') {
      await rm(COPY, { force: true }); // de winkel publiceert niet meer
      await rm(ETAG, { force: true });
      return 'removed';
    }
  }

  return 'kept'; // 429, 503, 5xx en al het andere: tijdelijk
}

Versies

Het contract heeft een versie in het pad. In v1 komen er alleen velden bij: bestaande velden verdwijnen niet en veranderen niet van betekenis, en een client negeert velden die hij niet kent. Een breuk komt als /api/v2/…, en v1 blijft bestaan zolang hij gebruikt wordt.

Heb je een vraag of loop je ergens tegenaan, mail dan support@repairflow.eu.