Descripción general

BarTender 2022 introduce una API RESTful que te permite automatizar trabajos de impresión usando llamadas REST. Las APIs REST son el método moderno para que aplicaciones y sistemas intercambien datos entre sí a través de la red o internet. Las solicitudes ejecutan funciones basadas en recursos del servidor que pueden cambiar su estado/forma/estatus, pero también realizar acciones relacionadas en el lado del servidor. Si has usado la API REST de Print Portal o cualquier otra API REST, este estilo de llamadas te resultará bastante familiar. Sin embargo, a diferencia de las APIs mencionadas, el funcionamiento de estas llamadas es más similar a las Acciones de Integration o Process Builder.

Aplicable a

BarTender 2022 y versiones posteriores

Edición Automation o superior

Información

Requisitos de la API REST

• Versión: BarTender 2022 R1 y posteriores
• Edición: Automation o Enterprise
• Aplicación de envío: Personalizada, Swagger, Insomnia, Postman
  • Soporta autenticación IWA, NTLM y básica
  • Soporta CORS
  • Curl, C# y lenguajes .NET son compatibles para aplicaciones personalizadas
• BarTender instalado para recibir los comandos

La API opera usando el puerto 5159, por lo que este puerto debe estar abierto para que la API pueda recibir los comandos REST.

Seguridad

La API REST admite varios tipos de autenticación

• Autenticación básica
• Autenticación integrada de Windows (IWA)
• Desafío/respuesta de Windows (NTLM)

Por defecto, la autenticación básica está deshabilitada.

Al usar Insomnia o Postman para enviar solicitudes, configura la autenticación en NLTM.

Al usar IWA, la cuenta que envía las solicitudes REST debe tener las siguientes propiedades:

• El usuario que envía la solicitud debe tener permiso para iniciar sesión en el servidor
• El usuario debe tener permisos para administrar integraciones según lo establecido en la Consola de Administración

Uso de la autenticación básica

La autenticación básica está deshabilitada por defecto. Para habilitarla, sigue estos pasos:

1. Navega a C:\Program Files\Seagull\BarTender 2022\net5.0 (\net6.0 si usas la versión más reciente).
2. Ubica el archivo appsettings.json.
3. Desplázate hasta AuthenticationSchemes cerca del final y cambia Basic de false a true (debe estar en minúsculas).
4. Guarda el archivo.
5. Abre la Consola de Administración.
6. Ve a Servicios de Windows en el menú lateral izquierdo y reinicia el BarTender Integration Service.

Envío por HTTPS

La API REST está construida sobre el servidor HTTP de Windows (Http.sys). Sin embargo, puedes configurar la API REST para usar HTTPS y así asegurar tus conexiones. 

Al igual que al configurar HTTPS con integraciones, las solicitudes REST pasarán por Print Portal. Necesitarás un certificado SSL, ya sea de una Autoridad Certificadora o un certificado autofirmado para este proceso.

1. Primero, asegura Print Portal con HTTPS usando tu certificado SSL.
2. Dirige todas las llamadas RESTful a https://localhost/Bartender/api/actions. Reemplaza localhost por el nombre del servidor o la IP según sea necesario.

Comandos de la API REST

La API REST de BarTender utiliza solo tres comandos REST: POST, GET y PATCH. Aquí tienes una descripción general de cómo interactúa cada uno con la API.

Se utilizan IDs para trabajar con cualquier acción actualmente desplegada. Cuando envías un script con POST, el ID se incluye en la respuesta si el script fue aceptado por la API. El ID solo dura mientras el script esté activo en el servidor de la API. Por defecto, esto es 60 minutos, pero se puede cambiar en el mensaje POST.

Las variables que puedes recuperar usando un GET son como las variables en una integración. Puedes recuperar variables de integración y globales, así como cualquier variable local que crees a través de acciones POST. Los valores que recuperes serán relativos al ID del script que envíes.

Scripts POST

