Conventions

Demandes et réponsesLien vers cette section#

• Les demandes et les réponses sont au format JSON. Envoyez Content-Type: application/json avec un corps.
• Les noms de champ sont en camelCase : listPrice, accountCode, nextOffset.
• Les paramètres de requête sont des chaînes simples : ?limit=20&status=new.

Toute réponse réussie est un objet avec data :

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

Les commandes portent leur propre champ currency, fixé lors de la commande.

PaginationLien vers cette section#

Les listes prennent limit et offset :

Continuez à demander avec offset=nextOffset jusqu'à ce que nextOffset soit 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
}

Le /products, nextOffset est défini chaque fois qu'une page est pleine. Si la taille du catalogue est un multiple exact de limit, la dernière demande renvoie une liste vide data avec nextOffset: null.

Certaines listes sont limitées. GET /orders couvre les 200 dernières commandes correspondantes, et GET /price-changes les 100 dernières.

ArgentLien vers cette section#

L'argent est un entier en unités mineures de la devise, donc il n'y a pas d'erreur d'arrondi :

Divisez par 10 à la puissance du nombre de décimales de la devise pour l'afficher. En JavaScript, Intl.NumberFormat le fait pour vous :

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"

Les prix sont tels que le fournisseur les définit dans sa liste de prix. Si cela inclut la taxe dépend de l'option taxLabel de l'espace de travail sur GET /workspace : par exemple « hors TVA » (avant la taxe), « inclus GST » (avec la taxe), ou vide lorsque le fournisseur n'affiche pas de mention de taxe.

PourcentagesLien vers cette section#

Les pourcentages sont des points de base : centièmes de pourcentage, sous forme d'entiers.

DatesLien vers cette section#

Les dates sont des chaînes au format ISO 8601 en UTC, comme 2026-09-27T08:15:00.000Z. La zone horaire propre à l'espace de travail est timezone sur GET /workspace.

IdentifiantsLien vers cette section#

Les identifiants sont des chaînes UUID. Là où un point de terminaison prend un client, vous pouvez passer l'identifiant du client ou son code de compte (insensible à la casse), selon ce que votre système possède :

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

Création et mise à jour (PUT)Lien vers cette section#

PUT /products et PUT /customers créent ou mettent à jour en une seule appel, jusqu'à 100 lignes à la fois :

• Les produits sont identifiés par SKU (insensible à la casse).
• Les clients sont identifiés par code de compte, sinon par email, sinon par nom.

Les deux sont sans danger pour être répétés. Envoyer les mêmes lignes deux fois donne le même résultat ; le second appel ne signale que les mettre à jour.

Un PUT écrit les champs que vous envoyez. Certains champs de produit optionnels sont effacés lorsque vous les omettez, d'autres sont conservés. Chaque page d'endpoint liste lesquels.

Limites de débitLien vers cette section#

Chaque clé peut effectuer 120 requêtes par minute. Au-delà, vous obtenez 429 rate_limited avec Retry-After: 60. Attendez et réessayez. Erreurs dispose d'un assistant de réessai.

Effectuez des écritures par lot là où c'est possible : un PUT avec 100 produits compte comme une seule requête.

VersioningLien vers cette section#

La version est dans le chemin : /api/v1.

• Dans v1, nous n’apportons que des changements additifs : nouveaux points de terminaison, nouveaux paramètres optionnels, nouveaux champs dans les réponses. Écrivez votre code pour ignorer les champs qu’il ne connaît pas.
• Un changement rétrograde entraînerait une nouvelle version (/api/v2), avec v1 qui continue à fonctionner et le changement annoncé dans le changelog.