# OpenAPI

> A descrição OpenAPI 3.1 da API TradeCatalog e como usá-la com Postman, clientes tipados e exploradores de API.

Toda a API é descrita em um único documento OpenAPI 3.1:

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

É público (não é necessário chave) e gerado a partir das mesmas estruturas que a API usa para verificar as requisições, então ele não pode se afastar do que a API aceita. Ele inclui todos os caminhos, parâmetros, corpo da requisição, limites e valores de enumeração.

## Importar para Postman ou Insomnia

1. No Postman, escolha **Importar** e cole a URL acima. No Insomnia, escolha **Importar** e depois **De URL**.
2. Defina a autenticação da coleção como **Token de Portador** com sua chave de API.

## Gerar tipos TypeScript

[openapi-typescript](https://openapi-ts.dev) os converte em tipos:

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

Use-os com `openapi-fetch` para um cliente tipado:

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

O documento descreve parâmetros e corpos de solicitação em detalhes. Os corpos de resposta são descritos como o envelope compartilhado `{ data, nextOffset, currency }`; as formas de resposta por campo estão na página de cada ponto final neste documento.

## Outras linguagens

Qualquer gerador OpenAPI funciona, por exemplo:

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

## Navegue por ele

Cole a URL no [Scalar](https://scalar.com), [Swagger Editor](https://editor.swagger.io) ou qualquer visualizador OpenAPI para navegar pelos pontos finais e testar solicitações com sua chave.

## Para agentes de IA

O documento OpenAPI está listado no catálogo de API em `/.well-known/api-catalog`, então os agentes podem encontrá-lo por conta própria. Veja [Recursos de IA e LLM](/docs/guides/llms).