# API REST

> Una visión general de lo que cubre la API de TradeCatalog REST, quién puede usarla y cada punto final.

La API REST le da a sus sistemas propios los mismos datos que ven sus empleados en TradeCatalog: productos, precios de clientes, clientes, pedidos, cambios de precios y el registro de actividad. Utiliza JSON sobre HTTPS y una clave de API por sistema.

## URL base

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

Cada solicitud necesita una clave de API en el encabezado `Authorization`. Vea [Autenticación](/docs/api/authentication).

## ¿Quién puede usarlo

- Los propietarios y administradores crean y revocan claves. Otro personal y compradores no pueden.
- El espacio de trabajo necesita una **entitlement Pro** o una cuenta de **piloto** para crear claves.
- Los espacios de trabajo de **demo** no pueden usar la API en absoluto.
- Cuando finaliza el Pro, el espacio de trabajo vuelve a Free: las claves de API existentes aún pueden leer, pero no pueden escribir. Las ediciones del catálogo y los pedidos de compradores en la aplicación siguen funcionando.

Una clave pertenece a un espacio de trabajo. Actúa con los permisos de la persona que la creó, por lo tanto, una clave de un propietario o administrador puede ver los precios de todos los clientes. Si esa persona deja el espacio de trabajo, la clave deja de funcionar.

## Puntos finales

| Método | Ruta                                                                    | Qué hace                                                            | Alcance   |
| ------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------- | --------- |
| GET    | [`/workspace`](/docs/api/workspace)                                     | El espacio de trabajo al que pertenece esta clave                   | lectura   |
| GET    | [`/products`](/docs/api/products#list-or-search-products)               | Lista o busca productos, opcionalmente a los precios de un cliente  | lectura   |
| GET    | [`/products/{id}`](/docs/api/products#get-one-product)                  | Un producto con su precio                                           | lectura   |
| PUT    | [`/products`](/docs/api/products#create-or-update-products)             | Crea o actualiza hasta 100 productos por SKU                        | escritura |
| GET    | [`/brands`](/docs/api/products#brands-and-categories)                   | Todos los marcas                                                    | lectura   |
| GET    | [`/categories`](/docs/api/products#brands-and-categories)               | Todas las categorías                                                | lectura   |
| GET    | [`/prices`](/docs/api/prices)                                           | Lo que un cliente paga por un SKU, y por qué                        | lectura   |
| GET    | [`/customers`](/docs/api/customers#list-customers)                      | Clientes comerciales                                                | lectura   |
| GET    | [`/customers/{id}`](/docs/api/customers#get-one-customer)               | Los términos, reglas, precios acordados y compradores de un cliente | lectura   |
| PUT    | [`/customers`](/docs/api/customers#create-or-update-customers)          | Crea o actualiza hasta 100 clientes                                 | escritura |
| GET    | [`/orders`](/docs/api/orders#list-orders)                               | Últimos pedidos, desde el más reciente                              | lectura   |
| GET    | [`/orders/{id}`](/docs/api/orders#get-one-order)                        | Un pedido con líneas y historial de estado                          | lectura   |
| PATCH  | [`/orders/{id}`](/docs/api/orders#move-an-order-on)                     | Mover un pedido adelante                                            | escritura |
| GET    | [`/price-changes`](/docs/api/price-changes#list-price-changes)          | Cambios de precios, desde el más reciente                           | lectura   |
| GET    | [`/price-changes/{id}`](/docs/api/price-changes#preview-a-price-change) | Vista previa de un cambio de precio                                 | lectura   |
| GET    | [`/activity`](/docs/api/activity)                                       | Quién cambió qué                                                    | lectura   |

La descripción completa y máquina legible está en [`/api/v1/openapi.json`](/docs/api/openapi).

## Antes de construir

- Lea [Convenciones](/docs/api/conventions) sobre dinero, paginación, fechas y cómo funciona `PUT`.
- Lea [Errores](/docs/api/errors) sobre códigos de estado y reintentos.
- Mantenga las claves en su servidor. La API no permite solicitudes de navegador (CORS).

## Aún no en la API

- Webhooks: use `GET /orders?status=new` en su lugar.
- Publicar, programar o cancelar cambios de precios: hágalo en la aplicación.
- Reglas de descuento y precios acordados: léalos con `GET /customers/{id}`, cámbielos en la aplicación.
- Eliminar productos o clientes, cargar imágenes directamente, invitar a compradores, realizar pedidos como comprador.