REST API
El origen Rest API permite conectar el lector de precios a cualquier sistema que devuelva en JSON el nombre y el precio de un producto para un código dado, p. ej. una tienda online, un sistema TPV o su propio servicio intermedio.
Cómo funciona
- (Opcional) Al iniciar la aplicación y tras guardar los ajustes, el lector de precios obtiene un token de la URL del token.
- Tras cada escaneo envía una petición a la URL de datos, en la que
{code}se sustituye por el código escaneado. Si dispone de un token, añade la cabeceraAuthorization: Bearer <token>. - Lee el nombre, el precio y, opcionalmente, el EAN de la respuesta JSON, utilizando las rutas que usted indique.
Funcionan tanto http:// como https://. La aplicación espera una respuesta durante unos 10 segundos.
Campos
Token (opcional) — deje Url to token vacío si la API no requiere autenticación.
| Campo | Qué introducir | Ejemplo |
|---|---|---|
| Url to token | La dirección que devuelve el token. | https://api.example.com/auth |
| GET / POST | Método de la petición del token. | POST |
| Body request | El cuerpo JSON enviado con POST (el campo solo es visible con POST). | {"user":"pricechecker","password":"…"} |
| Path to token | Dónde está el token en la respuesta JSON. | token o $.data.token |
Datos del producto
| Campo | Qué introducir | Ejemplo |
|---|---|---|
| Url to data | La dirección de la petición del producto; {code} se sustituye por el código escaneado. | https://api.example.com/price?code={code} |
| GET / POST | Método de la petición del producto. | GET |
| Body request | El cuerpo JSON para POST; aquí también puede usar {code}. | {"ean":"{code}"} |
| Path to name | Ruta al nombre del producto en la respuesta. | product.name |
| Path to price | Ruta al precio; el valor debe ser un número. | product.price |
| Path to EAN (optional) | Ruta al código EAN que se muestra bajo el precio. Vacío = bajo el precio se muestra el código escaneado. | product.ean |
Las rutas utilizan la sintaxis JsonPath: product.name y $.product.name significan lo mismo; un elemento de una matriz es, p. ej., $.items[0].price. Las peticiones POST se envían con la cabecera Content-Type: application/json; charset=utf-8.
Ejemplo
La petición tras escanear el código 5901234567890:
GET https://api.example.com/price?code=5901234567890
Authorization: Bearer eyJhbGciOi...
Una respuesta que el lector de precios entiende:
{
"product": {
"name": "Coffee beans 1 kg",
"price": 59.99,
"ean": "5901234567890"
}
}
Ajustes: Path to name product.name, Path to price product.price, Path to EAN product.ean. Devuelva el precio como un número con punto decimal: el lector de precios lo formatea según el campo Price format.
Requisitos de la API
- Para un producto encontrado, la API responde con un estado 2xx y un JSON que contiene el nombre y el precio.
- Cualquier otra respuesta (p. ej. 404 para un código desconocido, 401 para un token no válido, un campo ausente en el JSON) muestra Data download error en la pantalla. Con REST API la aplicación no muestra «Product not found»: si quiere que los clientes distingan estos casos, devuelva, p. ej., el nombre «Product not available» con precio 0.
- El código se inserta en la URL sin codificar. Los códigos EAN y los símbolos habituales no dan problemas; si sus símbolos contienen espacios o caracteres especiales, utilice una petición POST con el código en el cuerpo.
- El token se obtiene solo al iniciar la aplicación y tras guardar los ajustes: la aplicación no lo renueva por sí sola. Utilice un token de larga duración o una clave que no caduque; cuando el token caduca, ayuda reiniciar la aplicación.
La Connection test de los ajustes comprueba únicamente la petición del token. Cuando la URL del token está vacía, la prueba siempre tiene éxito: la comprobación real consiste en escanear unos cuantos productos tras guardar los ajustes.