API web

Aplica a: BarcoderX Basic y Ultimate

Estado: Planificado. Todavía no hay nada publicado y no hay nada que descargar. Esta página enumera la primera versión de la API tal como está prevista. Las rutas y el comportamiento pueden cambiar hasta la primera publicación. Después de eso, la versión 1 solo cambia agregando cosas.

Qué es la API web

El servidor de API que usted instala y ejecuta ofrece una API REST, de modo que un programa en cualquier lenguaje puede crear etiquetas, generar archivos e imprimir. Todo lo que guarda permanece en su propia base de datos. BarcoderX no aloja nada, y ninguna etiqueta, plantilla ni dato de impresión llega jamás a BarcoderX. La API vive bajo /api/v1 y un documento OpenAPI la describe. El editor de etiquetas usa la API y nada más. Los desarrolladores .NET cuentan además con BarcoderX.Client, un cliente tipado para cada operación.

La API pertenece al servidor que usted ejecuta. Un segundo host, el host de generación sin estado, ofrece solo las partes de generación. Vea más abajo.

Se generará una página de documentación a partir del documento OpenAPI, en inglés y en español, con un ejemplo de curl para cada operación. No usa ningún visor de documentación de terceros.

Cómo se comporta la API

• Versiones. La versión va en la ruta. Dentro de la versión 1, BarcoderX solo agrega cosas: endpoints nuevos, miembros opcionales nuevos en las solicitudes, miembros nuevos en las respuestas. Un cambio incompatible crearía /api/v2, y la versión 1 seguiría funcionando al menos 12 meses después. Cada respuesta indica las versiones que admite el servidor, y una versión que se va a retirar lleva los encabezados Deprecation y Sunset.
• Errores. Un error es un documento de detalles del problema (RFC 9457). Tiene un type que enlaza con la documentación, un code estable formado por BX y cuatro dígitos, un title y un detail en su idioma, una lista de diagnósticos que nombra el elemento y el lugar de la plantilla, y un ID de seguimiento. El idioma proviene del encabezado Accept-Language, luego del predeterminado de su servidor y luego del inglés.
• Reintentos seguros. Las solicitudes que crean algo, los trabajos de impresión, los trabajos por lotes y la asignación de secuencias aceptan un encabezado Idempotency-Key. BarcoderX guarda la respuesta durante 24 horas, de modo que repetir la solicitud devuelve la misma respuesta. La misma clave con un cuerpo distinto se rechaza con 422. Un duplicado que llega mientras el primero aún se ejecuta recibe 409.
• Edición segura. Los elementos guardados devuelven un ETag. La actualización de una plantilla debe enviar If-Match. Un cambio hecho por otra persona responde 412, y la falta del encabezado responde 428.
• Límites de frecuencia. Las solicitudes tienen un límite de frecuencia, y hay un límite de solicitudes de generación simultáneas. Cuando se excede, la respuesta es 429 con un encabezado Retry-After.
• Tamaño de una solicitud. Una solicitud síncrona puede pedir hasta 100 etiquetas, o las que quepan en el presupuesto de píxeles. Una solicitud mayor se acepta con 202 y se ejecuta como un trabajo. Un trabajo informa su avance, se puede cancelar, conserva su salida durante un tiempo limitado y puede llamar a un webhook al terminar. Los webhooks se firman con HMAC-SHA-256 sobre la hora y el cuerpo, y se reintentan con pausas cada vez más largas.
• Listas. Las listas usan un cursor y devuelven como máximo 200 elementos cada vez.
• Entrada estricta. Los cuerpos tienen un tamaño limitado y se revisan con rigor. Los miembros que BarcoderX no conoce se rechazan, salvo dentro de una plantilla.
• Comprobaciones de estado. /health/live y /health/ready no requieren inicio de sesión y no revelan ningún dato guardado.

Los códigos de diagnóstico tienen la forma BX y cuatro dígitos. El primer dígito los agrupa por área:

Cada código tendrá su propia página de documentación en inglés y en español.

La primera versión prevista

Las rutas son relativas a /api/v1. Todo lo que aparece en la tabla está previsto para la primera versión, salvo que la última columna indique otra cosa. El inicio de sesión y los permisos están en Autenticación y acceso.

Notas sobre algunas de ellas:

• POST /barcodes/encode devuelve una imagen en cualquier formato ya publicado, elegido con el encabezado Accept, o un documento JSON con los datos de los módulos y detalles, o un URI de datos en base64. Pedir un formato que no se ha publicado responde 406. Los problemas de datos responden 422 con los diagnósticos.
• POST /commands y cada conjunto de etiquetas de un trabajo de impresión aceptan opciones que solo tiene un lenguaje de impresora. Una opción que el lenguaje no ofrece se rechaza con 422.
• GET /meta/licence muestra el estado de la licencia y nunca la clave. Consulte Ediciones y licencias.
• /openapi/v1.json entrega el documento OpenAPI. No está bajo /api/v1.

El host de generación sin estado

El host de generación sin estado es un host más pequeño del mismo motor. Está previsto como una imagen de contenedor para Linux x64 y Linux arm64. No tiene base de datos ni plantillas guardadas. Ofrece /render, /commands, /barcodes, /expressions y /meta, y recibe una plantilla completa en cada solicitud.

• Lo protege una sola clave de API. El host se niega a arrancar sin ella, y su mensaje nombra el ajuste que falta.
• Usted lo configura en un archivo de configuración junto al host, o con variables de entorno o la línea de comandos.
• Las fuentes y las imágenes provienen de la solicitud, o de una carpeta que el operador registra al iniciar.

BarcoderX es un producto de P4 Software.