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

# Übersicht

> Authentifizieren Sie Anfragen, senden Sie idempotente Schreibvorgänge, behandeln Sie Rate Limits und lesen Sie Fehler der Admin API.

Mit der Admin API automatisieren Sie PricePirate-Workflows aus Ihren eigenen Tools.

## Basis-URL

Verwenden Sie diese Basis-URL für alle Anfragen an die Admin API:

```text theme={null}
https://app.pricepirate.com/api/v1
```

## Authentifizierung

Erstellen Sie einen API-Schlüssel unter **Einstellungen → API-Schlüssel**. Der Token hat das Format `pp_live_<prefix>.<secret>` und wird nur einmal angezeigt. Kopieren Sie ihn sofort.

Übergeben Sie den Token im `Authorization`-Header:

```text theme={null}
Authorization: Bearer pp_live_<prefix>.<secret>
```

Fehlende, ungültige oder widerrufene Token führen zu `401 UNAUTHORIZED`.

```bash theme={null}
curl https://app.pricepirate.com/api/v1/shop \
  -H "Authorization: Bearer pp_live_<prefix>.<secret>"
```

## Schreibvorgänge und Idempotenz

Schreibende Anfragen erfordern einen `Idempotency-Key`-Header. Das gilt für `POST`-, `PUT`-, `PATCH`- und `DELETE`-Anfragen.

Verwenden Sie für jeden logischen Schreibvorgang einen eindeutigen Schlüssel. Eine UUID eignet sich gut.

```bash theme={null}
curl https://app.pricepirate.com/api/v1/tracked-variants/activate \
  -X POST \
  -H "Authorization: Bearer pp_live_<prefix>.<secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0e43f632-f4c2-4d83-a125-f5b4a5dc8f51" \
  -d '{
    "variantIds": ["gid://shopify/ProductVariant/1234567890"]
  }'
```

Wird derselbe Schlüssel mit identischem Inhalt erneut gesendet, antwortet die API mit der zwischengespeicherten Antwort und diesem Header:

```text theme={null}
Idempotency-Replayed: true
```

Die API speichert Idempotenzantworten 24 Stunden lang.

Wenn Sie denselben Schlüssel mit anderem Inhalt erneut verwenden, antwortet die API mit `409 idempotency_key_reuse`. Wenn eine andere Anfrage mit demselben Schlüssel noch läuft, antwortet die API mit `409 idempotency_key_in_progress`.

## Rate Limits

Pro API-Schlüssel sind 60 Anfragen pro Minute zulässig.

Bei Überschreitung antwortet die API mit `429 TOO_MANY_REQUESTS` und einem `Retry-After`-Header. Der Header enthält die Anzahl der Sekunden, die Sie vor dem nächsten Versuch warten sollten.

## Fehler

Fehlerantworten verwenden eine einheitliche JSON-Struktur:

```json theme={null}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Request validation failed",
    "details": "Validation details, when available",
    "requestId": "req_123"
  }
}
```

Jede Fehlerantwort enthält eine `requestId`. Geben Sie diese bei Supportanfragen an.

| HTTP-Status | Fehlercode                                                         |
| ----------- | ------------------------------------------------------------------ |
| `400`       | `BAD_REQUEST`, `idempotency_key_required`                          |
| `401`       | `UNAUTHORIZED`                                                     |
| `403`       | `FORBIDDEN`                                                        |
| `404`       | `NOT_FOUND`                                                        |
| `409`       | `CONFLICT`, `idempotency_key_reuse`, `idempotency_key_in_progress` |
| `429`       | `TOO_MANY_REQUESTS`                                                |
| `500`       | `INTERNAL_SERVER_ERROR`                                            |

## Paginierung

Listen-Endpunkte verwenden die Query-Parameter `page` und `perPage`.

`page` ist einsbasiert. Verwenden Sie `page=1` für die erste Seite.

```bash theme={null}
curl "https://app.pricepirate.com/api/v1/tracked-variants?page=1&perPage=50" \
  -H "Authorization: Bearer pp_live_<prefix>.<secret>"
```

## Referenz

Nutzen Sie die Endpunkte in der Admin API Navigation für Parameter, Antwortschemas und Beispiele.