# Quickstart

> Erstellen Sie einen API-Schlüssel und machen Sie Ihre ersten TradeCatalog API-Aufrufe in fünf Minuten.

Sie müssen der **Besitzer** eines TradeCatalog-Arbeitsbereichs mit einer Pro-Berechtigung oder einem Pilotkonto sein. Demo-Arbeitsbereiche können die API nicht verwenden.

## 1. Erstellen Sie einen API-Schlüssel

1. Öffnen Sie Ihren Arbeitsbereich und gehen Sie zu **Einstellungen → API**.
2. Geben Sie dem Schlüssel einen Namen, den Sie später erkennen können, z. B. „Sage Bestandsynchronisation“.
3. Wählen Sie **Nur Lesen**, um nachzuschauen, oder **Lesen und Schreiben**, um auch Produkte, Kunden und Bestellungen zu aktualisieren.
4. Wählen Sie **Schlüssel erstellen** und kopieren Sie ihn. Er beginnt mit `tc_live_`.

**Kopieren Sie ihn jetzt:** Wir zeigen einen Schlüssel nur einmal an, und wir speichern nur einen Hash davon. Wenn Sie ihn verlieren, widerrufen Sie ihn und erstellen Sie einen neuen.

Legen Sie den Schlüssel in eine Umgebungsvariable, damit er nicht in Ihrem Code landet:

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

## 2. Prüfen Sie, ob der Schlüssel funktioniert

```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. Produkte suchen

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

Geld ist immer in **Mikroeinheiten** der Arbeitsbereichswährung, also ist `1850` £18.50. Siehe [Konventionen](/docs/api/conventions).

## 4. Kundenpreis abrufen

Übergeben Sie den Kontocode (oder die ID) eines Kunden und eine 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"
}
```

[Wie Preise berechnet werden](/docs/api/prices) erklärt `source` und `label`.

## 5. Produkt erstellen oder aktualisieren

Dazu benötigen Sie einen **Lesen und Schreiben**-Schlüssel.

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

Neue Produkte werden sofort zu ihrem Listenpreis aktiviert. Wenn Sie einen anderen Preis für ein Produkt senden, das bereits einen Preis hat, ändert sich der Preis noch nicht. Er wird in einen Entwurf für einen Preisanpassung gespeichert, den Sie in der App überprüfen und veröffentlichen. Siehe [Produkte](/docs/api/products#create-or-update-products).

## Das gleiche 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`)
```

## Nächste Schritte

- [Authentifizierung](/docs/api/authentication): Bereiche, Widerruf von Schlüsseln und Sicherung.
- [Fehler](/docs/api/errors): Jeder Fehlercode und wie Sie neu versuchen können.
- [Synchronisation mit Ihrem ERP](/docs/guides/erp-sync): Eine vollständige Nacht-Synchronisation und Bestellabfrage.
- [OpenAPI](/docs/api/openapi): Generieren Sie einen typisierten Client.