Órdenes y Sincronización

Consulte, gestione e importe las órdenes recibidas desde MercadoLibre y monitoree el historial de sincronizaciones de stock y precios.

Requisitos previos

• Cuenta de MercadoLibre conectada con la opción Sincronización activa habilitada.
• Permiso marketplace.ver en ALTUM ERP.

Pantalla de Órdenes Marketplace

Navegue a Marketplace → Órdenes para ver la lista de órdenes importadas desde MercadoLibre.

La tabla muestra las siguientes columnas:

Columna	Descripción
ID MercadoLibre	Identificador original de la orden en MercadoLibre (meliOrderId).
Comprador	Nombre o nickname del comprador en MercadoLibre.
Total	Monto total de la orden con la moneda de la transacción.
Artículos	Número de líneas en la orden (itemCount).
Estado	PENDING, IMPORTED, CANCELLED, ERROR o ATTENTION.
Fecha de importación	Fecha y hora en que ALTUM ERP procesó la orden.

Importación automática de órdenes

El sistema consulta la API de MercadoLibre en el intervalo configurado en Marketplace → Configuración (orderPollIntervalMinutes). Por cada orden nueva encontrada:

1. Verifica si la orden ya fue importada (idempotencia por meliOrderId).
2. Intenta asociar al comprador con un cliente existente en ALTUM ERP usando el ID de comprador de MercadoLibre o el correo electrónico.
3. Si no existe el cliente, crea automáticamente un cliente invitado con los datos del comprador y el RFC genérico XAXX010101000 (público en general).
4. Verifica si cada artículo de la orden tiene un mapeo de producto en ALTUM ERP.
5. Si todos los artículos están mapeados, la orden se importa con estado IMPORTED. Si algún artículo no tiene mapeo, el estado es ATTENTION.

Estados de una orden

Estado	Significado
PENDING	La orden fue recibida pero aún no se ha procesado.
IMPORTED	La orden se importó exitosamente y todos sus artículos tienen mapeo.
CANCELLED	La orden fue cancelada en MercadoLibre.
ERROR	Ocurrió un error al procesar la orden. El campo errorMessage contiene el detalle.
ATTENTION	La orden se importó pero uno o más artículos no tienen mapeo de producto en ALTUM ERP. Requiere revisión manual.

Revisar una orden con estado ATTENTION

Las órdenes con estado ATTENTION incluyen en el campo attentionReason la lista de IDs de artículos de MercadoLibre que no tienen mapeo. Para resolver:

1. Abra el detalle de la orden haciendo clic en la fila de la tabla.
2. Identifique los artículos sin mapeo listados en la sección de detalles.
3. Navegue a Marketplace → Productos y cree el mapeo para cada artículo faltante.
4. La próxima sincronización actualizará el estado de la orden.

Tipos de sincronización

El sistema realiza tres tipos de operaciones de sincronización, registradas en el historial:

Tipo	Dirección	Descripción
STOCK_PUSH	ALTUM → MeLi	Envía existencias y precios actualizados a todas las publicaciones mapeadas con estado SYNCED o PENDING.
ORDER_PULL	MeLi → ALTUM	Consulta y descarga órdenes nuevas desde la última sincronización exitosa.
FULL_SYNC	Ambas	Ejecuta primero el STOCK_PUSH y luego el ORDER_PULL en un solo proceso.

Historial de sincronización

Cada ejecución de sincronización genera un registro (MarketplaceSyncLog) con la siguiente información:

Campo	Descripción
Tipo	STOCK_PUSH, ORDER_PULL o FULL_SYNC.
Estado	RUNNING, COMPLETED, PARTIAL o FAILED.
Procesados	Total de elementos procesados en la ejecución.
Exitosos	Elementos procesados sin error.
Fallidos	Elementos que no pudieron sincronizarse.
Duración	Tiempo total de la ejecución en milisegundos.
Iniciado por	SYSTEM para ejecuciones automáticas o el ID del usuario que inició la sincronización manual.

El estado PARTIAL indica que algunos elementos fallaron pero el proceso continuó. El campo errorDetails contiene la lista de mensajes de error individuales.

Mecanismo de reintentos

Si una sincronización falla, el sistema reintenta automáticamente con retardo exponencial:

Intento	Espera antes del reintento
1	1 segundo
2	5 segundos
3	15 segundos
4	60 segundos
5	300 segundos (5 minutos)

Tras 6 intentos fallidos consecutivos, la sincronización se marca como FAILED y se emite una notificación al administrador del sistema.

Reglas y validaciones

• Las órdenes ya importadas no se duplican; la verificación de idempotencia usa el meliOrderId.
• El campo lastOrderSyncAt del tenant se actualiza tras cada ORDER_PULL exitoso para que la próxima consulta no descargue órdenes ya procesadas.
• Los clientes invitados creados automáticamente usan el RFC XAXX010101000 y el régimen fiscal 616 (Sin obligaciones fiscales), conforme al SAT para operaciones con público en general.
• La dirección de envío de la orden, si está disponible en MercadoLibre, se almacena en el campo shippingAddress de la orden importada.

Casos frecuentes

No aparecen órdenes nuevas a pesar de tener ventas en MercadoLibre. Verifique que la opción Sincronización activa esté habilitada en Marketplace → Configuración y que el intervalo de consulta de órdenes sea mayor que cero.

Una orden aparece en estado ERROR. Revise el campo errorMessage en el detalle de la orden. Si el error es transitorio (problema de red), desaparecerá en la siguiente sincronización. Si el error persiste, contacte a soporte técnico con el ID de la orden.

Se crearon clientes duplicados. El sistema intenta emparejar compradores usando primero el ID de comprador de MercadoLibre y, como segunda opción, el correo electrónico. Si el comprador no tiene correo en su cuenta de MercadoLibre y es la primera compra, se crea un cliente invitado. Puede fusionar clientes duplicados desde el módulo Clientes.