Información de Usuario

Los usuarios autenticados pueden recuperar sus datos personales a través del endpoint /users/me. La información incluye id, nickname, registration_date, country_id, address (estado, ciudad), user_type, tags, logo, points y site_id.

Para consultar la información pública de otros usuarios, se utiliza /users/{User_id}. Los datos privados permanecen ocultos a menos que se cuente con permiso explícito. Si solo conoces el nickname, puedes obtener el User_id con /sites/{Site_id}/search?nickname={Nickname}.

Usuarios de Prueba

Mercado Libre permite crear usuarios de prueba globales y de mercado para facilitar el desarrollo y las pruebas sin afectar cuentas reales. Poseen atributos como id, nickname, password, site_status y email.

Existen ciertas limitaciones: máximo 10 por cuenta, temporales (eliminados después de 60 días de inactividad) y no pueden ser eliminados por el usuario ni por Mercado Libre. Las operaciones de prueba están restringidas a publicaciones creadas por otras cuentas de prueba.

Tiendas Oficiales

Las Tiendas Oficiales son usuarios seleccionados que pueden tener una o más marcas bajo la misma cuenta. La API permite consultar marcas asociadas a un user_id a través del recurso /official_store. El atributo official_store_id identifica una tienda, y la respuesta incluye campos como status, normalized_name y last_updated.

Para operaciones con ítems en Tiendas Oficiales multi-marca, es obligatorio enviar el official_store_id; de lo contrario, se puede recibir un error de validación 400 o un error 403 Forbidden si el ID es inválido.

Búsqueda de Productos y Detalles de Ítems

Es posible buscar ítems mediante consultas de texto a través del endpoint /sites/$SITE_ID/search?q=$TEXT_TO_SEARCH. Los resultados de la búsqueda pueden filtrarse por category_id, nickname o seller_id.

Para recuperar detalles de múltiples ítems simultáneamente, se utiliza /items?ids=$ITEM_ID1,$ITEM_ID2. Se pueden seleccionar campos específicos de interés con el parámetro attributes para reducir el tamaño de la respuesta. Los detalles completos de un ítem específico se obtienen a través de /items/{item_id}, y todas las descripciones asociadas a un ítem se consultan en /item_descriptions/{item_id}. La API también permite obtener datos de visitas para ítems (/item_visits), con un límite de 50 ítems por solicitud. Para Global Selling, el mapeo entre un ítem del sitio global y sus ítems en los mercados locales se obtiene con /items/$ITEM_ID/marketplace_items.

Endpoints Clave:

Categorías, Atributos y Dominios:

La API permite gestionar categorías (/categories) y atributos de productos. También se puede acceder a información de dominios, así como a datos de ubicaciones y monedas, incluyendo países, estados, ciudades, monedas y tasas de conversión (/countries, /currencies, etc.).

Tipos de Publicación y Exposición

Mercado Libre ofrece diferentes tipos de publicación (ej. free, gold_special, gold_pro, bronze), cada uno con características y niveles de exposición distintos, y asociados a tarifas específicas. Los desarrolladores pueden verificar las mejoras disponibles (/items/$ITEM_ID/available_upgrades) y las degradaciones (/items/$ITEM_ID/available_downgrades) para las publicaciones. Es posible actualizar el tipo de publicación mediante solicitudes POST.

Gestión de Stock e Inventario: Cantidades Referenciales

Para consultar el stock y las operaciones de los ítems en el centro de cumplimiento (fulfillment), se debe obtener primero el inventory_id a través del recurso /marketplace/items. Los detalles del stock incluyen campos como total, available_quantity, not_available_quantity y not_available_detail.

Las operaciones de stock pueden filtrarse por inventory_id, seller_id, date_from, date_to, type (ej. inbound_reception, sale_confirmation, sale_cancellation, withdrawal_reservation, transfer_reservation) y external_references.

Es importante destacar que los campos sold_quantity y available_quantity en los recursos públicos de ítems y búsquedas son "referenciales" y se presentan en rangos, no como números exactos en tiempo real. Para una gestión precisa del inventario, es necesario consultar APIs más especializadas, como los endpoints dedicados a /stock/. La introducción del "Stock Multi-Origen" requiere un encabezado x-version obligatorio para las actualizaciones.

