Saltar al contenido
P4 Software P4 Software / BarcoderX Español

Agrega esta documentación a Claude

Hazle preguntas a Claude sobre esta documentación. Claude lee las páginas publicadas y te enlaza a ellas. Copia esta dirección:

https://p4-software.opendocs.page/mcp

En claude.ai o Claude Desktop: abre Configuración, luego Conectores, elige Agregar conector personalizado y pega la dirección.

En Claude Code, ejecuta:

claude mcp add --transport http docs https://p4-software.opendocs.page/mcp

El servicio de etiquetas

El servicio de etiquetas

Aplica a: BarcoderX Basic y Ultimate

Estado: Construido, aún sin publicar. La primera parte del servicio de etiquetas existe y está probada, pero todavía no se ha publicado nada y no hay nada que descargar. Es un programa pequeño que usted ejecuta por su cuenta. Dibuja una etiqueta a partir de una plantilla con el motor de etiquetas y responde con un archivo PNG, o con los comandos de impresora ZPL de la etiqueta. Las imágenes y los comandos llevan la marca de evaluación, y el servicio no es para uso en producción. El resto de la API web está planificado: consulte API web. Todo lo que está marcado como "planificado" todavía no se puede usar.

El servicio de etiquetas recibe una plantilla de etiqueta en JSON y devuelve una imagen de la etiqueta como archivo PNG, o los comandos de impresora de la etiqueta (consulte Salida ZPL), o una lista de problemas. Es la primera parte construida de la API web, y sirve para probar BarcoderX y para una página de demostración. No guarda nada: ni la plantilla ni la imagen. Dibuja solo a través del motor de etiquetas, de modo que lo que hace es lo que hace el motor. Consulte El motor de etiquetas y Salida PNG.

Cómo ejecutarlo

Usted inicia el servicio con un doble clic en su programa. No hay opciones de línea de comandos ni variables de entorno que aprender.

  • La primera vez, el programa escribe un archivo llamado settings.json junto a sí mismo, con un comentario sobre cada ajuste. Se lo dice en la ventana.
  • Para cambiar algo, edite settings.json, guárdelo e inicie el programa de nuevo. Si daña el archivo, bórrelo: el programa escribe una copia nueva con valores seguros.
  • Si un ajuste está mal, la ventana dice cuál y dónde, con palabras sencillas, y espera a que usted presione Entrar antes de cerrarse, para que pueda leerlo.
  • Sin cambios, el servicio escucha solo en este equipo, en http://127.0.0.1:5187, y atiende a cualquiera que pueda llegar a él (publicDemo es true en el archivo inicial).

El servicio habla http sencillo. Para usarlo desde otros equipos, ponga delante un servidor web que maneje https. Consulte "Si usted aloja el servicio" más abajo.

Cómo pedir una imagen

Envíe un POST a /api/v1/render/png con la plantilla como cuerpo.

curl -X POST "http://127.0.0.1:5187/api/v1/render/png?imageType=color" -H "Content-Type: application/json" --data-binary @label.json -o label.png

Aquí label.json es una plantilla, por ejemplo la plantilla más pequeña de El formato de plantilla de etiqueta. Da una imagen de 799 por 400 puntos a 203 puntos por pulgada. Si fijó una clave de API, agregue -H "Authorization: Bearer <su clave>". En Windows, escriba curl.exe.

Parte de la solicitudQué hace
Content-TypeDebe ser application/json, sin juego de caracteres o con utf-8. Cualquier otro valor se rechaza con 415.
El cuerpoLa plantilla como texto JSON. Como máximo 262,144 bytes de forma predeterminada.
dpi en la direcciónLa resolución a la que se dibuja, en puntos por pulgada. Opcional. Sin él, se usa la resolución escrita en la plantilla. Debe estar dentro de los límites del servicio (de 96 a 600 de forma predeterminada).
imageType en la direcciónEl tipo de imagen. Opcional. blackAndWhite es el predeterminado: lo que imprimiría una impresora, sin suavizado. gray y color tienen bordes suaves, para mirarlas en una pantalla.
Accept-Languageen o es. Los mensajes de una respuesta de problema vienen en ese idioma. El inglés es el predeterminado.
AuthorizationBearer y su clave. Se necesita solo cuando el servicio tiene una apiKey.

Un ajuste de la dirección que el servicio no conoce, uno repetido, o un valor que no se puede usar, se rechaza con 400. Los nombres distinguen mayúsculas y minúsculas.

Pedir comandos de impresora

Envíe un POST a /api/v1/commands?dialect=zpl con la plantilla como cuerpo. Es el mismo manejador que la ruta de la imagen, de modo que la clave, el tipo de contenido, el tamaño del cuerpo, los lugares para dibujar, los límites de frecuencia, el límite de tiempo y el plazo de escritura son los mismos, y también lo son las respuestas de problema. Los ajustes de la dirección son dialect (obligatorio: zpl es el único valor, en minúsculas) y dpi (como para la imagen). imageType no es un ajuste de esta ruta y se rechaza con 400 como cualquier otro nombre que la ruta no conoce.

