Die API: aus Ihrem eigenen System bestellen

Wie erstellen und verwalten Sie einen API-Schlüssel?

Jeder API-Aufruf nutzt einen Schlüssel. Es gibt zwei Arten: Ein Live-Schlüssel (beginnt mit prk_live_) erzeugt echte Bestellungen, die abgerechnet und produziert werden. Ein Testschlüssel (beginnt mit prk_test_) arbeitet in der Sandbox: Bestellungen werden angelegt, aber nichts wird abgerechnet oder produziert.

1. 1

   Registerkarte öffnen

   Öffnen Sie in Ihrem Dashboard API-Schlüssel.

2. 2

   Schlüssel benennen

   Geben Sie unter Name des Schlüssels einen erkennbaren Namen ein, zum Beispiel den Namen Ihres Shops oder Servers. So wissen Sie später, welcher Schlüssel wo verwendet wird.

3. 3

   Test oder live wählen

   Setzen Sie das Häkchen bei Testschlüssel für einen Sandbox-Schlüssel (prk_test_). Ohne Häkchen erhalten Sie einen Live-Schlüssel (prk_live_). Wählen Sie danach unter Berechtigungen (Scopes), was der Schlüssel darf; lassen Sie alles angehakt, hat er alle Rechte.

4. 4

   Schlüssel erstellen

   Klicken Sie auf Schlüssel erstellen. Der vollständige Schlüssel erscheint einmalig mit dem Hinweis Kopieren Sie diesen Schlüssel jetzt. Sie sehen ihn nur einmal.

5. 5

   Kopieren und aufbewahren

   Klicken Sie auf Kopieren und legen Sie den Schlüssel sofort sicher ab, etwa als Umgebungsvariable auf Ihrem Server oder in einem Passwortmanager. Danach zeigt die Liste nur noch den Anfang des Schlüssels und wann er Zuletzt verwendet wurde.

Die API kennt Berechtigungen (Scopes) pro Schlüssel. Ein Schlüssel ohne Scopes hat alle Rechte. Im Dashboard wählen Sie sie beim Erstellen unter Berechtigungen (Scopes). Lassen Sie alles angehakt, erhält der Schlüssel alle Rechte, auch später hinzukommende. In der Liste sehen Sie die Berechtigungen jedes Schlüssels. Möchten Sie die Berechtigungen ändern, erstellen Sie einen neuen Schlüssel und widerrufen den alten.

Base URL, Authentifizierung und Limits

• Base URL: https://www.printen.eu/api/reseller/v1. Alle Pfade in diesem Artikel sind relativ dazu.
• Authentifizierung: Senden Sie bei jeder Anfrage den Header Authorization: Bearer prk_live_... oder Authorization: Bearer prk_test_....
• Format: Anfragen und Antworten sind JSON. Eine erfolgreiche Antwort steht immer in einem Feld data; Listen enthalten zusätzlich nextCursor für die nächste Seite.
• Beträge: immer in Eurocent. 2873 bedeutet also 28,73 €.
• Limit: höchstens 120 Anfragen pro Minute und Schlüssel. Angebote (POST /quotes) und neue Bestellungen haben zusätzlich ein eigenes Limit pro Konto, das für neue Konten niedriger ist. Jede Antwort enthält RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset (Sekunden) für das Limit, das zuerst erreicht wird. Darüber erhalten Sie Status 429 mit einem Retry-After-Header.
• Spezifikation: Die vollständige OpenAPI-Spezifikation liegt unter https://www.printen.eu/reseller-api/openapi.json. Sie können sie in Postman, Insomnia oder einen Codegenerator importieren.

Testen Sie Ihren Schlüssel mit einem einfachen Aufruf, zum Beispiel der Guthabenabfrage. Erhalten Sie JSON mit data zurück, funktioniert Ihr Schlüssel.

curl https://www.printen.eu/api/reseller/v1/wallet \
  -H "Authorization: Bearer prk_test_..."

