Manejo de Órdenes

Con el desembarco de esta nueva funcionalidad se verá un cambio en la estructura del JSON en el recurso Orders. La principal diferencia será que la información del envío ya no estará disponible aquí dentro, sino que solo estará el ID asociado, para luego ir a buscar la data complementaria al recurso /shipments.

Nota: Recuerda que para trabajar con el JSON actualizado, al hacer el GET deberás enviar el parámetro “x-format-new: true”.

El resto de la estructura del recurso seguirá funcionando de la misma manera, con algunas modificaciones que deberás tener en cuenta.

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

JSON previo

{
    "id": 1014059850,
    "date_created": "2015-10-23T16:51:28.000-04:00",
    "date_closed": "2015-10-23T16:53:23.000-04:00",
    "last_updated": "2017-01-11T10:10:01.000-04:00",
    "feedback": {
        "purchase": {
            "id": 9040293414049,
            "date_created": null,
            "fulfilled": null,
            "rating": null,
            "status": "inactive"
        },
        "sale": {
            "id": 9040293397904,
            "date_created": "2015-10-27T19:02:38.000-04:00",
            "fulfilled": true,
            "rating": "positive",
            "status": "active"
        }
    },
    "mediations": [
        
    ],
    "comments": null,
    "order_request": {
        "return": null,
        "change": null
    },
    "fulfilled": true,
    "shipping": {
        "id": 21491526998,
        "site_id": "MLM",
        "shipment_type": "shipping",
        "mode": "me2",
        "shipping_mode": "me2",
        "status": "delivered",
        "shipping_items": [
            {
                "id": "MLM688179011",
                "description": "Item de Test",
                "quantity": 1,
                "dimensions": "5.0x11.0x25.0,100.0"
            }
        ],
        "shipping_option": {
            "id": 100184113,
            "shipping_method_id": 111,
            "name": "Testing Method",
            "currency_id": "MXN",
            "list_cost": 7.89,
            "cost": 0,
            "estimated_handling_limit": {
                "date": "2015-10-26T00:00:00.000-02:00"
            },
            "estimated_delivery_final": {
                "date": "2015-11-26T00:00:00.000-02:00"
            },
            "estimated_delivery_limit": {
                "date": "2015-11-19T00:00:00.000-02:00"
            },
            "estimated_delivery_extended": {
                "date": "2015-11-03T00:00:00.000-02:00"
            },
            "estimated_delivery_time": {
                "type": "known_frame",
                "date": "2015-10-27T00:00:00.000-02:00",
                "shipping": 24,
                "handling": 24,
                "unit": "hour",
                "offset": {
                    "date": "2015-10-28T00:00:00.000-02:00",
                    "shipping": 24
                },
                "time_frame": {
                    "from": null,
                    "to": null
                },
                "pay_before": null
            }
        },
        "currency_id": "MXN",
        "receiver_address": {
            "id": 167418200,
            "address_line": "Test Street 123",
            "street_name": "Test Street",
            "street_number": "123",
            "comment": "apartamento 2",
            "zip_code": "343435",
            "city": {
                "id": "TUxNQ1RPTDc0Mzc",
                "name": "Toluca"
            },
            "state": {
                "id": "MX-MEX",
                "name": "Estado de Mexico"
            },
            "country": {
                "id": "MX",
                "name": "Mexico"
            },
            "neighborhood": {
                "id": null,
                "name": "Test"
            },
            "municipality": {
                "id": null,
                "name": null
            },
            "types": [
                "default_buying_address",
                "billing"
            ],
            "latitude": -19.88,
            "longitude": -43.96,
            "geolocation_type": "ROOFTOP",
            "agency": null,
            "is_valid_for_carrier": true,
            "receiver_name": "Juan Garcia",
            "receiver_phone": "3131313131"
        },
        "sender_address": {
            "id": 73125800,
            "address_line": "Calle Sin Nombre 1234",
            "street_name": "Calle Sin Nombre",
            "street_number": "1234",
            "comment": "  ",
            "zip_code": "454545",
            "city": {
                "id": "TUxNQ1RPTDc0Mzc",
                "name": "Toluca"
            },
            "state": {
                "id": "MX-MEX",
                "name": "Estado de Mexico"
            },
            "country": {
                "id": "MX",
                "name": "Mexico"
            },
            "neighborhood": {
                "id": null,
                "name": "Test"
            },
            "municipality": {
                "id": null,
                "name": null
            },
            "types": [
                "billing",
                "default_buying_address",
                "shipping",
                "default_selling_address"
            ],
            "latitude": -19.87,
            "longitude": -43.95,
            "geolocation_type": "RANGE_INTERPOLATED",
            "agency": null,
            "is_valid_for_carrier": true
        },
        "picking_type": null,
        "cost": 0,
        "substatus": null,
        "date_created": "2015-10-23T16:53:13.000-04:00",
        "date_first_printed": "2015-10-26T09:26:31.000-04:00",
        "service_id": 23,
        "receiver_id": 121212121,
        "sender_id": 3434343434,
        "cost_components": {
            "special_discount": 0,
            "loyal_discount": 0,
            "compensation": 0
        }
    },
    "expiration_date": "2015-11-13T16:53:23.000-04:00",
    "status": "paid",
    "status_detail": null,
    "order_items": [
        {
            "item": {
                "id": "MLB688179011",
                "title": "Paleta Naked 2 - Urban Decay !!! Frete Grátis !!!",
                "category_id": "MLB182078",
                "variation_id": null,
                "seller_custom_field": null,
                "variation_attributes": [
                    
                ],
                "warranty": null,
                "condition": null
            },
            "quantity": 1,
            "unit_price": 79.99,
            "currency_id": "BRL"
        }
    ],
    "currency_id": "BRL",
    "buyer": {
        "id": 121212121,
        "nickname": "TESTMEX",
        "email": "testing+email@mercadolibre.com",
        "phone": {
            "area_code": null,
            "number": "011111111",
            "extension": "",
            "verified": false
        },
        "alternative_phone": {
            "area_code": "",
            "number": "",
            "extension": ""
        },
        "first_name": "Juan",
        "last_name": "Garcia",
        "billing_info": {
            "doc_type": "RFC",
            "doc_number": "ROHA944443AT5"
        }
    },
    "seller": {
        "id": 3434343434,
        "nickname": "TESTSELLER",
        "email": "seller+testing12@mercadolibre.com",
        "phone": {
            "area_code": null,
            "number": "( 54) 3456799",
            "extension": "",
            "verified": false
        },
        "alternative_phone": {
            "area_code": "",
            "number": "",
            "extension": ""
        },
        "first_name": "Raúl",
        "last_name": "Perez"
    },
    "payments": [
        {
            "id": 1347347348,
            "order_id": 1014059850,
            "payer_id": 3434343434,
            "collector": {
                "id": 67170474
            },
            "card_id": 157057223,
            "site_id": "MLM",
            "reason": "Item de Test",
            "payment_method_id": "test",
            "currency_id": "MXN",
            "installments": 6,
            "issuer_id": "24",
            "atm_transfer_reference": {
                "company_id": null,
                "transaction_id": null
            },
            "coupon_id": null,
            "activation_uri": null,
            "operation_type": "regular_payment",
            "payment_type": "credit_card",
            "available_actions": [
                
            ],
            "status": "approved",
            "status_code": "00",
            "status_detail": "accredited",
            "transaction_amount": 79.99,
            "shipping_cost": 0,
            "coupon_amount": 0,
            "overpaid_amount": 0,
            "total_paid_amount": 79.99,
            "installment_amount": 13.33,
            "deferred_period": null,
            "date_approved": "2015-10-23T16:53:21.000-04:00",
            "authorization_code": "631964",
            "transaction_order_id": "10617272430002CB367A",
            "date_created": "2015-10-23T16:53:22.000-04:00",
            "date_last_modified": "2017-01-11T10:10:14.000-04:00"
        }
    ],
    "coupon": {
        "id": null,
        "amount": 0
    },
    "tags": [
        "not_delivered",
        "paid"
    ],
    "total_amount": 79.99,
    "total_amount_with_shipping": 79.99,
    "paid_amount": 79.99
}

