La integración de su API con OptiSigns tiene muchos usos y permite mostrar fácilmente datos que se actualizan automáticamente en sus pantallas. En esta guía, le explicaremos cómo conectar su API, sin necesidad de conocimientos de ingeniería de software.
- Qué puede hacer la integración de API
- Qué necesitará para comenzar
-
Cómo configurar una solicitud de API
- Cómo mapear datos de API en Designer
- Más sobre casos de uso de OptiSync
|
NOTA: La integración de API solo está disponible con un plan Pro Plus o superior. |
Qué puede hacer la integración de API
OptiSigns permite una fácil integración con las API de usuarios. Esto permite que los datos de la API de un usuario se muestren en cualquiera de sus letreros digitales. Esto permite actualizaciones dinámicas para:
- Tableros de menú digitales - Integre con sus sistemas POS y obtenga el DMB actualizado automáticamente, y edite el formato de su DMB usando la aplicación designer cuando sea necesario.
- Actualización automatizada de RR.HH. - Use la API de sus sistemas de RR.HH. para mostrar cumpleaños o aniversarios laborales en las pantallas automáticamente.
- Seguimiento de inventario de almacén - Use la API de su almacén para mostrar niveles de inventario con actualizaciones automáticas en toda su organización
- Cualquier otro caso de uso de visualización de información que necesite consumir datos de API y mostrarlos en las pantallas.
Esta integración de API se puede lograr en OptiSigns con poca o ninguna codificación, haciéndola accesible para aquellos sin experiencia en ingeniería de software. En esta guía, le explicaremos cómo configurarla con el ejemplo a continuación usando una API del sistema POS Clover.
Qué necesitará para comenzar
Necesitará su:
- URL del punto final de API
- Token de autorización de API
Estos son necesarios para que OptiSigns se conecte con su API deseada. Asegúrese de tenerlos en un lugar fácilmente accesible antes de intentar configurar su solicitud de API en el portal web de OptiSigns. Debería poder obtenerlos de un profesional de TI en su organización, o a través del administrador de su sistema POS.
Cómo configurar una solicitud de API
La puerta de enlace API es una herramienta poderosa que permite a los usuarios administrar centralmente las API, así como configurar y probar las API.
Ahora que tiene todo lo que necesita, comencemos a configurar una solicitud de API. Con una solicitud de API, puede:
- Usar el OptiSigns API Keystore para almacenar y usar de forma segura claves API de otros sistemas.
- Probar los puntos finales de API, con la capacidad de modificar encabezados y parámetros.
- Usar parámetros de sustitución y reglas de preprocesamiento y posprocesamiento para manejar integraciones complejas. Las reglas de preprocesamiento pueden ayudarle a manejar esas situaciones de integración de API que requieren una llamada adicional para obtener un token de autenticación antes de hacer la llamada API. El posprocesamiento le permitirá procesar los datos devueltos y adaptarlos para que se ajusten mejor a su uso.
Para comenzar, abra su portal web de OptiSigns.
Una vez allí, navegue hasta la esquina superior derecha de la pantalla y pase el cursor sobre el nombre de su cuenta.
Pase el cursor sobre Más → DataSources
Verá la siguiente pantalla.
Ahora está listo para comenzar.
Paso 1: Almacenar su token de autorización de API en el OptiSigns API Keystore
El primer paso es tomar su token de autorización de API y almacenarlo en el OptiSigns API Keystore.
Este paso es técnicamente opcional: puede ingresar su token de autorización de API en una solicitud de API individual. Sin embargo, el Keystore tiene algunas ventajas importantes:
- Permite que su token de autorización de API se envíe a múltiples solicitudes de API, sin necesidad de ingresarlo manualmente cada vez
- Proporciona seguridad superior para su token de autorización de API, haciéndolo mucho más difícil de descubrir para actores externos
Por lo tanto, recomendamos encarecidamente este paso.
Para ingresar al Keystore, encuentre el ícono de candado y haga clic en él.
Esto abrirá el API Keystore.
Haga clic en Add Key.
Hay dos campos aquí.
- Primer campo - Ingrese el nombre de la clave aquí. Recomendamos algo que le ayude a recordarla. Usará esto para configurar una solicitud de API.
- Segundo campo - El código de acceso único real para sus comunicaciones API.
Una vez que haya ingresado su token de autorización de API, presione Save. Cuando quiera ejecutar una solicitud usando esta clave API, usará el término: {{apiKeystore.<<key>>}} donde "<<key>>" se reemplaza por el nombre que insertó anteriormente. En este ejemplo, nombraremos nuestra solicitud "clover".
Ahora, estamos listos para configurar su solicitud de API.
Paso 2: Configurar y probar la solicitud de API
Antes de avanzar en OptiSigns, recomendamos probar su API usando una herramienta gratuita, como Postman. Esto proporciona varias ventajas, incluyendo:
- Verificar el formato de sus datos
- Asegurar que se proporcionen los datos correctos
- Verificar su autenticación
- Identificar problemas de integración o errores de conexión
Los parámetros de prueba, puntos finales y autenticadores se pueden usar luego en OptiSigns para configurar su solicitud de API. Así es como hacerlo.
Haga clic en el botón Add Request, se abrirá la ventana para configurar y probar la solicitud de API.
- Display Name - Esto se mostrará en la lista de la puerta de enlace API, principalmente para ayudar a los usuarios a identificar la solicitud de API.
- Name - Esto se usa como referencia a la solicitud de API, es un nombre técnico que se usará más adelante en la ruta para referirse a los datos de la solicitud de API.
- URL - Este es el punto final de la API, puede usar el método GET o POST dependiendo de la solicitud de API, por ejemplo, si está usando GraphQL, entonces todas las solicitudes usarán POST.
- Params - Le permite definir los parámetros en su solicitud de API. Puede ver parámetros en su URL de punto final de API, estos estarán precedidos por un signo "?". Estos se pueden usar en el código de solicitud de preprocesamiento y posprocesamiento para automatizar aún más su solicitud de API.
- Headers - El/los encabezado(s) de la solicitud de API. Aquí es donde querrá ingresar su token de autenticación de API.
- Pre-request - Un fragmento de código opcional que prepara el contexto antes de la solicitud de API. Por ejemplo, puede necesitar llamar a otra API para obtener un token de autenticación de corta duración antes de llamar a la API, o necesita calcular algunas variables para usar en la solicitud de API.
- Post-request - Un fragmento de código opcional que modifica los datos recibidos de la solicitud. Por ejemplo, si los datos que recibe no están exactamente como quiere que se muestren, puede escribir un poco de código para modificarlos según las necesidades de su pantalla digital.
- Enable Webhook - Genera un enlace webhook y un token asociado. Este webhook se puede usar para notificarnos de un cambio en los datos, lo que actualizará la solicitud de API y actualizará sus pantallas automáticamente.
- Enable this Request - Establecer el estado de la solicitud de API.
Para probar la solicitud, necesitaremos configurar el encabezado. Aquí es donde entra el Keystore. En el segundo cuadro, escriba Bearer {{apiKeystore.<<key>>}}, donde Bearer es el tipo de token y {{apiKeystore.<<key>>}} extrae el token almacenado en el Keystore. En este ejemplo, usaremos el nombre "clover" como se mencionó anteriormente.
Una vez hecho eso, haga clic en "Run Test". Si el código de respuesta es 200, la API ha devuelto datos exitosamente. Si hay cualquier otro código, hay un problema en la solicitud de API.
Cómo usar parámetros
Los parámetros están presentes en URL de todo tipo. Hay dos elementos en un parámetro:
- Tienen que seguir un signo '?' en la URL;
- Tienen un valor asociado con ellos
La pestaña Params le permite especificar los parámetros cuyo valor desea cambiar.
Por lo general, la pestaña Params se usa junto con las pestañas Pre-request y Post-request para crear valores que se actualizan automáticamente.
Cómo usar procesamiento pre y post-solicitud
Para usar el procesamiento pre y post-solicitud, se necesita cierto conocimiento de Javascript.
| ¿Cuál es la diferencia entre los dos? |
| Pre-request: Este es un fragmento de código que normalmente establece el contexto antes de la solicitud de API. Esto puede ser recuperar un token de autenticación de otra API, o cambiar parámetros para permitir más automatización. |
| Post-request: Un fragmento de código para aplicar a los datos recibidos de la solicitud de API. Este código se puede usar para modificar los datos recibidos para cambiar cómo se muestran en sus pantallas. |
La pestaña Pre-request es donde ingresará el código para el procesamiento de pre-solicitud.
Ejemplo: Para los sistemas que requieren un token de autenticación generado dinámicamente como Toast, esto se puede usar para llamar a otra API para recuperar el token de autenticación y establecerlo en el contexto de la API.
Para más información sobre este ejemplo, vea este artículo sobre cómo conectar su API de Toast.
La pestaña Post-request es donde ingresará el código para el procesamiento de post-solicitud.
Ejemplo: Está recibiendo datos de la API de su software de punto de venta (POS), pero ciertos datos no se muestran como le gustaría.
Los precios pueden mostrarse como números enteros (es decir, 1299) en lugar de como un precio adecuado (es decir, $12.99). Para esto, necesitaríamos un fragmento de código para convertir el número entero en un precio, y que ese código sea extensible a cualquier error de visualización similar (por ejemplo, 1899 en lugar de $18.99).
Para este ejemplo común, este fragmento de código JavaScript debería resolver su problema. También podemos configurar la capacidad de mapear la disponibilidad del producto al mismo tiempo.
Esto corregirá los datos devueltos, permitiendo que se muestren correctamente:
Esto también se puede usar para hacer que los datos aparezcan como "AGOTADO", para tachar un artículo si no está disponible, o para mostrar advertencias en un sistema de gestión de inventario. Para más información sobre este ejemplo, vea nuestro artículo sobre tableros de menú digitales.
Paso 3 (Opcional): Usar parámetros de sustitución de los atributos del dispositivo.
Muchos sistemas de punto de venta (POS) tienen licencia por tienda/ubicación. Es posible configurar una única solicitud de API con OptiSync y hacer que funcione con diferentes ubicaciones usando parámetros de sustitución. Ingresar estos permite que su pantalla comunique su información de identificación de tienda o ubicación. Esto significa que una sola solicitud de API puede comunicar datos diferentes a diferentes tiendas o ubicaciones, en lugar de necesitar hacer solicitudes de API individuales por pantalla.
Para comenzar, encuentre la pantalla que desea editar.
Haga clic en Advanced → More → Device Additional Attributes.
Aparecerán dos campos, Key y Value.
- Key - Un parámetro que se usará durante la llamada API para sustituir por el valor de su tienda. Esto reemplazará parte de su URL de punto final de API.
- Value - Representa el código único asociado con la tienda o ubicación que desea pasar a su API.
En este ejemplo, estamos manteniendo el merchantID de Clover aquí. El valor ingresado deberá obtenerse por su cuenta ya que será único.
Ahora, vuelva a la página de configuración de solicitud de API. Sustituya el merchantID en el punto final de API con el nombre de clave que definió anteriormente.
Cuando se active la llamada API en el dispositivo, tomará el valor del dispositivo y lo sustituirá en tiempo de ejecución. Para cada pantalla, querrá realizar estos mismos pasos, manteniendo el mismo nombre de clave mientras cambia el valor. Esto le permitirá enviar datos diferentes a diferentes pantallas.
Cómo mapear datos de API en Designer
Para enviar datos desde su API a una pantalla, necesitará registrarse como un DataSource. Esto permite que los elementos de datos se agreguen a la aplicación Designer de OptiSigns, donde se pueden formatear e incorporar en cualquier diseño visual que desee mostrar.
La aplicación Designer y las plantillas se pueden usar para hacer el formateo, y la fuente de datos de API manejará el mapeo de datos. Cualquier cuadro de texto o elemento de imagen se puede mapear en Designer. Cuando mapea un elemento de imagen, la URL de la imagen se reemplazará en tiempo de ejecución.
Paso 1: Crear un DataSource de API
Para comenzar, encuentre su diseño o cree uno nuevo en la pestaña Files/Assets.
Con el diseño abierto, haga clic en "DataSource" en la columna de la izquierda. Luego, haga clic en "Add DataSource" para agregar una fuente de datos de API al diseño.
Desplácese hacia abajo hasta donde dice "API Gateway" y haga clic en él.
Debería ver esta pantalla:
Seleccione la solicitud de API creada anteriormente. Verá una pantalla como la siguiente:
Aquí, puede elegir qué datos específicamente desea agregar al diseño. Si desea todas las opciones, presione "Continue". Aparecerá esta pantalla.
DataSource Name es cómo aparecerá este DataSource en Designer. Nómbrelo como le ayude a identificarlo.
Synchronization le permite elegir con qué frecuencia sincronizar con su API. Only import once tiene sentido para promociones únicas y similares. Si esto es para un activo a largo plazo, elija Periodic direct access o Periodic background sync dependiendo de si necesita usar los datos de un dispositivo específico para establecer el contexto.
Presione Done, y el DataSource se creará.
Debería aparecer en la columna izquierda bajo "Used in this design". Definitivamente aparecerá en la sección "Other DataSources" . Es posible que deba actualizar la página para que aparezca.
Ahora, pasamos al paso 2.
Paso 2: Mantener el mapeo de elementos
Una vez que se ha creado el DataSource de API, está listo para mapear los datos.
En Designer, abra su DataSource.
Haga clic en él y aparecerá una pantalla similar a esta:
Al abrir cualquiera de estos, se mostrarán los datos extraídos de su API:
Al hacer clic en cualquier parte de estos datos y arrastrarlo a la pantalla, aparecerán los datos. Tendrá la opción de usar los datos como Repetidor o por sí solos.
En este caso, queremos usarlo por sí solo. Para menús, un Repetidor tiene más sentido.
Para verificar el enlace de datos, puede hacer clic en cualquier elemento mapeado, luego hacer clic en Settings. Verá el Asset Element Name allí.
Tenemos el nombre del artículo y el precio de la API mapeados al diseño. Cuando se publique en la pantalla, el valor se reemplazará automáticamente con el valor de la API. Si se realizan actualizaciones en el sistema POS Clover, el cambio se reflejará en la pantalla automáticamente.
Repita este paso para todos los elementos que desee mapear a la fuente de datos de API, y guarde el diseño. Su diseño está listo para usar.
Más casos de uso de OptiSync
Si desea más detalles sobre casos de uso de integración de API, tenemos varios artículos adicionales. Por favor vea:
- Sistemas de punto de venta para construir tableros de menú digitales
- Mostrar horarios de eventos
- Integración de sistemas API de Toast
- Fuentes RSS personalizadas
- Mapeo dinámico de datos
¡Eso es todo!
Así es como integra datos de API y los publica en su pantalla. ¡Lo más importante, sin codificación!
Si tiene preguntas adicionales, inquietudes o cualquier comentario sobre OptiSigns, no dude en comunicarse con nuestro equipo de soporte en support@optisigns.com