Valores Referenciales para sold_quantity y available_quantity:

Detalles y Búsqueda de Pedidos

Es posible buscar todos los pedidos de un vendedor utilizando /marketplace/orders/search. Esta búsqueda puede filtrarse por seller_id y admite parámetros de paginación y ordenamiento como sort, order, limit y offset. Para el Global Selling, los pedidos corresponden a cada mercado local (México, Brasil y Chile) y se gestionan de manera unificada.

Gestión de Paquetes (Packs)

El concepto de "Pack" es un componente obligatorio en todas las compras, ya que todos los pedidos se asocian a un pack_id. Un pack puede contener uno o varios pedidos de uno o varios vendedores (relación 1 a N). La relación con el envío es de 0 a 1, lo que significa que un pack puede estar o no vinculado a un proceso de envío. Un pedido tiene una relación 1 a N con los pagos, y los pagos tienen una relación N a N con los descuentos. Se recomienda consultar primero el endpoint /packs para obtener una visión general de los pedidos vinculados, y luego usar el endpoint /orders para acceder a los detalles específicos de los pedidos dentro de ese paquete. Los estados posibles de un pack incluyen Released, Error, Pending_cancel y Cancelled.

Mensajes Post-Venta y Calificaciones

La API de mensajería permite a los vendedores mantener contacto con los compradores después de una venta, cubriendo diversas razones de mensajería, así como la gestión de mensajes pendientes y bloqueados.

Es posible obtener las calificaciones tanto del vendedor como del comprador para un pedido específico a través de /orders/{order_id}/feedback.

Detalles y Seguimiento de Envíos

El recurso Shipments (/shipments/{shipment_id}) incluye toda la información referente al envío necesario para completar una transacción. Es importante enviar el parámetro x-format-new: true en la cabecera para obtener el JSON actualizado, ya que el nuevo JSON de Órdenes ya no incluirá datos de Envío. Los estados consultables clave de un envío incluyen pending, handling, ready_to_ship, shipped, delivered, not_delivered y cancelled.

Las APIs permiten informar a los usuarios sobre el seguimiento de sus paquetes, y se pueden establecer el tracking_number y la tracking_url. Los ítems asociados a un envío se recuperan mediante /shipments/{shipment_id}/items, incluyendo variaciones y permitiendo múltiples ítems por envío. Los costos de envío a pagar por el usuario se obtienen en /shipments/{shipment_id}/costs, con detalles como shipping_fee, billable_weight y el estado de free_shipping. Los pagos asociados al envío se encuentran en /shipments/{shipment_id}/payments. La información detallada sobre los tiempos de entrega y el tipo de servicio, incluyendo estimated_handling_limit, estimated_delivery_extended, estimated_delivery_limit y estimated_delivery_final, se consulta en /shipments/{shipment_id}/lead_time.

Estados Clave del Envío:

Métodos de Envío

Mercado Libre soporta varios métodos de envío:

• Mercado Envíos (ME1): El vendedor utiliza su propia infraestructura y proporciona el número de seguimiento.
• Mercado Envíos (ME2): Transportista elegido por Mercado Libre. Se proporciona una etiqueta prepagada y un número de seguimiento. Incluye Fulfillment by Mercado Libre (FBM) (Mercado Libre se encarga del envío) y Remote partnered carrier (Drop Off, Cross Docking).
• Envío Personalizado: Permite opciones de envío no cubiertas por Mercado Envíos.

Razones de Problemas Comunes:

Gestión de Promociones

El recurso /seller-promotions es un punto centralizado para gestionar diversos tipos de promociones, incluyendo DEAL (campañas tradicionales), MARKETPLACE_CAMPAIGN (campañas cofinanciadas por Mercado Libre), PRICE_DISCOUNT (descuentos de precio), LIGHTNING (ofertas relámpago), DOD (ofertas del día), VOLUME (descuentos por volumen), PRE_NEGOTIATED (descuentos prenegociados), SELLER_CAMPAIGN y SMART.

Los detalles específicos de las campañas tradicionales, cofinanciadas y de descuentos por volumen se pueden consultar a través de /seller-promotions/promotions/$PROMOTION_ID. La API permite identificar los ítems invitados a participar en una promoción (/seller-promotions/candidates) y detectar cambios en las ofertas de ítems (/seller-promotions/offers). Para verificar los ítems incluidos en una promoción específica, se utiliza /seller-promotions/promotions/$PROMOTIONS_ID/items. Es posible aplicar filtros por item_id, status (estado de la oferta: started, pending, candidate) y status_item (estado de los ítems en la campaña: active o paused).

