Gerenciamento de Envios

A chegada do Carrinho de Compras traz mudanças nos principais recursos da nossa API. Uma delas, o recurso de Shipments, contém todas as informações relacionadas ao envio que deve ser realizado para finalizar a transação.

Nota: Lembre que, para trabalhar com o JSON de shipments, ao fazer o GET, você deverá enviar o parâmetro “x-format-new: true”.

Conteúdo:

É importante lembrar que o novo JSON de Orders não vai mais conter os dados de Shipping, como tem sido até agora.
O recurso /shipments/shipment_id/ continuará tendo sua estrutura, mostrando as informações básicas para a realização do envio.
Introduzimos algumas mudanças na estrutura do JSON, que você pode ver abaixo:

GET https://api.mercadolibre.com/shipments/shipment_id?access_token=token
{
  "id": 0,
  "external_reference": "string",
   "status": "string",
  "substatus": "string",
  "date_created": "string",
  "last_updated": "string",
  "declared_value": 0,
  "dimensions": {
    "height": 0,
    "width": 0,
    "length": 0,
    "weight": 0
  },
  "logistic": {
    "direction": "forward",
    "mode": "me2",
    "type": "drop_off"
  },
  "source": {
    "site_id": "MLM",
    "market_place": "MELI",
    "application_id": null
  },
  "tracking_number": "string",
  "origin": {
    "type": "selling_address",
    "sender_id": 0,
    "shipping_address": {
      "id": 0,
      "address_id": 0,
      "address_line": "string",
      "street_name": "string",
      "street_number": 0,
      "comment": "string",
      "zip_code": "string",
      "city": {
        "id": "string",
        "name": "string"
      },
      "state": {
        "id": "string",
        "name": "string"
      },
      "country": {
        "id": "string",
        "name": "string"
      },
      "neighborhood": {
        "id": "string",
        "name": "string"
      },
      "municipality": {
        "id": "string",
        "name": "string"
      },
      "types": {
        "default_buying_address": 0
      },
      "agency": {
        "carrier_id": 0,
        "agency_id": "string",
        "description": "string",
        "phone": "string",
        "open_hours": "string"
      },
      "latitude": 0,
      "longitude": 0,
      "geolocation_type": "string",
      "is_valid_for_carrier": true
    }
  },
  "destination": {
    "type": "buying_address",
    "receiver_id": 0,
    "receiver_name": "string",
    "receiver_phone": "string",
    "comments": "string",
    "shipping_address": {
      "id": 0,
      "address_id": 0,
      "address_line": "string",
      "street_name": "string",
      "street_number": 0,
      "comment": "string",
      "zip_code": "string",
      "city": {
        "id": "string",
        "name": "string"
      },
      "state": {
        "id": "string",
        "name": "string"
      },
      "country": {
        "id": "string",
        "name": "string"
      },
      "neighborhood": {
        "id": "string",
        "name": "string"
      },
      "municipality": {
        "id": "string",
        "name": "string"
      },
      "types": {
        "default_buying_address": 0
      },
      "agency": {
        "carrier_id": 0,
        "agency_id": "string",
        "description": "string",
        "phone": "string",
        "open_hours": "string"
      },
      "latitude": 0,
      "longitude": 0,
      "geolocation_type": "string",
      "is_valid_for_carrier": true
    }
  },
  "lead_time": {
    "option_id": 0,
    "shipping_method": {
      "id": 0,
      "type": "standard",
      "name": "string",
      "deliver_to": "address"
    },
    "currency_id": "string",
    "cost": 0,
    "cost_type": "charged",
    "service_id": 0,
    "estimated_delivery_time": {
      "type": "known",
      "date": "string",
      "shipping": 0,
      "handling": 0,
      "unit": "string",
      "offset": {
        "date": "string",
        "shipping": 0
      },
      "time_frame": {
        "from": 0,
        "to": 0
      },
      "pay_before": "string"
    }
  },
  "tags": [
    "string"
  ]
}

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

GET https://api.mercadolibre.com/shipments/shipment_id?options&access_token=token

Novos recursos

Com a nova versão do recurso Shipments, há novos recursos complementares que trarão informações detalhadas para poder trabalhar de maneira mais eficiente. A seguir, ampliamos cada um deles.
Ver api docs de recursos existentes.

Itens

O recurso /shipments/shipment_id/items retorna os itens associados a um shipment. Caso o item contenha variações (Por exemplo, tamanho ou cor em vestuário), você também poderá ver qual corresponde à ordem dentro do envio. À medida que envios com mais de um item forem sendo habilitados, a lista passará a conter cada um deles.
Nota: Cada vendedor só visualizará seus próprios produtos.

GET https://api.mercadolibre.com/shipments/shipment_id/items

[
  {
    "item_id": "string",
    "description": "string",
    "quantity": 0,
    "variation_id": 0,
    "dimensions": {
      "height": 0,
      "width": 0,
      "length": 0,
      "weight": 0
    },
    "order_id": 0,
    "sender_id": 0
  }
]

Costs

