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

API web

API web

Aplica a: BarcoderX Basic y Ultimate

Estado: Planificado, con una parte construida. Todavía no hay nada publicado y no hay nada que descargar. La primera parte, el servicio de etiquetas, está construida y probada: dibuja una etiqueta a partir de una plantilla y responde con un archivo PNG. Consulte El servicio de etiquetas. El resto de 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 versión. Después, la versión 1 cambia solo por adición.

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:

RangoÁrea
1000 a 1999Modelo y plantillas
2000 a 2999Datos y expresiones
3000 a 3999Gráficos, imágenes, fuentes, texto, exportación y el motor de etiquetas
4000 a 4999Códigos de barras
5000 a 5999Comandos e impresión
6000 a 6999La API
7000 a 7999El agente de impresión
8000 a 8999El editor
9000 a 9999Licencias

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

Lo que está construido hoy

El servicio de etiquetas es un programa pequeño que usted ejecuta por su cuenta. Atiende estas rutas, todas bajo /api/v1 salvo las de salud:

RutaQué hace
POST /render/pngDibuja una etiqueta a partir de la plantilla del cuerpo y responde con un archivo PNG, en blanco y negro, gris o color, a la resolución que usted pida.
POST /render/elementsDibuja hasta 64 elementos de una plantilla, cada uno por separado, y responde con una imagen PNG de un bit de cada elemento que puede dibujar, para el editor.
POST /commands?dialect=zplEscribe los comandos ZPL de una etiqueta, como texto simple o como JSON.
POST /templates/validate, POST /templates/convertRevisan una plantilla y enumeran cada hallazgo, o devuelven su texto canónico.
GET /meta/limitsLos límites de este servicio.
GET /meta/versionEl producto, las versiones de la API y la compilación.
GET /meta/licenceEl estado de la licencia, sin la clave, y si la salida se marca.
GET /meta/elements, GET /barcodes/symbologiesLos descriptores de elementos y los tipos de código de barras con sus opciones, para el editor.
GET /printer-dialects, GET /printer-profilesLos lenguajes de impresora y los perfiles de impresora.
GET /health/live, GET /health/ready{"status":"ok"}, sin clave.

Estas rutas se describen en El servicio de etiquetas. Los errores son documentos de problema con un código del rango 6000 y, cuando una plantilla tiene problemas, la lista de ellos. Todavía no existe un documento OpenAPI, ni una plantilla guardada, ni otro formato de salida. Todo lo demás de esta página está planificado. Las rutas de la tabla de abajo son las previstas: por ejemplo, el POST /render previsto hace todos los formatos, y POST /render/png es su primera forma construida, junto con POST /render/elements.

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.

RecursoPara qué sirveMétodos y rutasVersión
PlantillasGuardar, versionar, publicar, validar y convertir plantillasGET, POST /templates; GET, PUT, DELETE /templates/{id}; GET /templates/{id}/versions; GET /templates/{id}/versions/{n}; POST /templates/{id}/versions/{n}/restore; POST /templates/{id}/publish; PUT /templates/{id}/draft; POST /templates/validate; POST /templates/convertPrimera
Archivos de plantillaMover una plantilla con sus fuentes e imágenes entre servidoresGET /templates/{id}/archive; POST /templates/import-archivePrimera
Generación y exportaciónCrear un archivo de etiqueta a partir de una plantilla guardada o en línea y de datos. Formatos: PNG, JPG, PDF, SVG, PCX y HTML, y EPS más adelante.POST /render; POST /render/elements; POST /render/thumbnailPrimera (EPS más adelante)
ComandosCrear los comandos de impresora para una plantilla y datosPOST /commandsPrimera
Trabajos por lotesEjecutar generaciones grandes en segundo planoPOST /jobs; GET /jobs/{id}; GET /jobs/{id}/output; DELETE /jobs/{id}Primera
Trabajos de impresiónEnviar etiquetas a impresorasPOST /print-jobs; GET /print-jobs; GET /print-jobs/{id}; POST /print-jobs/{id}/cancelPrimera
ImpresorasRegistrar impresoras, leer su estado, listar lenguajes de impresora y perfilesGET, POST /printers; GET, PUT, DELETE /printers/{id}; GET /printers/{id}/status; GET /printer-dialects; GET /printer-profilesPrimera
AgentesListar agentes de impresión, iniciar el alta, revocar un agenteGET /agents; POST /agents/enrollments; DELETE /agents/{id}Primera
Códigos de barrasListar simbologías, verificar datos, crear un código de barrasGET /barcodes/symbologies; POST /barcodes/validate; POST /barcodes/encodePrimera
RecursosGuardar fuentes e imágenesGET, POST /assets/fonts; GET, POST /assets/images; GET /assets/{id}; GET /assets/{id}/content; DELETE /assets/{id}Primera
DatosFuentes de datos guardadas, descubrimiento de campos y secuenciasGET, POST /data-sources; GET, PUT, DELETE /data-sources/{id}; POST /data-sources/infer-schema; GET, POST /sequences; POST /sequences/{id}/allocatePrimera
ExpresionesListar funciones, verificar y probar expresiones, guardar macrosGET /expressions/functions; POST /expressions/validate; POST /expressions/evaluate; GET, POST /expressions/macros; PUT, DELETE /expressions/macros/{id}Primera
MetadatosDescribir las propiedades de los elementos, los límites vigentes y el estado de la licenciaGET /meta/elements; GET /meta/limits; GET /meta/licencePrimera
AdministraciónClaves de API y el registro de auditoríaGET, POST /api-keys; DELETE /api-keys/{id}; GET /audit-eventsPrimera
Mantenimiento de impresorasPausar, reanudar, cortar, calibrar y operaciones similaresPOST /printers/{id}/maintenance/{operation}Más adelante

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.
  • La primera parte de POST /commands está construida en el servicio sin estado como POST /api/v1/commands?dialect=zpl. Recibe una plantilla completa y devuelve los comandos ZPL de toda la etiqueta como texto simple, con los mismos límites, lugares, límites de frecuencia y límite de tiempo que la dirección de la imagen. El perfil de impresora, los datos y las plantillas guardadas del /commands completo llegan después. Consulte Salida ZPL.
  • 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. La primera parte construida, el servicio de etiquetas, usa solo el archivo de ajustes.
  • 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.

¿Te resultó útil esta página?