Publicidad (Mercado Ads)

Mercado Ads es la solución publicitaria integrada en Mercado Libre para dar mayor visibilidad a los productos. Existen dos modos de gestión de anuncios:

• Automático: Mercado Ads selecciona publicaciones con buen nivel de ventas y las muestra en las primeras posiciones de los resultados de búsqueda. Este es el modo predeterminado al iniciar.
• Personalizado: Permite crear múltiples campañas para agrupar anuncios, asignar presupuestos y establecer objetivos. Este modo ofrece mayor control sobre las campañas.

Los datos consultables incluyen advertiser_id, site_id, advertiser_name y account_name. Las métricas disponibles abarcan clicks, prints, cost, cpc, acos, organic_units_quantity, organic_units_amount, organic_items_quantity, direct_items_quantity, indirect_items_quantity, advertising_items_quantity, cvr, roas, sov, direct_units_quantity, indirect_units_quantity, units_quantity, direct_amount, indirect_amount y total_amount.

Creación y Consulta de Pagos

Los pagos pueden crearse mediante solicitudes POST (POST /v1/payments). Se requieren parámetros como total_amount, payment_method.id y payment_method.type. Además, se pueden incluir datos del pagador (payer) y de los ítems (items) para mejorar la tasa de aprobación de los pagos, con detalles como first_name, last_name, identification, phone, address, category_id, quantity y unit_price.

Es posible buscar pagos existentes con GET /payments/search y recuperar los detalles de un pago específico con GET /payments/{id}. La API también permite actualizar pagos existentes con solicitudes PUT (PUT /payments/{id}).

Métodos de Pago y Gestión de Tarjetas

La API permite recuperar una lista de todos los métodos de pago disponibles (GET /v1/payment_methods).

Para la gestión de tarjetas, se pueden guardar (POST /cards), recuperar tarjetas de clientes (GET /customers/{customer_id}/cards), obtener detalles de una tarjeta específica (GET /cards/{id}), actualizar (PUT /cards/{id}) y eliminar tarjetas (DELETE /cards/{id}).

Estados y Manejo de Pagos

La API proporciona información detallada sobre los posibles estados de un pago. Las notificaciones de pago se configuran mediante webhooks, que envían información en tiempo real sobre la creación y actualización del estado de los pagos (Pendiente, Rechazado, Aprobado). Haz clic en cada estado para ver sus sub-estados posibles.

Órdenes de Pagos en Línea

Para pagos en línea, se pueden crear órdenes en modo "automático" (procesamiento en una sola etapa) o "manual" (procesamiento incremental) mediante POST /v1/orders. Los parámetros de solicitud incluyen type (siempre "online"), external_reference y transactions. La respuesta de una orden incluye id, type, processing_mode y external_reference.

Las órdenes pueden capturarse completamente (POST /orders/{id}/capture), cancelarse (POST /orders/{id}/cancel) y reembolsarse (POST /orders/{id}/refund). También es posible añadir transacciones a una orden (POST /orders/{id}/transactions), actualizar (PUT /orders/{id}/transactions/{transaction_id}) y eliminar transacciones (DELETE /orders/{id}/transactions/{transaction_id}). El procesamiento de una orden se realiza con POST /orders/{id}/process.

Órdenes de Pagos Presenciales (Mercado Pago Point)

Para pagos presenciales a través de Mercado Pago Point, se pueden crear órdenes con POST /point/orders. Los parámetros de solicitud incluyen type (siempre "point"), external_reference, transactions y config. Las órdenes pueden consultarse por ID (GET /point/orders/{id}), cancelarse (POST /point/orders/{id}/cancel) y reembolsarse (POST /point/orders/{id}/refund).

Gestión de Clientes

Se pueden crear nuevos clientes mediante POST /v1/customers. La búsqueda de clientes se realiza con GET /v1/customers/search, y los detalles de un cliente específico se obtienen con GET /v1/customers/{id}. La información de los clientes puede actualizarse con PUT /v1/customers/{id}.

