n8n-nodes-mercadolibre

Nodos n8n para integración con la API de MercadoLibre (developers.mercadolibre.com).

Incluye:

• MercadoLibre (acción) - Productos, Categorías, Órdenes, Envíos, Preguntas, Mensajes, Usuarios, Búsqueda, Factura (cargar a pack), Facturación (reportes) y una operación de Llamada Personalizada para cualquier endpoint no cubierto explícitamente.
• MercadoLibre Trigger - recibe webhooks/notificaciones en tiempo real (órdenes, preguntas, mensajes, envíos, pagos, reclamos, etc.).
• MercadoLibre OAuth2 API - credencial OAuth2 (Authorization Code) lista para cualquier país/sitio de MercadoLibre.

🚀 Recursos y Operaciones

Producto (Item)

• Crear, Obtener, Obtener varios por IDs, Actualizar
• Actualizar Estado (activar/pausar/cerrar), Actualizar Stock
• Buscar por Vendedor, Obtener/Actualizar Descripción
• Subir Imagen (por URL o datos binarios del flujo)

Categoría

• Listar por Sitio, Obtener, Obtener Atributos, Predecir Categoría (a partir de un título)

Producto de Catálogo

• Obtener por ID

Orden

• Obtener, Buscar (por vendedor, con filtros JSON libres), Agregar Feedback

Envío

• Obtener, Obtener Items, Obtener Costos

Pregunta

• Buscar, Obtener, Responder, Eliminar

Mensaje

• Obtener por Pack (venta), Enviar

Usuario

• Obtener Mi Cuenta (/users/me), Obtener por ID, Obtener Mis Publicaciones

Búsqueda

• Buscar en Sitio (/sites/{site}/search) con filtros adicionales libres en JSON

Factura (Cargar a Pack)

Corresponde a Cargar Factura — la factura fiscal que el vendedor adjunta a cada venta (obligatorio en Colombia por regulación DIAN/logística).

• Subir Factura — POST /packs/{pack_id}/fiscal_documents (multipart, campo fiscal_document, PDF, máx. 1 MB, solo un documento por pack)
• Obtener Factura — GET /packs/{pack_id}/fiscal_documents/{fiscal_document_id}
• Eliminar Factura — DELETE /packs/{pack_id}/fiscal_documents/{fiscal_document_id} (para volver a subir una corregida)

Facturación (Reportes)

Corresponde a Facturación — las facturas/notas crédito que MercadoLibre le emite al vendedor por comisiones y servicios (Mercado Libre o Mercado Pago). No confundir con el recurso "Factura" de arriba.

• Obtener Períodos — GET /billing/integration/monthly/periods (últimos períodos, máx. 12 por página)
• Obtener Documentos — GET /billing/integration/periods/key/{key}/documents (facturas BILL / notas crédito CREDIT_NOTE del período)
• Obtener Resumen — GET /billing/integration/periods/key/{key}/summary/details (cargos, bonificaciones e impuestos)
• Obtener Detalle de Ventas — GET /billing/integration/periods/key/{key}/group/{ML|MP}/details
• Descargar Documento — GET /billing/integration/legal_document/{file_id} (devuelve el PDF como dato binario, usa el file_id del array files de "Obtener Documentos")

Llamada Personalizada (Custom API Call)

Ejecuta cualquier método/endpoint de api.mercadolibre.com con query params y body en JSON. Cubre cualquier endpoint de la API no modelado explícitamente como operación (catálogo avanzado, fulfillment, reputación, promociones, etc.), reutilizando siempre la autenticación OAuth2 configurada.

🔔 MercadoLibre Trigger (Webhooks)

MercadoLibre no permite suscribir webhooks vía API — se configuran manualmente:

1. Agrega el nodo MercadoLibre Trigger a tu flujo y actívalo (o copia la URL de test/producción).
2. En developers.mercadolibre.com → tu aplicación → Notificaciones, pega esa URL como Callback URL.
3. Selecciona los topics que te interesan (orders_v2, items, questions, messages, shipments, payments, claims, etc.) tanto en el panel de MercadoLibre como en el filtro del nodo.
4. El nodo responde 200 OK inmediatamente (requerido por MercadoLibre) y entrega el payload crudo de la notificación ({ resource, user_id, topic, ... }). Encadena un nodo MercadoLibre (p. ej. Obtener Orden/Producto) usando {{$json.resource}} para traer el recurso completo.

⚙️ Configuración de Credenciales

1. Crea una aplicación en developers.mercadolibre.com y obtén Client ID y Client Secret.
2. Configura la Redirect URI de la app igual a la que n8n muestra en la pantalla de credenciales OAuth2.
3. En n8n, crea una credencial MercadoLibre OAuth2 API, elige el País/Sitio donde está registrada la app (define el dominio auth.mercadolibre.<país> usado solo para el paso de autorización; el intercambio de tokens siempre ocurre en api.mercadolibre.com).
4. Pulsa Connect my account y autoriza. El refresh token se gestiona automáticamente (offline_access).

📦 Instalación

En n8n (recomendado)

1. Ve a Settings → Community Nodes
2. Clic en Install
3. Escribe: n8n-nodes-mercadolibre
4. Clic en Install

Vía npm

npm install n8n-nodes-mercadolibre

🔗 Documentación de la API

• https://developers.mercadolibre.com.co/es_ar/guia-para-producto
• https://developers.mercadolibre.com.co/es_ar/autenticacion-y-autorizacion
• https://developers.mercadolibre.com.co/es_ar/notificaciones
• https://developers.mercadolibre.com.co/es_ar/cargar-factura
• https://developers.mercadolibre.com.co/es_ar/facturacion

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor abre un issue o pull request.

📄 Licencia

MIT © Manuel Reyes Bravo