Gerenciamento de Ordens de Carrinho

Com a chegada desta nova funcionalidade, haverá uma mudança na estrutura do JSON no recurso Orders. A diferença principal será que as informações de envio não estarão mais disponíveis dentro dele, só estará disponível o ID associado, para depois procurar as informações complementares no recurso /shipments.
Nota: Lembre que, para trabalhar com o JSON atualizado, ao fazer o GET, você deverá enviar o parâmetro "x-format-new: true". O restante da estrutura do recurso continuará funcionando da mesma forma, com algumas alterações que você deverá levar em conta.

curl -X GET -H x-format-new: true https://api.mercadolibre.com/orders/order_id?access_token=ACCESS_TOKEN

JSON prévio

{
    "id": 2053577644,
    "date_created": "2019-06-13T09:20:02.000-04:00",
    "date_closed": "2019-06-13T09:20:08.000-04:00",
    "last_updated": "2019-06-13T09:20:08.000-04:00",
    "manufacturing_ending_date": null,
    "feedback": {
        "sale": null,
        "purchase": null
    },
    "mediations": [],
    "comments": null,
    "pack_id": 2000000101334825,
    "pickup_id": null,
    "order_request": {
        "return": null,
        "change": null
    },
    "fulfilled": null,
    "total_amount": 9.99,
    "total_amount_with_shipping": 20.04,
    "paid_amount": 20.04,
    "coupon": {
        "id": null,
        "amount": 0
    },
    "expiration_date": "2019-07-11T09:20:08.000-04:00",
    "order_items": [
        
            "item": {
                "id": "MLB1226730704",
                "title": "Produto Teste - Não Ofertar",
                "category_id": "MLB11742",
                "variation_id": null,
                "seller_custom_field": null,
                "variation_attributes": [],
                "warranty": "12 months",
                "condition": "new",
                "seller_sku": null
            },
            "quantity": 1,
            "unit_price": 9.99,
            "full_unit_price": 9.99,
            "currency_id": "BRL",
            "manufacturing_days": null
        
    ],
    "currency_id": "BRL",
    "payments": [
        
            "id": 4863317779,
            "order_id": 2053577644,
            "payer_id": 419067349,
            "collector": {
                "id": 419059118
            },
            "card_id": null,
            "site_id": "MLB",
            "reason": "Produto Teste - Não Ofertar",
            "payment_method_id": "account_money",
            "currency_id": "BRL",
            "installments": 1,
            "issuer_id": null,
            "atm_transfer_reference": {
                "company_id": null,
                "transaction_id": null
            },
            "coupon_id": null,
            "activation_uri": null,
            "operation_type": "regular_payment",
            "payment_type": "account_money",
            "available_actions": [
                "refund"
            ],
            "status": "approved",
            "status_code": null,
            "status_detail": "accredited",
            "transaction_amount": 9.99,
            "taxes_amount": 0,
            "shipping_cost": 0,
            "coupon_amount": 0,
            "overpaid_amount": 0,
            "total_paid_amount": 9.99,
            "installment_amount": null,
            "deferred_period": null,
            "date_approved": "2019-06-13T09:20:07.000-04:00",
            "authorization_code": null,
            "transaction_order_id": null,
            "date_created": "2019-06-13T09:20:07.000-04:00",
            "date_last_modified": "2019-06-13T09:20:07.000-04:00"
        },
        
            "id": 4863151808,
            "order_id": 2053577644,
            "payer_id": 419067349,
            "collector": {
                "id": 419059118
            },
            "card_id": null,
            "site_id": "MLB",
            "reason": "marketplace_shipment",
            "payment_method_id": "account_money",
            "currency_id": "BRL",
            "installments": 1,
            "issuer_id": null,
            "atm_transfer_reference": {
                "company_id": null,
                "transaction_id": null
            },
            "coupon_id": null,
            "activation_uri": null,
            "operation_type": "regular_payment",
            "payment_type": "account_money",
            "available_actions": [
                "refund"
            ],
            "status": "approved",
            "status_code": null,
            "status_detail": "accredited",
            "transaction_amount": 10.05,
            "taxes_amount": 0,
            "shipping_cost": 0,
            "coupon_amount": 0,
            "overpaid_amount": 0,
            "total_paid_amount": 10.05,
            "installment_amount": null,
            "deferred_period": null,
            "date_approved": "2019-06-13T09:20:07.000-04:00",
            "authorization_code": null,
            "transaction_order_id": null,
            "date_created": "2019-06-13T09:20:07.000-04:00",
            "date_last_modified": "2019-06-13T09:20:07.000-04:00"
        
    ],
    "shipping": {
        "id": 27987243797,
        "site_id": "MLB",
        "shipment_type": "shipping",
        "mode": "me1",
        "shipping_mode": "me1",
        "status": "pending",
        "substatus": "shipment_paid",
        "date_created": "2019-06-13T09:20:03.000-04:00",
        "receiver_address": {
            "id": 1036317458,
            "address_line": "Rua Direita 123, ",
            "street_name": "Rua Direita",
            "street_number": "123",
            "comment": null,
            "zip_code": "04567000",
            "city": {
                "id": "BR-SP-44",
                "name": "São Paulo"
            },
            "state": {
                "id": "BR-SP",
                "name": "São Paulo"
            },
            "country": {
                "id": "BR",
                "name": "Brasil"
            },
            "neighborhood": {
                "id": null,
                "name": "Centro"
            },
            "municipality": {
                "id": null,
                "name": null
            },
            "agency": null,
            "types": [
                "default_buying_address"
            ],
            "latitude": -23.729929,
            "longitude": -46.680368,
            "geolocation_type": "ROOFTOP",
            "receiver_name": "Teste Teste",
            "receiver_phone": "11999999999"
        },
        "sender_address": {
            "id": 1032937241,
            "address_line": "Rua de Teste 123",
            "street_name": "Rua da Teste",
            "street_number": "123",
            "comment": null,
            "zip_code": "05678100",
            "city": {
                "id": "BR-SP-44",
                "name": "São Paulo"
            },
            "state": {
                "id": "BR-SP",
                "name": "São Paulo"
            },
            "country": {
                "id": "BR",
                "name": "Brasil"
            },
            "neighborhood": {
                "id": null,
                "name": "bairro teste"
            },
            "municipality": {
                "id": null,
                "name": null
            },
            "agency": null,
            "types": [
                "billing",
                "default_selling_address",
                "shipping"
            ],
            "latitude": -23.625124,
            "longitude": -46.744142,
            "geolocation_type": "ROOFTOP"
        },
        "currency_id": "BRL",
        "date_first_printed": null,
        "service_id": null,
        "shipping_items": [
            
                "id": "MLB1226730704",
                "description": "Produto Teste - Não Ofertar",
                "quantity": 1,
                "dimensions": "10.0x18.0x28.0,300.0",
                "dimensions_source": {
                    "id": "MLB11742",
                    "origin": "categories"
                
            
        ],
        "receiver_id": 419067349,
        "sender_id": 419059118,
        "shipping_option": {
            "id": 40000048146400001,
            "shipping_method_id": 182,
            "name": "Expresso",
            "currency_id": "BRL",
            "list_cost": 10.05,
            "cost": 10.05,
            "delivery_type": "estimated",
            "estimated_schedule_limit": {
                "date": null
            },
            "estimated_delivery_time": {
                "type": "known_frame",
                "date": "2019-06-18T00:00:00.000-03:00",
                "unit": "hour",
                "offset": {
                    "date": "2019-06-19T00:00:00.000-03:00",
                    "shipping": 24
                },
                "time_frame": {
                    "from": null,
                    "to": null
                },
                "pay_before": null,
                "shipping": 24,
                "handling": 48,
                "schedule": null
            },
            "estimated_delivery_limit": {
                "date": "2019-07-04T00:00:00.000-03:00",
                "offset": 240
            },
            "estimated_delivery_final": {
                "date": "2019-10-11T00:00:00.000-03:00",
                "offset": 1920
            },
            "estimated_delivery_extended": {
                "date": "2019-06-27T00:00:00.000-03:00",
                "offset": 120
            },
            "estimated_handling_limit": {
                "date": "2019-06-17T00:00:00.000-03:00"
            
        },
        "logistic_type": "default",
        "picking_type": null,
        "cost_components": {
            "special_discount": 0,
            "loyal_discount": 0,
            "compensation": 0,
            "gap_discount": 0,
            "ratio": 0
        },
        "cost": 10.05
    },
    "status": "paid",
    "status_detail": null,
    "tags": [
        "test_order",
        "pack_order",
        "not_delivered",
        "paid"
    ],
    "buyer": {
        "id": 419067349,
        "nickname": "TT763866",
        "email": "ttest.6hqmq6+2-ogiydkmzvg43tmobx@mail.mercadolivre.com",
        "phone": {
            "area_code": "01",
            "extension": "",
            "number": "1111-1111",
            "verified": false
        },
        "alternative_phone": {
            "area_code": "",
            "extension": "",
            "number": ""
        },
        "first_name": "Test",
        "last_name": "Test",
        "billing_info": {
            "doc_type": "CPF",
            "doc_number": "78525276200"
        
    },
    "seller": {
        "id": 419059118,
        "nickname": "TETE8288849",
        "email": "ttest.hpz2z6q+2-ogiydkmzvg43tmobs@mail.mercadolivre.com",
        "phone": {
            "area_code": "01",
            "extension": "",
            "number": "1111-1111",
            "verified": false
        },
        "alternative_phone": {
            "area_code": "",
            "extension": "",
            "number": ""
        },
        "first_name": "Test",
        "last_name": "Test"
    },
    "taxes": {
        "amount": null,
        "currency_id": null
    
}

 

JSON novo

{
    "id": 2053577644,
    "date_created": "2019-06-13T09:20:02.000-04:00",
    "date_closed": "2019-06-13T09:20:08.000-04:00",
    "last_updated": "2019-06-13T09:20:08.000-04:00",
    "manufacturing_ending_date": null,
    "feedback": {
        "sale": null,
        "purchase": null
    },
    "mediations": [],
    "comments": null,
    "pack_id": 2000000101334825,
    "pickup_id": null,
    "order_request": {
        "return": null,
        "change": null
    },
    "fulfilled": null,
    "total_amount": 9.99,
    "paid_amount": 9.99,
    "coupon": {
        "id": null,
        "amount": 0
    },
    "expiration_date": "2019-07-11T09:20:08.000-04:00",
    "order_items": [
        
            "item": {
                "id": "MLB1226730704",
                "title": "Produto Teste - Não Ofertar",
                "category_id": "MLB11742",
                "variation_id": null,
                "seller_custom_field": null,
                "variation_attributes": [],
                "warranty": "12 months",
                "condition": "new",
                "seller_sku": null
            },
            "quantity": 1,
            "unit_price": 9.99,
            "full_unit_price": 9.99,
            "currency_id": "BRL",
            "manufacturing_days": null
        
    ],
    "currency_id": "BRL",
    "payments": [
        
            "id": 4863317779,
            "order_id": 2053577644,
            "payer_id": 419067349,
            "collector": {
                "id": 419059118
            },
            "card_id": null,
            "site_id": "MLB",
            "reason": "Produto Teste - Não Ofertar",
            "payment_method_id": "account_money",
            "currency_id": "BRL",
            "installments": 1,
            "issuer_id": null,
            "atm_transfer_reference": {
                "company_id": null,
                "transaction_id": null
            },
            "coupon_id": null,
            "activation_uri": null,
            "operation_type": "regular_payment",
            "payment_type": "account_money",
            "available_actions": [
                "refund"
            ],
            "status": "approved",
            "status_code": null,
            "status_detail": "accredited",
            "transaction_amount": 9.99,
            "taxes_amount": 0,
            "shipping_cost": 0,
            "coupon_amount": 0,
            "overpaid_amount": 0,
            "total_paid_amount": 9.99,
            "installment_amount": null,
            "deferred_period": null,
            "date_approved": "2019-06-13T09:20:07.000-04:00",
            "authorization_code": null,
            "transaction_order_id": null,
            "date_created": "2019-06-13T09:20:07.000-04:00",
            "date_last_modified": "2019-06-13T09:20:07.000-04:00"
        
    ],
    "shipping": {
        "id": 27987243797
    },
    "status": "paid",
    "status_detail": null,
    "tags": [
        "test_order",
        "pack_order",
        "paid"
    ],
    "buyer": {
        "id": 419067349,
        "nickname": "TT763866",
        "email": "ttest.6hqmq6+2-ogiydkmzvg43tmobx@mail.mercadolivre.com",
        "phone": {
            "area_code": "01",
            "extension": "",
            "number": "1111-1111",
            "verified": false
        },
        "alternative_phone": {
            "area_code": "",
            "extension": "",
            "number": ""
        },
        "first_name": "Test",
        "last_name": "Test",
        "billing_info": {
            "doc_type": "CPF",
            "doc_number": "78525276200"
        
    },
    "seller": {
        "id": 419059118,
        "nickname": "TETE8288849",
        "email": "ttest.hpz2z6q+2-ogiydkmzvg43tmobs@mail.mercadolivre.com",
        "phone": {
            "area_code": "01",
            "extension": "",
            "number": "1111-1111",
            "verified": false
        },
        "alternative_phone": {
            "area_code": "",
            "extension": "",
            "number": ""
        },
        "first_name": "Test",
        "last_name": "Test"
    },
    "taxes": {
        "amount": null,
        "currency_id": null
    
}

Para entender a que refere cada um dos parâmetros, faça a seguinte chamada:

GET https://api.mercadolibre.com/orders/order_id?options&access_token=token

Revise a documentação de Recurso de Ordens para ver mais informações.


Considerações:

  • A tag "pack_order" é gerada automaticamente para poder discriminar se a ordem é associada a um carrinho e não poderá ser removida pelo comprador nem pelo vendedor.

  • O campo "pack_id" mostra o número do carrinho ao qual a ordem pertence.

  • Caso a ordem não esteja associada a um Carrinho de Compras e a transação seja sob a modalidade "combinar com o vendedor", você não receberá mais o status to be agreed, mas o shipping ID virá diretamente como nule. Isso indicará que você deve entrar em contato com o comprador para combinar a forma de envio.

  • Você só terá a ID do envio, e terá que procurar as informações nos novos recursos de Shipping.

  • Existe a possibilidade de que, ainda existindo uma ordem, o envio demore a ser criado. Nesses casos, a ID será nula até sua criação. Quando isso acontecer, você será notificado.

  • As tags “delivered/not delivered” não serão mais adicionadas automaticamente. Somente existirá a marca caso o integrador realize um PUT com a tag definida.

  • As ordens em status paid serão canceladas se o pagamento for rejeitado ou devolvido. Caso isso aconteça, você receberá uma notificação para poder conhecer a alteração no status da ordem.

  • Leve em conta que a Ordem continuará mostrando o campo "seller_custom_field", mas apresentará a informação de SKU. 1- SELLER_SKU de atributos de variação 2- seller_custom_field de variação 3- SELLER_SKU de atributos de item 4- seller_custom_field de item.


Seguinte: Gerenciamento de Envios.

Faça parte da nossa comunidade