Warenkorb
Übersetzung
Anmelden/Login
logo

API: purchase

>> zurück zur Liste aller Schnittstellen

Beschreibung

ACHTUNG: Wenn Sie diese Schnittstelle verwenden möchten, wenden Sie sich bitte an daten@booklooker.de

Löst den Kauf eines oder mehrerer Artikel. Es können bis zu 100 Artikelnummern in einem einzigen Aufruf übergeben werden, auch von unterschiedlichen Anbietern.

Ablauf

  • Die übergebenen Artikelnummern werden nach Anbieter gruppiert. Artikelnummern, die keinem Anbieter zugeordnet werden können (unbekannt oder fehlerhaft), werden übersprungen und in invalidArticles zurückgegeben.
  • Pro Anbieter wird eine Bestellung angelegt. Die Bestellungen sind unabhängig voneinander: Sofern eine Bestellung fehlschlägt hat dies keine Auswirkungen auf andere Bestellungen
  • Für jede Bestellung wird aus der Liste der Zahlungsarten paymentId die erste vom Anbieter angebotene und zulässige Zahlungsart gewählt. Achtung: Sofern für eine Zahlungsart ein Mindestbestellwert verlangt wird und die Bestellung diesen Wert nicht erreicht, wird kein Fehler erzeugt, sondern die nächste Zahlungsart in der Liste verwendet!
  • Verfügbare Artikel werden bestellt; nicht verfügbare oder abgewiesene Artikel werden pro Anbieter einzeln ausgewiesen (siehe articles in der Rückgabe).

Wichtige Hinweise

  • Käufer ist stets der authentifizierte Nutzer. Der Kauf bei sich selbst ist nicht möglich.
  • Es kann pro Aufruf nur eine Lieferadresse (addressId) angegeben werden; diese gilt für alle im Aufruf entstehenden Bestellungen.
  • Jeder Aufruf muss einen eindeutigen orderToken enthalten, der nur einmal verwendet werden kann. Hat ein Aufruf bereits mindestens eine Bestellung ausgelöst, wird jeder weitere Aufruf mit demselben orderToken mit ORDER_TOKEN_ALREADY_USED abgelehnt. So wird nach einem Verbindungsabbruch eine versehentliche Doppelbestellung verhindert. Die Antwort des ursprünglichen Aufrufs wird dabei nicht erneut geliefert; ob und welche Bestellungen tatsächlich zustande kamen, ist der Ablehnung nicht zu entnehmen.
  • articleId und paymentId sind Listen und werden mit eckigen Klammern hinter dem Parameternamen übergeben, ein Eintrag je Wert — auch dann, wenn nur ein Wert übergeben wird (siehe Mehrere Werte übergeben).
  • status ist NOK nur, wenn der Aufruf gar nicht verarbeitet werden konnte (fehlerhafte Parameter, Authentifizierung, Kontingent o. Ä.); returnValue ist dann eine einzelne Fehlerzeichenkette (siehe die entsprechenden Beispiele). Sobald der Aufruf verarbeitet wurde, ist status stets OK und returnValue ein Objekt mit den Listen invalidArticles und orders (s.u.) — auch dann, wenn keine gültige Artikelnummer übergeben wurde oder keine Bestellung zustande kam! Werten Sie daher stets die Detaildaten in orders und invalidArticles aus; status = OK bedeutet nicht, dass jede Bestellung erfolgreich war.

Mehrere Werte übergeben

Jeder Wert von articleId bzw. paymentId wird als eigener Parameter mit angehängtem [] übergeben, entweder im Request-Body (application/x-www-form-urlencoded) oder in der URL. Beispiel für zwei Artikel, Zahlung bevorzugt per Banküberweisung, ersatzweise per offener Rechnung: 

articleId[]=A02HuK3Z01ZZc&articleId[]=A02ItXa601ZZx&paymentId[]=1&paymentId[]=2

