# OpenAPI

> La descripción de OpenAPI 3.1 de la API de TradeCatalog, y cómo usarla con Postman, clientes tipados y exploradores de API.

La totalidad de la API se describe en un único documento OpenAPI 3.1:

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

Es público (no se necesita clave) y se genera a partir de los mismos esquemas que utiliza la API para verificar las solicitudes, por lo que no se desfasará de lo que acepta la API. Incluye cada ruta, parámetro, cuerpo de solicitud, límite y valor de enumeración.

## Importar en Postman o Insomnia

1. En Postman, elija **Importar** y pegue la URL anterior. En Insomnia, elija **Importar** y luego **Desde URL**.
2. Establezca la autenticación de la colección en **Token de portador** con su clave de API.

## Generar tipos de TypeScript

[openapi-typescript](https://openapi-ts.dev) los convierte en tipos:

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

Luego use los tipos con `openapi-fetch` para un 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 } },
})
```

El documento describe parámetros y cuerpos de solicitud en detalle. Los cuerpos de respuesta se describen como el sobre compartido `{ data, nextOffset, currency }`; las formas de respuesta por campo están en la página de cada punto final en estos documentos.

## Otros lenguajes

Cualquier generador de OpenAPI funciona, por ejemplo:

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

## Navegarlo

Pegue la URL en [Scalar](https://scalar.com), [Swagger Editor](https://editor.swagger.io) o cualquier visualizador de OpenAPI para navegar los puntos finales y probar solicitudes con su clave.

## Para agentes de IA

El documento OpenAPI está listado en el catálogo de API en `/.well-known/api-catalog`, por lo que los agentes pueden encontrarlo por sí mismos. Vea [Recursos de IA y LLM](/docs/guides/llms).