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. Considere que apenas é levada em conta a data, pois a hora é informada somente para manter uma estrutura. Isto é, você tem todo o dia informado no campo para realizar o envio antes de este ser marcado como demorado para o dia seguinte.

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

Itens não combináveis (nova funcionalidade)

No caso em que você tenha um problema no momento de agrupar diferentes produtos em um mesmo pacote (seja porque estão em depósitos diferentes, ou são frágeis, ou não entram em uma mesma caixa, etc) você pode utilizar o recurso que te permite gerar pacotes adicionais para poder despachar todos os produtos.

Exemplo:

POST https://api.mercadolibre.com/shipments/shipment_id/split?access_token=token

JSON:

	{
  "shipments": [
    {
      "reason": "text",
                   “description”: “text”
      "orders": [
        {
          "id": "order_id",

        }
      ]
    }
  ]
}

Tenha em conta que esse recurso é para evitar problemas na hora de empacotar os produtos mas não deve ser usada em todos os casos. Somente em casos de extrema necessidade. Mais pra frente estaremos melhorando esse processo.

Valores possíveis no campo “reason”

  • different_warehouse
  • fragile
  • shape
  • other_reason

Notas:

  • O “order_ID” acima se refere ao produto a ser retirado do “Shipping” original.
  • Um novo shipping será gerado contendo o order ID acima.
  • A API não irá devolver nenhuma resposta após esta chamada somente o status 201.
  • Deve-se escutar via notificações se existe algum novo shipping e fazer o GET deste novo.



Seguinte: Gerenciamento de Pagamentos.

Please rate this