# OpenAPI

> La description OpenAPI 3.1 de l'API TradeCatalog, et comment l'utiliser avec Postman, des clients typés et des outils d'exploration d'API.

L'ensemble de l'API est décrit dans un seul document OpenAPI 3.1 :

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

Il est public (aucune clé n’est nécessaire) et généré à partir des mêmes schémas que l’API utilise pour vérifier les requêtes, donc il ne peut pas s’éloigner de ce que l’API accepte. Il inclut chaque chemin, paramètre, corps de la requête, limite et valeur d’énumération.

## Importer dans Postman ou Insomnia

1. Dans Postman, sélectionnez **Importer** et collez l'URL ci-dessus. Dans Insomnia, sélectionnez **Importer**, puis **À partir d'une URL**.
2. Configurez l'authentification de la collection sur **Jeton Bearer** avec votre clé API.

## Générer des types TypeScript

[openapi-typescript](https://openapi-ts.dev) les transforme en types :

```bash
npx openapi-typescript https://tradecatalog.app/api/v1/openapi.json -o tradecatalog.d.ts
```

Utilisez-les avec `openapi-fetch` pour un client typé :

```js
import createClient from 'openapi-fetch'

const client = createClient({
  baseUrl: 'https://tradecatalog.app/api/v1',
  headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
})

const { data, error } = await client.GET('/prices', {
  params: { query: { customer: 'OAK01', sku: 'HX-8510', qty: 10 } },
})
```

Le document décrit en détail les paramètres et les corps des requêtes. Les corps des réponses sont décrits sous la forme de l'enveloppe partagée `{ data, nextOffset, currency }` ; les formes des réponses par champ sont disponibles sur la page de chaque point de terminaison dans ces documents.

## Autres langages

Tout générateur OpenAPI fonctionne, par exemple :

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://tradecatalog.app/api/v1/openapi.json \
  -g python -o tradecatalog-client
```

## Parcourir le document

Collez l'URL dans [Scalar](https://scalar.com), [Swagger Editor](https://editor.swagger.io) ou tout visualiseur OpenAPI pour explorer les points de terminaison et tester des requêtes avec votre clé.

## Pour les agents d'IA

Le document OpenAPI est répertorié dans le catalogue API à `/.well-known/api-catalog`, donc les agents peuvent le trouver seuls. Voir [Ressources sur l'IA et les modèles de langage](/docs/guides/llms).