Zum Hauptinhalt springen

REST API

Mit der Quelle Rest API verbinden Sie den Preisprüfer mit jedem System, das zu einem Code Name und Preis eines Produkts als JSON zurückgibt — z. B. einem Onlineshop, einem Kassensystem oder Ihrem eigenen Middleware-Dienst.

Funktionsweise​

  1. (Optional) Beim Start der App und nach dem Speichern der Einstellungen holt der Preisprüfer ein Token von der Token-URL.
  2. Nach jedem Scan sendet er eine Anfrage an die Daten-URL, in der {code} durch den gescannten Code ersetzt wird. Hat er ein Token, fügt er den Header Authorization: Bearer <token> hinzu.
  3. Er liest Name, Preis und optional die EAN aus der JSON-Antwort — anhand der von Ihnen angegebenen Pfade.

Sowohl http:// als auch https:// funktionieren. Die App wartet etwa 10 Sekunden auf eine Antwort.

Felder​

Token (optional) — lassen Sie Url to token leer, wenn die API keine Authentifizierung erfordert.

FeldWas einzutragen istBeispiel
Url to tokenDie Adresse, die das Token zurückgibt.https://api.example.com/auth
GET / POSTMethode der Token-Anfrage.POST
Body requestDer mit POST gesendete JSON-Body (das Feld ist nur bei POST sichtbar).{"user":"pricechecker","password":"…"}
Path to tokenWo das Token in der JSON-Antwort steht.token oder $.data.token

Produktdaten

FeldWas einzutragen istBeispiel
Url to dataDie Adresse der Produktanfrage; {code} wird durch den gescannten Code ersetzt.https://api.example.com/price?code={code}
GET / POSTMethode der Produktanfrage.GET
Body requestDer JSON-Body für POST; auch hier können Sie {code} verwenden.{"ean":"{code}"}
Path to namePfad zum Produktnamen in der Antwort.product.name
Path to pricePfad zum Preis; der Wert muss eine Zahl sein.product.price
Path to EAN (optional)Pfad zum EAN-Code, der unter dem Preis angezeigt wird. Leer = unter dem Preis wird der gescannte Code angezeigt.product.ean

Die Pfade verwenden die JsonPath-Syntax: product.name und $.product.name bedeuten dasselbe, ein Array-Element ist z. B. $.items[0].price. POST-Anfragen werden mit dem Header Content-Type: application/json; charset=utf-8 gesendet.

Beispiel​

Die Anfrage nach dem Scannen des Codes 5901234567890:

GET https://api.example.com/price?code=5901234567890
Authorization: Bearer eyJhbGciOi...

Eine Antwort, die der Preisprüfer versteht:

{
"product": {
"name": "Coffee beans 1 kg",
"price": 59.99,
"ean": "5901234567890"
}
}

Einstellungen: Path to name product.name, Path to price product.price, Path to EAN product.ean. Geben Sie den Preis als Zahl mit Dezimalpunkt zurück — der Preisprüfer formatiert ihn gemäß dem Feld Price format.

Anforderungen an die API​

  • Für ein gefundenes Produkt antwortet die API mit einem 2xx-Status und JSON, das Name und Preis enthält.
  • Jede andere Antwort (z. B. 404 für einen unbekannten Code, 401 für ein ungültiges Token, ein fehlendes Feld im JSON) zeigt auf dem Bildschirm Data download error an. Bei REST API zeigt die App nicht „Product not found“ — wenn Kunden diese Fälle unterscheiden können sollen, geben Sie z. B. den Namen „Product not available“ mit dem Preis 0 zurück.
  • Der Code wird ohne Kodierung in die URL eingesetzt. EAN-Codes und typische Symbole machen keine Probleme; enthalten Ihre Symbole Leerzeichen oder Sonderzeichen, verwenden Sie eine POST-Anfrage mit dem Code im Body.
  • Das Token wird nur beim Start der App und nach dem Speichern der Einstellungen geholt — die App erneuert es nicht selbst. Verwenden Sie ein langlebiges Token oder einen Schlüssel, der nicht abläuft; nach Ablauf des Tokens hilft ein Neustart der App.

Der Connection test in den Einstellungen prüft nur die Token-Anfrage. Ist die Token-URL leer, ist der Test immer erfolgreich — die eigentliche Prüfung ist, nach dem Speichern der Einstellungen einige Produkte zu scannen.

REST API — FAQ

Wie verbinde ich den HDWR-Preisprüfer mit meinem eigenen System?
Wählen Sie die Quelle Rest API und tragen Sie die Adresse der Produktanfrage mit dem Platzhalter {code} an der Stelle des Codes ein, z. B. https://api.example.com/price?code={code}, dazu die Pfade zu Name und Preis in der JSON-Antwort. Optional tragen Sie eine Adresse ein, von der die App ein Bearer-Token holt.
Warum zeigt der Preisprüfer bei REST API Data download error statt Product not found?
Bei REST API wird jede andere Antwort als 2xx oder eine Antwort ohne das Feld für Name oder Preis als Fehler behandelt. Gibt die API für einen unbekannten Code 404 zurück, zeigt der Bildschirm Data download error.
Erneuert die App das REST-API-Token?
Nein. Das Token wird beim Start der App und nach dem Speichern der Einstellungen geholt. Verwenden Sie ein langlebiges Token; nach seinem Ablauf starten Sie die App neu.
Unterstützt der Preisprüfer reines HTTP?
Ja, er unterstützt http und https. Im lokalen Netzwerk des Geschäfts können Sie http verwenden; für eine API im Internet verwenden Sie https.