JSON API para aplicaciones móviles y externas

Una integración no debe depender del marcado de una página web

Una plataforma empresarial deja de ser un sitio aislado cuando se conectan una aplicación móvil, el puesto de un conductor, un portal interno, un terminal o el servicio de un socio. Intentar utilizar páginas HTML crea pronto una dependencia frágil del diseño. El acceso directo a la base de datos es aún más peligroso: el cliente externo empieza a repetir reglas de negocio, omite controles de acceso y depende de la estructura interna de almacenamiento.

Sapphire I.C.D.S. ofrece un entorno de integración independiente para estas tareas: una JSON API sobre HTTPS. Recibe solicitudes estructuradas y devuelve respuestas procesables por máquinas, sin representar páginas para usuarios ni exigir que el cliente conozca la organización de la base de datos del servidor. El Roadmap público registra este entorno como base publicada para clientes nativos e integraciones empresariales.

JSON es el formato de intercambio, no toda la arquitectura

JSON por sí solo no hace fiable una integración. Importa quién define el comando disponible, cómo se valida al usuario y dónde se ejecuta la validación de negocio. En Sapphire I.C.D.S., la API del sistema gestiona la autenticación y los módulos publican los comandos de dominio mediante un contrato independiente. El cliente indica una acción y sus datos, pero el servidor selecciona el módulo responsable, comprueba la solicitud y forma el resultado.

Gracias a ello, la interfaz web, la aplicación móvil y un sistema externo pueden utilizar la misma lógica de dominio. Por ejemplo, la operación que registra el resultado de una entrega debe verificar ruta, tienda, mercancía y derechos del ejecutor de la misma forma, con independencia de la pantalla de origen. El cliente proporciona una interfaz cómoda; el módulo garantiza la corrección del proceso.

El servidor verifica la sesión y la identidad

La API admite el ciclo básico de una sesión de cliente: inicio de sesión, obtención del usuario confirmado actual, renovación del acceso y cierre de sesión. Tras un inicio correcto, el cliente recibe un token de acceso de corta duración y otro token de renovación. Al renovar se sustituye el par, por lo que la aplicación debe guardarlo de forma atómica y no repetir con el valor antiguo una operación ya completada.

El principio crítico es que los campos de usuario, grupo u objeto incluidos en JSON no demuestran ninguna facultad. El servidor extrae la identidad de la sesión validada y solo entonces determina el ámbito de datos accesible. Un módulo logístico, por ejemplo, no debe mostrar otra ruta porque el cliente haya enviado el identificador de otro conductor. La relación con el rol de negocio se resuelve en el servidor.

Los módulos publican únicamente acciones explícitas

La API específica no abre automáticamente todas las funciones de Sapphire I.C.D.S. El módulo debe ofrecer un proveedor de API y enumerar los comandos compatibles. Así se pueden publicar integraciones por etapas: primero lecturas seguras, después cambios reducidos y, tras la validación, procesos más complejos. Un módulo sin contrato externo no se vuelve accesible solo por estar instalado.

Los comandos que cambian el estado deben usar solicitudes previstas para modificaciones, mientras que la lectura puede permanecer como una operación separada. El servidor devuelve códigos claros para una solicitud incorrecta, una sesión caducada, una prohibición, un método inadecuado o la indisponibilidad temporal de una dependencia. La aplicación cliente recibe una rama definida de tratamiento, no una página HTML de error.

• El cliente móvil envía solo los datos necesarios y almacena los tokens en el almacenamiento protegido del dispositivo.
• El entorno API valida la sesión, el método de solicitud y el tamaño de entrada permitido.
• El módulo comprueba las reglas de dominio, el ámbito del usuario y la transición de estado permitida.
• La base de datos permanece detrás de la capa del servidor y nunca se publica directamente al cliente.

Escenarios de negocio adecuados

La JSON API resulta especialmente útil cuando el empleado trabaja fuera del back-office principal. En logística puede ofrecer la lista de rutas asignadas, los datos de un punto y el registro de cantidades entregadas, devoluciones o estados documentales. En contabilidad puede proporcionar un catálogo y aceptar una operación confirmada. En una aplicación externa permite leer un estado autorizado y ejecutar un comando concreto sin imitar acciones del navegador.

El Roadmap público menciona logística, contabilidad y trabajo de campo como ámbitos naturales de evolución. Esto no significa que ya exista un endpoint universal para cada caso. La disponibilidad depende de los comandos API del módulo instalado. Antes de iniciar una integración se debe preparar una matriz de operaciones, datos, roles y versiones.

La JSON API no es el MCP externo

Ambos entornos utilizan datos estructurados, pero atienden a clases de clientes diferentes. La JSON API está destinada a aplicaciones móviles y empresariales con un proceso de usuario diseñado de antemano. El MCP externo, que permanece en developer alpha y solo se ha verificado con la integración actual de ChatGPT en sapphire-project.com, está destinado a clientes de AI compatibles que descubren herramientas y las invocan en una sesión de agente. Sus permisos y reglas de publicación no son intercambiables.

La API tampoco es una consola SQL remota, un generador arbitrario de informes ni una promesa de acceso a todas las tablas. Proporciona comandos de negocio bajo la responsabilidad de un módulo. Este nivel de abstracción resiste mejor los cambios del esquema de datos y es más seguro para un mantenimiento prolongado.

Qué se exige a la aplicación cliente

Un cliente nativo debe gestionar correctamente la caducidad del token de acceso, la sustitución del token de renovación, el cierre de sesión, la falta de red y los reintentos. En las operaciones que modifican estado es especialmente importante distinguir entre una denegación confirmada y un resultado de transporte incierto: sin una idempotencia acordada no se puede repetir automáticamente una acción que quizá se ejecutó. La caché local no debe considerarse fuente de permisos actuales.

El equipo técnico también define el versionado de contratos, los registros, los límites de solicitudes y la estrategia de compatibilidad. La plataforma aporta un entorno modular común, pero la calidad de un producto móvil concreto depende de la disciplina del cliente y de la integridad del contrato de negocio publicado.

Camino de adopción

El trabajo debe comenzar con un inventario de escenarios de usuario, no con una lista de tablas. Para cada paso se definen los campos de entrada, la respuesta, el rol, el ámbito de datos, las transiciones admisibles y el comportamiento ante repeticiones. Después, el módulo publica el conjunto mínimo de comandos, el equipo móvil construye la interfaz y las pruebas conjuntas comprueban casos permitidos y prohibidos.

Para el propietario, el resultado es la capacidad de desarrollar aplicaciones propias sin copiar la lógica del servidor. Para la dirección técnica, supone una frontera de integración gobernada, con autenticación común y comandos modulares. La JSON API extiende Sapphire I.C.D.S. más allá de la interfaz web, pero mantiene los datos, los derechos y las reglas del proceso dentro del entorno autoritativo del servidor.