O recurso /shipments/shipment_id/costs retorna os custos do envio a serem pagos pelo usuário.
Também poderá ser visualizada a economia atingida pelo envio de mais de um produto na mesma caixa (quando esta funcionalidade estiver habilitada), através do parâmetro “save”, caso exista.

GET https://api.mercadolibre.com/shipments/shipment_id/costs
{
    "receiver": {
    "user_id": 123,
    "cost": 100,
    "discount": {
      "rate": 0,
      "type": "string",
      "promoted_amount": 0
    },
    "compensation": 0,
    "save": 0
  },
  "senders": [
    {
      "user_id": 321,
      "cost": 0,
      "discount": {
        "rate": 0,
        "type": "string",
        "promoted_amount": 0
      },
      "compensation": 0,
      "save": 0
    }
  ]
}

Lead Time

O recurso /shipments/shipment_id/lead_time retorna tudo o referido a prazos de entrega de um envio e tipo de serviço, adicionando datas-limite de encaminhamento e entrega.
Embora o recurso de shipment já contenha informações úteis para fazer essas estimativas, aqui você poderá visualizá-lo de forma mais detalhada, ajudando a oferecer uma melhor experiência ao usuário.

GET https://api.mercadolibre.com/shipments/shipment_id/lead_time
{
  "option_id": 0,
  "shipping_method": {
    "id": 0,
    "type": "standard",
    "name": "string",
    "deliver_to": "address"
  },
  "currency_id": "string",
  "cost": 0,
  "cost_type": "charged",
  "service_id": 0,
  "estimated_delivery_time": {
    "type": "known",
    "date": "string",
    "shipping": 0,
    "handling": 0,
    "unit": "string",
    "offset": {
      "date": "string",
      "shipping": 0
    },
    "time_frame": {
      "from": 0,
      "to": 0
    },
    "pay_before": "string"
  },
  "estimated_handling_limit": {
    "date":  "2016-12-30T12:32:35.000Z"
  },
  "estimated_delivery_extended": {
    "date":  "2016-12-30T12:32:35.000Z"
  },
  "estimated_delivery_limit": {
    "date":  "2016-12-30T12:32:35.000Z"
  },
  "estimated_delivery_final": {
    "date":  "2016-12-30T12:32:35.000Z"
  },
  "delay": [
    "shipping_delayed",
  ]
}

Nota: lembre que o campo cost_type pode ser “free”, “charged” ou “partially_free”.

Descrição dos tempos de estimativa

São as datas-limite para o envio ser encaminhado e enviado.

estimated_handling_limit: Data-limite para o vendedor encaminhar.

estimated_delivery_extended: Segunda promessa de entrega, caso a primeira não tenha sido atendida.

estimated_delivery_limit: Data-limite para o comprador cancelar a compra e pedir a devolução de dinheiro, desde que o envio ainda não tenha chegado.

estimated_delivery_final: Data final para a chegada do envio e para determinação do status final, que pode ser delivered ou, caso haja alguma reclamação, not_delivered.

Ver mais informações sobre tipos de promessa de entrega.

History

O recurso /shipments/shipment_id/history retorna o histórico de status e substatus associados ao ciclo de vida do shipment.

GET https://api.mercadolibre.com/shipments/shipment_id/history

[
  {
    "status": "string",
    "substatus": "string",
    "date": "2016-12-30T12:32:35.000Z"
  }
]

Exemplo:

https://api.mercadolibre.com/shipments/1234567899/history

[
  {
    "status": "ready_to_ship",
    "substatus": "printed",
    "date":  "2016-12-30T12:32:35.000Z"
  },
  {
    "status": "handling",
    "substatus": "waiting_for_label_generation",
    "date":  "2016-12-30T12:32:35.000Z"
  },

]

Ver informações sobre status e substatus pelos que um envio pode passar.

Payments

O recurso /shipments/shipment_id/payments retorna os payments associados ao envio.
Lembre que agora o pagamento do envio será discriminado e você poderá, a partir deste recurso, consumir informações básicas sobre ele. O payment_id funciona da mesma forma que o de uma ordem.

GET https://api.mercadolibre.com/shipments/shipment_id/payments
[
  {
    "payment_id": 0,
    "amount": 0,
    "status": "string"
  }
]

Parâmetros disponíveis

A seguir, mostramos os valores disponíveis para cada parâmetro:
logistic.direction: forward, return
logistic.mode: me2, me1, custom
logistic.type: default, drop_off, xd_drop_off, cross_docking, fulfillment


source.site_id: sites
source.market_place: Mercado Livre, OFF


lead_time.shipping_method.type: next_day, express, standard, same_day
lead_time.shipping_method.deliver_to: address, agency


lead_time.currency_id: currencies
lead_time.cost_type: free, partially_free, charged


lead_time.delay: handling_delayed, shipping_delayed, shipping_delayed_extended


destination/origin.type: agency, buying_address, selling_address


discount.type: loyal, special



Seguinte: Gerenciamento de Pagamentos.

Qualifique entre 1 e 5