Gerenciamento de Envios

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

→Consultar envios
→Itens associados a um envio
→Costs
    ↳Parâmetros
→Pagos de um envio
→Prazos de entrega (Handling time)
→Campos da resposta
→Envios com atraso
→History
→Status e substatus Front X API
→Informações de rastreio
→Informações sobre status e substatus
→Itens não combináveis


É 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:


Consultar envios

Nota:
Você pode acessar as informações sobre os diferentes tipos de logística no Mercado Envios 2.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/shipment_id
{
  "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:

curl -X OPTION -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/shipment_id
Nota:
external_reference faz referência ao número de pack relacionado com o envio.


Itens associados a um envio

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.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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.

Nota:
Durante a implementação das mudanças, se manterá a resposta atual de shipments.api costs em paralelo e para acessar o novo formato, deverá ser utilizado o header "X-Costos-New = true".
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/SHIPMENT_ID/costs
{
  "gross_amount": 24.55,
  "receiver": {
      "user_id": 74425755,
      "cost": 0,
      "compensation": 0,
      "save": 0,
      "discounts": [
          {
              "rate": 1,
              "type": "loyal",
              "promoted_amount": 4.07
          }
        ]
  },
  "senders": [
      {
          "user_id": 81387353,
          "cost": 8.19,
          "compensation": 0,
          "save": 0,
          "discounts": [
              {
                  "rate": 0.6,
                  "type": "mandatory",
                  "promoted_amount": 12.29
              }
          ]
      }
  ]
}

Parâmetros

    gross_amount: É o custo total do shipment sem nenhum tipo de desconto.
    discounts: representa os descontos aplicados para o comprador (receiver) e para o vendedor (sender), e a lista virá vazia caso não tenha descontos.
    senders: é uma lista que representa os valores pagos pelo vendedor (sender), e um só envio poderá conter produtos de diferentes vendedores.
    cost: representa o custo final do envio que corresponde ao comprador (receiver) e ao vendedor (sender).


    Pagos de um envio

    O recurso /shipments/shipment_id/payments retorna os payments associado ao frete. Lembre-se que agora o pagamento do envio será discriminado.

    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/payments

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/1111111111/payments

    Resposta:

    [
       {
           "payment_id": 1111111111,
           "user_id": 291760105,
           "amount": 17.7,
           "status": "approved"
       }
    ]


    Prazos de entrega (Handling time)

    O recurso /shipments/$SHIPMENT_ID/lead_time devolve tudo relacionado ao prazo de entrega de um envío e tipo de serviço, somando os prazos de despacho e entrega. Embora o recurso de base de shipment já traga informações úteis para fazer estas estimativas, aqui você poderá visualizá-las de forma mais detalhada, o que ajudará a proporcionar uma melhor experiência para o usuário.

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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",
      ]
    }
    

    O campo cost_type pode ser "free", "charged" ou "partially_free".


    Campos da resposta

    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.


    Envios com atraso

    Agora temos um recurso que possibilita reconhecer os envios com atraso.

    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/{shipment_id}/delays

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/30143583389/delays

    Resposta:

    {
    	"shipment_id": 30143583389,
    	"delays": [{
    		"type": "handling_delayed",
    		"date": "2020-09-23T09:07:20Z",
    		"source": "shipping-delays"
    	}]
    }
    Importante:
    Quando o envio não tiver atraso será retornado o erro 404 com a seguinte mensagem "Delays Not Found for shipment".


    History

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

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/shipment_id/history
    
    [
      {
        "status": "string",
        "substatus": "string",
        "date": "2016-12-30T12:32:35.000Z"
      }
    ]

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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"
      },
    
    ]


    Status e substatus Front X API

    Lembre-se que os status podem mudar de acordo com o tipo de logística.


    Tracking para Cross Docking

    Front Descrição API - "status_history"
    "Em preparação" "Estamos preparando o seu pacote" status: handling
    "A caminho" "O vendedor enviou o seu pacote" status: ready_to_ship
    substatus: picked_up, authorized_by_carrier
    "Recebido no centro de distribuição de ....." status: ready_to_ship
    substatus: in_hub
    "Entregue" "Entregamos o pacote" status: delivered

    Tracking para Fulfillment

    Front Descrição API - "status_history"
    "Em preparação" "Estamos preparando o pacote" status: handling
    "A caminho" "Saiu do centro de distribuição" status: shipped
    "Entregue" "Entregamos o pacote" status: delivered

    Informações de rastreio

    O recurso /shipments/shipment_id/carrier devolver o nome e o URL para acessar as informações específicas da rastreio que está gerenciando o envio.

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/shipment_id/carrier
    
      {
              "url": "string",
              "name": "string"
    
      }

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/27691621451/carrier
    
    {
         "url":"http://tracking.totalexpress.com.br/poupup_track.php?reid=3&pedido=14&nfiscal=1",
    "name":"Total Express"
    }

    Informações sobre status e substatus

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

    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipment_statuses

    Resposta:

    {
        "id": "to_be_agreed",
        "name": "To be agreed",
        "substatuses": [
        ]
      },
      {
        "id": "pending",
        "name": "Pending",
        "substatuses": [
          {
            "id": "cost_exceeded",
            "name": "Cost exceeded"
          }
        ]
      },
      {
        "id": "handling",
        "name": "Handling",
        "substatuses": [
          {
            "id": "regenerating",
            "name": "Regenerating"
          },
          {
            "id": "waiting_for_label_generation",
            "name": "Waiting for label generation"
          }
        ]
      },
      {
        "id": "ready_to_ship",
        "name": "Ready to ship",
        "substatuses": [
          {
            "id": "ready_to_print",
            "name": "Ready to print"
          },
          {
            "id": "invoice_pending",
            "name": "Invoice pending"
          },
          {
            "id": "printed",
            "name": "Printed"
          },
          {
            "id": "in_pickup_list",
            "name": "In pikcup list"
          },
          {
            "id": "ready_for_pkl_creation",
            "name": "Ready for pkl creation"
          },
          {
            "id": "ready_for_pickup",
            "name": "Ready for pickup"
          },
          {
            "id": "picked_up",
            "name": "Picked up"
          },
          {
            "id": "stale",
            "name": "Stale Ready To Ship"
          },
          {
            "id": "in_hub",
            "name": "In hub"
          },
          {
            "id": "measures_ready",
            "name": "Measures and weight ready"
          },
          {
            "id": "waiting_for_carrier_authorization",
            "name": "Waiting for carrier authorization"
          },
          {
            "id": "authorized_by_carrier",
            "name": "Authorized by carrier"
          },
          {
            "id": "in_plp",
            "name": "In PLP"
          }
        ]
      },
      {
        "id": "shipped",
        "name": "Shipped",
        "substatuses": [
          {
            "id": "delayed",
            "name": "Delayed"
          },
          {
            "id": "waiting_for_withdrawal",
            "name": "Waiting for withdrawal"
          },
          {
            "id": "contact_with_carrier_required",
            "name": "Contact with carrier required"
          },
          {
            "id": "receiver_absent",
            "name": "Receiver absent"
          },
          {
            "id": "reclaimed",
            "name": "Reclaimed"
          },
          {
            "id": "not_localized",
            "name": "Not localized"
          },
          {
            "id": "forwarded_to_third",
            "name": "Forwarded to third party"
          },
          {
            "id": "soon_deliver",
            "name": "Soon deliver"
          },
          {
            "id": "refused_delivery",
            "name": "Delivery refused"
          },
          {
            "id": "bad_address",
            "name": "Bad address"
          },
          {
            "id": "negative_feedback",
            "name": "Stale shipped with negative feedback by buyer"
          },
          {
            "id": "need_review",
            "name": "Need to review carrier status to understand what happened"
          },
          {
            "id": "stale",
            "name": "Stale shipped"
          }
        ]
      },
      {
        "id": "delivered",
        "name": "Delivered",
        "substatuses": [
          {
            "id": "damaged",
            "name": "damaged"
          },
          {
            "id": "fulfilled_feedback",
            "name": "Fulfilled by buyer feedback"
          },
          {
            "id": "no_action_taken",
            "name": "No action taken by buyer"
          },
          {
            "id": "double_refund",
            "name": "Double Refund"
          }
        ]
      },
      {
        "id": "not_delivered",
        "name": "Not delivered",
        "substatuses": [
          {
            "id": "returning_to_sender",
            "name": "Returning to sender"
          },
          {
            "id": "retained",
            "name": "Retained"
          },
          {
            "id": "stolen",
            "name": "Stolen"
          },
          {
            "id": "returned",
            "name": "Returned"
          },
          {
            "id": "receiver_absent",
            "name": "Receiver absent"
          },
          {
            "id": "confiscated",
            "name": "confiscated"
          },
          {
            "id": "to_review",
            "name": "Closed shipment"
          },
          {
            "id": "destroyed",
            "name": "Destroyed"
          },
          {
            "id": "waiting_for_withdrawal",
            "name": "Waiting for withdrawal"
          },
          {
            "id": "negative_feedback",
            "name": "Stale shipped forced to not delivered due to negative feedback by buyer"
          },
          {
            "id": "claimed_me",
            "name": "Stale shipped with claim that was forced to not delivered"
          },
          {
            "id": "not_localized",
            "name": "Not localized"
          },
          {
            "id": "double_refund",
            "name": "Double Refund"
          }
        ]
      },
      {
        "id": "not_verified",
        "name": "Not verified",
        "substatuses": [
        ]
      },
      {
        "id": "cancelled",
        "name": "Cancelled",
        "substatuses": [
        ]
      },
      {
        "id": "closed",
        "name": "Closed",
        "substatuses": [
        ]
      },
      {
        "id": "error",
        "name": "Error",
        "substatuses": [
        ]
      },
      {
        "id": "active",
        "name": "Active",
        "substatuses": [
        ]
      },
      {
        "id": "not_specified",
        "name": "Not specified",
        "substatuses": [
        ]
      },
      {
        "id": "stale_ready_to_ship",
        "name": "Stale ready to ship",
        "substatuses": [
        ]
      },
      {
        "id": "stale_shipped",
        "name": "Stale shipped",
        "substatuses": [
        ]
      }


    Itens não combináveis

    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.

    Chamada:

    curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -d
    {
      "shipments": [
        {
          "reason": "text",
                       "description": "text"
          "orders": [
            {
              "id": "order_id",
    
            }
          ]
        }
      ]
    }
    https://api.mercadolibre.com/shipments/$SHIPMENT_ID/split


    Valores possíveis no campo "reason"

    • fragile
    • another_warehouse
    • irregular_shape
    • other_motive
    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.

    Importante:
    Para mais informações acesse os Modos de Envios.

    Seguinte: Pagamentos.

ou registre-se para receber as últimas notícias sobre nossa API