Conventies

Aanvragen en antwoordenLink naar deze sectie#

• Aanvragen en antwoorden zijn JSON. Stuur Content-Type: application/json met een body.
• Veldnamen zijn camelCase: listPrice, accountCode, nextOffset.
• Query parameters zijn gewone strings: ?limit=20&status=new.

Elk succesvol antwoord is een object met data:

{
  "data": [],
  "nextOffset": 50,
  "currency": "GBP"
}

Bestellingen hebben hun eigen currency veld, vastgelegd op het moment dat de bestelling is geplaatst.

PaginerenLink naar deze sectie#

Lijsten nemen limit en offset:

Blijf aanvragen met offset=nextOffset tot nextOffset null:

let offset = 0
const all = []
while (offset !== null) {
  const res = await fetch(
    `https://tradecatalog.app/api/v1/products?limit=50&offset=${offset}`,
    {
      headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
    },
  )
  const page = await res.json()
  all.push(...page.data)
  offset = page.nextOffset
}

Op /products wordt nextOffset ingesteld wanneer een pagina vol is. Als de catalogusgrootte een exacte veelvoud is van limit, retourneert de laatste aanvraag een lege data-lijst met nextOffset: null.

Enkele lijsten zijn beperkt. GET /orders omvat de 200 meest recente overeenkomende bestellingen, en GET /price-changes de 100 meest recente.

GeldLink naar deze sectie#

Geld is een geheel getal in mindere eenheden van de valuta, zodat er geen afrondingsfout is:

Deel door 10 tot de macht van het aantal decimalen van de valuta om het weer te geven. In JavaScript doet Intl.NumberFormat dat voor je:

const format = (minor, currency) => {
  const f = new Intl.NumberFormat('en-GB', { style: 'currency', currency })
  const digits = f.resolvedOptions().maximumFractionDigits
  return f.format(minor / 10 ** digits)
}
format(1234, 'GBP') // "£12.34"

De prijzen zijn zoals de leverancier ze in hun prijslijst heeft ingesteld. Of dat belastingen bevat, is de instelling van de werkruimte taxLabel op GET /workspace: bijvoorbeeld “ex BTW” (voor belasting), “inc BTW” (inclusief belasting), of leeg wanneer de leverancier geen belastingtekst toont.

PercentagesLink naar deze sectie#

Percentages zijn basispunten: honderdsten van een procent, als gehele getallen.

DatumsLink naar deze sectie#

Datums zijn ISO 8601-strings in UTC, zoals 2026-09-27T08:15:00.000Z. De tijdzone van de werkruimte is timezone op GET /workspace.

IdsLink naar deze sectie#

Ids zijn UUID-strings. Waar een eindpunt een klant verwacht, kunt u het klant-id of hun accountcode (gevoelig voor hoofdletters) doorgeven, afhankelijk van wat uw systeem heeft:

curl "https://tradecatalog.app/api/v1/prices?customer=OAK01&sku=HX-8510" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

Aanmaken en bijwerken (PUT)Link naar deze sectie#

PUT /products en PUT /customers maken of bijwerken in één oproep, maximaal 100 rijen tegelijk:

• Producten worden geïdentificeerd aan de hand van SKU (gevoelig voor hoofdletters).
• Klanten worden geïdentificeerd aan de hand van accountcode, anders e-mail, anders naam.

Beide zijn veilig te herhalen. Hetzelfde rijen meesturen twee keer geeft hetzelfde resultaat; de tweede oproep rapporteert ze alleen als bijgewerkt.

Een PUT schrijft de velden die u stuurt. Sommige optionele productvelden worden gewist wanneer u ze weglaat, andere blijven behouden. Elke eindpuntpagina geeft aan welke velden dat zijn.

RatenbeperkingenLink naar deze sectie#

Elke sleutel kan 120 aanvragen per minuut maken. Boven dat aantal krijgt u 429 rate_limited met Retry-After: 60. Wacht en probeer het opnieuw. Fouten bevat een herhaalhulpmiddel.

Batch-schrijven waar mogelijk: één PUT met 100 producten telt als één aanvraag.

VersiebeheerLink naar deze sectie#

De versie is in de pad: /api/v1.

• Binnen v1 maken we alleen additieve wijzigingen: nieuwe eindpunten, nieuwe optionele parameters, nieuwe velden in antwoorden. Schrijf je code zodat deze onbekende velden negeert.
• Een brekende wijziging krijgt een nieuwe versie (/api/v2), met v1 die nog draait en de wijziging aangekondigd in de changelog.