Instructivo de JZ Middle

1. Qué hace

JZ Middle conecta las tiendas online de la organización con Tracker360, que sigue siendo el dueño del stock:

• Ventas → pedidos: cada venta pagada entra a Tracker como un pedido para preparar, con su etiqueta de envío cuando la tienda la da.
• Stock → tienda: cuando cambia el stock en Tracker, el middleware actualiza las publicaciones que tienen el mismo SKU.
• Publicaciones: le informa a Tracker qué publicaciones se sincronizan y cuáles tienen problemas (sin SKU, SKU que no está en Tracker, Full).

Se instala uno por cliente, en el mismo servidor que su Tracker. Hoy funciona completo con Mercado Libre; las demás tiendas ya se pueden configurar y sus conectores están en desarrollo.

2. Instalación

El instalador deja el middleware escuchando por http en el puerto 8040 del servidor. Para Mercado Libre hace falta además un subdominio público con HTTPS que llegue a ese puerto (por ejemplo middle.cliente.com): se le pasa al instalador con JZM_DOMAIN.

Con Docker (recomendado)

1. Instalar primero Tracker360 con Docker en el mismo servidor (así el middleware se une a su red).
2. El repositorio es privado: el servidor necesita su clave de despliegue de GitHub (la da JZ Tech Solutions al instalar).
3. Clonar y correr el instalador:
   sudo git clone git@github.com:Jonnyonz/JZMiddle.git /opt/jztech/jzmiddle
cd /opt/jztech/jzmiddle
sudo JZM_DOMAIN=middle.cliente.com ./install.sh
4. Al terminar muestra el token de configuración inicial, la dirección y el puerto donde quedó escuchando, y la dirección de Tracker para cargar en la página.

Sin Docker

sudo JZM_DOMAIN=middle.cliente.com ./install-native.sh (Debian 12/13, Ubuntu 24.04). Queda como servicio del sistema jzmiddle, escuchando en el puerto 8040, con su base en el PostgreSQL del servidor.

3. Primer ingreso

1. Entrar a https://middle.cliente.com.
2. La página pide el token de instalación, un usuario y una contraseña (mínimo 10 caracteres). El token sirve una sola vez.
3. Si no quedó a mano: con Docker está en el .env de la carpeta de la instalación (sudo grep '^SETUP_TOKEN=' .env); sin Docker, en /etc/jzmiddle/jzmiddle.env.

4. Conexión con Tracker360

En la sección Conexión con Tracker360 del panel se carga la dirección de Tracker (vale para todas las tiendas) y la clave del canal de Mercado Libre. Cada una de las demás tiendas carga la clave de su propio canal en su módulo de la barra lateral.

Qué dirección usar

