Recursos Cross

Explora los recursos principales de nuestras APIs
circulos azuis em degrade

Documentación

Puedes usar esta documentación para las siguientes unidades de negocio:

Última actualización 25/09/2024

Gestión de packs

Importante:
Actualmente, la funcionalidad está disponible para vendedores de Argentina, Brasil, México, Chile, Colombia, Uruguay, Perú y Ecuador.

Relación de entidades


El diagrama ilustra cómo se interrelacionan los componentes clave dentro de un pack:

  • Pack: Se convierte en un componente obligatorio en todas las compras, ya que todas las órdenes estarán asociadas a un pack_id.
    • Relación con Order (Orden): Existe una relación de 1 a N entre un pack y una o más órdenes. Esto significa que un pack puede contener múltiples órdenes, lo que refleja situaciones donde varias órdenes se agrupan en un solo pack.
    • Relación con Shipping (Envío): Existe una relación de 0 a 1, lo que sugiere que un pack puede o no estar vinculado a un proceso de envío. Este caso es común, especialmente en ventas de ítems not_specified, donde no siempre se requiere un shipment_id.
    • Relación con Payments (Pagos): Existe una relación de 1 a N entre una orden y uno o más pagos. Esto implica que una orden puede requerir múltiples pagos, como en el caso de pagos a plazos o cuando una orden está asociada a varias transacciones diferentes.

Este diagrama proporciona una visión clara del flujo de packs, órdenes, envíos y pagos, destacando la flexibilidad y las posibles variaciones en cada componente.

Nota:
  • De manera gradual y durante este año 2024, todas las órdenes estarán vinculadas a un pack_id.
  • Recuerda que al agregar la garantía extendida para ítems not_specified, se generará una excepción. Este ítem se considerará adicional, creando un nuevo pack_id, aunque no se asignará un shipment_id.

Conoce más sobre:

Consultar órdenes de un pack

Representa un paquete de compra, puede tener una o varias órdenes del mismo o de distintos vendedores.

Este endpoint te permite consultar información sobre las órdenes de un pack.


Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/packs/$PACK_ID

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/packs/2000006181551917

Respuesta:

{
    "shipment": {
        "id": 43729529445
    },
    "orders": [
        {
            "id": 2000009047722568
        },
        {
            "id": 2000009047707726
        }
    ],
    "id": 2000006181551917,
    "status": "released",
    "status_detail": null,
    "family_pack_id": null,
    "buyer": {
        "id": 1944693439
    },
    "date_created": "2024-08-15T17:38:30.000-0400",
    "last_updated": "2024-08-15T17:42:52.000-0400"
}

Parámetros de respuesta:

  • shipment.id: Identificador único del envío.
  • orders.id: Identificadores únicos de las órdenes que están asociadas a un pack.
  • id: Identificador único del pack.
  • status: Estado actual del pack. Podría tomar los siguientes valores:
    • Released: las órdenes y el envío están pagados.
    • Error: Algo falló dentro del proceso y podría recuperarse.
    • Pending_cancel: ocurrió un error no recuperable.
    • Cancelled: las órdenes y el envío están cancelados.
  • status_detail: Proporciona detalles adicionales sobre el estado del pack, como los motivos de una cancelación o cualquier otro problema específico que afecte el envío (en este caso, null indica que no hay detalles adicionales).
  • buyer.id: Identificador único del comprador asociado al pack.
  • date_created: Fecha y hora en que se creó el pack.
  • last_updated: Fecha y hora de la última actualización del pack.

Códigos de estado de respuesta:

Código Mensaje Descripción Posible Solución
200 - OK - Consulta exitosa. -
403 - forbidden Can not identify the user No se puede identificar al usuario. Validar access token.
403 - forbidden The user has not access to the order El caller no está autorizado a acceder al recurso. Validar access token.
404 - not_found Order do not exists El pack no existe. Validar el pack_id.
Nota:
  • Solo podrás ver o leer las órdenes de los vendedores que estén utilizando tu integración o sistema. Esto significa que si una consulta devuelve solo una orden, podría deberse a que las otras órdenes no están asociadas a vendedores que usen tu sistema.

Consultar órdenes

Una orden representa la compra de un ítem-variación en el marketplace. Siempre la orden es de un solo ítem, pero pueden ser múltiples unidades del mismo.

Este endpoint te permite obtener detalles sobre una orden específica.


Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/2000008779458474

