Bestellungen API

Die Bestellungen-API ermöglicht das Abrufen, Filtern und Verwalten von Bestellungen. Alle Endpunkte erfordern Admin-Authentifizierung und die Berechtigung orders.read bzw. orders.write.

Endpunkte

Bestellungen auflisten

GET /api2/admin/orders

Gibt eine paginierte Liste aller Bestellungen zurück. Unterstützt umfangreiche Filter- und Sortieroptionen.

Query-Parameter:

Parameter	Typ	Beschreibung
`search`	string	Suche nach Bestellnummer, Kundenname oder E-Mail
`status`	string	Filter nach Status (siehe unten)
`paymentMethod`	string	Filter nach Zahlungsmethode
`dateFrom`	string	Bestellungen ab diesem Datum (ISO 8601)
`dateTo`	string	Bestellungen bis zu diesem Datum (ISO 8601)
`minAmount`	number	Mindest-Bestellwert in EUR
`maxAmount`	number	Maximal-Bestellwert in EUR
`orderSource`	string	Herkunftskanal der Bestellung
`tagId`	string[]	Filter nach Bestelltag (mehrfach verwendbar)
`page`	number	Seite (Standard: 1)
`limit`	number	Einträge pro Seite (Standard: 50, max: 200)
`sortBy`	string	Sortierfeld (Standard: `createdAt`)
`sortOrder`	string	`asc` oder `desc` (Standard: `desc`)

Bestellstatus:

Status	Bedeutung
`pending`	Ausstehend, Zahlung noch nicht bestätigt
`paid`	Bezahlt
`processing`	In Bearbeitung
`shipped`	Versandt
`delivered`	Geliefert
`cancelled`	Storniert
`refunded`	Erstattet

Beispiel-Anfrage:

GET /api2/admin/orders?status=paid&dateFrom=2025-01-01&sortBy=totalAmount&sortOrder=desc&limit=25

Antwort:

{
  "orders": [
    {
      "id": 1001,
      "orderNumber": 10042,
      "status": "paid",
      "customerName": "Max Mustermann",
      "customerEmail": "[email protected]",
      "totalAmount": 2490.00,
      "paymentMethod": "paypal",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 248,
  "page": 1,
  "limit": 25,
  "totalPages": 10
}

Bestellung abrufen

GET /api2/admin/orders/{id}

Gibt eine einzelne Bestellung mit allen Details zurück: Positionen, Lieferadresse, Zahlungsinformationen und zugehörige Rechnung.

Antwort:

{
  "id": 1001,
  "orderNumber": 10042,
  "status": "paid",
  "customerName": "Max Mustermann",
  "customerEmail": "[email protected]",
  "shippingAddress": {
    "street": "Musterstraße 1",
    "city": "Konstanz",
    "postalCode": "78462",
    "country": "DE"
  },
  "items": [
    {
      "id": 5001,
      "productId": 42,
      "productName": "Zirbenbett Königstein",
      "sku": "BEDIKB180X200",
      "quantity": 1,
      "unitPrice": 2490.00,
      "totalPrice": 2490.00
    }
  ],
  "subtotal": 2490.00,
  "shippingCost": 0.00,
  "totalAmount": 2490.00,
  "paymentMethod": "paypal",
  "paymentStatus": "completed",
  "invoice": {
    "id": 301,
    "invoiceNumber": "RE-2025-0042",
    "pdfUrl": "/api2/admin/invoices/301/pdf"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:35:00Z"
}

Bestellstatus aktualisieren

PATCH /api2/admin/orders/{id}
X-CSRF-Token: <csrf-token>
Content-Type: application/json

{
  "status": "shipped",
  "trackingNumber": "1Z999AA10123456784",
  "trackingUrl": "https://www.ups.com/track?loc=de&tracknum=1Z999AA10123456784"
}

Antwort (200):

{
  "id": 1001,
  "status": "shipped",
  "updatedAt": "2025-01-16T09:00:00Z"
}

Bestellung stornieren

POST /api2/admin/orders/{id}/cancel
X-CSRF-Token: <csrf-token>
Content-Type: application/json

{
  "reason": "Kundenwunsch"
}

Rechnung herunterladen

GET /api2/admin/invoices/{invoiceId}/pdf

Gibt die Rechnung als PDF zurück (Content-Type: application/pdf).

Bestellbestätigung erneut senden

POST /api2/admin/orders/{id}/send-email
X-CSRF-Token: <csrf-token>
Content-Type: application/json

{
  "type": "order_confirmation"
}

Bestellungen exportieren

GET /api2/admin/orders/export?status=paid&dateFrom=2025-01-01&dateTo=2025-01-31

Gibt alle gefilterten Bestellungen als CSV-Datei zurück. Gleiche Filterparameter wie die Auflisten-Route.

Letzte Bestellungen (Dashboard)

GET /api2/admin/orders/recent?limit=5

Gibt die neuesten Bestellungen für das Admin-Dashboard zurück.

Rückgaben

GET  /api2/admin/returns
POST /api2/admin/returns
GET  /api2/admin/returns/{id}
PATCH /api2/admin/returns/{id}

Verwaltet Rücksendeanfragen zu Bestellungen. Rückgaben sind mit einer Bestellung verknüpft (orderId).