# Guida rapida

> Crea una chiave API e effettua le tue prime chiamate all'API TradeCatalog in cinque minuti.

È necessario essere il **proprietario** di un workspace TradeCatalog con un'autorizzazione Pro o un account di prova. I workspace di demo non possono utilizzare l'API.

## 1. Crea una chiave API

1. Apri il tuo workspace e vai su **Impostazioni → API**.
2. Assegna al key un nome che riconoscerai in futuro, ad esempio "Sage stock sync".
3. Scegli **Solo lettura** per cercare informazioni, o **Lettura e scrittura** per aggiornare prodotti, clienti e ordini.
4. Scegli **Crea chiave** e copiala. Inizia con `tc_live_`.

**Copiala ora:** Mostreremo una chiave solo una volta e terrò solo un hash di essa. Se la perdi, revocala e creane una nuova.

Inserisci la chiave in una variabile d'ambiente per mantenerla fuori dal tuo codice:

```bash
export TRADECATALOG_API_KEY="tc_live_…"
```

## 2. Verifica che la chiave funzioni

```bash
curl https://tradecatalog.app/api/v1/workspace \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"
```

```json
{
  "data": {
    "id": "0b6c1f5e-6f7a-4a57-9a0c-2f4d4c1e8a11",
    "slug": "northgate",
    "name": "Northgate Fixings",
    "currency": "GBP",
    "timezone": "Europe/London",
    "taxLabel": "ex VAT",
    "key": { "name": "Sage stock sync", "scope": "write" }
  }
}
```

## 3. Cerca prodotti

```bash
curl "https://tradecatalog.app/api/v1/products?q=hinge&limit=2" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"
```

I soldi sono sempre in **unità minori** della valuta del workspace, quindi `1850` è £18.50.. Vedere [Convenzioni](/docs/api/conventions).

## 4. Ottieni il prezzo di un cliente

Passa il codice (o l'id) dell'account del cliente e un SKU:

```bash
curl "https://tradecatalog.app/api/v1/prices?customer=OAK01&sku=HX-8510&qty=10" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"
```

```json
{
  "data": {
    "customer": {
      "id": "7d2e4f0a-1b3c-4d5e-8f90-a1b2c3d4e5f6",
      "accountCode": "OAK01",
      "name": "Oakfield Joinery"
    },
    "sku": "HX-8510",
    "name": "Hex bolt M10 x 50 zinc",
    "qty": 10,
    "unit": 1573,
    "line": 15730,
    "list": 1850,
    "discountBp": 1500,
    "source": "brand",
    "label": "Brand discount −15%"
  },
  "currency": "GBP"
}
```

[Come vengono calcolati i prezzi](/docs/api/prices) spiega `source` e `label`.

## 5. Crea o aggiorna un prodotto

È necessaria una chiave **Lettura e scrittura**.

```bash
curl -X PUT https://tradecatalog.app/api/v1/products \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "sku": "HX-8512",
        "name": "Hex bolt M12 x 50 zinc",
        "listPrice": 2240,
        "unitLabel": "Box of 100",
        "brand": "Northgate",
        "category": "Bolts"
      }
    ]
  }'
```

```json
{
  "data": {
    "created": 1,
    "updated": 0,
    "priceChanges": 0,
    "priceChangeId": null,
    "unknownCustomers": []
  }
}
```

I nuovi prodotti vengono messi in vendita al loro prezzo di listino immediatamente. Se invii un prezzo diverso per un prodotto che ne ha già uno, il prezzo non cambia ancora. Verrà inserito in una modifica del prezzo in bozza che puoi revisionare e pubblicare nell'app. Vedere [Prodotti](/docs/api/products#create-or-update-products).

## Lo stesso in JavaScript

```js
const api = (path, init = {}) =>
  fetch(`https://tradecatalog.app/api/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}`,
      'Content-Type': 'application/json',
      ...init.headers,
    },
  }).then(async (res) => {
    const body = await res.json()
    if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`)
    return body
  })

const { data: workspace } = await api('/workspace')
const { data: price } = await api('/prices?customer=OAK01&sku=HX-8510&qty=10')
console.log(`${workspace.name}: ${price.name} is ${price.unit / 100} each`)
```

## Passaggi successivi

- [Autenticazione](/docs/api/authentication): scope, revoca delle chiavi, conservazione sicura.
- [Errori](/docs/api/errors): ogni codice di errore e come riprovare.
- [Sincronizzazione con il tuo ERP](/docs/guides/erp-sync): una sincronizzazione completa notturna e un poller degli ordini.
- [OpenAPI](/docs/api/openapi): genera un client tipizzato.