Wie rufen Sie Katalog und Optionen ab?

Mit GET /products durchsuchen Sie den Katalog. Nutzen Sie q als Suchbegriff, category für eine Kategorie, lang für die Sprache von Namen und Optionen (nl, en, de oder fr) sowie limit (höchstens 100) und cursor zum Blättern.

curl "https://www.printen.eu/api/reseller/v1/products?q=poster&lang=nl&limit=5" \
  -H "Authorization: Bearer prk_test_..."

Mit der id aus dieser Liste rufen Sie ein einzelnes Produkt mit allen Optionen und Dateianforderungen ab.

curl "https://www.printen.eu/api/reseller/v1/products/PRODUCT_ID?lang=nl" \
  -H "Authorization: Bearer prk_test_..."

{
  "data": {
    "id": "PRODUCT_ID",
    "slug": "poster",
    "name": "Poster",
    "options": [
      {
        "key": "size",
        "label": "Formaat",
        "type": "select",
        "values": [
          { "value": "A3", "label": "A3" },
          { "value": "A2", "label": "A2" }
        ]
      }
    ],
    "quantities": [1, 5, 10],
    "fileRequirements": {
      "required": true,
      "formats": ["pdf", "png", "jpg"],
      "minDpi": 300,
      "colorProfile": "CMYK",
      "bleedMm": 3,
      "fileUrlMustBeHttps": true
    }
  }
}

Ihr erstes Angebot: was kostet eine Bestellung?

Mit POST /quotes berechnen Sie den Preis einer oder mehrerer Positionen für ein Zielland, inklusive Rabatt, Versand und Umsatzsteuer. Es wird nichts bestellt oder abgerechnet. Eine Position enthält eine resellerSku (Ihr eigenes Produkt) oder eine productId mit options, dazu eine quantity.

curl -X POST https://www.printen.eu/api/reseller/v1/quotes \
  -H "Authorization: Bearer prk_test_..." -H "Content-Type: application/json" \
  -d '{"country":"NL","lines":[{"resellerSku":"POSTER-A2","quantity":1}]}'

{
  "data": {
    "lines": [
      {
        "productId": "PRODUCT_ID",
        "productName": "Poster",
        "options": { "size": "A2" },
        "quantity": 1,
        "retailNetCents": 2000,
        "netCents": 1800,
        "resellerProductId": "RESELLER_PRODUCT_ID"
      }
    ],
    "discountPercent": 10,
    "subtotalNetCents": 1800,
    "shippingNetCents": 574,
    "vatRate": 21,
    "vatTreatment": "domestic-business",
    "vatCents": 499,
    "totalCents": 2873,
    "currency": "EUR"
  }
}

Ihre erste Bestellung aufgeben (mit Idempotency-Key)

1. 1

   Eindeutigen Schlüssel wählen

   Wählen Sie pro Bestellung einen eindeutigen Idempotency-Key, am besten Ihre eigene Bestellnummer (zum Beispiel shop-order-1001). Dieser Header ist Pflicht.

2. 2

   Positionen zusammenstellen

   Verwenden Sie pro Position eine resellerSku und eine quantity. Hat Ihr Produkt noch kein Design, senden Sie zusätzlich eine fileUrl (https).

3. 3

   Empfänger angeben

   Pflicht sind name, address1, postalCode, city und country (ISO-2, zum Beispiel DE). Optional: company, email, phone, address2 und state.

4. 4

   Eigene Referenzen ergänzen

   Mit externalOrderId und externalOrderNumber verknüpfen Sie die Bestellung mit Ihrem System; beide kommen in jedem Webhook zurück. reference ist Ihre eigene Referenz.

5. 5

   Anfrage senden

   Eine neue Bestellung liefert Status 201. Prüfen Sie state in der Antwort: SUBMITTED bedeutet bezahlt und auf dem Weg in die Produktion.

