# API REST

> O que a API REST do TradeCatalog abrange, quem pode usá-la e todos os pontos finais de um olhar.

A API REST fornece aos seus sistemas próprios os mesmos dados que sua equipe vê no TradeCatalog: produtos, preços dos clientes, clientes, pedidos, mudanças de preços e o log de atividades. Ela usa JSON sobre HTTPS e uma chave de API por sistema.

## URL base

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

Toda requisição precisa de uma chave de API no cabeçalho `Authorization`. Veja [Autenticação](/docs/api/authentication).

## Quem pode usá-lo

- **Proprietários e administradores** criam e revogam chaves. Outros funcionários e compradores não podem.
- O workspace precisa de uma **entidade Pro** ou de uma **conta de pilotagem** para criar chaves.
- **Workspaces de demonstração** não podem usar a API de forma alguma.
- Quando o Pro termina, o workspace retorna para Free: as chaves de API existentes ainda podem ler, mas não podem gravar. Edições no catálogo e pedidos de compradores no app continuam funcionando.

Uma chave pertence a um único workspace. Ela age com as permissões da pessoa que a criou, então uma chave de proprietário ou administrador pode ver os preços de todos os clientes. Se essa pessoa sair do workspace, a chave deixará de funcionar.

## Pontos finais

| Método | Caminho                                                                 | O que ele faz                                                      | Escopo  |
| ------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------ | ------- |
| GET    | [`/workspace`](/docs/api/workspace)                                     | O workspace ao qual esta chave pertence                            | leitura |
| GET    | [`/products`](/docs/api/products#list-or-search-products)               | Lista ou pesquisa produtos, opcionalmente com preços de um cliente | leitura |
| GET    | [`/products/{id}`](/docs/api/products#get-one-product)                  | Um produto com seu preço                                           | leitura |
| PUT    | [`/products`](/docs/api/products#create-or-update-products)             | Cria ou atualiza até 100 produtos por SKU                          | escrita |
| GET    | [`/brands`](/docs/api/products#brands-and-categories)                   | Todos os marcas                                                    | leitura |
| GET    | [`/categories`](/docs/api/products#brands-and-categories)               | Todas as categorias                                                | leitura |
| GET    | [`/prices`](/docs/api/prices)                                           | O que um cliente paga por um SKU, e por quê                        | leitura |
| GET    | [`/customers`](/docs/api/customers#list-customers)                      | Clientes comerciais                                                | leitura |
| GET    | [`/customers/{id}`](/docs/api/customers#get-one-customer)               | Termos, regras, preços acordados e compradores de um cliente       | leitura |
| PUT    | [`/customers`](/docs/api/customers#create-or-update-customers)          | Cria ou atualiza até 100 clientes                                  | escrita |
| GET    | [`/orders`](/docs/api/orders#list-orders)                               | Pedidos recentes, do mais novo para o mais antigo                  | leitura |
| GET    | [`/orders/{id}`](/docs/api/orders#get-one-order)                        | Um pedido com linhas e histórico de status                         | leitura |
| PATCH  | [`/orders/{id}`](/docs/api/orders#move-an-order-on)                     | Avança um pedido                                                   | escrita |
| GET    | [`/price-changes`](/docs/api/price-changes#list-price-changes)          | Mudanças de preços, do mais novo para o mais antigo                | leitura |
| GET    | [`/price-changes/{id}`](/docs/api/price-changes#preview-a-price-change) | Visualização de uma mudança de preço                               | leitura |
| GET    | [`/activity`](/docs/api/activity)                                       | Quem alterou o quê                                                 | leitura |

A descrição completa e de leitura automática está em [`/api/v1/openapi.json`](/docs/api/openapi).

## Antes de começar a desenvolver

- Leia [Convenções](/docs/api/conventions) sobre dinheiro, paginação, datas e como `PUT` funciona.
- Leia [Erros](/docs/api/errors) sobre códigos de status e tentativas de novo.
- Mantenha as chaves no seu servidor. A API não permite solicitações de navegador (CORS).

## Ainda não disponível na API

- Webhooks: faça poll em `GET /orders?status=new` em vez disso.
- Publicação, agendamento ou cancelamento de mudanças de preço: faça isso no app.
- Regras de desconto e preços acordados: leia-os com `GET /customers/{id}`, altere-os no app.
- Exclusão de produtos ou clientes, upload de imagens diretamente, convite de compradores, colocação de pedidos como comprador.