Los parámetros para la información del pagador incluyen first_name, last_name, identification (tipo y número), phone (código de área y número) y address (código postal, nombre y número de calle).

Tipos de Identificación

La API permite consultar los tipos de documentos de identificación disponibles a través de GET /v1/identification_types.

Creación y Consulta de Suscripciones

Las suscripciones pueden crearse con POST /v1/subscriptions. Es posible buscar suscripciones existentes (GET /v1/subscriptions/search) y obtener los detalles de una suscripción específica (GET /v1/subscriptions/{id}). Las suscripciones pueden actualizarse (PUT /v1/subscriptions/{id}) y exportarse (GET /v1/subscriptions/export).

Para crear una suscripción, es necesario vincularla a una dirección de correo electrónico del pagador (payer_email).

Planes de Suscripción y Facturas

La API permite crear planes de suscripción (POST /v1/plans), buscar planes (GET /v1/plans/search), obtener detalles de un plan específico (GET /v1/plans/{id}) y actualizarlos (PUT /v1/plans/{id}).

La API también permite obtener datos de facturas (GET /v1/invoices/{id}) y buscar facturas (GET /v1/invoices/search).

Cancelaciones y Reembolsos

Las cancelaciones se realizan cuando un pago no ha finalizado o está en proceso (PUT /v1/cancellations/{id}). Solo pueden realizarse si el estado del pago es pending o in_process.

Los reembolsos se efectúan después de que el pago ha sido capturado (POST /v1/refunds). Pueden ser totales (cuerpo de la solicitud vacío) o parciales (especificando el monto a reembolsar y el ID de la transacción). Se pueden consultar listas de reembolsos (GET /v1/refunds/search) y reembolsos específicos (GET /v1/refunds/{id}). Los reembolsos pueden emitirse hasta 180 días después de la aprobación del pago, y requieren saldo suficiente en la cuenta.

Contracargos (Chargebacks)

La API permite obtener información sobre contracargos (GET /v1/chargebacks/{id}). Esto incluye la consulta de detalles del contracargo por ID o payment_id, y la posibilidad de enviar documentación para disputarlos si el campo documentation_required es true y la fecha límite (date_documentation_deadline) es futura. Los archivos deben ser .jpg, .png o .pdf.

Reclamos (Claims)

La API ofrece una gestión integral de reclamos:

• Detalles y Búsqueda: Obtener detalles de un reclamo (GET /v1/claims/{id}), buscar reclamos (GET /v1/claims/search), obtener la razón del reclamo (GET /v1/claims/{id}/reason), historial (GET /v1/claims/{id}/history), evidencia (GET /v1/claims/{id}/evidence) y notificaciones (GET /v1/claims/{id}/notifications).
• Archivos y Mensajes: Consultar mensajes de reclamo (GET /v1/claims/{id}/messages), adjuntar archivos a mensajes (POST /v1/claims/{id}/messages/files), enviar mensajes con archivos (POST /v1/claims/{id}/messages), obtener datos de archivos (GET /v1/files/{id}/data) y descargar archivos adjuntos (GET /v1/files/{id}/download).
• Resoluciones: Solicitar mediación de un reclamo (POST /v1/claims/{id}/mediation_request) y ver las resoluciones esperadas en la mediación (GET /v1/claims/{id}/expected_resolutions).
• Evidencia de Envío: Subir evidencia de envío (POST /v1/deliveries/{id}/evidence).

Los reclamos pueden filtrarse por stage, status y date. Los campos de respuesta incluyen sender_role, receiver_role, attachments (filename, original_filename, size, type), message, player_role, expected_resolution (refund, product, change_product, return_product), status (pending, accepted, rejected), affects_reputation, has_incentive y due_date.

Tipos de Reportes y Atributos Configurables

Los reportes disponibles incluyen: Dinero Liberado, Balance de Cuenta y Reporte de Ventas de Solución de Pago Dividido de Mercado Pago.

Los atributos configurables para los reportes incluyen coupon_detailed, columns, file_name_prefix, frequency (diaria, semanal, mensual), display_timezone, include_withdraw, report_translation, refund_detailed, scheduled, separator, notification_email_list, sftp_info, shipping_detail, show_chargeback_cancel y show_fee_prevision.

Endpoints de Configuración y Generación: