> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Einführung

Diese Referenz wird aus der [OpenAPI-Spezifikation](#openapi-spezifikation) von Topsort generiert und umfasst viele Operationen.

Allerdings werden nur zwei für eine typische Integration benötigt.

## Eine typische Integration

<Steps>
  <Step>
    Stellen Sie Ihren Katalog über einen Produktfeed bereit.
  </Step>

  <Step>
    (Lassen Sie Verkäufer Kampagnen erstellen).
  </Step>

  <Step>
    Führen Sie Auktionen [über die API](/en/api-reference/auctions/create-auctions) oder mit unseren Clients durch.

    Die Details hängen von Ihrem Marketplace und Ihren Anforderungen ab. Eine Auswahl an Beispielen finden Sie [hier](/en/api-reference/examples/auctions).
  </Step>

  <Step>
    Verwenden Sie eine der Analytics-Bibliotheken, um Ereignisse zu melden.
  </Step>
</Steps>

## Verfügbare APIs

Typische Integrationen verwenden diese APIs:

* **Auctions:** Führt Auktionen auf Ihrem Marketplace durch.
* **Events:** Sammelt Daten über Auktionsergebnisse.

Für erweiterte Integrationen möchten Sie möglicherweise Folgendes konsultieren:

* **Audiences:** Verwalten Sie Zielgruppen.
* **Campaigns:** Verwalten Sie Kampagnen.
* **Catalog:** Verwalten Sie Produkte, Kategorien und Verkäufer.
* **Billing:** Verwalten Sie Verkäuferguthaben.
* **Reporting:** Lesen Sie Berichte über Marketplace-, Kampagnen- oder Produktleistung.
* **Invitations:** Laden Sie Verkäufer zu Ihrem Marketplace ein.

## URLs und Weiterleitungen

Um die Auswirkungen von Auktionen auf die Leistung Ihrer Anwendung zu minimieren, gibt es keine Weiterleitung von URLs mit einem abschließenden Schrägstrich (`/`). Dies vermeidet einen zusätzlichen Roundtrip, bevor die Auktionsgewinner zurückgegeben werden.

Verwenden Sie zum Beispiel `/v2/auctions` statt `/v2/auctions/`, wenn Sie eine Auktion durchführen möchten.

Die Verwendung einer URL mit abschließendem Schrägstrich führt zu einem `404 Not Found` Fehler.

## API-Status

Sie können den Status der API [hier](https://topsort.statuspage.io/) überwachen und überprüfen.

## Rate Limits

Topsort wendet Rate Limits auf einige der Endpoints an, um sicherzustellen, dass die Servicequalität für alle Benutzer aufrechterhalten wird.
Die Rate Limits unterscheiden sich für Produktions- und Sandbox-Umgebungen und sind wie folgt:

| Umgebung   | Endpoint             | Rate Limit                  |
| ---------- | -------------------- | --------------------------- |
| Sandbox    | Catalog API          | 4 rps                       |
| Sandbox    | Andere Advanced APIs | 5 Anfragen alle 2 Sekunden  |
| Sandbox    | Auctions und Events  | Kein Rate Limit             |
| Produktion | Catalog API          | 10 rps                      |
| Produktion | Andere Advanced APIs | 45 Anfragen alle 2 Sekunden |
| Produktion | Auctions und Events  | Kein Rate Limit             |

### Rate Limit Header

Verwenden Sie diese Header, um die Rate Limits zu navigieren und zu wissen, wann Sie eine weitere Anfrage stellen können:

* `X-RateLimit-Limit` - Gesamtzahl der zulässigen Anfragen für den Zeitraum
* `X-RateLimit-Remaining` - Verbleibende Anzahl von Anfragen für den Zeitraum
* `X-RateLimit-Reset` - Wann Sie eine weitere Anfrage stellen können

### Umgang mit Rate Limits

Wenn Sie das Rate Limit überschreiten, erhalten Sie eine `429 Too Many Requests` Antwort. Um damit umzugehen, können Sie einen Retry-Mechanismus mit einer exponentiellen Backoff-Strategie implementieren. Dies hilft Ihnen, das Rate Limit nicht erneut zu erreichen.

Hier ist ein Beispiel, wie Sie dies in Typescript implementieren können:

```typescript theme={null}
/**
 * Wraps `fetch()` with a retry function that respects retry limits from the API
 *
 * @param {string|URL} url
 * @param {RequestInit} request
 * @param {number} retries = 1
 * @returns {Promise<Response>}
 */
async function fetchWithRetry(url, request, retries = 1) {
  const response = await fetch(url, request);
  if (!response.ok) {
    if (response.status === 429) {
      // Handle rate limit
      const ms = response.headers.get("X-RateLimit-Reset");
      await new Promise((resolve) => setTimeout(resolve, ms));
      return fetchWithRetry(url, request, retries + 1);
    }
    throw new Error(
      `Failed to upload: ${response.status} ${await response.text()}`,
    );
  }
}
```

## OpenAPI-Spezifikation

Die OpenAPI-Spezifikation ist als JSON-Datei [hier](/openapi.json) verfügbar.