• Tracker en el mismo servidor, con Docker: http://tracker360_api:8000 (red interna de Docker; la muestra el instalador). No sale del servidor ni depende del certificado ni del DNS.
• Tracker en el mismo servidor, sin Docker: http://127.0.0.1:<puerto de Tracker>.
• Tracker en otro servidor: su dirección pública con HTTPS (https://wms.cliente.com).

Crear el canal en Tracker

1. En Tracker: Configuración, Tiendas online: activar la tienda.
2. Configuración, Canales de venta, + Nuevo canal: código (por ejemplo ML-EMPRESA), nombre, tienda, stock que se informa: disponible menos lo comprometido (obligatorio: con "disponible" lo vendido y todavía no despachado se volvería a publicar, y la prueba de conexión lo rechaza) y sucursales.
3. Copiar la clave (empieza con tch_): se muestra una sola vez. Si se pierde, en Ver canales se rota.
4. Cargarla en el middleware y tocar Probar conexión. Si el canal es de otra tienda, el middleware lo avisa.

5. Tiendas

La barra lateral del panel tiene un módulo por tienda, con su logo. En cada uno: el interruptor Trabajo con …, los pasos para conectarla, sus datos y su canal de Tracker. Solo las tiendas activadas cuentan en el estado de la configuración.

Crear la aplicación

En developers.mercadolibre.com.ar, con la cuenta vendedora (el titular tiene que tener los datos validados), Mis aplicaciones, Crear nueva aplicación:

Desde el 30/08/2026 la aplicación tiene que ser solo de Mercado Libre, sin permisos de Mercado Pago: si no, pierde el acceso a la API.

Copiar el Client ID (App ID) y la Secret Key en la sección Aplicación de Mercado Libre del panel y guardar.

Conectar las cuentas

1. En Cuentas de Mercado Libre, tocar Conectar cuenta y autorizar en Mercado Libre.
2. Mercado Libre autoriza la cuenta que tenga la sesión abierta en ese navegador: para conectar otra, cerrar la sesión antes o usar una ventana privada.
3. La cuenta tiene que quedar conectada. Probar confirma que responde; Desconectar la deja de sincronizar.

Antes de conectar una cuenta real: el middleware empieza a mandar el stock de Tracker a las publicaciones con el mismo SKU. Si en Tracker un artículo tiene 0, en Mercado Libre queda en 0 y la publicación se pausa. Ver Stock.

7. Ventas y pedidos

• Se cargan las ventas creadas desde que se conectó la cuenta (las anteriores no).
• Una venta entra cuando está pagada (también si tuvo un reembolso parcial). Un carrito (varias órdenes del mismo comprador) entra como un solo pedido.
• El pedido lleva el comprador, la dirección, el tipo de envío y los artículos por SKU. Las ventas Flex entran como urgentes.
• Full: el stock está en el depósito de Mercado Libre: el pedido queda solo informativo en Tracker.
• Cancelaciones: si se cancela en Mercado Libre, se cancela en Tracker (si ya se despachó, queda como error para revisar). Si en un carrito se cancela una orden y el resto sigue, en Tracker se cancelan solo sus artículos.
• Etiqueta: cuando el envío está listo para despachar, la etiqueta (ZPL) se manda a Tracker para imprimirla al empacar. Si Mercado Libre todavía no la da (por ejemplo, falta la factura), se reintenta sola; y si se perdió el aviso del envío, el repaso la vuelve a buscar. Los envíos sin etiqueta de Mercado Libre (Mercado Envíos 1, acordar con el vendedor) no la piden: se avisa una vez en Alertas para despacharlos por fuera.
• Además de los avisos, cada 10 minutos se repasan las ventas recientes por si algún aviso se perdió.

8. Stock

• Se actualizan las publicaciones activas (y las pausadas por falta de stock) cuyo SKU (atributo SKU o código del vendedor) esté en Tracker.
• La cantidad es la que Tracker informa para el canal (disponible menos lo comprometido en pedidos abiertos, de las sucursales del canal) menos las ventas de Mercado Libre que todavía no están en Tracker (esperando el pago, o pagadas que no se pudieron cargar: un SKU que falta, Tracker sin responder). Así una unidad vendida no se vuelve a publicar.
• Si el canal de Tracker está en modo "disponible" no se manda stock y queda una alerta.
• No se tocan: las publicaciones sin SKU, las de SKU que no está en Tracker, las Full y las pausadas a mano.
• En la sección Stock en Mercado Libre del panel se ve cuántas se sincronizan y la lista de las que tienen problemas. Repasar todo ahora fuerza un repaso completo (también se hace cada hora).

9. Avisos, errores y alertas

Mercado Libre avisa cada venta, cambio de envío o de publicación. El middleware los consulta y los procesa en orden (sección Avisos de Mercado Libre).

• Si Mercado Libre o Tracker no responden un momento, se reintenta solo (hasta una hora).
• Los que quedan con error se reintentan solos cada 30 minutos durante 7 días, o a mano con Reintentar los que fallaron.
• Si una cuenta pierde la autorización (cambio de contraseña, permiso revocado), queda para reconectar: volver a tocar Conectar cuenta con esa cuenta.
• Con Mercado Libre apagada en su módulo (Trabajo con Mercado Libre), no se procesan avisos, no se repasan ventas ni se manda stock. Al volver a activarla, el repaso trae lo que se vendió mientras tanto y se concilia el stock.

Alertas y avisos por mail

En el módulo General, Alertas muestra lo que hay que mirar: ventas con error, errores que ya no se reintentan (más de 7 días), una cuenta para reconectar, avisos atrasados en la cola, Tracker sin responder, Mercado Libre sin mandar avisos, el canal de Tracker sin el modo de stock correcto y envíos sin etiqueta de Mercado Libre.

1. En Avisos por mail, cargar el servidor de correo (SMTP), el puerto, la seguridad (STARTTLS en 587 o SSL en 465), el usuario, la clave y los destinatarios. Con Gmail: smtp.gmail.com, 587, STARTTLS y una contraseña de aplicación de la cuenta.
2. Tocar Enviar prueba: si el servidor rechaza algo, el panel dice qué (usuario o clave, conexión, destinatarios).
3. Opcional: ajustar cuándo avisar (cola atrasada, Tracker sin responder, sin avisos de Mercado Libre) y cada cuántas horas se repite la misma alerta.

Las alertas nuevas llegan juntas en un solo mail. La misma alerta no se repite antes de esas horas, salvo que aparezca algo nuevo (otra venta con error). La clave del correo no se muestra nunca.

Conector en desarrollo: los datos se guardan y se usan cuando esté listo.

1. En el administrador de Tiendanube, menú lateral Aplicaciones a medida, Crear aplicación a medida (no hace falta ser socio de Tiendanube).
2. En Identificación, ponerle un nombre.
3. En Perfiles de acceso: Pedidos, lectura; Productos/stock, escritura. No hace falta Acceso total.
4. Guardar, abrir la aplicación y tocar Revelar. Copiar el token con Copiar token: se ve una sola vez (si se pierde, se revoca y se crea otro).
5. En el middleware, módulo Tiendanube: activar, cargar el ID de tienda y el token de acceso, y la clave de su canal de Tracker.

Los avisos de ventas los registra el middleware solo: no hay que pegar ninguna dirección en Tiendanube.

Conector en desarrollo: los datos se guardan y se usan cuando esté listo.

1. En WordPress, Ajustes, Enlaces permanentes: cualquier opción menos Simple (con Simple la API no funciona).
2. En WooCommerce, Ajustes, Avanzado, API REST: Añadir clave.
3. Descripción libre, usuario administrador y permisos Lectura/Escritura. Generar la clave.
4. Copiar la Consumer key (ck_…) y el Consumer secret (cs_…, se ve una sola vez).
5. En el middleware, módulo WooCommerce: activar, cargar la dirección de la tienda (https://…), las dos claves y la clave de su canal de Tracker.

La tienda tiene que tener HTTPS. Los nombres de los menús pueden variar un poco según la versión y el idioma de WordPress.

Conector en desarrollo: los datos se guardan y se usan cuando esté listo.

1. En el admin de Shopify: Configuración, Apps, Desarrollar apps, y Crear apps en Dev Dashboard (desde 2026 las apps propias se crean ahí).
2. Crear app y ponerle un nombre.
3. En la versión de la app: como URL de la app, la dirección del middleware; en Acceso, los permisos read_orders, read_products, read_inventory, write_inventory y read_locations.
4. Publicar la versión y, en Instalaciones, Instalar app en la tienda.
5. Copiar el Client ID y el Client secret de la app.
6. En el middleware, módulo Shopify: activar, cargar el dominio tienda.myshopify.com, las dos claves y la clave de su canal de Tracker.

La app y la tienda tienen que ser de la misma organización de Shopify. La crea el dueño o alguien del equipo con permiso para desarrollar apps.

Conector en desarrollo: los datos se guardan y se usan cuando esté listo.

1. En el back office, Parámetros avanzados, Webservice: activar el webservice y guardar.
2. Añadir nueva clave de webservice y tocar Generar.
3. Descripción, estado activo y permisos: orders, order_details, order_histories, order_states, products y combinations con GET; stock_availables con GET y PUT.
4. Si es multitienda, asociar la clave a la tienda. Guardar.
5. En el middleware, módulo PrestaShop: activar, cargar la dirección de la tienda, la clave (32 caracteres), el ID de tienda si es multitienda y la clave de su canal de Tracker.

PrestaShop no avisa las ventas por su cuenta: el middleware las va a repasar cada pocos minutos. Necesita URL amigables (mod_rewrite) activadas.

Empretienda no tiene una API pública para sistemas externos, así que no se puede conectar en forma automática. La conexión va a ser por archivo (en desarrollo):

• Ventas: en Empretienda, Gestión de ventas, Listado de ventas, Exportar; el middleware va a leer ese archivo y cargar los pedidos en Tracker.
• Stock: el middleware va a armar la planilla con el stock de Tracker para subirla en Productos, Importación de productos.

15. Actualizar

• Con Docker: en la carpeta de la instalación, sudo ./install.sh. Trae la versión nueva, respalda la base en backups/ y vuelve a levantar. Recuerda el subdominio.
• Sin Docker: sudo jz-middle-actualizar (respalda la base y, si la versión nueva no responde, vuelve sola a la anterior). --volver vuelve a la versión anterior a mano.
• La sección Estado del servicio del panel avisa si hay una versión nueva.

16. Problemas frecuentes

17. Soporte

JZ Tech Solutions: jonaiker.jimenez.g@gmail.com · jz-tech.mywire.org

Conviene contar qué se quería hacer, qué pasó y adjuntar una captura. Nunca mandar contraseñas ni claves de canal o de las tiendas.