curl -X POST https://www.printen.eu/api/reseller/v1/orders \
  -H "Authorization: Bearer prk_test_..." -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-order-1001" \
  -d '{"externalOrderId":"1001","lines":[{"resellerSku":"POSTER-A2","quantity":1}],
       "recipient":{"name":"Anna de Vries","address1":"Dorpsstraat 1","postalCode":"1234 AB","city":"Utrecht","country":"NL"}}'

{
  "data": {
    "id": "ORDER_ID",
    "resellerOrderId": "RESELLER_ORDER_ID",
    "orderNumber": "RS-3F9A1C7B2E",
    "state": "SUBMITTED",
    "totalCents": 2873,
    "chargedCents": 0,
    "duplicate": false,
    "test": true
  }
}

Warum ein Idempotency-Key? Netzwerke sind unzuverlässig: Ein Timeout heißt nicht, dass Ihre Bestellung nicht angekommen ist. Mit einem Idempotency-Key können Sie eine Anfrage gefahrlos wiederholen. Senden Sie denselben Schlüssel erneut, erhalten Sie die bestehende Bestellung mit "duplicate": true und Status 200 zurück. Eine zweite Bestellung entsteht nie.

{
  "data": {
    "id": "ORDER_ID",
    "resellerOrderId": "RESELLER_ORDER_ID",
    "orderNumber": "RS-3F9A1C7B2E",
    "state": "SUBMITTED",
    "totalCents": 2873,
    "chargedCents": 0,
    "duplicate": true,
    "test": true
  }
}

• Verwenden Sie einen Schlüssel pro Bestellung und immer denselben, wenn Sie diese Bestellung erneut senden.
• Ein bestehender Schlüssel liefert immer die ursprüngliche Bestellung zurück, auch wenn der Inhalt Ihrer Anfrage abweicht. Möchten Sie wirklich eine neue Bestellung, verwenden Sie einen neuen Schlüssel.
• Ein Schlüssel hat höchstens 200 Zeichen (sichtbare ASCII-Zeichen).
• Live- und Testschlüssel haben jeweils einen eigenen Bereich. Eine Testbestellung mit shop-order-1001 blockiert also keine Live-Bestellung mit demselben Schlüssel.

Eigene Produkte über die API verwalten

Ein eigenes Produkt ist ein Katalogprodukt mit festen Optionen, Ihrer SKU, Ihrer Designdatei, einem Titel und optional Ihrem Verkaufspreis. Mit POST /reseller-products legen Sie eines an; danach bestellen Sie es mit resellerSku.

curl -X POST https://www.printen.eu/api/reseller/v1/reseller-products \
  -H "Authorization: Bearer prk_test_..." -H "Content-Type: application/json" \
  -d '{"productId":"PRODUCT_ID","sku":"POSTER-A2-MAT","title":"Poster A2 mat",
       "options":{"size":"A2"},"fileUrl":"https://example.com/designs/poster-a2.pdf",
       "retailPriceCents":4995,"active":true}'

Mit PATCH /reseller-products/{id} ändern Sie ein bestehendes Produkt. Statt der id können Sie auch die SKU verwenden. Senden Sie nur die Felder, die Sie ändern möchten, zum Beispiel eine neue Datei, einen anderen Preis oder Mockup-Bilder in mockupUrls.

curl -X PATCH https://www.printen.eu/api/reseller/v1/reseller-products/POSTER-A2-MAT \
  -H "Authorization: Bearer prk_test_..." -H "Content-Type: application/json" \
  -d '{"mockupUrls":["https://example.com/mockups/poster-a2-living-room.jpg",
                     "https://example.com/mockups/poster-a2-detail.jpg"],
       "retailPriceCents":4495}'

