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
- (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.
- 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êteAuthorization: Bearer <token>. - 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.
| Champ | Que saisir | Exemple |
|---|---|---|
| Url to token | L'adresse qui renvoie le jeton. | https://api.example.com/auth |
| GET / POST | Méthode de la requête du jeton. | POST |
| Body request | Le corps JSON envoyé avec POST (le champ n'est visible que pour POST). | {"user":"pricechecker","password":"…"} |
| Path to token | L'emplacement du jeton dans la réponse JSON. | token ou $.data.token |
Données du produit
| Champ | Que saisir | Exemple |
|---|---|---|
| Url to data | L'adresse de la requête produit ; {code} est remplacé par le code scanné. | https://api.example.com/price?code={code} |
| GET / POST | Méthode de la requête produit. | GET |
| Body request | Le corps JSON pour POST ; vous pouvez aussi y utiliser {code}. | {"ean":"{code}"} |
| Path to name | Chemin vers le nom du produit dans la réponse. | product.name |
| Path to price | Chemin 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.