Al usar un comando POST, puedes indicarle a BarTender que realice varias acciones y dejar estas acciones en ejecución después de enviarlas. Por defecto, una acción permanecerá activa durante 60 minutos, pero este tiempo se puede modificar.

POST permite varias acciones para indicarle a BarTender lo que deseas que haga. Si has usado Integration Builder o Process Builder, estas categorías te resultarán familiares, ya que son el mismo tipo de comandos que usan ambas aplicaciones. Aquí tienes una lista de categorías:

• Acciones de impresión - Imprimir documento, script de comandos, script BTXML
• Acciones de entrada - Leer un archivo, escuchar el puerto serie, etc.
• Acciones de salida – Escribir mensaje en el registro, enviar solicitud a un servicio web, etc.
• Acciones de ejecución – Establecer variable, ejecutar un comando de shell, etc.
• Acciones de archivo - Crear una carpeta, copiar un archivo, eliminar un archivo, etc.
• Acciones de transformación – Buscar y reemplazar, buscar y eliminar, etc.
• Acciones de base de datos - Ejecutar SQL, transformar texto en conjunto de registros, para cada registro de base de datos, etc. (ver sección de base de datos abajo)

Al enviar un POST, estas acciones pueden escribirse en script BTXML, YAML o JSON. Si ya tienes una integración BTXML funcionando, usar BTXML puede ser la transición más rápida para ti. Aquí tienes un ejemplo de script BTXML de impresión:

Si ya has trabajado con APIs REST, estás creando una nueva interfaz de API o simplemente te resulta más cómodo usar JSON o YAML, la API también acepta estas llamadas. Son un poco más simples y fáciles de leer que BTXML. Aquí tienes algunos ejemplos en ambos formatos:

Después de enviar el POST, la API enviará una respuesta. Esta respuesta contendrá un código de estado que te indicará si el script fue aceptado o no. Debes buscar el código 201, que indica que el script ha sido aceptado y está programado para ejecutarse. Si recibes una respuesta exitosa, el ID del script también estará incluido en la respuesta.

Sin embargo, si recibes otra respuesta, la documentación de ayuda tiene una lista completa de cada código de respuesta para ayudarte a diagnosticar el problema. La ubicación de la documentación se indica en la sección de Referencia de la API más abajo.

Acciones de base de datos

Al trabajar con acciones de base de datos, deberás especificar la conexión a la base de datos. A diferencia de las integraciones, no puedes especificar esto a través del cuadro de diálogo de la acción. En su lugar, esto se hace en una de las propiedades de la acción.

Para configurar la conexión, necesitarás un archivo de conexión que le indique a la API lo que deseas. Este archivo define la conexión a la base de datos, así como cualquier configuración que hayas especificado, como SQL personalizado o alias. 

Para crear un archivo de conexión de base de datos, primero configura la conexión en BarTender Designer conectándote a una base de datos. Una vez que hayas hecho la conexión, si el cuadro de diálogo de la base de datos no está abierto, ve a Archivo > Configuración de conexión de base de datos para abrirlo. En la parte inferior del cuadro de diálogo, haz clic en el botón Exportar.

Esto guardará la información de la conexión en formato XML. Tu nombre de usuario, contraseña y otra información identificativa están ofuscados y no se guardan en texto plano.

Una vez que tengas el archivo, puedes usarlo en la propiedad ConnectionSetup para cualquier acción que use una conexión de base de datos. Las conexiones solo funcionan para esa acción específica, así que configura una para cada acción que utilices.

Referencia de la API

Hay varios lugares en la documentación de ayuda para ayudarte a comenzar. La documentación de ayuda se encuentra en BarTender Designer o en línea. Una vez que abras Designer, cierra las ventanas emergentes y ve a Ayuda > Ayuda de BarTender. Aquí tienes los lugares clave para encontrar la documentación de la API REST:

Referencia BTXML

Si usas BTXML para enviar tus scripts, puedes encontrar una referencia completa de scripts BTXML aquí en el archivo de ayuda de BarTender:

Aquí encontrarás una introducción a BTXML y una referencia completa con una lista de todas las etiquetas.