Respuesta:


    {
        "id": 2000009047691488,
        "date_created": "2024-08-15T17:36:41.000-04:00",
        "last_updated": "2024-08-15T17:42:10.000-04:00",
        "expiration_date": "2024-09-12T17:36:43.000-04:00",
        "date_closed": "2024-08-15T17:36:43.000-04:00",
        "pack_id": null,
        "fulfilled": true,
        "buying_mode": "buy_equals_pay",
        "shipping_cost": null,
        "mediations": [],
        "total_amount": 1000.00,
        "paid_amount": 4784.99,
        "coupon": {
            "amount": 0.00,
            "id": null
        },
        "order_items": [
            {
                "item": {
                    "id": "MLA1443455161",
                    "title": "Lápiz Labial Love Me De Batom Mac You, 431, Color Rojo",
                    "category_id": "MLA29883",
                    "variation_id": 181369367530,
                    "seller_custom_field": null,
                    "variation_attributes": [
                        {
                            "name": "Color",
                            "id": "COLOR",
                            "value_id": "51993",
                            "value_name": "Rojo"
                        }
                    ],
                    "warranty": "Garantía del vendedor: 30 días",
                    "condition": "new",
                    "seller_sku": null,
                    "global_price": null,
                    "net_weight": null,
                    "user_product_id": "MLAU458107282",
                    "release_date": null
                },
                "quantity": 1,
                "requested_quantity": {
                    "value": 1,
                    "measure": "unit"
                },
                "picked_quantity": null,
                "unit_price": 1000.00,
                "full_unit_price": 1000.00,
                "currency_id": "ARS",
                "manufacturing_days": null,
                "sale_fee": 1290.00,
                "listing_type_id": "gold_pro",
                "base_exchange_rate": null,
                "base_currency_id": null,
                "element_id": null,
                "discounts": null,
                "bundle": null,
                "compat_id": null,
                "stock": [
                    {
                      "store_id": "54936888", // Nuevos atributos de Stock Distribuido y Multi Origen
                      "node_id": "163942": "54936888", // Nuevos atributos de Stock Distribuido y Multi Origen
    
                    }
               ],
            }
        ],
        "currency_id": "ARS",
        "payments": [
            {
                "id": 85100978297,
                "order_id": 2000009047691488,
                "payer_id": 1944693439,
                "collector": {
                    "id": 1947296464
                },
                "card_id": null,
                "reason": "Lápiz Labial Love Me De Batom Mac You, 431, Color Rojo",
                "site_id": "MLA",
                "payment_method_id": "master",
                "currency_id": "ARS",
                "installments": 1,
                "issuer_id": "3",
                "atm_transfer_reference": {
                    "transaction_id": null,
                    "company_id": null
                },
                "coupon_id": null,
                "activation_uri": null,
                "operation_type": "regular_payment",
                "payment_type": "credit_card",
                "available_actions": [
                    "refund"
                ],
                "status": "approved",
                "status_code": null,
                "status_detail": "accredited",
                "transaction_amount": 1000.00,
                "transaction_amount_refunded": 0.00,
                "taxes_amount": 0.00,
                "shipping_cost": 3784.99,
                "coupon_amount": 0.00,
                "overpaid_amount": 0.00,
                "total_paid_amount": 4784.99,
                "installment_amount": 4784.99,
                "deferred_period": null,
                "date_approved": "2024-08-15T17:36:43.000-04:00",
                "transaction_order_id": null,
                "date_created": "2024-08-15T17:36:42.000-04:00",
                "date_last_modified": "2024-08-15T17:36:49.000-04:00",
                "marketplace_fee": 0.00,
                "reference_id": null,
                "authorization_code": "301299"
            }
        ],
        "shipping": {
            "id": 43729693454
        },
        "status": "paid",
        "status_detail": null,
        "tags": [
            "paid",
            "delivered",
            "test_order"
        ],
        "feedback": {
            "seller": null,
            "buyer": null
        },
        "context": {
            "channel": "marketplace",
            "site": "MLA",
            "flows": []
        },
        "seller": {
            "id": 1947296464,
            "user_type": null,
            "tags": [],
            "status": null,
            "buy_restrictions": []
        },
        "buyer": {
            "id": 1944693439,
            "nickname": "TESTUSER559713256",
            "first_name": "Test",
            "last_name": "Test",
            "user_type": null,
            "tags": [],
            "status": null,
            "buy_restrictions": []
        },
        "taxes": {
            "amount": null,
            "currency_id": null,
            "id": null
        },
        "cancel_detail": null,
        "manufacturing_ending_date": null,
        "order_request": {
            "change": null,
            "return": null
        }
    }
    