JSON nuevo

{
  "id": 1252867227,
  "date_created": "2016-12-29T11:14:00.000-04:00",
  "date_closed": "2016-12-29T11:17:07.000-04:00",
  "last_updated": "2016-12-29T11:37:59.000-04:00",
  "feedback": {
    "sale": null,
    "purchase": null
  },
  "mediations": [],
  "comments": null,
  "order_request": {
    "return": null,
    "change": null
  },
  "fulfilled": null,
  "shipping": {
    "id": 25851291671
  },
  "expiration_date": "2017-01-19T11:17:07.000-04:00",
  "status": "confirmed",
  "status_detail": null,
  "order_items": [
    {
      "item": {
        "id": "MLM571544424",
        "title": "Item De Testeo Por Favor No Ofertar",
        "category_id": "MLM1915",
        "variation_id": null,
        "seller_custom_field": null,
        "variation_attributes": [],
        "warranty": null,
        "condition": "used"
      },
      "quantity": 1,
      "unit_price": 100,
      "currency_id": "MXN"
    }
  ],
  "currency_id": "MXN",
  "buyer": {
    "id": 226104627,
    "nickname": "TETE582019",
    "email": "ttest.f1d92q3+2-ogezdkmrygy3tenjx@mail.mercadolibre.com.mx",
    "phone": {
      "area_code": "01",
      "number": "1111-1111",
      "extension": "",
      "verified": false
    },
    "alternative_phone": {
      "area_code": "",
      "number": "",
      "extension": ""
    },
    "first_name": "Test",
    "last_name": "Test",
    "billing_info": {
      "doc_type": null,
      "doc_number": null
    }
  },
  "seller": {
    "id": 226080093,
    "nickname": "TETE8781491",
    "email": "ttest.zxwryc+2-ogezdkmrygy3tenjx@mail.mercadolibre.com.mx",
    "phone": {
      "area_code": "01",
      "number": "1111-1111",
      "extension": "",
      "verified": false
    },
    "alternative_phone": {
      "area_code": "",
      "number": "",
      "extension": ""
    },
    "first_name": "Test",
    "last_name": "Test"
  },
  "payments": [
    {
      "id": 2515202115,
      "order_id": 1252867227,
      "payer_id": 226104627,
      "collector": {
        "id": 226080093
      },
      "card_id": null,
      "site_id": "MLM",
      "reason": "Item De Testeo Por Favor No Ofertar",
      "payment_method_id": "account_money",
      "currency_id": "MXN",
      "installments": null,
      "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": [],
      "status": "refunded",
      "status_code": null,
      "status_detail": "bpp_covered",
      "transaction_amount": 100,
      "shipping_cost": 0,
      "coupon_amount": 0,
      "overpaid_amount": 0,
      "total_paid_amount": 100,
      "installment_amount": null,
      "deferred_period": null,
      "date_approved": "2016-12-29T11:17:05.000-04:00",
      "authorization_code": null,
      "transaction_order_id": null,
      "date_created": "2016-12-29T11:17:05.000-04:00",
      "date_last_modified": "2016-12-29T11:37:59.000-04:00"
    }
  ],
  "coupon": {
    "id": null,
    "amount": 0
  },
  "tags": [
    "pack_order",
    "not_paid"
  ],
  "total_amount": 100,
  "total_amount_with_shipping": 100,
  "paid_amount": 0
}