• productId, sku und title sind beim Anlegen Pflicht. Beträge wie retailPriceCents sind in Eurocent.
• Eine SKU muss in Ihrem Konto eindeutig sein. Existiert sie bereits, erhalten Sie 409.
• Passen die Optionen nicht zu diesem Produkt, erhalten Sie 422.
• Mit "active": false setzen Sie ein Produkt auf inaktiv. Bestellungen mit dieser SKU werden dann abgelehnt.
• Mit DELETE /reseller-products/{id} löschen Sie ein Produkt. Ist es noch mit einem verbundenen Shop verknüpft, erhalten Sie 409.

Welche Bestellstatus gibt es, und was ist zu tun?

Jede Bestellung hat einen state: den Status auf Ihrer Seite (Zahlung und Datei). Sobald die Bestellung SUBMITTED ist, folgt zusätzlich ein Produktionsstatus in status.

Der Produktionsstatus in status läuft von PAID über PROCESSING und PRINTING bis SHIPPED und DELIVERED. Bei SHIPPED finden Sie Sendungsnummer und Tracking-Link in tracking. Eine stornierte Bestellung erhält CANCELLED oder REFUNDED.

# Orders that are waiting for balance
curl "https://www.printen.eu/api/reseller/v1/orders?state=AWAITING_FUNDS" \
  -H "Authorization: Bearer prk_test_..."

# One order: by id, resellerOrderId or order number
curl https://www.printen.eu/api/reseller/v1/orders/RS-3F9A1C7B2E \
  -H "Authorization: Bearer prk_test_..."

Wie stornieren Sie eine Bestellung?

Mit POST /orders/{id}/cancel stornieren Sie eine Bestellung, solange sie noch nicht in die Produktion gegangen ist. Für {id} können Sie die Bestell-id, die resellerOrderId oder die Bestellnummer verwenden.

curl -X POST https://www.printen.eu/api/reseller/v1/orders/RS-3F9A1C7B2E/cancel \
  -H "Authorization: Bearer prk_test_..."

• Klappt es, erhalten Sie die Bestellung mit state CANCELLED zurück.
• Ist die Bestellung bereits in Produktion, erhalten Sie 409: Eine Stornierung ist dann nicht mehr möglich.
• Mit Guthaben bezahlt: Der Betrag geht zurück auf Ihr Guthaben und erscheint als Erstattung unter Buchungen.
• Mit Karte bezahlt: Der Betrag geht zurück auf diese Karte.
• Wurde noch nichts abgebucht (zum Beispiel bei AWAITING_FUNDS), wird auch nichts erstattet.

Wie testen Sie sicher in der Sandbox?

Mit einem Testschlüssel (prk_test_) bauen und testen Sie Ihre Anbindung ohne Risiko. Sie verwenden dieselbe Base URL und dieselben Aufrufe wie live.

1. 1

   Alles mit prk_test_ testen

   Prüfen Sie Angebote, Bestellungen, wiederholte Anfragen mit demselben Idempotency-Key, Stornierungen und Ihre Webhook-Verarbeitung.

2. 2

   Live-Schlüssel erstellen

   Erstellen Sie unter API-Schlüssel einen Schlüssel, ohne Testschlüssel anzuhaken.

3. 3

   Schlüssel austauschen

   Ersetzen Sie in Ihrer Konfiguration den prk_test_-Schlüssel durch den prk_live_-Schlüssel. Sonst ändert sich nichts.

4. 4

   Zahlungsart prüfen

   Sorgen Sie unter Guthaben & Zahlung für genug Guthaben oder eine hinterlegte Karte, sonst bleiben Live-Bestellungen auf AWAITING_FUNDS oder PAYMENT_FAILED stehen.

Was bedeutet eine Fehlermeldung?

Jeder Fehler hat dieselbe Form: ein error-Objekt mit einem kurzen code und einer lesbaren message. Achten Sie zuerst auf den HTTP-Status; die message sagt Ihnen meist genau, was nicht stimmt.

{
  "error": {
    "code": "...",
    "message": "..."
  }
}