Gestão de packs

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.

Saiba mais sobre:

• Como uso a garantia estendida?
• Como estender a garantia de um produto?
• Como cancelo a garantia estendida?

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:

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.
• coupon: Informações sobre o cupom utilizado no pedido, incluindo:
  • id: Um identificador do cupom associado ao pedido.
  • amount: O valor do desconto aplicado pelo cupom.
• 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:

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.

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:

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.