Ayuda: conectar cuentas de Mercado Libre
Manual completo del plugin MercadoLibre Importer. Esta ayuda está pensada para usuarios técnicos y no técnicos. Describe en detalle qué hace cada pantalla, cada botón y cada configuración del plugin.
Qué hace el plugin
El plugin importa publicaciones de Mercado Libre a WooCommerce, soporta múltiples cuentas/token, detecta cambios en productos existentes, permite revisión campo a campo (staging), administra duplicados y trae herramientas de mantenimiento operativo.
Mapa de pantallas
- Importar MercadoLibre: ejecución de importación y seguimiento de progreso/logs.
- Configuración: tokens, reglas de importación, revisión, deduplicación y reemplazos de texto.
- Revisión de Cambios: aplicar/descartar cambios detectados para productos existentes.
- Fusionar duplicados: resolución de grupos duplicados por clave canónica.
- Troubleshooting: utilidades de diagnóstico, limpieza y recálculo.
- Ayuda: guía integral (esta página) y utilidades OAuth.
Flujo recomendado para usar el plugin
- Configurar app de Mercado Libre y credenciales OAuth.
- Cargar tokens en Configuración y elegir cuenta principal.
- Definir reglas de importación/revisión según tu negocio.
- Ejecutar importación desde la pantalla Importar.
- Revisar y aplicar cambios pendientes en Revisión de Cambios.
- Resolver duplicados desde Fusionar duplicados cuando aparezcan.
- Usar Troubleshooting para mantenimiento y control.
Pantalla: Importar Productos desde MercadoLibre
Esta pantalla gestiona toda la corrida de importación (obtener IDs + procesar productos) y muestra logs en tiempo real.
Controles y botones (detalle completo)
| Control | Ubicación | Qué hace | Cuándo usarlo |
|---|---|---|---|
Seleccionar Client Token (#ml_selected_token) |
Arriba, dentro del formulario principal | Selecciona la cuenta/token con la que se consultará la API de Mercado Libre para esta corrida. | Siempre antes de iniciar una importación nueva. |
Iniciar Nueva Importación / Continuar Importación (#start-import) |
Botón principal de acción | Según estado detectado, inicia una corrida nueva o reanuda una cola pendiente. | Usar "Continuar" si quedó pendiente; usar "Nueva" para limpiar cola/log y arrancar desde cero. |
Iniciar Nueva Importación secundario (#new-import) |
Al lado del botón principal (se muestra cuando hay pendiente) | Fuerza reinicio completo: limpia cola de IDs y logs del importador para empezar de cero. | Cuando querés descartar la cola pendiente actual. |
Barra de progreso (#progress-bar) y contador (#processed-count/#total-count) |
Debajo de acciones | Muestra avance en 2 etapas: obtención de IDs y procesamiento. | Monitoreo durante toda la corrida. |
Log de Importación (#log-messages) |
Panel de logs | Renderiza mensajes de backend y mensajes de frontend (reintentos, fallback, errores). | Diagnóstico operativo y seguimiento detallado. |
Abrir revisión (#ml-staging-review-link) |
Panel "Revisión de cambios pendientes" | Abre la pantalla de Revisión de Cambios cuando hay pendientes en staging. | Después de importar, para aprobar/descartar cambios detectados. |
Comportamiento interno de importación
- Etapa 1: obtiene IDs desde ML y los encola en base de datos.
- Etapa 2: procesa la cola por lotes según
ml_import_batch_size. - Resiliencia: reintentos automáticos ante errores AJAX/servidor.
- Si falla el sync del lote, hace fallback por producto para ese lote.
- IDs con fallos repetidos se descartan para no bloquear la cola completa.
Pantalla: Configuración de MercadoLibre
Esta pantalla concentra todas las opciones del plugin y ahora está dividida en pestañas para reducir scroll y agrupar mejor los controles. A continuación se detalla cada sección, cada campo y cada botón.
Pestañas principales
- Cuentas: tokens activos, cuenta principal y aprobaciones pendientes.
- Importación: reglas operativas del importador y deduplicación.
- Categorías: fallback, árbol canónico y equivalencias ML→Woo.
- Revisión: comportamiento de la pantalla ml-import-review.
- Texto: reglas de reemplazo pre-importación.
Sección: Tokens de Cliente
| Campo/Botón | Nombre técnico | Descripción exacta | Validación/Notas |
|---|---|---|---|
| Nombre | ml_client_tokens[*][name] | Identificador interno de la cuenta/token. | Obligatorio por fila. |
| Access Token | ml_client_tokens[*][token] | Token OAuth activo para consultar API. | Obligatorio por fila. |
| Refresh Token | ml_client_tokens[*][refresh_token] | Se usa para renovar access token. | Opcional, pero recomendado. |
| Client ID | ml_client_tokens[*][client_id] | ID de app ML asociada. | Opcional, necesario para refresh automático. |
| Client Secret | ml_client_tokens[*][client_secret] | Secreto de app ML asociada. | Opcional, necesario para refresh automático. |
| % Recargo | ml_client_tokens[*][surcharge_percent] | Recargo para productos nuevos o sin precio previo. | Acepta números positivos/negativos decimales. Si queda en blanco, no aplica recargo. |
| Eliminar fila | botón 🗑️ | Quita la fila de token en el formulario. | Se aplica al guardar. |
| Agregar Token | #add-token | Agrega una fila nueva de token al formulario. | Recordá completar campos obligatorios. |
Sección: Cuenta principal
Control ml_primary_token. Define preferencia por defecto para conflictos de deduplicación/fusión y reglas de cuentas no principales.
Tambien define la regla de precio en sincronizacion: si el producto ya tiene precio en WooCommerce y entra desde la cuenta principal, el plugin conserva el mayor entre el precio actual de Woo y el precio importado desde Mercado Libre con recargo aplicado si corresponde.
Sección: Tokens Pendientes de Aprobación
| Botón | Acción | Efecto |
|---|---|---|
| Agregar token | Aprobar solicitud pendiente | Mueve credenciales pendientes a lista activa de tokens. |
| Rechazar | Descartar solicitud | Elimina la solicitud pendiente sin activar token. |
Sección: Configuración de importación
| Campo | Nombre técnico | Qué controla |
|---|---|---|
| Categorías a ignorar | ml_ignore_categories | Filtra por palabras clave en nombres de categoría ML. |
| Auto-mapear similares (botón) | #ml-auto-map-categories | Propone equivalencias ML->Woo por similitud de rutas; evita duplicar ML ya mapeadas y reaprovecha reglas existentes. |
| Omitir campos en comparación de duplicados | ml_dedup_ignore_attribute_ids[] + custom | Excluye atributos de la construcción de _ml_dedup_key. |
| Establecer stock en 1 si es 0 | ml_set_stock_one | Si ML reporta 0, fuerza stock 1. |
| Extender tiempo de ejecución a 5 minutos | ml_extend_execution_time | Intenta aumentar max_execution_time en procesamiento. |
| Enviar a papelera productos sin publicación activa | ml_trash_inactive_products | Mueve a papelera productos cuyo estado ML no está activo. |
| Ignorar productos ya en papelera | ml_ignore_products_in_trash | Si el match está en trash, no crea un duplicado nuevo. |
| Importar solo publicaciones activas | ml_import_only_active_products | Solo sincroniza publicaciones con estado ML active. |
| Eliminar adjuntos desasignados | ml_delete_unselected_attachments | Borra adjuntos huérfanos al actualizar imágenes. |
| Staging estricto | ml_strict_staging | Todo pasa por revisión manual antes de aplicar. |
| Permitir pedidos pendientes | ml_allow_backorders | Configura política WooCommerce de backorders. |
| Habilitar stock mínimo + cantidad | ml_set_low_stock, ml_low_stock_value | Activa y define umbral de low stock. |
| Productos por lote | ml_import_batch_size | Tamaño de lote del procesamiento. |
| Retraso entre lotes (ms) | ml_import_delay | Espera entre lotes para aliviar carga. |
Sección: Configuración de ml-import-review
| Campo | Nombre técnico | Qué controla |
|---|---|---|
| Artículos por página | ml_review_page_size | Paginación de la revisión. |
| Selección por defecto de imágenes | ml_review_image_default_selection | Marca imágenes actuales/nuevas/todas/ninguna por defecto. |
| Omitir campos para cuentas no principales | ml_review_ignore_fields_non_primary[] | Para tokens no principales, conserva esos campos actuales y no los expone como cambio revisable. El precio ya no entra en staging por defecto, asi que su comportamiento real se resuelve en la sincronizacion del producto. |
Reglas de precio
- El precio no se compara en la pantalla de revision y no genera pendientes de staging por si solo.
- Si WooCommerce no tiene precio y Mercado Libre si, se toma el precio de Mercado Libre con el recargo configurado para esa cuenta, si existe.
- Si la importacion viene de la cuenta principal y el producto ya tiene precio en WooCommerce, se conserva el mayor entre Woo y Mercado Libre ajustado.
- Si la importacion viene de una cuenta no principal y el producto ya existia, se conserva el precio actual de WooCommerce.
- Si la importacion viene de una cuenta no principal y el producto es nuevo, se usa el precio de Mercado Libre con el recargo configurado para esa cuenta.
Sección: Reglas de Reemplazo de Texto (pre-importación)
| Control | Función |
|---|---|
| Buscar | Texto original que se reemplaza. |
| Reemplazar por | Texto resultante. |
| Campo | Ámbito de la regla: todos / título / descripción / descripción corta. |
| Eliminar | Quita regla de la tabla antes de guardar. |
| Agregar regla | Agrega una nueva fila de regla. |
| Guardar Configuración | Persiste todos los cambios de la pantalla. |
Pantalla: Revisión de Cambios Importados (ml-import-review)
Esta pantalla gestiona staging: cambios detectados en productos existentes antes de aplicarlos definitivamente.
El precio no forma parte de esta comparacion. Aunque un producto cambie de precio en Mercado Libre, ese cambio no aparece como decision manual en revision; el valor final se define al sincronizar segun las reglas de la cuenta origen.
Barra de acciones superior
| Control | Qué hace |
|---|---|
Filtro por token (#ml-review-token-filter) | Muestra solo pendientes del token origen seleccionado. |
Buscar texto (#ml-review-search) | Busca por ML ID, WC ID o texto libre. |
| Actualizar listado | Refresca consulta y renderizado actual. |
| Aplicar seleccionados | Aplica al catálogo WooCommerce los cambios elegidos por campo para filas tildadas. |
| Descartar seleccionados | Elimina pendientes seleccionados sin aplicar cambios. |
Paginación y navegación
- Anterior y Siguiente: cambia de página.
- Ir a página + botón Ir: salto directo.
- Resumen (
#ml-review-summary): estado de consulta/resultados.
Tabla de resultados
- Checkbox superior
#ml-review-select-all: selecciona/deselecciona filas visibles. - Cada fila muestra WC ID, ML ID, título, origen y fecha.
- Dentro de "Campos con cambios" se renderizan bloques por campo.
Decisión por campo (dentro de cada fila)
- Radio Nuevo: aplica valor entrante.
- Radio Actual: conserva valor actual del producto.
- Textareas editables: permiten ajustar texto antes de aplicar.
- Imágenes: checkboxes por imagen para selección manual.
- Click en miniatura: abre modal de imagen ampliada; botón × cierra modal.
Progreso de aplicación/descartado
Al aplicar o descartar, muestra barra de progreso y avance en lotes según tamaño de lote configurado.
Pantalla: Fusionar Productos Duplicados
Modo listado de grupos
- Tabla de grupos por
dedup_key. - Botón Revisar fusión: abre detalle del grupo.
Modo detalle de un grupo
| Bloque | Control | Función |
|---|---|---|
| 1) Producto ganador | winner_id (select) | Define producto que se conservará. |
| 2) Productos a fusionar | checkboxes merge_ids[] | Define productos que se enviarán a papelera tras fusión. |
| 3) Campo por campo | radios field_source[field] | Elige de qué producto tomar cada campo (título, descripciones, precio, stock). |
| Acción principal | Fusionar seleccionados | Ejecuta fusión en lotes vía AJAX. |
| Acción secundaria | Volver al listado | Regresa a la tabla de grupos. |
Progreso de fusión
Muestra barra y resumen final con cantidad fusionada/fallida. Si termina bien, recarga la página para actualizar estado.
Pantalla: Troubleshooting MercadoLibre Importer
Bloques de búsqueda/diagnóstico
| Bloque | Controles | Qué hace |
|---|---|---|
| 1) Variaciones duplicadas | Buscar duplicados | Encuentra productos variables con combinaciones repetidas más de 2 veces. |
| 2) Estado de importación | Modo, Fecha límite, Buscar por estado de importación | Lista nunca importados o importados antes de fecha según modo. |
| 3) Papelera | Buscar en papelera | Lista productos en papelera para limpieza. |
| 4) Duplicados canónicos | Buscar duplicados de producto, Recalcular dedup keys | Detecta grupos por _ml_dedup_key y permite recalcular claves existentes. |
| 5) Medios huérfanos | Máximo a escanear, Buscar medios huérfanos | Detecta adjuntos sin referencias activas. |
| 6) Envío y dimensiones | Actualizar envío y dimensiones | Completa faltantes desde el term_meta de la categoría Woo más específica. |
Bloque de resultados y acciones masivas
| Control | Función |
|---|---|
Seleccionar todos | Marca/desmarca todas las filas visibles. |
| Enviar seleccionados a papelera | Mueve productos seleccionados a papelera. |
| Eliminar definitivamente seleccionados | Borra productos seleccionados de forma permanente. |
| Eliminar medios huérfanos seleccionados | Borra adjuntos seleccionados sin referencias. |
| Barra de progreso | Muestra avance de operaciones por lotes. |
Estado de procesamiento
- Mientras una acción de troubleshooting está corriendo, los botones conflictivos quedan deshabilitados para evitar dobles ejecuciones.
- Las búsquedas simples muestran una barra de progreso como indicador visual de proceso en curso y las acciones por lotes muestran el avance real.
- El botón Cancelar aborta la petición AJAX activa o detiene el siguiente lote pendiente de una acción masiva.
Resultado de deduplicación canónica
Cuando buscás duplicados por dedup key, aparece botón Abrir pantalla de fusión para saltar directo a resolución del grupo.
OAuth y creación de app en Mercado Libre
Esta sección explica el acceso API y provee utilidades prácticas para generar URL de autorización, PKCE, probar token y enviar credenciales para revisión.
Paso 1: crear app en Developers
- Abrir https://developers.mercadolibre.com.ar/apps.
- Crear aplicación nueva y completar los campos obligatorios: nombre, nombre corto, descripción, propósito, cantidad estimada de usuarios y logo.
- Hacer click en Continuar.
- Configurar Redirect URI con la callback mostrada abajo.
- Habilitar Authorization Code y Refresh Token.
- Para más seguridad, también podés habilitar PKCE. Si lo activás, después tenés que usar el mismo
code_verifier/code_challengeen este asistente. - En Permisos: dejar Usuarios en lectura si la integración necesita editar datos del usuario; cambiar Publicación a lectura; cambiar Sincronización a lectura.
- En Tópicos, no tocar nada salvo que realmente vayas a implementar webhooks.
- Resolver el captcha de I'm not a robot y completar cualquier validación adicional que pida Mercado Libre.
- Guardar la app y copiar
Client ID+Client Secret.
Paso 2: pedir code de autorización
Generar URL de autorización
| Client ID | |
|---|---|
| App con PKCE |
Si está activo, esta herramienta agrega |
| Redirect URI | |
| URL generada |
Paso 3: cambiar code por token
Probar request de token en nueva pestaña
Paso 4: enviar token para aprobación (opcional)
Formulario de revisión de token
| Nombre de la cuenta | |
|---|---|
| Access token | |
| Refresh token | |
| Client ID | |
| Client Secret |
Procedimientos completos de punta a punta
Procedimiento A: primera puesta en marcha (sin datos previos)
- Crear app ML y obtener credenciales OAuth.
- Configurar tokens y guardar.
- Definir cuenta principal.
- Configurar tamaño de lote, retraso y reglas de negocio.
- Iniciar nueva importación desde pantalla Importar.
- Esperar fin de cola y revisar staging pendiente.
- Aplicar o descartar cambios en Revisión de Cambios.
- Ejecutar troubleshooting de duplicados si corresponde.
Procedimiento B: importar desde múltiples cuentas
- Cargar un token por cuenta.
- Definir la cuenta principal en Configuración.
- Configurar campos omitidos para cuentas no principales si queres reducir cambios revisables en staging. El precio ya no necesita configurarse ahi porque no entra en comparacion.
- Importar cada cuenta según necesidad operativa.
- Recordar la regla de precio: la cuenta principal conserva el valor mas alto entre Woo y ML ajustado; las cuentas no principales solo aplican su recargo en productos nuevos o sin precio previo.
- Revisar cambios filtrando por token en ml-import-review.
- Resolver duplicados por dedup_key y fusionar si aplica.
Procedimiento C: cambio de criterios de deduplicación
- Actualizar campos omitidos en Configuración.
- Guardar.
- Ir a Troubleshooting y ejecutar Recalcular dedup keys.
- Luego ejecutar Buscar duplicados de producto.
- Abrir pantalla de fusión para grupos relevantes.
Procedimiento D: limpieza operativa periódica
- Buscar productos en papelera y limpiar definitivamente si corresponde.
- Buscar medios huérfanos con límite prudente (ej. 500).
- Eliminar huérfanos seleccionados.
- Auditar log de importación y errores críticos.
Errores frecuentes y qué hacer
1) "Error de AJAX" en la UI, pero logs siguen
- Inspeccionar request
admin-ajax.phpen Network. - Correlacionar timestamp con log PHP.
- Revisar si hubo respuesta no JSON (salida inesperada de otro plugin/theme).
- El importador intenta recuperación automática por estado; si persiste, baja lote y revisar recursos servidor.
2) timeouts/memory
- Bajar
Productos por lote. - Subir
Retraso entre lotes. - Activar
Extender tiempo de ejecución. - Revisar límites reales de PHP/hosting (memory_limit, max_execution_time, límites de reverse proxy).
3) Duplicados no cambian después de configurar omisiones
- Guardar configuración.
- Ejecutar Recalcular dedup keys.
- Volver a buscar duplicados.
4) OAuth devuelve errores (invalid_grant, code_verifier, etc.)
- Verificar redirect URI exacta.
- Usar
codeuna sola vez. - Si hay PKCE, enviar exactamente el mismo
code_verifierque generó el challenge. - Confirmar que app tiene Authorization Code y Refresh Token habilitados.
5) Taxonomía no válida al crear atributos
- Verificar que el atributo global existe en WooCommerce.
- Verificar registro de taxonomía
pa_*y estado de WooCommerce. - Reintentar importación del producto puntual y revisar log detallado.