Neue Bestellung für einen Kunden erstellen

Dieser Endpoint erstellt eine neue Bestellung für einen Kunden mit den angegebenen Shop-Artikeln. Die Artikel werden dem Warenkorb des Kunden hinzugefügt und anschließend wird daraus eine Bestellung generiert.

Endpoint-Details

HTTP-Methode: POST

URL: /external/v1/customers/{customer_id}/orders

Authentifizierung: API-Schlüssel (erforderlich)

Parameter

URL-Parameter

Parameter	Typ	Erforderlich	Beschreibung
customer_id	long	Ja	Die eindeutige ID des Kunden

Header

Header	Typ	Erforderlich	Beschreibung
X-Api-Key	string	Ja	API-Schlüssel für die Authentifizierung

Request Body

Beispiel: Shop-Artikel Bestellung

{
  "shopArticles": [
    {
      "id": 1001,
      "amount": 2
    },
    {
      "id": 1005,
      "amount": 1
    }
  ]
}

Beispiel: Labor-Auftrags-Bestellung

{
  "shopArticles": [
    {
      "id": 2001,
      "amount": 1
    }
  ],
  "questionnaireSurveyType": 20,
  "labOrderPaymentType": 17,
  "labSamples": [
    {
      "labSampleTypeId": 101,
      "id": "SAMPLE-12345",
      "date": "2026-06-01",
      "note": "Morgenwert"
    },
    {
      "labSampleTypeId": 102,
      "id": "SAMPLE-12346",
      "date": "2026-06-01",
      "note": null
    }
  ]
}

Request-Felder

Feld	Typ	Erforderlich	Beschreibung
shopArticles	array	Ja	Liste der zu bestellenden Artikel
questionnaireSurveyType	int?	Bei Labor-Auftrags-Artikeln	Fragebogen-Typ (siehe Tabelle unten)
labOrderPaymentType	int?	Bei Labor-Auftrags-Artikeln	Zahlungsart für Laboraufträge (siehe Tabelle unten)
labSamples	array?	Bei Labor-Auftrags-Artikeln	Liste der Laborproben

ShopArticle-Felder

Feld	Typ	Erforderlich	Beschreibung
id	long	Ja	Eindeutige ID des Artikels
amount	int	Ja	Bestellmenge (muss zwischen 1 und OrderMaximum des Artikels liegen)

LabSample-Felder (nur bei Labor-Auftrags-Artikeln)

Feld	Typ	Erforderlich	Beschreibung
labSampleTypeId	long	Ja	ID des Laborproben-Typs
id	string	Ja	Eindeutige Proben-ID (darf nicht leer sein)
date	DateTime	Ja	Entnahmedatum/-zeit (max. ±14 Tage von heute)
note	string?	Nein	Notiz zur Probe

Response

Erfolgreiche Response (200 OK)

{
  "id": 67890,
  "success": true,
  "errorMessage": null
}

Fehlerhafte Response (400 Bad Request)

{
  "id": 0,
  "success": false,
  "errorMessage": "Article with Id '9999' not found or not orderable"
}

Response-Felder

Feld	Typ	Beschreibung
id	long	Die ID der neu erstellten Bestellung (bei Erfolg)
success	boolean	Gibt an, ob die Bestellung erfolgreich erstellt wurde
errorMessage	string?	Fehlermeldung, falls ein Fehler aufgetreten ist (ansonsten null)

Status-Codes

Code	Beschreibung
200	OK - Bestellung wurde erfolgreich erstellt (prüfe success-Feld)
400	Bad Request - Anfragedaten sind ungültig oder unvollständig
401	Unauthorized - API-Schlüssel ist ungültig oder fehlt
403	Forbidden - Keine Zugriffsberechtigung auf den Kunden
500	Internal Server Error - Interner Serverfehler bei Bestellerstellung

Fragebogen-Typen (questionnaireSurveyType)

Wert	Bezeichnung	Beschreibung
20	UseExisting	Bestehenden Fragebogen verwenden
30	SendFilloutLink	Ausfülllink per E-Mail an Kunden senden

Zahlungsarten für Laboraufträge (labOrderPaymentType)

Die Zahlungsart ist eine Kombination aus Basis-Zahlvariante und Rechnungstyp:

Wert	Kombination	Beschreibung
17	SelfPayer + InvoiceToCustomer	Selbstzahler, Rechnung an Kunde
33	SelfPayer + InvoiceToTherapist	Selbstzahler, Rechnung an Therapeut
19	Insurance + SelfPayer + InvoiceToCustomer	Krankenkasse + Selbstzahler, Rechnung an Kunde
35	Insurance + SelfPayer + InvoiceToTherapist	Krankenkasse + Selbstzahler, Rechnung an Therapeut

Hinweis: Nicht alle Artikel unterstützen Krankenkassezahlung. Die Werte 19 und 35 können nur verwendet werden, wenn mindestens ein bestellter Artikel Krankenkassezahlung erlaubt. Manche Artikel erlauben die teilweise Abrechnung über die Krankenkasse, während der Restbetrag als Selbstzahler berechnet wird. In diesem Fall wird die Bestellung automatisch mit der Kombination aus Selbstzahler und Krankenkassezahlung erstellt.

