# API REST

> Panoramica di ciò che copre l'API REST di TradeCatalog, chi può utilizzarla e ogni endpoint.

L'API REST fornisce ai tuoi sistemi gli stessi dati che i tuoi dipendenti vedono in TradeCatalog: prodotti, prezzi dei clienti, clienti, ordini, modifiche dei prezzi e il registro delle attività. Utilizza JSON su HTTPS e una chiave API per sistema.

## URL di base

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

Ogni richiesta necessita di una chiave API nell'intestazione `Authorization`. Vedere [Autenticazione](/docs/api/authentication).

## Chi può utilizzarlo

- **Proprietari e amministratori** creano e revocano le chiavi. Altri dipendenti e acquirenti non possono.
- Il workspace necessita di una **entitlement Pro** o di un **account pilota** per creare le chiavi.
- I **workspaces di demo** non possono utilizzare l'API affatto.
- Quando Pro termina, il workspace torna a Free: le chiavi API esistenti possono ancora leggere ma non scrivere. Le modifiche al catalogo e gli ordini degli acquirenti nell'app continuano a funzionare.

Una chiave appartiene a un solo workspace. Agisce con le autorizzazioni della persona che l'ha creata, quindi una chiave di un proprietario o amministratore può vedere i prezzi di tutti i clienti. Se quella persona lascia il workspace, la chiave smette di funzionare.

## Endpoint

| Metodo | Percorso                                                                | Cosa fa                                                                      | Scope |
| ------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----- |
| GET    | [`/workspace`](/docs/api/workspace)                                     | Il workspace a cui appartiene questa chiave                                  | read  |
| GET    | [`/products`](/docs/api/products#list-or-search-products)               | Elenco o ricerca prodotti, opzionalmente con i prezzi di un cliente          | read  |
| GET    | [`/products/{id}`](/docs/api/products#get-one-product)                  | Un prodotto con il suo prezzo                                                | read  |
| PUT    | [`/products`](/docs/api/products#create-or-update-products)             | Crea o aggiorna fino a 100 prodotti per SKU                                  | write |
| GET    | [`/brands`](/docs/api/products#brands-and-categories)                   | Tutte le marche                                                              | read  |
| GET    | [`/categories`](/docs/api/products#brands-and-categories)               | Tutte le categorie                                                           | read  |
| GET    | [`/prices`](/docs/api/prices)                                           | Quanto paga un cliente per un SKU, e perché                                  | read  |
| GET    | [`/customers`](/docs/api/customers#list-customers)                      | Clienti commerciali                                                          | read  |
| GET    | [`/customers/{id}`](/docs/api/customers#get-one-customer)               | Le condizioni, le regole, i prezzi concordati e gli acquirenti di un cliente | read  |
| PUT    | [`/customers`](/docs/api/customers#create-or-update-customers)          | Crea o aggiorna fino a 100 clienti                                           | write |
| GET    | [`/orders`](/docs/api/orders#list-orders)                               | Ordini recenti, dal più recente al più vecchio                               | read  |
| GET    | [`/orders/{id}`](/docs/api/orders#get-one-order)                        | Un ordine con le linee e la cronologia dello stato                           | read  |
| PATCH  | [`/orders/{id}`](/docs/api/orders#move-an-order-on)                     | Sposta un ordine in avanti                                                   | write |
| GET    | [`/price-changes`](/docs/api/price-changes#list-price-changes)          | Modifiche dei prezzi, dal più recente al più vecchio                         | read  |
| GET    | [`/price-changes/{id}`](/docs/api/price-changes#preview-a-price-change) | Anteprima una modifica dei prezzi                                            | read  |
| GET    | [`/activity`](/docs/api/activity)                                       | Chi ha modificato cosa                                                       | read  |

La descrizione completa e leggibile dalla macchina è su [`/api/v1/openapi.json`](/docs/api/openapi).

## Prima di iniziare a sviluppare

- Leggi [Convenzioni](/docs/api/conventions) per denaro, paginazione, date e come funziona `PUT`.
- Leggi [Errori](/docs/api/errors) per codici di stato e riprovare.
- Mantieni le chiavi sul tuo server. L'API non permette richieste dal browser (CORS).

## Non ancora disponibile nell'API

- Webhook: usa invece `GET /orders?status=new`.
- Pubblicazione, pianificazione o annullamento di modifiche dei prezzi: fai questo nell'app.
- Regole di sconto e prezzi concordati: leggili con `GET /customers/{id}`, modificali nell'app.
- Cancellare prodotti o clienti, caricare immagini direttamente, invitare acquirenti, effettuare ordini come acquirente.