# Snelstart

> Maak een API-sleutel aan en maak uw eerste TradeCatalog API-aanroepen in vijf minuten.

U moet de **eigenaar** zijn van een TradeCatalog-werkruimte met een Pro-entiteit of een pilotaccount. Demo-werkruimtes kunnen de API niet gebruiken.

## 1. Maak een API-sleutel

1. Open uw werkruimte en ga naar **Instellingen → API**.
2. Geef de sleutel een naam die u later herkent, zoals "Sage stock sync".
3. Kies **Alleen-lezen** om informatie op te zoeken, of **Lezen en schrijven** om ook producten, klanten en bestellingen bij te werken.
4. Kies **Sleutel maken** en kopieer deze. Deze begint met `tc_live_`.

**Kopieer het nu:** We tonen een sleutel slechts één keer, en we bewaren alleen een hash ervan. Als u deze verliest, schakelt u deze in en maakt u een nieuwe aan.

Plaats de sleutel in een omgevingsvariabele zodat deze uit uw code blijft:

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

## 2. Controleer of de sleutel werkt

```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. Zoek producten

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

Geld is altijd in **kleine eenheden** van de werkruimtevaluta, dus `1850` is £18.50. Zie [Conventies](/docs/api/conventions).

## 4. Haal de prijs van een klant op

Geef een klantaccountcode (of id) en een SKU mee:

```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"
}
```

[Hoe prijzen worden berekend](/docs/api/prices) verklaart `source` en `label`.

## 5. Maak of werk een product bij

Hier is een **Lezen en schrijven**-sleutel nodig.

```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": []
  }
}
```

Nieuwe producten worden direct met hun verkoopprijs live gezet. Als u een andere prijs stuurt voor een product dat al een prijs heeft, verandert de prijs nog niet. Het gaat naar een conceptprijswijziging die u in de app beoordeelt en publiceert. Zie [Producten](/docs/api/products#create-or-update-products).

## Hetzelfde 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`)
```

## Volgende stappen

- [Authenticatie](/docs/api/authentication): scopes, sleutels intrekken en veilig opslaan.
- [Fouten](/docs/api/errors): elke foutcode en hoe u opnieuw kunt proberen.
- [Synchronisatie met uw ERP](/docs/guides/erp-sync): een volledige nachtelijke synchronisatie en bestellingspoller.
- [OpenAPI](/docs/api/openapi): genereer een getypeerde client.