Validierungsregeln

Artikel-Validierung

• Artikel muss existieren und vom Typ ShopArticle oder LabOrderArticle sein
• Artikel muss einen gültigen Preis haben (> 0)
• Bestellmenge muss gültig sein: 1 ≤ amount ≤ OrderMaximum

Laborauftrag-Validierung

• questionnaireSurveyType muss 20 (UseExisting) oder 30 (SendFilloutLink) sein
• labOrderPaymentType muss 17, 33, 19 oder 35 sein
• Jede Laborprobe muss:
  • Einen gültigen labSampleTypeId haben
  • Eine nicht-leere id haben
  • Ein Datum innerhalb von ±14 Tagen haben

Funktionsweise

Bei normalen Shop-Artikeln:

1. Authentifizierung über API-Schlüssel
2. Validierung der Zugriffsberechtigung auf den Kunden
3. Validierung der Artikel
4. Leeren des bisherigen Warenkorbs
5. Hinzufügen der Artikel zum Warenkorb
6. Berechnung von Versandkosten und Gesamtpreis
7. Hinzufügen der Versandposition (Normal Versand)
8. Erstellung der Bestellung aus dem Warenkorb
9. Rückgabe der Bestellungs-ID

Bei Labor-Auftrags-Artikeln:

Zusätzlich zu den obigen Schritten:

1. Validierung der Laborauftrag-spezifischen Felder
2. Überprüfung der Krankenkassenzahlung-Berechtigung (bei Werten 19 oder 35)
3. Hinzufügen aller Laborproben

Wichtige Hinweise

Allgemeine Regeln

• Keine Mischung erlaubt: Shop-Artikel und Labor-Auftrags-Artikel können nicht in derselben Bestellung kombiniert werden
• Warenkorb wird geleert: Der bisherige Warenkorb des Kunden wird vor Hinzufügen der neuen Artikel vollständig geleert
• Preisvalidierung: Artikel ohne gültigen Preis (Preis = 0) können nicht bestellt werden
• Mengenvalidierung: Die Bestellmenge muss zwischen 1 und dem OrderMaximum des Artikels liegen

Laborproben-Regeln

• Zeitfenster: Das Entnahmedatum muss innerhalb von ±14 Tagen vom aktuellen Datum liegen
• Proben-ID erforderlich: Jede Laborprobe muss eine eindeutige, nicht-leere ID haben
• Gültiger Typ: Die labSampleTypeId muss einem existierenden Laborproben-Typ entsprechen und kann aus dem Abruf der verfügbaren Shop-Artikel ermittelt werden

Krankenkassenzahlung

• Nur verfügbar, wenn mindestens ein Artikel im Auftrag Krankenkassenzahlung unterstützt
• Wird automatisch mit Selbstzahler kombiniert, wenn die Bestellung einen Selbstzahleranteil hat

Fehlermeldungen

Häufige Fehlermeldungen und ihre Bedeutung:

Fehlermeldung	Ursache	Lösung
Article with Id 'X' not found or not orderable	Artikel existiert nicht oder ist nicht bestellbar	Artikel-ID überprüfen, nur Shop- oder Labor-Auftrags-Artikel verwenden
Article with Id 'X' does not have a valid price	Artikel hat keinen Preis oder Preis ist 0	Sicherstellen, dass Artikel für den Verkaufsmarkt einen Preis hat
Article with Id 'X' has an invalid amount 'Y'	Bestellmenge außerhalb des erlaubten Bereichs	Menge zwischen 1 und OrderMaximum setzen
Request cannot contain both shop articles and lab order articles	Mischung von Shop- und Labor-Auftrags-Artikeln	Nur einen Artikel-Typ pro Bestellung verwenden
QuestionnaireSurveyType is required and must be either '20' or '30'	Fragebogen-Typ fehlt oder ungültig bei Labor-Bestellung	Wert 20 oder 30 für questionnaireSurveyType setzen
LabOrderPaymentType is required and must be either '19', '35' or '17', '33'	Zahlungsart fehlt oder ungültig	Einen der erlaubten Werte für labOrderPaymentType setzen
No Article does allow insurance payment	Krankenkassenzahlung gewählt, aber kein Artikel unterstützt diese	LabOrderPaymentType auf 17 oder 33 ändern (ohne Insurance)
LabSample with LabSampleTypeId 'X' has an invalid LabSampleTypeId	Laborproben-Typ existiert nicht	Gültige labSampleTypeId verwenden
LabSample with LabSampleTypeId 'X' has an invalid Date	Datum liegt außerhalb des ±14 Tage Fensters	Datum innerhalb von ±14 Tagen vom aktuellen Datum setzen
LabSample with LabSampleTypeId 'X' has an invalid Id	Proben-ID ist leer oder null	Eindeutige, nicht-leere ID für jede Probe setzen