curl -X POST "http://127.0.0.1:5187/api/v1/commands?dialect=zpl&dpi=203" -H "Content-Type: application/json" --data-binary @label.json -o label.zpl
  • 200. El cuerpo son los comandos ZPL de la etiqueta como texto ASCII simple, con Content-Type: text/plain; charset=utf-8. El encabezado BarcoderX-Warnings enumera los códigos de los avisos, y BX5130 (la etiqueta se envía como una sola imagen) va primero. Mientras no haya ninguna licencia registrada también enumera BX9001, y los comandos llevan la marca de evaluación. Los comandos ocupan como máximo limits.maxCommandsBytes bytes; una etiqueta que necesitara más recibe un 422 con BX6008 y BX5112 en errors. Consulte Salida ZPL para ver qué hay en los comandos.
  • Como documento JSON. Envíe Accept: application/json y la respuesta es un documento JSON en lugar de texto simple: dialect, commands (el mismo texto), diagnostics (los avisos del motor en el idioma de la solicitud, cada uno con code, severity, title y message), warningCodes (los mismos códigos que el encabezado) y marked. Una solicitud sin encabezado Accept, con */*, con text/plain o con application/json con peso 0 recibe el texto simple, como antes. La respuesta dice Vary: Accept. La forma JSON es un poco mayor que el texto simple (se escapan los fines de línea y se añaden los avisos), y se arma un momento en memoria fuera del presupuesto de las respuestas (vea "Cuánta memoria dar al servicio" en Despliegue del servicio de etiquetas); si es mayor que toda la reserva de respuestas, la respuesta es 413 con BX6019 y sin Retry-After, y el texto simple se sigue enviando. Los comandos como bytes para una descarga son la respuesta de texto simple.
  • No probado en una impresora. Ninguna codificación de los comandos se ha probado todavía en una impresora física.

La respuesta

  • 200. El cuerpo es el archivo PNG, con Content-Type: image/png. La resolución queda escrita en el archivo. Los encabezados BarcoderX-Image-Width y BarcoderX-Image-Height dan el tamaño de la imagen en puntos (un punto es un píxel), para que una página pueda dibujarla con un zoom entero antes de decodificar el archivo. El encabezado BarcoderX-Marked (en una imagen y en los comandos de impresora) dice true cuando el motor marcó la etiqueta con la marca de evaluación y false cuando no. Cuando el motor tuvo advertencias o avisos sobre la etiqueta, el encabezado BarcoderX-Warnings enumera sus códigos, separados por comas, por ejemplo BX3902,BX3906. Contiene solo códigos, nunca texto de la plantilla. Consulte Códigos de diagnóstico.
  • Cualquier otro estado. El cuerpo es un documento de problema (application/problem+json, RFC 9457) en el idioma de la solicitud: type, title, status, detail, code, traceId y, cuando la plantilla tenía problemas, una lista errors. Cada entrada de la lista tiene un code, una severity, un title, un message, el elementId y el pointer al lugar de la plantilla, y los args.
  • Toda respuesta lleva Api-Supported-Versions: v1, Cache-Control: no-store y X-Content-Type-Options: nosniff. Cuando un proxy que usted indica en network.trustedProxies dice que quien visita usó https, toda respuesta lleva además Strict-Transport-Security: max-age=15552000 (seis meses, sin includeSubDomains y sin preload); nunca se envía por http sin cifrar (vea network.sendStrictTransportSecurity). Después de una respuesta de problema, la conexión se cierra.
EstadoCódigoQué significa
400BX6002, BX6003, BX6013Un ajuste de la dirección no se conoce o no es válido, o el cuerpo no es texto JSON.
401BX6010Falta la clave o es incorrecta. La respuesta lleva WWW-Authenticate: Bearer realm="BarcoderX".
403BX6024Solo cuando network.edge.mode es azureFrontDoor: la solicitud no llegó por la puerta de entrada del servicio (falta el ID de Front Door o es incorrecto, falta el nombre de host o es incorrecto, o no viene de su servidor web). La respuesta no dice nada de la puerta de entrada. Se responde antes de leer el cuerpo y no gasta la cuota de ningún cliente.
404BX6011No hay nada en esa dirección.
405BX6012No se acepta el método. La respuesta lleva Allow.
408BX6017La plantilla completa no llegó dentro de limits.bodyReadMilliseconds, o llegó más despacio de lo que acepta el servidor (consulte ese ajuste). La respuesta se envía con Connection: close.
413BX6000, BX6019La plantilla supera el límite (BX6000), o la respuesta es mayor que lo máximo que el servicio retiene para una respuesta (BX6019, solo para comandos de impresora en JSON): no lleva Retry-After, porque volver a pedirla da el mismo rechazo. Pida texto simple, o haga la etiqueta más pequeña.
415BX6001El tipo de contenido no es JSON en UTF-8.
422BX6004, BX6007, BX6008No se acepta la resolución, la solicitud tardó demasiado, o la plantilla tiene problemas, que se enumeran en errors. Cuando los comandos de impresora superarían limits.maxCommandsBytes, errors trae BX5112, o BX6025 (el mismo hallazgo explicado para quien visita) cuando publicDemo es true.
429BX6005, BX6006, BX6014, BX6015, BX6016, BX6018, BX6023Este cliente hizo demasiadas solicitudes (BX6005) o demasiadas solicitudes de imágenes de elementos sueltos (BX6023), todos los lugares para dibujar están ocupados (BX6006), entre todos los clientes hicieron demasiadas (BX6014), este cliente ya tiene una solicitud en curso (BX6015), hay demasiadas respuestas esperando a ser recibidas por sus lectores (BX6016), o están llegando demasiadas plantillas a la vez (BX6018). La respuesta lleva Retry-After en segundos, calculado a partir del límite que se alcanzó: espere ese tiempo.
500BX6009Un problema inesperado. La respuesta no da detalles; indique el identificador de seguimiento al soporte técnico.

Los textos de estos códigos, en español y en inglés, están en Códigos de diagnóstico.

El miembro type de un documento de problema es una dirección bajo docs.barcoderx.example, seguida del código. Es un marcador de posición: el dominio real de la documentación aún no está decidido, y nada en el servicio ni en el cliente de .NET sigue esa dirección. Use el code.

Lo que un cliente puede tener al mismo tiempo

  • Una solicitud a la vez. De forma predeterminada, cada cliente (vea "Quién llama" más abajo) puede tener una solicitud en curso, desde el primer byte de la plantilla hasta el último byte de la respuesta. Una segunda solicitud mientras la primera sigue en curso se rechaza de inmediato con 429 y BX6015, antes de leer nada. El ajuste es limits.maxRequestsInFlightPerClient.
  • La plantilla se lee antes de tomar un lugar para dibujar. La plantilla completa debe llegar dentro de limits.bodyReadMilliseconds (5,000 de forma predeterminada), y su tamaño se limita a medida que llegan los bytes. Un cliente que envía despacio retiene solo su propio lugar y una conexión, como máximo ese tiempo, y luego se detiene con BX6017. Nunca retiene un lugar para dibujar.
  • Un lugar para dibujar solo mientras se genera la etiqueta. Los pocos lugares para dibujar se ocupan mientras se compone y se dibuja la etiqueta, y se devuelven cuando la respuesta está lista. Una respuesta que espera a un lector lento espera en una reserva de memoria propia (limits.outputBudgetMegabytes), y un lector lento solo puede retener su propia respuesta. Cuando esa reserva está llena, la solicitud se rechaza con BX6016 después de generar su etiqueta.
  • Conexiones. Un cliente puede tener abiertas al mismo tiempo limits.maxConnectionsPerClient conexiones (16 de forma predeterminada). Una conexión que pasa de ese número se cierra de inmediato, sin respuesta, antes de leer un solo byte. Un rechazo que se envía antes de que llegue la plantilla completa se termina de inmediato, y el servicio espera entonces un segundo por el resto de la plantilla y corta la conexión si no llegó, de modo que un cliente rechazado que sigue enviando despacio no conserva su conexión. Las conexiones de un proxy que usted indique en network.trustedProxies no se cuentan: limítelas en el proxy.
  • Solicitudes. Cada solicitud de un cliente, incluida una solicitud de una dirección que no existe, cuenta contra su propio límite rateLimit.requestsPerMinutePerClient. Solo las solicitudes que llegan a una ruta que dibuja cuentan contra el límite de todos los clientes juntos, rateLimit.requestsPerMinuteAllClients, de modo que una avalancha de solicitudes a direcciones que no existen no puede agotar la cuota de todos. Las comprobaciones de estado nunca se cuentan.
  • Tiempos de espera. Un rechazo dice cuánto esperar. En un límite de frecuencia es el tiempo hasta que se permite la siguiente solicitud. En BX6018 es el tiempo para enviar una plantilla. En BX6006 es aproximadamente la suma del tiempo para componer una etiqueta (limits.engineMilliseconds) y del límite de tiempo de una solicitud (limits.renderMilliseconds), que es el tiempo que, en la práctica, se retiene un lugar para dibujar. En BX6015 son juntos el tiempo para enviar la plantilla, esos dos y el plazo de escritura, y en BX6016 es el plazo de escritura.

Comprobar una plantilla

El servicio no guarda ninguna plantilla. Dos rutas trabajan sobre una plantilla que usted envía, para un editor o un paso de compilación que quiere saber qué falla en ella, o cuál es su texto canónico. Ambas toman la plantilla como cuerpo (Content-Type: application/json), ningún ajuste en la dirección, y la misma clave, límite de tamaño, tiempo de envío y límite por cliente que la ruta de la imagen. No dibujan nada, así que no usan el límite de todos los clientes juntos, pero, una vez que llegó la plantilla, toman un lugar para dibujar mientras el servicio trabaja con ella, como una imagen, porque leer una plantilla grande cuesta memoria, de modo que un servicio con un limits.maxBodyBytes grande necesita un limits.memoryBudgetMegabytes mayor, y un editor que envía varias solicitudes a la vez necesita un limits.maxRequestsInFlightPerClient más alto.

  • POST /api/v1/templates/validate. La respuesta es siempre 200 cuando se recibió la plantilla: valid (false cuando la plantilla no se pudo leer o algún hallazgo es un error) y diagnostics, cada hallazgo en el idioma de la solicitud (Accept-Language), cada uno con code, severity, title, message, elementId, pointer y args. Un hallazgo del lector sobre el texto (un carácter que JSON no permite, por ejemplo) lleva en sus args la line y la position donde empieza el problema. Un texto que no es JSON da 200 con valid en false, no un estado de error, porque la respuesta son los hallazgos. Un cuerpo por encima del límite es 413, y un tipo de contenido que no es JSON es 415.
  • POST /api/v1/templates/convert. La respuesta es el texto canónico de la plantilla (Content-Type: application/json): la única forma fija en que BarcoderX escribe una plantilla, con cada elemento y los miembros que conserva el modelo. Convertir el texto canónico da el mismo texto. El texto canónico nunca es mayor que limits.maxBodyBytes, así que siempre se puede volver a enviar a este servicio; una plantilla cuyo texto canónico sería mayor se rechaza con 422 y el hallazgo BX1130. Una plantilla que no es válida es un problema con sus hallazgos en errors, como en la ruta de la imagen (422, o 400 para un texto que no es JSON). Todavía no se convierte ninguna versión anterior del formato de plantilla, así que hoy es la forma canónica de una plantilla que ya está en el formato actual.

Imágenes de elementos sueltos

Un editor que muestra una etiqueta necesita la imagen de cada elemento por separado, con el recuadro que ocupa en la etiqueta y, en un código de barras, el tamaño de su símbolo. POST /api/v1/render/elements las da. El servicio no guarda nada: la plantilla viaja en la solicitud, como en las demás rutas, y la respuesta se hace a partir de ella.

El cuerpo es JSON con estos miembros: template (la plantilla como objeto; una plantilla parcial sirve), ids (los ids de los elementos que se dibujan: de 1 a 64, de 1 a 128 caracteres cada uno, sin repetidos) y, si los quiere, dpi (de 96 a 600; un elemento se dibuja con el menor entre este valor y 300), culture (en o es, el idioma de los hallazgos; sin él el servicio sigue Accept-Language) y record (un registro de datos como objeto). Un miembro que no se conoce, que está repetido o que no es válido se rechaza con 400 y el código BX6020, que nombra el miembro. La clave, el límite de tamaño, el tiempo para enviar, el tipo de contenido y los límites de cada cliente son los de la ruta de la imagen, y una solicitud de elementos cuenta contra el límite de todos los clientes juntos igual que una imagen.

La respuesta es 200 con engineVersion e items, una entrada por cada id pedido, en el orden pedido. Cada una tiene:

  • status: ok (se dibujó), error (no se pudo dibujar o no se pudo enviar su imagen: consulte sus diagnósticos), notFound (la plantilla no tiene ningún elemento con ese id) o skipped (un elemento de un tipo que el motor todavía no dibuja por sí solo, como una línea o una elipse, o uno cuyo contenido viene de datos).
  • En una entrada ok: form (png) y png (la imagen como texto en base 64 de un archivo PNG con un bit por punto, recortada al recuadro del elemento); bounds (unit y box en la unidad de la página, y dots a la resolución de la imagen, de modo que la imagen tiene justo ese tamaño); symbol en un código de barras (el tamaño del símbolo en la unidad de la página y en puntos, y el ancho de un módulo en puntos); y hash.
  • diagnostics: los hallazgos sobre el elemento, en el idioma pedido.

El hash es el mismo para el mismo dibujo y cambia con todo lo que lo influye: el elemento, la plantilla, los datos, el idioma, la resolución, la versión del motor y si la imagen lleva la marca. Un cliente puede guardar una imagen bajo su hash. Un elemento que falla no hace fallar la solicitud.

La marca de evaluación. Sin una licencia que lo permita, cada imagen lleva la marca de evaluación mezclada en sus puntos, y la respuesta lo dice: el encabezado BarcoderX-Marked vale true y BarcoderX-Warnings enumera el aviso sobre la licencia (por ejemplo BX9001, no hay ninguna licencia registrada). El servicio lo decide con su propio estado de licencia, y nada en una solicitud puede cambiarlo. La marca disuade, no es una cerradura.

Límites. Como máximo 64 ids; como máximo 4,000,000 de puntos en la imagen de un elemento y 16,000,000 en todas las imágenes de una solicitud (un elemento que pase de ahí queda en error con sus diagnósticos); como máximo 512 KB para el PNG de un elemento (BX6021); como máximo 8 MB para toda la respuesta (cuando la imagen siguiente la pasaría, esa y las que siguen se dejan fuera con BX6022). GET /api/v1/meta/limits publica estas cifras como maxFragmentIds, maxFragmentDots, maxFragmentDotsPerRequest, maxFragmentBytes y maxFragmentsAnswerBytes. El límite de tiempo de una solicitud (limits.renderMilliseconds) no detiene el dibujo de los elementos: la marca se mezcla en los puntos en la misma llamada, y a quien no tiene licencia no se le debe rechazar por un tiempo que quien sí la tiene no gasta. El dibujo lo detiene el plazo propio del motor (limits.engineMilliseconds), y la escritura de las imágenes recibe el límite de tiempo desde que termina el dibujo. La respuesta nunca se guarda en una caché (Cache-Control: no-store); guarde las imágenes por su hash. Una solicitud de elementos retiene más memoria que una imagen, así que ocupa más de uno de los lugares para dibujar: con los ajustes predeterminados hay cuatro lugares y ocupa dos, de modo que todavía se dibuja una imagen y todavía se ejecuta una segunda solicitud de elementos, y una tercera solicitud de elementos se rechaza de inmediato con BX6006 mientras se ejecutan (consulte Despliegue del servicio de etiquetas). Además, un cliente solo puede hacer unas pocas solicitudes de elementos por minuto (rateLimit.elementRequestsPerMinutePerClient, 6 de forma predeterminada, además de su otro límite): quien pide con más frecuencia recibe BX6023 y se le dice cuánto esperar, y GET /api/v1/meta/limits publica el número como elementRequestsPerMinutePerClient.

Las demás rutas

RutaQué da
GET /api/v1/meta/limitsLos límites de este servicio como JSON: maxBodyBytes, maxElements, maxCharactersPerText, maxCharactersPerLabel, maxBlackAndWhitePixels, maxColorPixels (también para gris), maxSideDots, maxOutputBytes, maxCommandsBytes, minDpi, maxDpi, renderMilliseconds, bodyReadMilliseconds y requestsPerMinutePerClient, requestsPerMinuteAllClients, maxRequestsInFlightPerClient, maxConnectionsPerClient, responseWriteMilliseconds, elementRequestsPerMinutePerClient, maxFragmentIds, maxFragmentDots, maxFragmentDotsPerRequest, maxFragmentBytes y maxFragmentsAnswerBytes (los límites de la ruta de elementos sueltos), maxCoordinateMillimeters y maxQuietZoneModules (los dos límites a los que se refieren los extremos de rango llamados coordinateMagnitude y quietZoneModules en los descriptores de elementos). Una página puede leerlos para comprobar una plantilla antes de enviarla y para saber con qué rapidez puede enviar.
GET /api/v1/meta/licenceEl estado de la licencia de este servicio: state (unlicensed, grace, evaluation o licensed), outputMarked (verdadero cuando el estado es unlicensed, lo que significa que toda la salida se marca: cada imagen y cada conjunto de comandos lleva la marca de evaluación; no cubre una etiqueta suelta que se marca porque usa algo que la licencia no incluye, como un tipo de código de barras que no cubre, lo que puede ocurrir en un servicio con licencia) y, solo en un servicio que tiene una clave y solo para un cliente que la ha presentado, expiresOn y updatesUntil (fechas como yyyy-MM-dd, omitidas cuando no hay ninguna). Las fechas revelan cuánto dura la licencia y cuánto tiempo recibe actualizaciones, así que un servicio abierto a todos no las da. Nunca da la clave, el identificador de la licencia ni el nombre del licenciatario. La respuesta es private: una caché compartida no debe conservarla. En un servicio que tiene una clave, un cliente que la ha presentado recibe además entitlements (los identificadores de las funciones que la licencia concede ahora, ninguno cuando la salida se marca), findingCodes (los códigos de diagnóstico de los hallazgos, como BX9004) y nextChangeOn con nextChangeKind (expiry, graceEnd o updatesEnd), omitidos cuando no hay ningún cambio con fecha. Revelan los términos de la licencia, así que un servicio abierto a todos no los da.
GET /api/v1/printer-dialectsLos lenguajes de impresora que escribe la dirección de comandos, como items: id (el valor de dialect), displayName en el idioma de la solicitud y fidelity (raster: toda la etiqueta se envía como una sola imagen). Hoy la lista es zpl.
GET /api/v1/printer-profilesLos perfiles de impresora, como items: id, displayName, dialect y dpi. Hoy son zpl-generic-203, zpl-generic-300 y zpl-generic-600. No se lista nada de un modelo de impresora: ni ancho, ni memoria, ni fuentes, porque todavía no se han medido.
GET /api/v1/meta/versionproduct, apiVersions y build.
GET /api/v1/meta/elementsLos descriptores de elementos con los que se construyen los paneles del editor: version (un hash del contenido; también es el ETag) y kinds (text, barcode, line, box, ellipse), cada uno con sus groups de properties. Una propiedad tiene su name, path, labelKey, kind, unit, shape, isRequired, isOptional, acceptsExpression, isDerived, unitFollows, range, default, values (cada uno con key y labelKey), shownWhen (condiciones sobre otras propiedades) y members (las partes de una propiedad compuesta). Llevan claves de recurso para cada nombre y nunca los textos: el editor tiene sus propias etiquetas, así que la respuesta no depende del idioma. Cada extremo de un range es un número o un múltiplo de un límite que fija el servicio (coordinateMagnitude en milímetros, quietZoneModules): lea los números en GET /api/v1/meta/limits.
GET /api/v1/barcodes/symbologiesLas simbologías que puede usar un elemento de código de barras, como items: id (el valor de symbology), aliases, displayName en el idioma de la solicitud, family, tier (basic o ultimate), availability (implemented, o planned: listada pero todavía sin dibujar), sampleContent para un código de barras recién añadido, y las options de la simbología (name, kind, unit, minimum, maximum, defaultValue, enumKeys, shownWhen y usableInTemplates: false mientras el motor ignora la opción). Solo se listan las simbologías que pueden publicarse.
GET /health/live y GET /health/ready{"status":"ok"} y nada más. No necesitan clave.

Las rutas /meta/licence, /meta/elements, /printer-dialects, /printer-profiles y /barcodes/symbologies responden con un ETag y Cache-Control: no-cache (private, no-cache para el estado de la licencia). Devuelva ese valor en If-None-Match, y una respuesta sin cambios es 304, sin cuerpo. Los nombres siguen Accept-Language (en o es), y el ETag cambia según el idioma, salvo en /meta/elements, que no tiene texto y tiene un solo ETag.

Todas las rutas, salvo las dos de salud, necesitan la clave cuando el servicio tiene una. Toda ruta de producto está bajo /api/v1. Todavía no existe un documento OpenAPI.

Desde un programa de .NET

Un cliente de .NET con tipos para ambas rutas está construido y probado. Para la imagen recibe el texto de la plantilla y las opciones (la resolución, el tipo de imagen y el idioma), y devuelve los bytes del PNG y los códigos de las advertencias, o el documento de problema y el número de segundos que hay que esperar. Solo lanza una excepción por una falla de red o una solicitud cancelada, nunca por un problema que informa el servicio. RenderElementsAsync pide las imágenes de elementos sueltos: toma la plantilla, los ids y las opciones (resolución, idioma y registro de datos) y devuelve la lista de elementos, si las imágenes llevan la marca y los códigos de aviso, o el documento de problema. RenderCommandsAsync hace lo mismo para los comandos de impresora (las opciones son el lenguaje de impresora, la resolución y el idioma de los mensajes). Como lo demás, todavía no está publicado.

El archivo de ajustes

El archivo es JSON con comentarios. Un nombre que el programa no conoce es un error, de modo que un error de escritura se encuentra y no se ignora. Un ajuste que falta conserva el valor seguro. Cada número de abajo es una primera elección de quienes construyen BarcoderX. Todavía no se ha confirmado y puede cambiar antes de la primera versión.

AjusteValor predeterminadoQué hace
listenAddresshttp://127.0.0.1:5187Dónde escucha el servicio. Solo http, con una dirección IP o localhost. Use 0.0.0.0 para que otros equipos puedan llegar a él.
publicDemotrue en el archivo inicialtrue ejecuta el servicio abierto a todos, a propósito. false necesita una apiKey.
apiKeyvacíoUn secreto de al menos 32 caracteres. Cada solicitud debe enviarlo como Authorization: Bearer <clave>. Déjelo vacío solo cuando publicDemo sea true.
logLevelInformationInformation escribe una línea por solicitud: estado, ruta, tamaños, tiempo, el código de un problema y el identificador de seguimiento. Warning escribe solo los problemas. Nunca el contenido de una plantilla.
cors.allowedOriginsvacíoSitios web cuyas páginas pueden llamar al servicio desde un navegador, por ejemplo https://barcoderx.com. Vacío significa ninguno. Un asterisco se rechaza. Nunca se permiten cookies ni credenciales.
network.trustForwardedHeadersfalseSi se lee la dirección de quien llama desde un proxy. Actívelo solo con network.trustedProxies indicado. Vea "Quién llama" más abajo.
network.sendStrictTransportSecuritytrueSi se indica a los navegadores que usen solo https durante seis meses (el encabezado Strict-Transport-Security, max-age=15552000, nunca con includeSubDomains ni preload). El servicio habla solo http, así que envía el encabezado únicamente cuando network.trustForwardedHeaders es true y un proxy indicado en network.trustedProxies dice X-Forwarded-Proto: https (se cree la entrada del extremo derecho del encabezado). Entonces va en toda respuesta de ese tipo, errores y comprobaciones de estado incluidos, y nunca en la respuesta a una solicitud que no llegue así. Ponga false para no enviar nada.
network.trustedProxiesvacíoLos proxies en los que usted confía, cada uno como una dirección (10.0.0.5, 2001:db8::5) o un rango (10.0.0.0/8, 2001:db8::/32), como máximo 32. Una entrada mal escrita impide que el servicio arranque (un número con cero a la izquierda, como 010, se rechaza: la plataforma lo leería como octal). "Cualquier dirección" (0.0.0.0 o ::) y un rango que abarca todas las direcciones o casi todas (0.0.0.0/0, ::/0, cualquier rango más amplio que /8 en IPv4 o que /7 en IPv6) se rechazan, salvo que network.acceptAnyProxyAddress sea true. Los proxies que indique aquí tampoco los cuenta el límite de conexiones, tenga o no activado network.trustForwardedHeaders.
network.acceptAnyProxyAddressfalseDéjelo en false. Solo permite en network.trustedProxies un rango que abarca todas las direcciones, lo que convierte a todo cliente en un proxy de confianza que puede elegir su propia dirección.
network.edge.modeoffoff o azureFrontDoor. Con azureFrontDoor el servicio responde solo a las solicitudes que llegaron por su Azure Front Door: consulte "Azure Front Door delante de App Service" en Despliegue del servicio de etiquetas. Necesita network.trustForwardedHeaders en true, los rangos de su servidor web en network.trustedProxies, network.trustedProxyHops en 1 y network.acceptAnyProxyAddress en false, o el servicio no arranca.
network.edge.frontDoorIdvacíoEl ID de Front Door de su perfil (36 caracteres con guiones), tal como lo muestra el portal. Se necesita cuando el modo es azureFrontDoor. Trátelo como una contraseña: el servicio nunca lo registra ni lo muestra, y solo debe estar en el archivo junto al programa.
network.edge.hostsvacíoLos nombres de host que escriben sus visitantes, de 1 a 8, solo letras, dígitos, guiones y puntos (un nombre internacional en su forma xn--), comparados sin distinguir mayúsculas. Se necesita cuando el modo es azureFrontDoor.
network.trustedProxyHops1En cuántos proxies indicados seguidos, contados desde la conexión, se confía cuando nombran la siguiente dirección de X-Forwarded-For (de 1 a 8). 1 es el proxy desde el que llega la conexión. Use 2 solo cuando un servidor de entrada indicado está delante de un proxy indicado. Consulte "Quién llama" más abajo.
rateLimit.requestsPerMinutePerClient20Solicitudes que un cliente puede hacer por minuto en promedio (de 1 a 600). Un cliente puede enviar todas esas a la vez, y recibe una más cada minuto dividido por el número.
rateLimit.requestsPerMinuteAllClients600Solicitudes que todos los clientes juntos pueden hacer por minuto en promedio a las rutas que dibujan (de 1 a 6,000), contadas de la misma forma.
rateLimit.elementRequestsPerMinutePerClient6Solicitudes de imágenes de elementos sueltos (POST /api/v1/render/elements) que un cliente puede hacer por minuto en promedio (de 1 a 600), contadas de la misma forma y además de rateLimit.requestsPerMinutePerClient. Es más bajo porque una solicitud así usa más de la memoria para dibujar que una imagen; las rutas que dibujan una etiqueta conservan su propio límite. Un cliente rechazado recibe BX6023 y se le dice cuánto esperar.
limits.maxBodyBytes262,144Bytes de una plantilla (de 1,024 a 10 MB). Un servicio abierto a todos (publicDemo en true) acepta como máximo 262,144 y se niega a arrancar con más. Para el editor web, ponga publicDemo en false, dé una clave al servicio y auméntelo (2,097,152 son 2 MB). Un cuerpo mayor necesita más memoria: el presupuesto de memoria siguiente cuenta 60 veces el límite del cuerpo por cada solicitud, además de su imagen y su texto, así que aumente limits.memoryBudgetMegabytes para dibujar el mismo número de etiquetas a la vez. Con el presupuesto predeterminado (512 MB), un servicio con un límite de 2 MB dibuja una etiqueta a la vez, y otra solicitud que llegue mientras tanto se rechaza con BX6006.
limits.maxElements200Elementos de una plantilla.
limits.maxCharactersPerText2,000Caracteres de un texto o del contenido de un código de barras (hasta 50,000).
limits.maxCharactersPerLabel5,000Caracteres de texto en todos los elementos de una etiqueta (hasta 50,000).
limits.maxBlackAndWhitePixels9,000,000Puntos, ancho por alto, de una imagen en blanco y negro (hasta 64,000,000). De él dependen la imagen, los comandos de impresora y la memoria de un dibujo. El área de pruebas pública y gratuita de barcoderx.com usa unos 4,000,000, que mantienen la respuesta más grande cerca de 1 MB (etiquetas de 4 x 6 y 4 x 8 pulgadas a 300 dpi siguen cabiendo); una etiqueta mayor se rechaza de inmediato, antes de componerla, con BX3901, que dice que cambie el tamaño o la resolución.
limits.maxGrayPixels, limits.maxColorPixels2,500,000Puntos de una imagen en gris y de una en color (hasta 64,000,000).
limits.maxSideDots8,192El lado más largo, en puntos (hasta 65,536).
limits.maxOutputBytes2,000,000Bytes del archivo PNG de la respuesta (de 1,024 a 256,000,000).
limits.maxCommandsBytes16,777,216Bytes de los comandos ZPL de una etiqueta en la respuesta de la ruta de comandos (de 1,024 a 67,108,864). Los puntos de la etiqueta los limita limits.maxBlackAndWhitePixels, y el tamaño de los comandos se deriva de los puntos (2 caracteres hexadecimales por cada 8 puntos, cerca de un cuarto de byte por punto), así que con 9,000,000 de puntos ninguna respuesta pasa de unos 2.27 MB. El área de pruebas pública y gratuita usa 2,500,000, un techo escrito por encima de eso. Una etiqueta que lo supere se rechaza antes de dibujar nada.
limits.minDpi, limits.maxDpi96 y 600Las resoluciones que se aceptan. El motor mismo dibuja de 96 a 1,200.
limits.engineMilliseconds1,000Tiempo para componer una etiqueta o para dibujar los elementos de una solicitud.
limits.renderMilliseconds2,000Tiempo para leer una plantilla, una vez que llegó y se tomó un lugar para dibujar, y, contado de nuevo desde el final de la composición, tiempo para dibujar la imagen o hacer los comandos. La composición en sí tiene limits.engineMilliseconds; el tiempo que toma la marca de evaluación no está en ninguno de los dos, para que un servicio sin licencia no rechace lo que uno con licencia atiende.
limits.bodyReadMilliseconds5,000Tiempo que tiene un cliente para enviar la plantilla completa (100 a 60,000). Un cliente que envía más despacio se detiene con BX6017. El servidor también detiene a un remitente que envía, en promedio, menos de 240 bytes por segundo una vez pasados sus primeros 5 segundos, sea cual sea este ajuste.
limits.responseWriteMilliseconds5,000Tiempo para escribir la imagen terminada al cliente. Un cliente que lee más despacio se descarta.
limits.responseChunkBytes32,768La respuesta se escribe en trozos de este tamaño (de 4,096 a 65,536), para notar a un cliente que deja de leer. El máximo es 64 KB porque el sistema operativo toma entero un trozo mayor para un lector que no lee nada.
limits.maxRequestsInFlightPerClient1Solicitudes que un cliente puede tener en curso al mismo tiempo (de 1 a 64).
limits.maxConnectionsPerClient16Conexiones que un cliente puede tener abiertas al mismo tiempo (de 1 a 256). No se cuentan para un proxy indicado en network.trustedProxies.
limits.outputBudgetMegabytes128Memoria para las respuestas que ya se crearon y esperan a sus lectores, además del presupuesto de memoria de abajo (de 1 a 4,096). Debe alcanzar para la respuesta más grande: la mayor entre limits.maxOutputBytes y limits.maxCommandsBytes.
limits.memoryBudgetMegabytes1,024Memoria que pueden usar juntos los dibujos. Decide cuántas etiquetas se dibujan a la vez. Con los valores predeterminados son 4 a la vez; una solicitud de imágenes de elementos ocupa 2 de esos lugares. Una más se rechaza de inmediato con BX6006 y nunca se pone en cola. Una cuarta parte es también el presupuesto para las plantillas que se están recibiendo, contando cada byte tres veces; cuando está lleno, una solicitud se rechaza con BX6018 antes de leer toda su plantilla.

Los límites del motor de etiquetas que no están en esta tabla, como el número de segmentos de trazado, están fijos en el programa con los valores de El motor de etiquetas para una página de demostración.

Quién llama

Los límites de arriba son por cliente, y un cliente es la dirección de la conexión. Una dirección IPv4 es un cliente, y una dirección IPv6 se cuenta por sus primeros 64 bits, porque un suscriptor suele tener un bloque completo de ese tamaño.

  • De forma predeterminada se usa la dirección de la conexión y se ignora X-Forwarded-For. El encabezado es una afirmación de quien envió la solicitud.
  • Detrás de un proxy, todos los clientes se conectan desde el proxy. Sin ayuda, todos se ven como un solo cliente, y la regla de una solicitud a la vez dejaría pasar a uno solo por vez. Ponga network.trustForwardedHeaders en true e indique el proxy en network.trustedProxies.
  • Qué proxy es de confianza. Solo se confía en una conexión desde una dirección de network.trustedProxies. El servicio lee entonces X-Forwarded-For desde su extremo derecho, como máximo network.trustedProxyHops entradas (de 1 a 8, 1 de forma predeterminada): empezando por la dirección de la conexión, mientras una dirección es uno de sus proxies indicados, se confía en la entrada a su izquierda (la que añadió ese proxy), y el cliente es la última entrada en la que se confió. Con el valor predeterminado de 1 es la última entrada, la que añadió el propio proxy. Ponga 2 cuando un servidor de entrada indicado está delante de un proxy indicado, y así sucesivamente, nunca más de los que tiene la cadena: cada salto más allá del primero deja que un visitante cuya propia dirección está dentro de un rango indicado elija una vez la dirección con la que se le cuenta. Si se llega a una dirección que no está indicada antes de agotar los saltos, es el cliente. Las entradas a la izquierda del cliente las escribió el propio cliente y se ignoran. Una solicitud desde cualquier otra dirección conserva su propia dirección, diga lo que diga su encabezado.
  • Una comilla en X-Forwarded-For. Con network.edge.mode en off, un visitante que envía X-Forwarded-For empezando con comillas dobles se cuenta como la dirección de la propia conexión (el proxy), porque el paso que lee el encabezado toma toda la línea como un solo texto entrecomillado. Eso le da como mucho una cuota más, nunca la libre elección de la dirección, y el límite de todos los clientes se mantiene. Con network.edge.mode en azureFrontDoor una solicitud así se rechaza (403, BX6024).
  • Configure el proxy para que añada la dirección y no pase tal cual el encabezado del cliente. Las configuraciones de referencia de Despliegue del servicio de etiquetas lo hacen.

Si usted aloja el servicio

La página Despliegue del servicio de etiquetas dice qué poner delante del servicio y da una configuración de referencia para nginx y para Caddy. En resumen:

  • Ponga delante un servidor web con https, y haga que ese servidor almacene en búfer la solicitud y la respuesta. Es obligatorio antes de dejar que alguien que usted no conoce llegue al servicio. El servicio habla solo http y tiene límites propios, pero un proxy que almacena en búfer es lo único que mantiene a un cliente lento completamente lejos de él.
  • Limite las conexiones por dirección en el proxy.
  • Indique quién llama (la sección de arriba).
  • Mantenga un entorno de ejecución de .NET actualizado.
  • Muestre las respuestas como texto. La lista errors contiene ids y nombres que se escribieron en la plantilla. Inserte cada valor en una página como texto, nunca como marcado, y muestre los ids de elemento en un contexto de dirección aislado. El servicio ya reemplazó los caracteres de control, de dirección e invisibles por U+FFFD. Consulte Códigos de diagnóstico.
  • Una página web que llama al servicio no debe enviar cookies ni credenciales. Enumere su sitio web en cors.allowedOrigins. Los encabezados que la página puede leer son Retry-After, BarcoderX-Warnings, BarcoderX-Marked, BarcoderX-Image-Width, BarcoderX-Image-Height y Api-Supported-Versions.
  • Sepa lo que no hace. No guarda ninguna plantilla ni ninguna imagen, no escribe ningún archivo, nunca abre una dirección que nombre una plantilla y nunca redirige. Cada imagen y cada conjunto de comandos lleva la marca de evaluación.

Lo que todavía no está construido

  • El resto de la API web: plantillas guardadas, otros formatos de salida, lenguajes de impresora distintos de ZPL y los comandos propios de texto y de códigos de barras de la impresora, trabajos de impresión, trabajos por lotes, recursos y las rutas de administración. Consulte API web.
  • Un documento OpenAPI y una página de documentación generada a partir de él.
  • Una forma de darle una licencia al servicio. Hasta entonces, cada imagen y cada conjunto de comandos lleva la marca de evaluación.
  • Varias etiquetas en una solicitud, y datos combinados con una plantilla.

BarcoderX es un producto de P4 Software.

¿Te resultó útil esta página?