Konventionen

Anfragen und AntwortenLink zu diesem Abschnitt#

• Anfragen und Antworten sind JSON. Senden Sie Content-Type: application/json mit einem Body.
• Feldnamen sind camelCase: listPrice, accountCode, nextOffset.
• Abfrageparameter sind gewöhnliche Zeichenketten: ?limit=20&status=new.

Jede erfolgreiche Antwort ist ein Objekt mit data:

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

Bestellungen tragen ihr eigenes currency-Feld, das festgelegt wird, wenn die Bestellung aufgegeben wurde.

PagingLink zu diesem Abschnitt#

Listen nehmen limit und offset entgegen:

Weiterhin Anfragen mit offset=nextOffset stellen, bis nextOffset null ist:

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
}

Bei /products wird nextOffset gesetzt, sobald eine Seite vollständig ist. Wenn die Kataloggröße ein exaktes Vielfaches von limit ist, gibt die letzte Anfrage eine leere data-Liste mit nextOffset: null zurück.

Einige Listen sind begrenzt. GET /orders umfasst die 200 neuesten passenden Aufträge und GET /price-changes die 100 neuesten.

GeldLink zu diesem Abschnitt#

Geld ist eine Ganzzahl in Einheiten der Währung (Minor Units), sodass es keine Rundungsfehler gibt:

Durch die Anzahl der Dezimalstellen der Währung teilen, um sie anzuzeigen. In JavaScript übernimmt Intl.NumberFormat dies für Sie:

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"

Preise sind so festgelegt, wie der Lieferant sie in seinem Preislisten hat. Ob dies Steuern beinhaltet, ist die taxLabel des Workspaces auf GET /workspace: z. B. „ex VAT“ (vor Steuern), „inc GST“ (inkl. Steuern) oder leer, wenn der Lieferant keine Steuerausdrücke anzeigt.

ProzentsätzeLink zu diesem Abschnitt#

Prozentsätze sind Basispunkte: Hundertstel eines Prozents, als Ganzzahlen.

DatenLink zu diesem Abschnitt#

Daten sind ISO 8601-Strings in UTC, wie 2026-09-27T08:15:00.000Z. Die eigene Zeitzone des Workspaces ist timezone auf GET /workspace.

IDsLink zu diesem Abschnitt#

IDs sind UUID-Strings. Wo immer ein Endpunkt einen Kunden annimmt, können Sie die Kunden-ID oder den Kontocode des Kunden (case-insensitiv) übergeben, je nachdem, was Ihr System hat:

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

Erstellen und aktualisieren (PUT)Link zu diesem Abschnitt#

PUT /products und PUT /customers erstellen oder aktualisieren in einem Aufruf, bis zu 100 Zeilen gleichzeitig:

• Produkte werden anhand von SKU (case-insensitiv) abgeglichen.
• Kunden werden anhand von Kontocodes, dann E-Mail-Adressen, dann Namen abgeglichen.

Beide sind sicher wiederholbar. Das Senden der gleichen Zeilen zweimal ergibt das gleiche Ergebnis; der zweite Aufruf meldet sie nur als aktualisiert.

Ein PUT schreibt die Felder, die Sie senden. Einige optionale Produktfelder werden gelöscht, wenn Sie sie weglassen, andere bleiben erhalten. Jede Endpunktseite listet auf, welche.

BegrenzungenLink zu diesem Abschnitt#

Jeder Schlüssel kann 120 Anfragen pro Minute machen. Über diesem Limit erhalten Sie 429 rate_limited mit Retry-After: 60. Warten Sie und versuchen Sie es erneut. Fehler enthält einen Wiederholungshelper.

So viel Batch-Schreibvorgänge wie möglich: ein PUT mit 100 Produkten zählt als eine Anfrage.

VersionsverwaltungLink zu diesem Abschnitt#

Die Version ist im Pfad enthalten: /api/v1.

• Innerhalb von v1 führen wir nur additive Änderungen durch: neue Endpunkte, neue optionale Parameter, neue Felder in Antworten. Schreiben Sie Ihren Code so, dass er Felder ignoriert, die er nicht kennt.
• Eine Breaking Change erhält eine neue Version (/api/v2), wobei v1 weiterhin läuft und die Änderung im Changelog angekündigt wird.