# OpenAPI

> Die OpenAPI 3.1-Beschreibung der TradeCatalog-API und wie sie mit Postman, typisierten Clients und API-Explorern verwendet wird.

Die gesamte API wird in einem einzigen OpenAPI 3.1-Dokument beschrieben:

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

Sie ist öffentlich (kein Schlüssel erforderlich) und wird aus denselben Schemas generiert, die die API verwendet, um Anfragen zu überprüfen, sodass sie nicht von dem abweichen kann, was die API akzeptiert. Sie enthält jeden Pfad, jeden Parameter, jede Anfragekörper, jede Begrenzung und jeden Enum-Wert.

## In Postman oder Insomnia importieren

1. Wählen Sie in Postman **Importieren** und fügen Sie die oben stehende URL ein. Wählen Sie in Insomnia **Importieren** und dann **Aus URL**.
2. Legen Sie die Authentifizierung der Sammlung auf **Bearer Token** mit Ihrem API-Schlüssel fest.

## TypeScript-Typen generieren

[openapi-typescript](https://openapi-ts.dev) konvertiert es in Typen:

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

Verwenden Sie sie mit `openapi-fetch` für einen typisierten Client:

```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 } },
})
```

Das Dokument beschreibt Anforderungsparameter und -texte im Detail. Antworttexte werden als gemeinsamer `{ data, nextOffset, currency }`-Umschlag beschrieben; die feldweise Antwortformate sind auf der Seite jedes Endpunkts in diesen Dokumenten.

## Andere Sprachen

Jeder OpenAPI-Generator funktioniert, z. B.:

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

## Durchsuchen Sie es

Fügen Sie die URL in [Scalar](https://scalar.com), [Swagger Editor](https://editor.swagger.io) oder einen beliebigen OpenAPI-Betrachter ein, um die Endpunkte zu durchsuchen und Anfragen mit Ihrem Schlüssel zu testen.

## Für KI-Agenten

Das OpenAPI-Dokument ist in der API-Katalogliste unter `/.well-known/api-catalog` aufgeführt, sodass Agenten es selbst finden können. Siehe [AI- und LLM-Ressourcen](/docs/guides/llms).