Zum Hauptinhalt springen
Um für diese Bestellungen Kartenzahlungen auf Ihrer eigenen Website anzunehmen, siehe PapelPay.
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
Ä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:
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.
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. 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.
Erfolg
Fehler
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.

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:
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.
  • 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

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

Bestellungen erstellen

Nehmen Sie Bestellungen über Ihre eigene Website oder App entgegen und leiten Sie Kunden zum Checkout weiter.

Webhooks

Lassen Sie sich benachrichtigen, wenn Bestellungen bezahlt, storniert oder erstattet werden.