# API REST

> Ce que couvre l'API REST de TradeCatalog, qui peut l'utiliser et tous les points de terminaison en un coup d'œil.

L'API REST vous donne les mêmes données que celles que vos équipes voient dans TradeCatalog : produits, prix clients, clients, commandes, changements de prix et journal d'activité. Elle utilise le JSON sur HTTPS et une clé API par système.

## URL de base

```text
https://tradecatalog.app/api/v1
```

Chaque requête nécessite une clé API dans l’en-tête `Authorization`. Voir [Authentification](/docs/api/authentication).

## Qui peut l'utiliser

- **Les propriétaires et administrateurs** créent et révoquent les clés. Les autres employés et acheteurs ne peuvent pas.
- L’espace de travail doit avoir une **licence Pro** ou un **compte pilote** pour créer des clés.
- Les **espaces de travail de démonstration** ne peuvent pas utiliser l’API du tout.
- Lorsque la licence Pro expire, l’espace de travail revient à l’offre Free : les clés API existantes peuvent toujours lire mais ne peuvent pas écrire. Les modifications du catalogue et les commandes des acheteurs dans l’application fonctionnent toujours.

Une clé appartient à un seul espace de travail. Elle agit avec les autorisations de la personne qui l’a créée, donc une clé d’un propriétaire ou d’un administrateur peut voir les prix de tous les clients. Si cette personne quitte l’espace de travail, la clé ne fonctionne plus.

## Points de terminaison

| Méthode | Chemin                                                                  | Ce qu'il fait                                                        | Portée   |
| ------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------- | -------- |
| GET     | [`/workspace`](/docs/api/workspace)                                     | L'espace de travail auquel appartient cette clé                      | lecture  |
| GET     | [`/products`](/docs/api/products#list-or-search-products)               | Liste ou recherche de produits, optionnellement aux prix d'un client | lecture  |
| GET     | [`/products/{id}`](/docs/api/products#get-one-product)                  | Un produit avec son prix                                             | lecture  |
| PUT     | [`/products`](/docs/api/products#create-or-update-products)             | Créer ou mettre à jour jusqu'à 100 produits par SKU                  | écriture |
| GET     | [`/brands`](/docs/api/products#brands-and-categories)                   | Toutes les marques                                                   | lecture  |
| GET     | [`/categories`](/docs/api/products#brands-and-categories)               | Toutes les catégories                                                | lecture  |
| GET     | [`/prices`](/docs/api/prices)                                           | Ce que paie un client pour un SKU, et pourquoi                       | lecture  |
| GET     | [`/customers`](/docs/api/customers#list-customers)                      | Clients commerciaux                                                  | lecture  |
| GET     | [`/customers/{id}`](/docs/api/customers#get-one-customer)               | Les termes, règles, prix convenus et acheteurs d'un client           | lecture  |
| PUT     | [`/customers`](/docs/api/customers#create-or-update-customers)          | Créer ou mettre à jour jusqu'à 100 clients                           | écriture |
| GET     | [`/orders`](/docs/api/orders#list-orders)                               | Commandes récentes, du plus récent au plus ancien                    | lecture  |
| GET     | [`/orders/{id}`](/docs/api/orders#get-one-order)                        | Une commande avec ses lignes et son historique d'état                | lecture  |
| PATCH   | [`/orders/{id}`](/docs/api/orders#move-an-order-on)                     | Déplacer une commande sur                                            | écriture |
| GET     | [`/price-changes`](/docs/api/price-changes#list-price-changes)          | Changements de prix, du plus récent au plus ancien                   | lecture  |
| GET     | [`/price-changes/{id}`](/docs/api/price-changes#preview-a-price-change) | Aperçu d'un changement de prix                                       | lecture  |
| GET     | [`/activity`](/docs/api/activity)                                       | Qui a changé quoi                                                    | lecture  |

La description complète et lisible par la machine se trouve à [`/api/v1/openapi.json`](/docs/api/openapi).

## Avant de commencer à développer

- Lisez [Conventions](/docs/api/conventions) pour les montants, la pagination, les dates et comment `PUT` fonctionne.
- Lisez [Erreurs](/docs/api/errors) pour les codes d'état et les réessais.
- Gardez les clés sur votre serveur. L'API n'autorise pas les requêtes depuis le navigateur (CORS).

## Pas encore dans l'API

- Webhooks : utilisez l'interrogation de `GET /orders?status=new` au lieu de cela.
- Publication, planification ou annulation des changements de prix : faites-le dans l'application.
- Règles de remise et prix convenus : lisez-les avec `GET /customers/{id}`, modifiez-les dans l'application.
- Suppression de produits ou de clients, téléchargement d'images directement, invitation d'acheteurs, passation de commandes en tant qu'acheteur.