Saltar al contenido principal

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​

  1. (Opcional) Al iniciar la aplicación y tras guardar los ajustes, el lector de precios obtiene un token de la URL del token.
  2. 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 cabecera Authorization: Bearer <token>.
  3. 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.

CampoQué introducirEjemplo
Url to tokenLa dirección que devuelve el token.https://api.example.com/auth
GET / POSTMétodo de la petición del token.POST
Body requestEl cuerpo JSON enviado con POST (el campo solo es visible con POST).{"user":"pricechecker","password":"…"}
Path to tokenDónde está el token en la respuesta JSON.token o $.data.token

Datos del producto

CampoQué introducirEjemplo
Url to dataLa dirección de la petición del producto; {code} se sustituye por el código escaneado.https://api.example.com/price?code={code}
GET / POSTMétodo de la petición del producto.GET
Body requestEl cuerpo JSON para POST; aquí también puede usar {code}.{"ean":"{code}"}
Path to nameRuta al nombre del producto en la respuesta.product.name
Path to priceRuta 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.

REST API — preguntas frecuentes

¿Cómo conecto el lector de precios HDWR a mi propio sistema?
Elija el origen Rest API e introduzca la dirección de la petición del producto con el marcador {code} donde va el código, p. ej. https://api.example.com/price?code={code}, además de las rutas al nombre y al precio en la respuesta JSON. Opcionalmente, introduzca una dirección de la que la aplicación obtenga un token Bearer.
¿Por qué con REST API el lector de precios muestra Data download error en lugar de Product not found?
Con REST API, cualquier respuesta distinta de 2xx, o una respuesta sin el campo del nombre o del precio, se trata como un error. Si la API devuelve 404 para un código desconocido, la pantalla muestra Data download error.
¿La aplicación renueva el token de REST API?
No. El token se obtiene al iniciar la aplicación y tras guardar los ajustes. Utilice un token de larga duración; cuando caduque, reinicie la aplicación.
¿El lector de precios admite HTTP sin cifrar?
Sí, admite http y https. En la red local de la tienda puede usar http; para una API en Internet, utilice https.