Hoppa till huvudinnehåll

REST API

Källan Rest API låter dig ansluta priskontrollanten till vilket system som helst som returnerar en produkts namn och pris i JSON för en given kod — t.ex. en webbutik, ett kassasystem eller din egen mellanlagertjänst.

Så fungerar det​

  1. (Valfritt) När appen startar och efter att inställningarna sparats hämtar priskontrollanten en token från token-URL:en.
  2. Efter varje skanning skickar den en förfrågan till data-URL:en, där {code} ersätts med den skannade koden. Om den har en token lägger den till rubriken Authorization: Bearer <token>.
  3. Den läser namn, pris och eventuellt EAN från JSON-svaret — med hjälp av de sökvägar du anger.

Både http:// och https:// fungerar. Appen väntar cirka 10 sekunder på ett svar.

Fält​

Token (valfritt) — lämna Url to token tomt om API:et inte kräver autentisering.

FältVad du angerExempel
Url to tokenAdressen som returnerar token.https://api.example.com/auth
GET / POSTMetod för tokenförfrågan.POST
Body requestJSON-innehållet som skickas med POST (fältet syns bara för POST).{"user":"pricechecker","password":"…"}
Path to tokenVar token finns i JSON-svaret.token eller $.data.token

Produktdata

FältVad du angerExempel
Url to dataAdressen för produktförfrågan; {code} ersätts med den skannade koden.https://api.example.com/price?code={code}
GET / POSTMetod för produktförfrågan.GET
Body requestJSON-innehållet för POST; du kan använda {code} även här.{"ean":"{code}"}
Path to nameSökväg till produktnamnet i svaret.product.name
Path to priceSökväg till priset; värdet måste vara ett tal.product.price
Path to EAN (optional)Sökväg till EAN-koden som visas under priset. Tomt = den skannade koden visas under priset.product.ean

Sökvägarna använder JsonPath-syntax: product.name och $.product.name betyder samma sak, ett arrayelement skrivs t.ex. $.items[0].price. POST-förfrågningar skickas med rubriken Content-Type: application/json; charset=utf-8.

Exempel​

Förfrågan efter skanning av koden 5901234567890:

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

Ett svar som priskontrollanten förstår:

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

Inställningar: Path to name product.name, Path to price product.price, Path to EAN product.ean. Returnera priset som ett tal med decimalpunkt — priskontrollanten formaterar det enligt fältet Price format.

Krav på API:et​

  • För en hittad produkt svarar API:et med statusen 2xx och JSON som innehåller namn och pris.
  • Alla andra svar (t.ex. 404 för en okänd kod, 401 för en ogiltig token, ett saknat fält i JSON) visar Data download error på skärmen. Med REST API visar appen inte ”Product not found” — om du vill att kunderna ska kunna skilja fallen åt kan du returnera t.ex. namnet ”Product not available” med priset 0.
  • Koden sätts in i URL:en utan kodning. EAN-koder och typiska symboler ger inga problem; om dina symboler innehåller mellanslag eller specialtecken använder du en POST-förfrågan med koden i innehållet.
  • Token hämtas bara när appen startar och efter att inställningarna sparats — appen förnyar den inte själv. Använd en långlivad token eller en nyckel som inte löper ut; när token har gått ut hjälper det att starta om appen.

Connection test i inställningarna kontrollerar bara tokenförfrågan. När token-URL:en är tom lyckas testet alltid — den verkliga kontrollen är att skanna några produkter efter att inställningarna sparats.

REST API — vanliga frågor

Hur ansluter jag HDWR:s priskontrollant till mitt eget system?
Välj källan Rest API och ange adressen för produktförfrågan med platshållaren {code} där koden ska stå, t.ex. https://api.example.com/price?code={code}, samt sökvägarna till namn och pris i JSON-svaret. Du kan även ange en adress som appen hämtar en Bearer-token från.
Varför visar priskontrollanten Data download error i stället för Product not found med REST API?
Med REST API behandlas varje annat svar än 2xx, eller ett svar utan fältet för namn eller pris, som ett fel. Om API:et returnerar 404 för en okänd kod visar skärmen Data download error.
Förnyar appen REST API-token?
Nej. Token hämtas när appen startar och efter att inställningarna sparats. Använd en långlivad token; när den har gått ut startar du om appen.
Stöder priskontrollanten vanlig HTTP?
Ja, den stöder både http och https. I butikens lokala nätverk kan du använda http; för ett API på internet använder du https.