Die Klammern dürfen URL-kodiert sein (articleId%5B%5D=…) und auch einen Index enthalten (articleId[0]=…&articleId[1]=…), wie es z. B. PHPs http_build_query() erzeugt. Nicht unterstützt werden:

  • Wiederholung ohne Klammern (articleId=A&articleId=B): Es kommt nur der letzte Wert an und nicht als Liste, der Aufruf wird mit INVALID_PARAMETERS abgelehnt. Das gilt auch für einen einzelnen Wert ohne Klammern (articleId=A).
  • Kommagetrennte Werte in einem Parameter (articleId[]=A,B): Sie werden als ein Wert gelesen, eine solche Artikelnummer landet in invalidArticles.
  • JSON-Arrays im Request-Body.

Bei paymentId zählt die Reihenfolge, in der die Parameter im Aufruf stehen, nicht ein etwaiger Index: Der erste Eintrag hat die höchste Priorität. Bei articleId ist die Reihenfolge ohne Bedeutung.

URL https://api.booklooker.de/2.0/purchase?token=REST_API_TOKEN
REST_API_TOKEN = Der von der Authentifizierung zurückgelieferte Token.
Methode POST
Version 2.0

Parameter

Name Beschreibung Optional? Default-Wert
articleId[]

Artikelnummer eines zu kaufenden Artikels; für jeden Artikel ein eigener Eintrag (articleId[]=A02HuK3Z01ZZc&articleId[]=A02ItXa601ZZx). Höchstens 100 Einträge, auch ein einzelner Artikel wird mit [] übergeben. Mehr als 100 Einträge führen zu TOO_MANY_ARTICLES, dabei zählen auch doppelte Einträge mit.

Artikel verschiedener Anbieter sind zulässig und werden anbieterweise zu getrennten Bestellungen zusammengefasst. Doppelte Nummern werden nur einmal berücksichtigt, die Reihenfolge ist ohne Bedeutung.

Nein –
paymentId[]

Gewünschte Zahlungsarten als Prioritätsliste, je Zahlungsart ein eigener Eintrag in absteigender Priorität (paymentId[]=12&paymentId[]=1: PayPal, ersatzweise Banküberweisung). Auch eine einzelne Zahlungsart wird mit [] übergeben.

Die Liste gilt für jede im Aufruf entstehende Bestellung einzeln: Pro Bestellung wird die erste Zahlungsart der Liste verwendet, die der jeweilige Anbieter anbietet und die für diese Bestellung zulässig ist. So können Bestellungen bei verschiedenen Anbietern unterschiedliche Zahlungsarten erhalten. Wurde keine passende Zahlungsart gefunden, schlägt die betreffende Bestellung mit NO_PAYMENT_METHOD_AVAILABLE fehl. Enthält die Liste einen Wert, der nicht unten aufgeführt ist, wird der gesamte Aufruf mit INVALID_PARAMETERS abgelehnt.

Mögliche Werte:

  • 1 · Banküberweisung
  • 2 · Offene Rechnung
  • 5 · Nachnahme
  • 9 · Selbstabholung und Barzahlung
  • 11 · Offene Rechnung (Vorkasse vorbehalten)
  • 12 · PayPal
 Nein –
acceptTerms Bestätigung der Allgemeinen Geschäftsbedingungen. Der Kauf wird nur ausgeführt, wenn der Wert 1 übergeben wird. Andernfalls wird der Aufruf mit TERMS_NOT_ACCEPTED abgelehnt. Nein 0
orderToken Frei wählbare, eindeutige Kennung dieses Kaufs (z. B. eine UUID). Wird derselbe orderToken erneut übermittelt, wird der Aufruf mit ORDER_TOKEN_ALREADY_USED abgelehnt und keine zweite Bestellung ausgelöst. Erlaubt sind 1 bis 64 Zeichen, ausschließlich Buchstaben, Ziffern, Bindestrich und Unterstrich; andernfalls wird der Aufruf mit INVALID_PARAMETERS abgelehnt. Nein –
addressId ID der Lieferadresse des Käufers. Die Adresse muss dem authentifizierten Nutzer gehören. Wird 0 übergeben oder der Parameter weggelassen, wird die Rechnungsadresse des Nutzers verwendet. Eine ungültige oder fremde addressId führt zum Abbruch des gesamten Aufrufs mit INVALID_ADDRESS. Ja 0
requireCompleteOrder Steuert das Verhalten, wenn nicht alle Artikel eines Anbieters verfügbar sind. Mögliche Werte:
  • 0 · Es werden alle verfügbaren Artikel des Anbieters bestellt (Teilbestellung erlaubt).
  • 1 · Die Bestellung eines Anbieters wird nur ausgeführt, wenn alle seiner Artikel verfügbar sind; andernfalls entsteht für diesen Anbieter keine Bestellung (Bestellfehler INCOMPLETE_ORDER).
 Ja 0
