Recursos Cross

Confira os principais recursos das nossas APIs
circulos azuis em degrade

Documentação do

Você pode usar esta documentação para as seguintes unidades de negócio:

Última atualização em 25/09/2024

Gestão de packs

Importante:
Atualmente, a funcionalidade está disponível para vendedores da Argentina, Brasil, México, Chile, Colômbia, Uruguai, Peru e Equador.

Relação de entidades


O diagrama ilustra como os componentes-chave se inter-relacionam dentro de um pack:

  • Pack: Torna-se um componente obrigatório em todas as compras, pois todos os pedidos estarão associados a um pack_id.
    • Relação com Order (Pedido): Existe uma relação de 1 a N entre um pack e um ou mais pedidos. Isso significa que um pack pode conter múltiplos pedidos, o que reflete situações onde vários pedidos são agrupados em um único pack.
    • Relação com Shipping (Envio): Existe uma relação de 0 a 1, o que sugere que um pack pode ou não estar vinculado a um processo de envio. Este caso é comum, especialmente em vendas de itens not_specified, onde nem sempre é necessário um shipment_id.
    • Relação com Payments (Pagamentos): Existe uma relação de 1 a N entre um pedido e um ou mais pagamentos. Isso implica que um pedido pode exigir múltiplos pagamentos, como no caso de pagamentos a prazo ou quando um pedido está associado a várias transações diferentes.

Este diagrama fornece uma visão clara do fluxo de packs, ordens, envios e pagamentos, destacando a flexibilidade e as possíveis variações em cada componente.

Nota:
  • Gradualmente e durante o ano de 2024, todos os pedidos estarão vinculados a um pack_id.
  • Lembre-se de que, ao adicionar a garantia estendida para itens not_specified, uma exceção será gerada. Este item será considerado adicional, criando um novo pack_id, embora nenhum shipment_id seja atribuído.

Saiba mais sobre:

Consultar ordens de um pack

Representa um pacote de compra, pode conter uma ou várias ordens do mesmo ou de diferentes vendedores.

Este endpoint permite consultar informações sobre as ordens de um pack.


Chamada:

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

Exemplo:

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

Resposta:

{
    "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 resposta:

  • shipment.id: Identificador único do envio.
  • orders.id: Identificadores únicos dos pedidos que estão associados a um pack.
  • id: Identificador único do pack.
  • status: Estado atual do pack. Pode assumir os seguintes valores:
    • Released: os pedidos e o envio estão pagos.
    • Error: Algo falhou no processo e pode ser recuperado.
    • Pending_cancel: ocorreu um erro irrecuperável.
    • Cancelled: os pedidos e o envio foram cancelados.
  • status_detail: Fornece detalhes adicionais sobre o status do pack, como os motivos de um cancelamento ou qualquer outro problema específico que afete o envio (neste caso, null indica que não há detalhes adicionais).
  • buyer.id: Identificador único do comprador associado ao pack.
  • date_created: Data e hora em que o pack foi criado.
  • last_updated: Data e hora da última atualização do pack.

Códigos de status de resposta:

Código Mensagem Descrição Possível Solução
200 - OK - Consulta bem-sucedida. -
403 - forbidden Can not identify the user Não é possível identificar o usuário. Validar access token.
403 - forbidden The user has not access to the order O caller não está autorizado a acessar o recurso. Validar access token.
404 - not_found Order do not exists O pack não existe. Validar o pack_id.
Nota:
  • Você só poderá ver ou ler os pedidos dos vendedores que estão utilizando sua integração ou sistema. Isso significa que, se uma consulta retornar apenas um pedido, pode ser que os outros pedidos não estejam associados a vendedores que utilizam seu sistema.

Consultar orders

Um order representa a compra de um item-variação no marketplace. O pedido sempre é de um único item, mas pode haver várias unidades dele.

Este endpoint permite obter detalhes sobre um pedido específico.


Chamada:

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

Exemplo:

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

Resposta:


    {
        "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 resposta:

  • id: Identificador único do pedido.
  • date_created: Data e hora em que o pedido foi criado.
  • last_updated: Data e hora da última atualização do pedido.
  • expiration_date: Data e hora em que expira o pedido.
  • date_closed: Data e hora em que o pedido foi fechado.
  • pack_id: Identificador do pacote ao qual o pedido pertence, se estiver associado a um pacote.
  • fulfilled: Indica se o pedido foi cumprido ou concluído (valor booleano).
  • buying_mode: Modo de compra utilizado, neste caso, "buy_equals_pay" (comprar equivale a pagar).
  • shipping_cost: Custo de envio associado ao pedido. Pode ser nulo se fizer parte de um pack_id. Caso contrário, será mostrado o custo de envio que o comprador pagou pelo seu pedido.
  • mediations: Array de mediações associadas ao pedido (pode estar vazio).
  • total_amount: Valor total do pedido.
  • paid_amount: Valor pago pelo pedido.
  • order_items: Array que contém os detalhes dos produtos incluídos no pedido, como título, quantidade, preço unitário, etc.
  • order_items.stock: Este atributo representa uma estrutura que agrupa as informações relacionadas à disponibilidade e localização do estoque de um item.
    • order_items.stock.store_id: Este campo identifica a loja ou localização física específica onde o estoque de um item está armazenado.
    • order_items.stock.node_id: Este atributo representa o nó do vendedor ou a localização física específica de onde o item provém.
  • currency_id: Identificador da moeda utilizada na transação.
  • payments: Array de pagamentos associados ao pedido, incluindo detalhes como o método de pagamento, valor da transação, estado do pagamento, etc.
  • shipping: Informações sobre o envio, incluindo o id do envio.
  • status: Status atual do pedido (por exemplo, "paid").
  • status_detail: Detalhes adicionais sobre o status do pedido (pode ser nulo).
  • tags: Array de etiquetas associadas ao pedido.
  • feedback: Informações sobre o feedback do vendedor e comprador (pode ser nulo).
  • context: Informações contextuais do pedido, incluindo canal e país.
  • seller: Informações sobre o vendedor, incluindo seu “id”, tipo de usuário e restrições de compra.
  • buyer: Informações sobre o comprador, incluindo seu “id”, apelido, nome, sobrenome, tipo de usuário e restrições de compra.
  • taxes: Informações sobre os impostos aplicados ao pedido, incluindo o valor e a moeda (pode ser nulo).
  • cancel_detail: Detalhes sobre o cancelamento do pedido (pode ser nulo).
  • manufacturing_ending_date: Data de término da fabricação, se aplicável (pode ser nulo).
  • order_request: Informações sobre solicitações de troca ou devolução associadas ao pedido (pode ser nulo).

Códigos de status de resposta:

Código Mensagem Descrição Possível Solução
200 - OK - Consulta bem-sucedida. -
403 - forbidden Can not identify the user Não foi possível identificar o usuário. Validar access token.
403 - forbidden The user has not access to the order O caller não está autorizado a acessar o recurso. Validar access token.
404 - not_found Order does not exist O pedido não existe. Validar o order_id.

Considerações

  • O tag pack_order é gerado automaticamente para identificar se o pedido está associado a um pacote. Este tag não pode ser removido pelo comprador nem pelo vendedor.
  • Às vezes, pode acontecer que, mesmo havendo um pedido, o envio demore a ser criado. Nesses casos, o shipping ID será null até que o envio seja criado, e você receberá uma notificação quando for gerado.
  • Os tags delivered/not delivered não serão mais adicionados automaticamente. Se precisar que esses tags estejam presentes, o integrador deverá realizar um PUT com o tag correspondente.
  • Os pedidos no status paid serão cancelados se o pagamento for devolvido. Quando isso acontecer, você receberá uma notificação para acompanhar a alteração de status do pedido.
  • Embora o pedido continue exibindo o campo seller_custom_field, as informações exibidas neste campo seguirão determinados critérios para selecionar as informações do SKU, como:
    • seller_sku de atributos de variação
    • seller_custom_field de variação
    • seller_sku de atributos de item
    • seller_custom_field de item
  • Se o pedido não estiver associado a um pacote e a transação for realizada no modo “acordar com o vendedor”, você não receberá mais o status to be agreed, mas diretamente o shipping ID virá como null. Isso indicará que você deve entrar em contato com o comprador para coordenar o método de envio.
Nota:
  • Tenha em mente que o array "stock" e seus atributos serão exibidos assim que os fluxos de Stock Distribuído e Multiorigem estiverem ativos, e sua implementação será realizada de maneira progressiva à medida que os mesmos avançarem.
  • O array "coupon" será depreciado em breve, por isso recomendamos que você consulte esses valores diretamente na API de /orders/$ORDER_ID/discounts.

Já tenho o produto

Este endpoint permite que o vendedor marque a disponibilidade de estoque ou "Já tenho o produto", permitindo despachar o produto quando estiver pronto.



Chamada:

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

Exemplo:

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

Resposta:

{                                                                                                              
    "status": 200                                                                                              
}

Códigos de estado de resposta:

Código Mensagem Descrição Possível Solução
200 - OK - Consulta bem-sucedida. -
403 - forbidden At least one policy returned UNAUTHORIZED O chamador não está autorizado a acessar o recurso. Validar access token.
404 - not_found Not found shipment with id. shipment_id não encontrado. Validar shipment_id.

Considerações:

  • Tenha em mente que esta funcionalidade só pode ser usada para ordens ME2.
  • Considere que está habilitada em países que têm a funcionalidade de manufacturing_time e ME2.