# REST API

> Übersicht über das, was die TradeCatalog REST API abdeckt, wer sie verwenden kann und alle Endpunkte.

Die REST-API gibt Ihren eigenen Systemen dieselben Daten wie Ihre Mitarbeiter in TradeCatalog sehen: Produkte, Kundentarife, Kunden, Bestellungen, Preisanpassungen und das Aktivitätsprotokoll. Sie verwendet JSON über HTTPS und einen API-Schlüssel pro System.

## Basis-URL

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

Jede Anfrage benötigt einen API-Schlüssel im `Authorization`-Header. Siehe [Authentifizierung](/docs/api/authentication).

## Wer kann es verwenden

- **Besitzer und Administratoren** erstellen und widerrufen Schlüssel. Andere Mitarbeiter und Käufer können das nicht.
- Der Arbeitsbereich benötigt eine **Pro-Berechtigung** oder ein **Pilot-Konto**, um Schlüssel zu erstellen.
- **Demo-Arbeitsbereiche** können die API nicht verwenden.
- Wenn Pro endet, kehrt der Arbeitsbereich zu Free zurück: vorhandene API-Schlüssel können weiterhin lesen, aber nicht schreiben. Katalogbearbeitungen und Käuferbestellungen in der App funktionieren weiter.

Ein Schlüssel gehört zu einem Arbeitsbereich. Er wirkt mit den Berechtigungen der Person, die ihn erstellt hat, sodass ein Schlüssel eines Besitzers oder Administrators alle Kundentarife sehen kann. Wenn diese Person den Arbeitsbereich verlässt, funktioniert der Schlüssel nicht mehr.

## Endpunkte

| Methode | Pfad                                                                    | Was es tut                                                           | Bereich   |
| ------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------- | --------- |
| GET     | [`/workspace`](/docs/api/workspace)                                     | Der Arbeitsbereich, zu dem dieser Schlüssel gehört                   | lesen     |
| GET     | [`/products`](/docs/api/products#list-or-search-products)               | Liste oder Suche nach Produkten, optional mit Kundentarifen          | lesen     |
| GET     | [`/products/{id}`](/docs/api/products#get-one-product)                  | Ein Produkt mit seinem Preis                                         | lesen     |
| PUT     | [`/products`](/docs/api/products#create-or-update-products)             | Erstellen oder aktualisieren bis zu 100 Produkten anhand der SKU     | schreiben |
| GET     | [`/brands`](/docs/api/products#brands-and-categories)                   | Alle Marken                                                          | lesen     |
| GET     | [`/categories`](/docs/api/products#brands-and-categories)               | Alle Kategorien                                                      | lesen     |
| GET     | [`/prices`](/docs/api/prices)                                           | Was ein Kunde für eine SKU zahlt und warum                           | lesen     |
| GET     | [`/customers`](/docs/api/customers#list-customers)                      | Handelskunden                                                        | lesen     |
| GET     | [`/customers/{id}`](/docs/api/customers#get-one-customer)               | Die Bedingungen, Regeln, vereinbarten Tarife und Käufer eines Kunden | lesen     |
| PUT     | [`/customers`](/docs/api/customers#create-or-update-customers)          | Erstellen oder aktualisieren bis zu 100 Kunden                       | schreiben |
| GET     | [`/orders`](/docs/api/orders#list-orders)                               | Kürzlich erstellte Bestellungen, am neuesten zuerst                  | lesen     |
| GET     | [`/orders/{id}`](/docs/api/orders#get-one-order)                        | Eine Bestellung mit Zeilen und Statusverlauf                         | lesen     |
| PATCH   | [`/orders/{id}`](/docs/api/orders#move-an-order-on)                     | Eine Bestellung weitergeben                                          | schreiben |
| GET     | [`/price-changes`](/docs/api/price-changes#list-price-changes)          | Preisanpassungen, am neuesten zuerst                                 | lesen     |
| GET     | [`/price-changes/{id}`](/docs/api/price-changes#preview-a-price-change) | Vorschau einer Preisanpassung                                        | lesen     |
| GET     | [`/activity`](/docs/api/activity)                                       | Wer hat was geändert                                                 | lesen     |

Die vollständige maschinenlesbare Beschreibung finden Sie unter [`/api/v1/openapi.json`](/docs/api/openapi).

## Bevor Sie beginnen

- Lesen Sie [Konventionen](/docs/api/conventions) für Geldbeträge, Paging, Datumsangaben und wie `PUT` funktioniert.
- Lesen Sie [Fehler](/docs/api/errors) für Statuscodes und Wiederholungen.
- Halten Sie Schlüssel auf Ihrem Server. Die API erlaubt keine Browseranfragen (CORS).

## Noch nicht in der API

- Webhooks: stattdessen `GET /orders?status=new` abfragen.
- Veröffentlichen, planen oder stornieren von Preisanpassungen: das in der App tun.
- Rabattregeln und vereinbarte Preise: diese mit `GET /customers/{id}` abrufen, in der App ändern.
- Löschen von Produkten oder Kunden, direktes Hochladen von Bildern, Einladen von Käufern, Bestellungen als Käufer platzieren.