Parámetros de respuesta:

  • id: Identificador único de la orden.
  • date_created: Fecha y hora en que se creó la orden.
  • last_updated: Fecha y hora de la última actualización de la orden.
  • expiration_date: Fecha y hora en que expira la orden.
  • date_closed: Fecha y hora en que se cerró la orden.
  • pack_id: Identificador del pack al que pertenece la orden, si está asociada a un pack.
  • fulfilled: Indica si la orden ha sido cumplida o completada (valor booleano).
  • buying_mode: Modo de compra utilizado, en este caso, "buy_equals_pay" (comprar equivale a pagar).
  • shipping_cost: Costo del envío asociado a la orden. Puede ser nulo si forma parte de un pack_id. De no ser así, se mostrará el costo de envío que el comprador pagó por su pedido.
  • mediations: Array de mediaciones asociadas con la orden (puede estar vacío).
  • total_amount: Monto total de la orden.
  • paid_amount: Monto pagado por la orden.
  • order_items: Array que contiene los detalles de los productos incluidos en la orden, como el título, cantidad, precio unitario, etc.
  • order_items.stock: Este atributo representa una estructura que agrupa la información relacionada con la disponibilidad y localización del inventario de un ítem.
    • order_items.stock.store_id: Este campo identifica la tienda o ubicación física específica donde se encuentra almacenado el stock de un ítem.
    • order_items.stock.node_id: Este atributo representa el nodo del seller, o la ubicación física específica desde la cual proviene un ítem.
  • currency_id: Identificador de la moneda utilizada en la transacción.
  • payments: Array de pagos asociados a la orden, incluyendo detalles como el método de pago, monto de la transacción, estado del pago, etc.
  • shipping: Información sobre el envío, incluyendo el id del envío.
  • status: Estado actual de la orden (por ejemplo, "paid").
  • status_detail: Detalles adicionales sobre el estado de la orden (puede ser nulo).
  • tags: Array de etiquetas asociadas a la orden.
  • feedback: Información sobre el feedback del vendedor y comprador (puede ser nulo).
  • context: Información contextual de la orden, incluyendo canal, país.
  • seller: Información sobre el vendedor, incluyendo su “id”, tipo de usuario, y restricciones de compra.
  • buyer: Información sobre el comprador, incluyendo su “id”, apodo, nombre, apellido, tipo de usuario, y restricciones de compra.
  • taxes: Información sobre los impuestos aplicados a la orden, incluyendo el monto y la moneda (puede ser nulo).
  • cancel_detail: Detalles sobre la cancelación de la orden (puede ser nulo).
  • manufacturing_ending_date: Fecha de finalización de la fabricación, si aplica (puede ser nulo).
  • order_request: Información sobre solicitudes de cambio o devolución asociadas a la orden (puede ser nulo).

Códigos de estado de respuesta:

Código Mensaje Descripción Posible Solución
200 - OK - Consulta exitosa. -
403 - forbidden Can not identify the user No se puede identificar al usuario. Validar access token.
403 - forbidden The user has not access to the order El caller no está autorizado a acceder al recurso. Validar access token.
404 - not_found Order does not exist La orden no existe. Validar el order_id.

Consideraciones

  • El tag pack_order se genera automáticamente para identificar si la orden está asociada a un pack. Este tag no puede ser eliminado ni por el comprador ni por el vendedor.
  • En ocasiones, puede suceder que, aunque exista una orden, el envío demore en crearse. En estos casos, el shipping ID será null hasta que se cree el envío, y recibirás una notificación una vez se genere.
  • Los tags delivered/not delivered ya no se agregarán automáticamente. Si necesitas que estos tags estén presentes, el integrador deberá realizar un PUT con el tag correspondiente.
  • Las órdenes en estado paid se cancelarán si el pago es devuelto. Cuando esto ocurra, recibirás una notificación para que estés al tanto del cambio de estado de la orden.
  • Aunque la orden seguirá mostrando el campo seller_custom_field, la información mostrada en este campo seguirá ciertos criterios para seleccionar la información de SKU, tales como:
    • seller_sku de atributos de variación
    • seller_custom_field de variación
    • seller_sku de atributos de ítem
    • seller_custom_field de ítem
  • En caso que la orden no esté asociada a un pack y la transacción sea bajo la modalidad “acordar con el vendedor”, ya no recibirás un estado to be agreed sino que directamente el shipping ID vendrá como null. Eso te dará la pauta de que deberás entrar en contacto con el comprador para coordinar la forma de envío.
Nota:
  • Ten en cuenta que el array "stock" y sus atributos se desplegarán una vez que los flujos de Stock Distribuido y Multiorigen estén activos, y su implementación se realizará de manera progresiva según avancen los mismos.
  • El array "coupon" se deprecará pronto, por lo que te recomendamos consultar estos valores directamente en la API de /orders/$ORDER_ID/discounts.

Ya tengo el producto

Este endpoint permite al vendedor marcar la disponibilidad de stock o "Ya tengo el producto", permitiendo despachar el producto cuando esté listo.



Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/process/ready_to_ship

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/43664723386/process/ready_to_ship

Respuesta:

{                                                                                                              
    "status": 200                                                                                              
}

Códigos de estado de respuesta:

Código Mensaje Descripción Posible Solución
200 - OK - Consulta exitosa. -
403 - forbidden At least one policy returned UNAUTHORIZED El caller no está autorizado a acceder al recurso. Validar access token.
404 - not_found Not found shipment with id. No se encontró shipment_id. Validar shipment_id.

Consideraciones:

  • Tomar en cuenta que esta funcionalidad solo se puede usar para órdenes ME2.
  • Considerar que está habilitada en países que cuenten con la funcionalidad de manufacturing_time y ME2.