paypalFallback Steuert, ob bei Zahlungsart 12 (PayPal) zusätzlich das ältere PayPal-Verfahren versucht wird, falls PayPal für einen Anbieter nicht nutzbar ist. Es wird in der Prioritätsliste paymentId unmittelbar nach 12 versucht, also vor der nächsten angegebenen Zahlungsart. Mögliche Werte:
  • 0 · Kein Ausweichen auf das ältere PayPal-Verfahren.
  • 1 · Ausweichen erlaubt (Standard).
 Ja 1
message Optionale Nachricht an den Anbieter (Anmerkung zur Bestellung). Ja –

Rückgabe

Status Rückgabewert Beschreibung
OK

Der Aufruf wurde verarbeitet. Die Rückgabe ist ein Objekt mit den Listen invalidArticles und orders. Jede übergebene Artikelnummer erscheint genau einmal: entweder in invalidArticles (kein Anbieter ermittelbar) oder in der articles-Liste genau eines Anbieters.

Element Bedeutung
invalidArticles Liste von Artikelnummern, die keinem Anbieter zugeordnet werden konnten, weil sie fehlerhaft (ungültiges Format) oder unbekannt sind. Diese Artikel sind in keiner Bestellung enthalten. Leer, wenn alle Nummern aufgelöst werden konnten.
orders

Ein Eintrag je Anbieter, zu dem mindestens eine gültige Artikelnummer übergeben wurde.

Element Bedeutung
sellerId Interne ID des Anbieters.
status OK · für diesen Anbieter wurde eine Bestellung ausgelöst
NOK · für diesen Anbieter wurde keine Bestellung ausgelöst (siehe error)
error
Wert Bedeutung
NO_ORDERABLE_ARTICLESKein Artikel dieses Anbieters war (mehr) bestellbar.
INCOMPLETE_ORDER requireCompleteOrder=1 und mindestens ein Artikel des Anbieters nicht verfügbar; es wurde keine Bestellung erstellt.
NO_PAYMENT_METHOD_AVAILABLE Keine der gewünschten Zahlungsarten wird vom Anbieter angeboten oder der Mindestbestellwert wurde nicht erreicht.
ORDER_IN_PROGRESS Für diese Kombination wird bereits eine gleichartige Bestellung verarbeitet (paralleler Aufruf / erneuter Versuch).
SELF_ORDER Der Nutzer kann nicht bei sich selbst kaufen.
SELLER_NOT_FOUND Der Anbieter existiert nicht.
SELLER_NOT_AVAILABLE Der Anbieter ist derzeit nicht verkaufsberechtigt (gesperrt, ungültige E-Mail o. Ä.).
SELLER_IN_HOLIDAY Der Anbieter befindet sich im Urlaub.
ORDER_REFUSED Ein Kauf zwischen diesen Parteien ist nicht möglich (z. B. Sperrliste).
BUYER_NOT_ACTIVATED Das Käuferkonto ist nicht (vollständig) aktiviert.
ORDER_LIMIT_REACHED Ein Bestelllimit wurde erreicht.
INVALID_ADDRESS Ungültige Lieferadresse für diese Bestellung.
COUNTRY_NOT_SUPPORTED Lieferung in das Zielland nicht möglich.
PACKSTATION_NOT_SUPPORTED Lieferung an eine Packstation nicht möglich.
BUYER_NOT_FOUND Das Käuferkonto existiert nicht.
MIN_ORDER_VALUE_NOT_REACHED Der Warenwert liegt unter dem Mindestbestellwert des Anbieters.
ORDER_NOT_READY Die Bestellung war nicht bereit zum Abschluss.
INVALID_DEBIT_ACCOUNT Die Bankverbindung für die Lastschrift ist ungültig.
CANNOT_CREATE_DEBIT_ACCOUNT Für die Lastschrift konnte keine Bankverbindung angelegt werden.
UNEXPECTED_ERROR Unerwarteter Fehler bei der Verarbeitung dieser Bestellung.
orderId Interne booklooker-ID der erstellten Bestellung.
price Warenwert der Bestellung in Euro (ohne Versand).
shippingCost Versandkosten in Euro.
additionalCosts Zusätzliche Kosten der gewählten Zahlungsart in Euro.
totalCost Gesamtbetrag in Euro (Warenwert + Versand + Zusatzkosten).
paymentId Tatsächlich verwendete Zahlungsart aus der Prioritätsliste.
paymentNotice Hinweistext zur Zahlung (z. B. Bankverbindung des Anbieters bei Vorkasse).
articles

