Descripción general

BarTender 2022 introduce una API RESTful que le permite automatizar trabajos de impresión a través de llamadas REST. Las API REST son el método moderno por el cual las aplicaciones y sistemas intercambian datos a través de redes o Internet. Las solicitudes ejecutan funciones del recurso basado en servidor que pueden cambiar su estado/forma/estatus, pero también ejecutar acciones en el servidor. Si ha utilizado la API REST de Print Portal o cualquier otra API REST, este estilo de llamadas le resultará familiar. Sin embargo, a diferencia de las API mencionadas anteriormente, el funcionamiento de estas llamadas se parece más a las acciones de Integration Builder o Process Builder.

Aplicable a

BarTender 2022 y posterior

Edición Automation o superior

Información

Requisitos de la API REST

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

La API utiliza el puerto 5159; este puerto debe estar abierto para que la API reciba comandos REST.

Seguridad

La API REST admite múltiples 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.

Si usa Insomnia o Postman, configure la autenticación en NTLM.

Si usa IWA, la cuenta que envía las solicitudes REST debe cumplir:

• El usuario que envía la solicitud debe tener permisos para iniciar sesión en el servidor
• El usuario debe tener permisos para administrar integraciones en la Consola de administración

Usar autenticación básica

La autenticación básica está deshabilitada por defecto. Para habilitarla:

1. Navegue a C:\Program Files\Seagull\BarTender 2022\net5.0 (\net6.0 para la última versión).
2. Localice appsettings.json.
3. Desplácese hasta AuthenticationSchemes y cambie Basic de False a True
4. Guarde el archivo.
5. Abra la Consola de administración.
6. En el menú lateral izquierdo, vaya a Servicios de Windows y reinicie el Servicio de integración de BarTender.

Enviar sobre HTTPS

La API REST se basa en el servidor HTTP de Windows (Http.sys). Sin embargo, puede configurarla para usar HTTPS en su lugar y así asegurar sus conexiones. 

Al igual que al configurar HTTPS para las integraciones, redirigirá las solicitudes REST a través del Print Portal. Necesitará un certificado SSL de una autoridad de certificación o un certificado autofirmado.

1. Primero asegure el Print Portal con HTTPS usando su certificado SSL.
2. Dirija todas las llamadas REST a https://localhost/Bartender/api/actions. Redirija localhost al nombre del servidor o dirección 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í hay una descripción general de su funcionamiento.

Se utilizan identificadores (ID) para trabajar con acciones en ejecución. Cuando envía un script mediante POST, la respuesta incluye el ID si el script fue aceptado. El ID solo es válido mientras el script permanezca activo en el servidor (60 minutos por defecto, modificable en el mensaje POST).

Las variables obtenidas mediante GET funcionan como las variables en una integración. Puede recuperar variables de integración y globales, así como variables locales creadas mediante POST. Los valores se basan en el ID del script enviado.

Scripts POST

Al usar un comando POST, puedes indicar a BarTender que ejecute varias acciones y dejar estas acciones en ejecución después de enviarlas. De forma predeterminada, una acción permanecerá activa durante 60 minutos, pero este tiempo se puede cambiar.

POST permite diversas acciones para indicar a BarTender lo que deseas que haga. Si has utilizado Integration Builder o Process Builder, estas categorías te resultarán relativamente 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 un 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 archivos: 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 la sección de base de datos a continuación)

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

Si has trabajado antes con APIs REST, estás creando una nueva interfaz API o simplemente estás más familiarizado con 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 de vuelta. 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, también se incluirá el ID del script 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 Referencia de la API más abajo.

Acciones de base de datos

Al trabajar con acciones de base de datos, necesitarás especificar la conexión de 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, se hace en una de las propiedades de la acción.

Para configurar la conexión, necesitarás un archivo de conexión para indicar a la API lo que deseas. Este archivo de conexión 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 realizado la conexión, si el cuadro de diálogo de 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 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 utilice una conexión de base de datos. Las conexiones solo funcionan para esa acción específica, por lo que debes configurar una para cada acción que uses.

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 estás utilizando BTXML para enviar tus scripts, puedes encontrar una referencia completa de BTXML en el archivo de ayuda de BarTender:

Aquí puedes encontrar una introducción a BTXML y una referencia completa con una lista completa de etiquetas.

Referencia YAML y JSON

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

Cuando abras 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. Hacer clic en la acción te lleva a una página que enumera todas las propiedades disponibles para esa acción, así como un ejemplo de cómo podría verse en la práctica.

La página principal de la referencia YAML también indica cómo combinar acciones en grupos y crear matrices 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, además de 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, serás recibido por la API.

Cada uno de los comandos de la API puede encontrarse desplazándose hacia abajo en la página o utilizando el menú del lado izquierdo para llegar al comando deseado. Cuando navegues a cada comando, la barra de la derecha se desplazará contigo e incluye secciones interactivas que puedes usar para ver ejemplos de llamadas y respuestas de la API.

Para POST, se te presentan ejemplos de BTXML. El tipo de contenido puede cambiarse 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 JSON seleccionado:

Debajo del ejemplo y la descripción de cómo funciona, hay una lista de posibles respuestas enviadas por la API. La API utiliza códigos de respuesta HTTP comunes, aunque cada uno está adaptado para significar algo específico para la API, como que el script tiene un formato incorrecto o que el cliente no está 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 códigos verdes se pueden expandir para ver qué contiene una respuesta exitosa. Aquí tienes un ejemplo de respuestas de POST:

Swagger

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

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

Cada comando es clicable y se expande para mostrar una breve descripción, así como una herramienta de prueba. Cuando hagas clic en el botón Try it Out en el lado derecho, podrás editar los valores que deseas enviar al servidor. Para Swagger, puedes usar un archivo de texto que contenga un script personalizado o basarte en los ejemplos en el cuerpo de la solicitud en la parte inferior.

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

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

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

Puedes usar Swagger como una herramienta para probar tus scripts y asegurarte de que funcionan correctamente antes de ponerlos en producción. Es una buena herramienta para la resolución de problemas y para verificar los patrones de respuesta en tiempo real utilizando una representación visual del sistema.