Integrar básculas con su software mediante una API
Una API de báscula permite que el software lea el peso en vivo, la estabilidad, los preajustes y los registros almacenados, y envíe comandos como cero, tara e imprimir, normalmente como JSON a través de la red. Use lecturas estables y con marca de tiempo, tome los registros del histórico de la báscula en lugar de valores en vivo sondeados, y restrinja y registre los comandos remotos.
Qué hace una API de báscula
Una API (interfaz de programación de aplicaciones) de báscula permite que su propio software lea pesos y registros de una báscula y le envíe comandos, mediante una interfaz documentada y legible por máquina en lugar de leer una pantalla o analizar un flujo de impresora. Con una API, un programa de registro de capturas, un controlador de línea de envasado o un panel en tierra pueden usar la báscula como fuente de datos y como dispositivo controlable.
Las integraciones más antiguas dependían de una salida serie continua: la báscula enviaba una línea de texto con el peso varias veces por segundo a través de RS232, y el programa receptor la analizaba. Eso sigue funcionando, pero solo fluye en un sentido y el formato difiere entre fabricantes. Una API de red añade datos estructurados (normalmente JSON), acceso a registros y preajustes almacenados, y una forma definida de emitir comandos. El lado físico de esa conexión se trata en RS232, Ethernet, USB, Wi-Fi o Bluetooth LE: elegir la interfaz de una báscula.
Puntos de conexión y funciones típicos
La mayoría de las API de básculas exponen los mismos cinco grupos de funciones: peso en vivo, estabilidad y estado, preajustes, registros, y comandos como cero, tara e imprimir.
La tabla siguiente es una ilustración genérica de cómo suele organizarse una API de este tipo. No es el esquema de ningún producto específico, incluidos los de WPL.
| Grupo de funciones | Solicitud ilustrativa | Devuelve o hace |
|---|---|---|
| Peso en vivo | GET /weight | Neto y tara actuales, unidad, marca de tiempo |
| Estado | GET /status | Indicador de estabilidad, indicador de cero, sobrecarga, resultado de verificadora |
| Preajustes | GET /presets, GET /presets/{id} | Lista y detalles de productos, objetivos, límites, tara |
| Preajuste activo | PUT /presets/active | Cargar un preajuste en la báscula |
| Editar preajuste | PUT /presets/{id} | Cambiar objetivo, límites o asignación de etiqueta |
| Último registro | GET /logs/last | Pesaje registrado más reciente |
| Todos los registros | GET /logs?since=… | Pesajes almacenados, filtrados y paginados |
| Comandos | POST /commands | Cero, tara, imprimir y acciones similares |
Dos principios hacen que una API así sea predecible. La lectura de datos usa métodos seguros que no cambian nada en la báscula; cambiar preajustes o emitir comandos usa métodos cuyo efecto está documentado. La semántica HTTP, incluidos qué métodos son seguros e idempotentes, se define en RFC 9110. Muchos proveedores describen sus API HTTP en el formato OpenAPI Specification, que permite generar código cliente y validar solicitudes.
Ejemplos de carga útil
Una respuesta de peso en vivo debe llevar el valor, su unidad, una marca de tiempo y el estado necesario para decidir si el valor puede usarse.
Solo un ejemplo ilustrativo, no el esquema real de la API de WPL:
{
"scale_id": "scale-03",
"timestamp": "2026-09-14T06:42:17.250Z",
"net": 5.120,
"tare": 0.450,
"unit": "kg",
"stable": true,
"zero": false,
"check": "ok",
"preset": "COD-GUT-5KG"
}
Los campos más importantes para la integración son stable y timestamp. Un programa que registra el peso de una caja solo debería aceptar una lectura marcada como estable, y debería comparar marcas de tiempo para detectar un valor obsoleto cuando la conexión se bloquea. Los pesos deberían ser números JSON con una unidad fija, no cadenas de texto con la unidad añadida, para poder sumarlos sin analizar texto (RFC 8259).
Un intercambio de comandos, de nuevo como ejemplo ilustrativo:
POST /commands
{ "command": "tare", "request_id": "7f3c-0192" }
200 OK
{ "request_id": "7f3c-0192", "result": "done", "tare": 0.450, "unit": "kg" }
El request_id permite al cliente hacer coincidir la respuesta con su solicitud y permite a la báscula reconocer un reintento de un comando que ya ha ejecutado, de modo que una respuesta perdida en un enlace deficiente no provoque una segunda tara.
Sondeo frente a envío
El sondeo (polling) significa que el cliente pide datos a la báscula a intervalos; el envío (push) significa que la báscula envía datos en cuanto algo cambia. El sondeo es más sencillo de construir; el envío es más eficiente para valores y eventos en vivo.
| Método | Cómo funciona | Bueno para | Inconvenientes |
|---|---|---|---|
| Sondeo (HTTP) | El cliente solicita /weight o /logs cada n segundos | Integraciones sencillas, recogida periódica de registros | Latencia de hasta un intervalo; muchas solicitudes para pantallas en vivo |
| WebSocket | Conexión bidireccional persistente; la báscula envía actualizaciones | Pantallas de peso en vivo, control interactivo | Gestión de conexión y lógica de reconexión; definido en RFC 6455 |
| Server-Sent Events | Flujo de eventos unidireccional sobre HTTP | Notificaciones de estado y de nuevos registros en navegadores | Solo del servidor al cliente; véase el estándar WHATWG HTML |
| MQTT | Publicación/suscripción a través de un intermediario, con garantías de entrega | Muchos dispositivos, enlaces intermitentes, buque a tierra | Requiere un intermediario; diseño de temas y carga útil; véase OASIS MQTT 5.0 |
El coste del sondeo es fácil de subestimar. Sondear el peso en vivo cinco veces por segundo produce 432 000 solicitudes al día por cliente. Para una pantalla en vivo eso es aceptable en una red local; a través de un enlace satelital no lo es. Un patrón práctico es usar envío o sondeo rápido a bordo para pantallas y control, y recoger registros terminados del histórico a intervalos para todo lo que sale del buque.
Valores en vivo frente a registros
Trate el peso en vivo como un valor de visualización y el histórico como el sistema de referencia. Si su software construye sus propios registros a partir de valores en vivo sondeados, puede omitir pesajes entre sondeos o registrar la misma caja dos veces. Leer los registros registrados del histórico de la báscula, con un ID de registro único, evita ambos problemas. Lo que deben contener esos registros se describe en Registro de datos de pesaje en el mar.
Comandos, seguridad y control de acceso
Los comandos remotos son potentes y deben restringirse: un cero o una tara enviados en el momento equivocado corrompen silenciosamente todos los pesajes siguientes.
- Compruebe el estado antes de actuar. Ponga a cero solo una báscula vacía y estable; tare solo con el contenedor en la plataforma y la lectura estable.
- Confirme el resultado. Lea el estado después de un comando en lugar de asumir que tuvo éxito.
- Haga que los reintentos sean inofensivos. Use identificadores de solicitud u operaciones idempotentes para que una solicitud repetida tenga el mismo efecto que una sola.
- Autentique y limite el acceso. Separe el acceso de lectura de los derechos de comando y de edición de preajustes; no exponga las básculas directamente a internet.
- Registre los comandos. El cero, la tara y los cambios de preajuste remotos deben figurar en el registro de auditoría con el cliente que los envió.
La OMI publica orientación sobre la gestión del riesgo cibernético en buques en sus directrices de gestión del riesgo cibernético marítimo.
Integración paso a paso
Una integración de báscula fiable sigue una secuencia fija, de la documentación a la prueba de campo.
- Obtenga la documentación de la API para el modelo exacto de báscula y la versión de software.
- Enumere los datos que necesita su software y relacione cada elemento con un campo de la API, incluidas unidades y decimales.
- Decida por cada flujo de datos si debe sondear, suscribirse o leer registros.
- Use identificadores de registro para hacer las importaciones idempotentes y detectar huecos.
- Gestione explícitamente lecturas inestables, sobrecarga, desconexión y tiempos de espera.
- Sincronice los relojes y almacene marcas de tiempo UTC.
- Pruebe a bordo con la red real, no solo en la oficina, incluida la pérdida de conexión a mitad de turno.
- Registre la versión de API utilizada, para poder comprobar cambios en una futura actualización de software.
El enfoque de WPL
WeightControl incluye una API integrada que devuelve datos en JSON. A través de ella, el software externo puede obtener el peso actual, el estado de la verificadora y la indicación de estabilidad, cargar y editar preajustes, leer el último registro del histórico y todos los registros almacenados, y emitir comandos como Cero, Imprimir y Tara. WeightControl se ejecuta en la propia báscula R10 o como aplicación externa que gestiona varias básculas. La documentación se incluye con cada modelo; para más detalles y actualizaciones, contacte con info@wpl-industries.com. El módulo IOT de WeightControl está disponible como opción en las series M2, M3, M5 y M6; véase el centro de integración de datos para la arquitectura más amplia.
Preguntas frecuentes
¿Es mejor una API de red que la salida RS232 de la báscula?
Para integraciones nuevas, normalmente sí. Un flujo RS232 continuo es sencillo y robusto, pero solo envía el valor mostrado en un formato de texto específico del fabricante. Una API de red añade JSON estructurado, acceso a preajustes y registros almacenados, y comandos bidireccionales. RS232 sigue siendo útil para pantallas sencillas, software heredado y dispositivos que no pueden unirse a una red.
¿Con qué frecuencia debería el software sondear el peso en vivo?
Para una pantalla local en vivo, unas pocas veces por segundo es habitual e inofensivo en una red local. Para todo lo que sale del buque, evite sondear el peso en vivo por completo: recoja registros terminados del histórico a intervalos, o use un mecanismo de envío. Sondear cinco veces por segundo produce 432 000 solicitudes al día por cliente.
¿Pueden dos programas usar la API de la báscula al mismo tiempo?
Leer datos desde varios clientes generalmente no es problema. Los comandos y los cambios de preajuste son el riesgo: dos programas emitiendo tara o cargando preajustes distintos entrarán en conflicto. Designe una aplicación como cliente de control, dé acceso de solo lectura a las demás, y registre qué cliente emitió cada comando. Compruebe la documentación sobre límites de conexiones simultáneas.
¿Qué debería ocurrir cuando se pierde la conexión de la API?
La báscula debería seguir pesando y registrando localmente. El cliente debería detectar la marca de tiempo obsoleta, mostrar que el valor no está en vivo, reconectar automáticamente y después leer del histórico los registros que se perdió, usando identificadores de registro para evitar duplicados. Los comandos enviados durante una interrupción no deberían reproducirse ciegamente después.
Fuentes
Escrito y revisado por los ingenieros de pesaje de WPL Industries. El contenido técnico y normativo se verifica con las fuentes citadas. Política editorial