Referencia YAML y JSON

YAML y JSON usan los mismos tipos de variables y configuración, aunque el formato puede variar ligeramente entre ambos. La referencia YAML de BarTender tiene una lista extensa de todas las variables, scripts y llamadas que puedes hacer en el archivo de ayuda. Puedes encontrarla aquí.

Al abrir la referencia YAML, encontrarás una lista de todas las acciones disponibles dentro de la API, agrupadas por tipo de acción, así como una breve descripción de cada una. Al hacer clic en la acción, te lleva a una página que muestra todas las propiedades disponibles para cada acción, además de un ejemplo de cómo podría verse en la práctica.

La página principal de la referencia YAML también muestra cómo combinar acciones en grupos y crear arreglos de acciones para enviarlas como un solo script a la API.

ReDoc

ReDoc es una de las dos herramientas que puedes usar con la API. Contiene ejemplos, información breve sobre cada tipo de comando y una lista de patrones de respuesta que puedes recibir y lo que significa cada uno.

Puedes encontrar ReDoc en hostname:5159/api/actions/reference/index.html, donde hostname es el nombre del equipo que aloja BarTender. Cuando navegues a esta URL en tu navegador, la API te dará la bienvenida.

Cada uno de los comandos de la API se puede encontrar desplazándote por la página o usando el menú de la izquierda para ir al comando que desees. Al navegar a cada comando, la barra de la derecha se desplazará contigo y tiene secciones interactivas que puedes usar para ver ejemplos de llamadas y respuestas de la API.

Para POST, se presentan ejemplos de BTXML. El tipo de contenido se puede cambiar para alternar el formato entre BTXML, YAML y JSON. Algunos ejemplos tienen un segundo menú desplegable con ejemplos adicionales. Aquí tienes una captura de pantalla del comando POST con un ejemplo en JSON seleccionado

Debajo del ejemplo y la descripción de cómo funciona, hay una lista de posibles respuestas que envía la API. La API utiliza códigos de respuesta HTTP comunes, aunque cada uno está adaptado para significar algo específico en la API, como que el script tiene un formato incorrecto o que el cliente no es un usuario autenticado.

Cada tipo de comando tiene un conjunto diferente de códigos de respuesta y están codificados por colores para indicar si el comando fue exitoso o no. Los verdes se pueden expandir para ver qué contiene una respuesta exitosa. Aquí tienes un ejemplo de respuestas de un POST:

Swagger

Swagger es una referencia y herramienta de API que viene incluida con la instalación del paquete BarTender. Contiene una referencia completa de scripts y comandos REST, con el beneficio adicional de poder usarla para probar scripts.

Puedes encontrar Swagger en hostname:5159/swagger, donde "hostname" es el nombre del equipo que aloja BarTender. Cuando ingresas esta dirección en tu navegador web, se abre la página principal de la documentación.

Cada comando es clickeable y se expande para mostrar una breve descripción y una herramienta de prueba. Al hacer clic en el botón Try it Out en el lado derecho, puedes editar los valores que deseas enviar al servidor. En Swagger, puedes usar un archivo de texto con un script personalizado o partir de los ejemplos que aparecen en el cuerpo de la solicitud al final.

Una vez que hayas editado los valores y estés conforme, desplázate hacia abajo y haz clic en el gran botón azul Execute. Esto enviará el script al servidor, que responderá de vuelta.

Por ejemplo, esta es una respuesta exitosa devuelta por un comando POST:

Al igual que con ReDoc, debajo de la herramienta REST hay una lista de respuestas. Enumera todos los posibles códigos de respuesta junto con una breve descripción. Los códigos de respuesta exitosos también tendrán un ejemplo de lo que podría devolverse.

Puedes usar Swagger como una herramienta para probar tus scripts y asegurarte de que funcionen correctamente antes de ponerlos en producción. Es una buena herramienta para solucionar problemas y revisar los patrones de respuesta en tiempo real usando una representación visual del sistema.