# OpenAPI

> La descrizione OpenAPI 3.1 dell'API TradeCatalog e come utilizzarla con Postman, client tipizzati e esploratori API.

L'intera API è descritta in un documento OpenAPI 3.1:

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

È pubblico (non è necessaria una chiave) e generato dagli stessi schemi utilizzati dall'API per verificare le richieste, quindi non si allontana da ciò che l'API accetta. Include ogni percorso, parametro, corpo della richiesta, limite e valore enum.

## Importa in Postman o Insomnia

1. In Postman, scegliere **Importa** e incollare l'URL sopra. In Insomnia, scegliere **Importa** quindi **Da URL**.
2. Impostare l'autenticazione della raccolta su **Token Bearer** con la tua chiave API.

## Genera tipi TypeScript

[openapi-typescript](https://openapi-ts.dev) li converte in tipi:

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

Utilizzali con `openapi-fetch` per un client tipizzato:

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

Il documento descrive i parametri e i corpi delle richieste in modo completo. I corpi delle risposte sono descritti come l'envelope condiviso `{ data, nextOffset, currency }`; le forme dei campi delle risposte sono disponibili nella pagina di ogni endpoint in questi documenti.

## Altri linguaggi

Qualsiasi generatore OpenAPI funziona, ad esempio:

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

## Esploralo

Incolla l'URL in [Scalar](https://scalar.com), [Swagger Editor](https://editor.swagger.io) o qualsiasi visualizzatore OpenAPI per esplorare gli endpoint e provare le richieste con la tua chiave.

## Per gli agenti di intelligenza artificiale

Il documento OpenAPI è elencato nel catalogo API su `/.well-known/api-catalog`, quindi gli agenti possono trovarlo da soli. Vedere [risorse per l'IA e i modelli linguistici](/docs/guides/llms).