Aller au contenu principal

API REST

La source Rest API permet de connecter la borne à tout système qui renvoie en JSON le nom et le prix d'un produit pour un code donné — par ex. une boutique en ligne, un système de caisse ou votre propre service intermédiaire.

Fonctionnement​

  1. (Facultatif) Au démarrage de l'application et après l'enregistrement des paramètres, la borne récupère un jeton à l'adresse du jeton.
  2. Après chaque scan, elle envoie une requête à l'URL des données, dans laquelle {code} est remplacé par le code scanné. Si elle dispose d'un jeton, elle ajoute l'en-tête Authorization: Bearer <token>.
  3. Elle lit le nom, le prix et, éventuellement, l'EAN dans la réponse JSON — à l'aide des chemins que vous indiquez.

http:// et https:// fonctionnent tous deux. L'application attend environ 10 secondes une réponse.

Champs​

Jeton (facultatif) — laissez Url to token vide si l'API n'exige pas d'authentification.

ChampQue saisirExemple
Url to tokenL'adresse qui renvoie le jeton.https://api.example.com/auth
GET / POSTMéthode de la requête du jeton.POST
Body requestLe corps JSON envoyé avec POST (le champ n'est visible que pour POST).{"user":"pricechecker","password":"…"}
Path to tokenL'emplacement du jeton dans la réponse JSON.token ou $.data.token

Données du produit

ChampQue saisirExemple
Url to dataL'adresse de la requête produit ; {code} est remplacé par le code scanné.https://api.example.com/price?code={code}
GET / POSTMéthode de la requête produit.GET
Body requestLe corps JSON pour POST ; vous pouvez aussi y utiliser {code}.{"ean":"{code}"}
Path to nameChemin vers le nom du produit dans la réponse.product.name
Path to priceChemin vers le prix ; la valeur doit être un nombre.product.price
Path to EAN (optional)Chemin vers le code EAN affiché sous le prix. Vide = le code scanné est affiché sous le prix.product.ean

Les chemins utilisent la syntaxe JsonPath : product.name et $.product.name sont équivalents, un élément de tableau s'écrit par ex. $.items[0].price. Les requêtes POST sont envoyées avec l'en-tête Content-Type: application/json; charset=utf-8.

Exemple​

La requête après le scan du code 5901234567890 :

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

Une réponse que la borne comprend :

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

Paramètres : Path to name product.name, Path to price product.price, Path to EAN product.ean. Renvoyez le prix sous forme de nombre avec un point décimal — la borne le met en forme selon le champ Price format.

Exigences pour l'API​

  • Pour un produit trouvé, l'API répond avec un statut 2xx et un JSON contenant le nom et le prix.
  • Toute autre réponse (par ex. 404 pour un code inconnu, 401 pour un jeton invalide, un champ manquant dans le JSON) affiche Data download error à l'écran. Avec l'API REST, l'application n'affiche pas « Product not found » — si vous voulez que les clients distinguent ces cas, renvoyez par ex. le nom « Product not available » avec un prix de 0.
  • Le code est inséré dans l'URL sans encodage. Les codes EAN et les symboles usuels ne posent aucun problème ; si vos symboles contiennent des espaces ou des caractères spéciaux, utilisez une requête POST avec le code dans le corps.
  • Le jeton n'est récupéré qu'au démarrage de l'application et après l'enregistrement des paramètres — l'application ne le renouvelle pas d'elle-même. Utilisez un jeton de longue durée ou une clé qui n'expire pas ; une fois le jeton expiré, redémarrer l'application suffit.

Le Connection test des paramètres ne vérifie que la requête du jeton. Lorsque l'URL du jeton est vide, le test réussit toujours — la vraie vérification consiste à scanner quelques produits après l'enregistrement des paramètres.

API REST — FAQ

Comment connecter la borne HDWR à mon propre système ?
Choisissez la source Rest API et saisissez l'adresse de la requête produit avec le marqueur {code} à l'endroit où le code doit être inséré, par ex. https://api.example.com/price?code={code}, ainsi que les chemins vers le nom et le prix dans la réponse JSON. Vous pouvez aussi indiquer une adresse où l'application récupère un jeton Bearer.
Pourquoi la borne affiche-t-elle Data download error au lieu de Product not found avec l'API REST ?
Avec l'API REST, toute réponse autre que 2xx, ou une réponse sans champ de nom ou de prix, est traitée comme une erreur. Si l'API renvoie 404 pour un code inconnu, l'écran affiche Data download error.
L'application renouvelle-t-elle le jeton de l'API REST ?
Non. Le jeton est récupéré au démarrage de l'application et après l'enregistrement des paramètres. Utilisez un jeton de longue durée ; une fois expiré, redémarrez l'application.
La borne prend-elle en charge le HTTP simple ?
Oui, elle prend en charge http et https. Dans le réseau local du magasin, vous pouvez utiliser http ; pour une API sur Internet, utilisez https.