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

# Überblick über die User API

> Erstellen Sie Bestellungen, synchronisieren Sie Ihren Katalog, versenden Sie physische Waren und reagieren Sie auf Ereignisse aus Ihren eigenen Systemen.

> [!NOTE]
>
> Um für diese Bestellungen Kartenzahlungen auf Ihrer eigenen Website anzunehmen, siehe [PapelPay](https://developers.papelship.com/de/papelpay/overview.md).

Die User API (in Ihrem Dashboard Store API genannt) gibt Ihren Servern dieselbe Kontrolle, die Sie im Shop-Dashboard haben: Bestellungen, Produkte, Lagerbestand, Kunden, Support, Versand und Webhooks.

**Basis-URL:** `https://app.papelship.com/api/v1`

> [!NOTE]
>
> Ältere Integrationen, die `https://app.papelship.com/api_user/api/v1` aufrufen, funktionieren weiterhin. Verwenden Sie `/api/v1` für neuen Code.

## Authentifizieren

Erstellen Sie unter **Entwickler › API-Schlüssel** einen Schlüssel und senden Sie ihn bei jedem Request zusammen mit Ihrer Shop-ID:

```bash theme={"system"}
curl https://app.papelship.com/api/v1/me \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id"
```

`GET /me` funktioniert mit jedem gültigen Schlüssel. Der Endpunkt liefert den Shop, die Berechtigungen des Schlüssels und Ihre Limits. Nutzen Sie ihn daher, um Ihre Einrichtung zu testen.

> [!WARNING]
>
> Schlüssel handeln als Shop-Inhaber. Bewahren Sie sie auf Ihrem Server auf, niemals in Browser- oder Mobile-Code.

## Berechtigungen

Wählen Sie beim Erstellen eines Schlüssels **Vollzugriff**, **Nur lesen** oder **Benutzerdefiniert**. Bei Benutzerdefiniert legen Sie pro Bereich Lese- oder Schreibzugriff fest. Schreibzugriff schließt Lesezugriff ein.

| Bereich | Berechtigung | Umfasst |
| :- | :- | :- |
| Bestellungen | `orders` | `/invoices` |
| Produkte | `products` | `/products` und alles darunter |
| Kategorien & Gruppen | `catalog` | `/categories`, `/groups` |
| Gutscheine | `coupons` | `/coupons` |
| Kunden & Sperrliste | `customers` | `/customers`, `/blacklist` |
| Versand & Fulfillment | `fulfillment` | `/orders`, `/returns`, `/shipping` |
| Bewertungen | `reviews` | `/reviews` |
| Produktfragen | `questions` | `/questions` |
| Support-Tickets | `support` | `/tickets` |
| Abonnements | `subscriptions` | `/subscriptions` |
| Affiliates | `affiliates` | `/affiliates` |
| Webhooks | `webhooks` | `/webhooks`, `/events` |
| Analysen | `analytics` | `/analytics` (nur lesen) |
| Shop | `store` | `/store`, `/payment-methods` (nur lesen) |

`GET`-Requests benötigen Lesezugriff; `POST`, `PATCH`, `PUT` und `DELETE` benötigen Schreibzugriff. Ein Schlüssel ohne die passende Berechtigung erhält `403 INSUFFICIENT_SCOPE` mit der fehlenden Berechtigung in `required_scope`.

Sie können einen Schlüssel außerdem auf diesen Shop, eine Liste von IP-Adressen oder ein Ablaufdatum beschränken.

## Antworten

Jede Antwort ist JSON mit einem `success`-Flag.

```json Erfolg theme={"system"}
{ "success": true, "invoice": { "id": "c35ffd-19a1b2c3d4e-8c7a20", "status": "pending" } }
```

```json Fehler theme={"system"}
{
  "success": false,
  "code": "VALIDATION_FAILED",
  "error": "customer_email must be a valid email address",
  "details": { "field": "customer_email" },
  "request_id": "req_7YbK2mQ9xP1cRt4v"
}
```

Verzweigen Sie anhand von `code`, nicht anhand der Meldung. Jede Antwort hat einen `X-Request-Id`-Header; geben Sie ihn an, wenn Sie den Support kontaktieren. Alle Codes finden Sie unter [Fehler](https://developers.papelship.com/de/user-api/errors.md).

## Konventionen

* **Beträge** sind Ganzzahlen in der kleinsten Währungseinheit: `price_cents: 2999` entspricht 29,99.
* **Datumsangaben** sind ISO 8601 in UTC.
* **IDs** sind öffentliche IDs: Produkt-Hash-IDs, Bestell-IDs wie `c35ffd-19a1b2c3d4e-8c7a20`. Datensätze anderer Shops liefern `404`.
* **Erstellte** Datensätze liefern `201`.

## Paginierung

Listen akzeptieren `limit` (1 bis 100, Standard 25) und `offset` und liefern ein `pagination`-Objekt:

```bash theme={"system"}
curl "https://app.papelship.com/api/v1/invoices?status=completed&limit=50&offset=100" \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id"
```

```json theme={"system"}
{
  "success": true,
  "invoices": [ ... ],
  "pagination": { "total": 342, "limit": 50, "offset": 100, "has_more": true }
}
```

Affiliate-Listen verwenden stattdessen einen Cursor: Geben Sie `next_cursor` als `cursor` zurück.

## Sichere Wiederholungen

Senden Sie bei Erstellungsaufrufen (Bestellungen, Rückerstattungen, Sendungen, Produkte, Webhooks und weitere in der Referenz gekennzeichnete) einen `Idempotency-Key`-Header. Wenn das Netzwerk ausfällt, wiederholen Sie den Request mit demselben Schlüssel und Body: Sie erhalten das erste Ergebnis zurück statt eines Duplikats.

```bash theme={"system"}
curl -X POST https://app.papelship.com/api/v1/invoices \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id" \
  -H "Idempotency-Key: 6f1c8a52-4f0e-4b8e-9a7c-2d1b3e5f7a90" \
  -H "Content-Type: application/json" \
  -d '{ "customer_email": "buyer@example.com", "items": [{ "product_id": "a1B2c3D4e5F6" }] }'
```

* Schlüssel werden 24 Stunden lang aufbewahrt.
* Eine wiedergegebene Antwort hat den Header `Idempotent-Replayed: true`.
* Derselbe Schlüssel mit einem anderen Body liefert `422 IDEMPOTENCY_KEY_REUSED`.

## Limits

| Limit | Wert | Header |
| :- | :- | :- |
| Requests pro Schlüssel | 300 pro Minute | `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix-Zeit) |
| Monatliche Aufrufe | Abhängig von Ihrem Tarif | `X-Quota-Limit` |

Bei Überschreitung eines Limits erhalten Sie `429` mit `Retry-After`. `RATE_LIMITED` wird innerhalb einer Minute aufgehoben; `STORE_API_MONTHLY_QUOTA_EXCEEDED` wird am ersten Tag des Folgemonats (UTC) zurückgesetzt.

Jeder Request erscheint unter **Entwickler › API-Requests** mit seinem Status und seiner Dauer.

## Nächste Schritte

> [card] [Bestellungen erstellen](https://developers.papelship.com/de/user-api/orders.md)
>
> Nehmen Sie Bestellungen über Ihre eigene Website oder App entgegen und leiten Sie Kunden zum Checkout weiter.

> [card] [Webhooks](https://developers.papelship.com/de/user-api/webhooks.md)
>
> Lassen Sie sich benachrichtigen, wenn Bestellungen bezahlt, storniert oder erstattet werden.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.