Ergebnis je Artikel dieses Anbieters

Element Bedeutung
articleId Die Bestellnummer
status OK · der Artikel ist Teil der ausgelösten Bestellung
NOK · der Artikel ist nicht Teil der ausgelösten Bestellung (siehe error)
error
Wert Bedeutung
ARTICLE_SOLD Der Artikel wurde bereits verkauft.
ARTICLE_NOT_AVAILABLE Der Artikel ist gelöscht, gesperrt oder pausiert.
ARTICLE_IN_PROCESS Vorübergehend nicht verfügbar (in Verarbeitung / Warteschlange).
ARTICLE_SHORTAGE Der Bestand reicht nicht aus.
INVALID_ARTICLE_ID Einem Anbieter zugeordnet, aber nicht bestellbar (z. B. ungültige Quelle).
ORDER_NOT_PLACED Der Artikel wäre bestellbar gewesen, aber die Bestellung dieses Anbieters kam nicht zustande (siehe error der Bestellung)
NOK NOT_ENABLED Diese Schnittstelle muss freigeschaltet werden. Bitte wenden Sie sich an daten@booklooker.de.
NOK INVALID_PARAMETERS Es wurde kein Artikel, keine gültige Zahlungsart oder kein gültiger orderToken übergeben.
NOK TOO_MANY_ARTICLES Es wurden mehr als 100 Artikelnummern übergeben.
NOK TERMS_NOT_ACCEPTED Der Parameter acceptTerms wurde nicht mit dem Wert 1 übergeben.
NOK ORDER_TOKEN_ALREADY_USED Der übergebene orderToken wurde bereits verwendet.
NOK INVALID_ADDRESS Die übergebene addressId ist unbekannt oder gehört nicht zum Nutzer.
NOK ENCODING_ERROR Die Rückgabe enthält ungültige Zeichen.
NOK INVALID_INTERFACE Es wurde eine ungültige Schnittstelle verwendet.
NOK INVALID_REQUEST_METHOD Die Schnittstelle wurde mit einer ungültigen HTTP-Methode aufgerufen.
NOK QUOTA_EXCEEDED Die maximale Anzahl Abfragen/Minute wurde überschritten.
NOK SERVER_DOWN Aufgrund von Wartungsarbeiten ist die REST API momentan nicht verfügbar.
NOK TEMPORARILY_BLOCKED Der Zugang wurde vorübergehend gesperrt, bitte wenden Sie sich an unseren Kundensupport.
NOK TOKEN_EXPIRED Der Token ist nicht mehr gültig, eine erneute Authentifizierung ist notwendig.
NOK TOKEN_MISSING Der Token ist leer oder nicht vorhanden.
NOK TOKEN_UNKNOWN Der Token wurde nicht gefunden.