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: /api/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
    }
  ]
}

Beispiel: Labor-Auftrags-Bestellung mit Testkits

{
  "shopArticles": [
    {
      "id": 2001,
      "amount": 1
    }
  ],
  "questionnaireSurveyType": 20,
  "labOrderPaymentType": 17,
  "labSamples": [
    {
      "labSampleTypeId": 101
    },
    {
      "labSampleTypeId": 102
    }
  ],
  "testkits": [
    {
      "id": 3001
    }
  ]
}

Beispiel: Rezept-Bestellung

{
  "recipeId": 4501,
  "rangeInDays": 90
}

Request-Felder

Feld	Typ	Erforderlich	Beschreibung
shopArticles	array	Ja (außer bei Rezept)	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
testkits	array?	Nein	Liste der Testkit-Artikel (optional)
recipeId	long?	Bei Rezept-Bestellungen	ID des Rezepts, das bestellt werden soll
rangeInDays	int?	Bei Rezept-Bestellungen	Reichweite in Tagen

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 (außer bei Testkit-Nutzung)	Eindeutige Proben-ID (darf nicht leer sein)
date	DateTime	Ja (außer bei Testkit-Nutzung)	Entnahmedatum/-zeit (max. ±14 Tage von heute)
note	string?	Nein	Notiz zur Probe

Hinweis: Wenn testkits angegeben werden, entfallen die Felder id und date bei den Laborproben.

Testkit-Felder (optional bei Labor-Auftrags-Artikeln)

Feld	Typ	Erforderlich	Beschreibung
id	long	Ja	Eindeutige ID des Testkit-Artikels

Verwendungszweck:

• Testkits sind spezielle Artikel, die an Kunden versendet werden, um die Entnahme von Laborproben zu ermöglichen
• Bei Verwendung von Testkits entfallen Proben-ID (id) und Entnahmedatum (date) in den labSamples
• Testkits müssen mit den bestellten Labor-Auftrags-Artikeln verknüpft sein
• Die Testkit-ID muss einem gültigen Testkit-Artikel entsprechen

Rezept-Felder (bei Rezept-Bestellungen)

Feld	Typ	Erforderlich	Beschreibung
recipeId	long	Ja	Eindeutige ID des Rezepts, das dem Kunden gehört
rangeInDays	int	Ja	Reichweite in Tagen

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 (außer bei Testkit-Nutzung)
  • Ein Datum innerhalb von ±14 Tagen haben (außer bei Testkit-Nutzung)

Testkit-Validierung (bei Verwendung von Testkits)

• Jedes Testkit muss:
  • Eine gültige id haben, die einem Testkit-Artikel entspricht
  • Mit mindestens einem der bestellten Labor-Auftrags-Artikel verknüpft sein
• Wenn Testkits angegeben werden:
  • Entfallen Proben-ID und Entnahmedatum bei den Laborproben
  • Nur labSampleTypeId ist bei Laborproben erforderlich

Rezept-Validierung (bei Rezept-Bestellungen)

• recipeId muss einem Rezept gehören, das dem Kunden zugeordnet ist
• rangeInDays muss zwischen 30 und 180 liegen (erlaubte Werte 30, 60, 90, 120, 150, 180)

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

Bei Rezept-Bestellungen:

1. Authentifizierung über API-Schlüssel
2. Validierung der Zugriffsberechtigung auf den Kunden
3. Validierung, dass das Rezept dem Kunden gehört
4. Validierung der Reichweite (RangeInDays muss zwischen 30 und 180 liegen)
5. Konvertierung des Rezepts in ein verkaufbares Rezept (SellableRecipe) mit der angegebenen Reichweite
6. Hinzufügen des verkaufbaren Rezepts zum Warenkorb
7. Berechnung von Versandkosten und Gesamtpreis
8. Hinzufügen der Versandposition (Normal Versand)
9. Erstellung der Bestellung aus dem Warenkorb
10. Rückgabe der Bestellungs-ID

Wichtige Hinweise

Allgemeine Regeln

• Keine Mischung erlaubt: Shop-Artikel, Labor-Auftrags-Artikel und Rezepte 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 (außer bei Testkit-Nutzung)
• Proben-ID erforderlich: Jede Laborprobe muss eine eindeutige, nicht-leere ID haben (außer bei Testkit-Nutzung)
• 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 multiple types of orderable items in the same request	Mischung von Shop-, Labor-Auftrags-Artikeln und Rezept	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
Testkit with Id 'X' is not found or not orderable	Testkit-Artikel existiert nicht oder ist kein Testkit-Artikel	Gültige ID eines Testkit-Artikels verwenden
Testkit with Id 'X' is not associated with any of the ordered LabOrderArticles	Testkit ist nicht mit den bestellten Labor-Artikeln verknüpft	Testkit verwenden, das zu den bestellten Labor-Auftrags-Artikeln passt
Recipe with Id 'X' not found or does not belong to the customer	Rezept existiert nicht oder gehört nicht dem Kunden	Gültige RecipeId verwenden, die dem Kunden gehört
RangeInDays 'X' is invalid. It must be between 30 and 180 days.	Reichweite liegt außerhalb des erlaubten Bereichs	Wert zwischen 30 und 180 setzen (30, 60, 90, 120, 150, 180)