Para entender a qué hace referencia cada uno de los parámetros realiza la siguiente llamada:

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

Revisa la documentación de Recurso de Órdenes para ver más información.

Consideraciones:

  • El tag “pack_order” se genera de manera automática para poder discriminar si la orden está asociada a un carrito y no podrá ser borrado por el comprador o el vendedor.
  • En caso que la orden no esté asociada a un Carrito de Compras y la transacción sea bajo la modalidad “acordar con el vendedor”, ya no recibirás un status to be agreed si no que directamente el shipping ID vendrá como nule. Eso te dará la pauta de que deberás entrar en contacto con el comprador para coordinar la forma de envío.
  • Solo contarás con el ID del envío, para luego ir a buscar la información a los nuevos recursos de Shipping.
  • Existe la posibilidad de que, aún existiendo una orden, el envío demore en crearse. En esos casos el ID será nulo hasta su creación. Cuando eso pase, serás notificado.
  • El costo del envío, que se encuentra en el campo “shipping_cost”, de una orden asociada a un carrito siempre será 0 ya que no se asociará a la orden sino al paquete que contiene todos los ítems.
    Por ende, el “total_amount_with_shipping” será idéntico al “total_amount”
  • Los tags “delivered/not delivered” ya no se agregarán automáticamente. Solamente existirá la marca si el integrador realiza un PUT con el tag definido.
  • Las órdenes en status paid se cancelarán si se rechaza o devuelve el pago. Si sucede, recibirás una notificación para que puedas conocer el cambio en el estado de la orden.


Siguiente: Manejo de envíos.

Por favor califica del 1 al 5