Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 15/03/2023

Costos de envío y handling time

Los vendedores podrán utilizar la calculadora de envíos en la página de descripción del item y los compradores conocerán el costo de envío y el handling time.


Atributos de la calculadora

Destination (destino): Detalles del domicilio del receptor

Atributos:

  • zip_code (código postal): Código postal del destino.
  • city (ciudad): Información de la ciudad de destino.

    • id : ID de la ciudad de destino.
    name (nombre): Nombre de la ciudad de destino.

  • state (estado): Información del estado de destino.

    • id: ID del estado de destino.
    name (nombre): Nombre del estado de destino.

  • country (país): Información del país de destino.

    • id: ID del país de destino.
    name (nombre): Nombre del país de destino.

  • extended_attributes (atributos extendidos): Información adicional del domicilio de destino.

    • address (domicilio): Línea del domicilio de destino.
    owner_name (nombre del titular): Titular del domicilio de destino.
    zip_code_type (tipo de código postal): Información sobre el tipo de código postal de destino.
    - type (tipo): ID del tipo de código postal de destino.
    - Description (descripción): Nombre del tipo de código postal de destino.
    city_type (tipo de ciudad): ID del tipo de ciudad de destino.
    city_name (nombre de la ciudad) : Nombre de la ciudad de destino.
    version (versión): Versión interna de estos datos en la API de Códigos Postales.

Options (opciones): Colección de costos de envío para cada método de envío disponible.

Atributos:

  • id: ID de la regla de envío aplicada.
  • name (nombre): Nombre del método de envío.
  • currency_id (ID de moneda): ID de la moneda utilizada para mostrar los costos de envío.
  • list_cost (costo de publicación): Costos de envío reales; sin envío gratis aplicado.
  • cost (costo): Costo de envío final; se podría aplicar envío gratis.
  • tracks_shipments_status (seguimiento del estado de los envíos): Indica cómo se podrá realizar el seguimiento de este método.

    • verified (verificado): Se puede realizar el seguimiento a nivel interno.
    not_verified (no verificado): La información de seguimiento debe ser entregada por el vendedor.
    no: No se puede realizar seguimiento.

  • display (mostrar) : ID del método de envío para procesamiento frontend.

    • always (siempre): Se debe mostrar el método de envío.
    optional (opcional): Es posible no mostrar el método porque existe uno más rápido y económico.

  • speed (velocidad): Información de la velocidad de entrega.

    • shipping (envío): Horas promedio para el envío.
    handling (en manipulación): Horas promedio para que el vendedor despache el envío.


Costos de envío conforme a ítem y zip_code

Calcula los costos de envío para un ítem enviando solo los parámetros Item_id y zip_code (CP o CEP).

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/shipping_options?zip_code=$ZIP_CODE

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB2997181655/shipping_options?zip_code=06233903

Respuesta:

{
    "destination": {
        "zip_code": "06233903",
        "city": {
            "id": "BR-SP-31",
            "name": "Osasco"
        },
        "state": {
            "id": "BR-SP",
            "name": "São Paulo"
        },
        "country": {
            "id": "BR",
            "name": "Brasil"
        },
        "extended_attributes": {
            "address": "Avenida das Nações Unidas 3003",
            "zip_code_type": {
                "type": "GU",
                "description": "Grande Usuario"
            },
            "city_type": "CI",
            "city_name": "Osasco",
            "neighborhood": "Bonfim",
            "status": "active"
        }
    },
    "buyer": {
        "id": 0,
        "loyalty_level": 1,
        "shipping_level": "1"
    },
    "options": [
        {
            "id": 1423196752,
            "option_hash": "ae1bd0a2dbfe1358ec28585f4e432cae",
            "name": "Expresso",
            "currency_id": "BRL",
            "base_cost": 13.5,
            "cost": 0,
            "list_cost": 22.74,
            "display": "recommended",
            "shipping_method_id": 511948,
            "shipping_method_type": "sedex",
            "shipping_option_type": "address",
            "estimated_delivery_time": {
                "type": "known_frame",
                "date": "2022-12-01T00:00:00-03:00",
                "unit": "hour",
                "offset": {
                    "date": "2022-12-05T00:00:00-03:00",
                    "shipping": 48
                },
                "time_frame": {
                    "from": null,
                    "to": null
                },
                "pay_before": "2022-11-29T00:00:00-03:00",
                "shipping": 24,
                "handling": 48,
                "schedule": null
            },
            "discount": {
                "promoted_amount": 13.5,
                "rate": 1,
                "type": "ratio",
                "show_loyal_benefit": false
            }
        }
    ],
    "custom_message": {
        "display_mode": null,
        "reason": ""
    },
    "app_version": "2.1"
}
Nota:
La misma llamada puede ser utilizada para calcular los costos de envío para los sites de Argentina y México.

Costos de envío conforme a item y ciudad en MCO

Calcula los costos de envío para un item enviando solo los parámetros Item_id y City_to.

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MCO415774919/shipping_options?city_to=Q08tRENCb2dvdA

Respuesta:

{
  "destination": {
	"zip_code": null,
	"city": {
      "id": "Q08tRENCb2dvdA",
  	"name": "Bogotá"
	},
	"state": {
  	"id": "CO-DC",
  	"name": "Bogota D.C."
	},
	"country": {
  	"id": "CO",
  	"name": "Colombia"
	}
  },
  "options": [
	{
  	"id": 523835933,
  	"name": "Servientrega Normal",
  	"shipping_method_id": 501745,
  	"currency_id": "COP",
  	"list_cost": 5000,
  	"cost": 0,
      "tracks_shipments_status": "verified",
  	"display": "recommended",
  	"speed": {
    	"shipping": 24,
    	"handling": 72
  	},
  	"estimated_delivery": {
    	"date": "2015-06-22T00:00:00.000-05:00",
    	"pay_before": null,
    	"time_from": null,
    	"time_to": null
  	},
  	"discount": {
    	"rate": 0,
    	"type": "none",
        "promoted_amount": 0
  	}
	}
  ]
}

Descripción de atributos

type:tipo de promesa de entrega.
date: fecha estimada de entrega. En caso de ser rango: es la fecha inferior de rango.
shipping: tiempo que tarda el carrier en entregar el envío. En caso de ser rango: es el límite inferior del rango.
handling: tiempo que tarda el vendedor en despachar el envío.
unit: unidad de tiempo para los atributos shipping, handling y offset.shipping.
offset: sólo aplica para rangos.
date: fecha superior del rango.
shipping: amplitud del rango de días.
time_frame: franja horaria de entrega.
pay_before: fecha límite para realizar el pago. 

{
	"estimated_delivery_time": {
		"type": "known|known_frame|unknown_frame",
		"date": 2015-09-10T00: 00: 00: 000-03: 00,
		"shipping": 72,
		"handling": 24,
		"unit": "hour",
		"offset": {
			"date": null,
			"shipping": null
		},
		"time_frame": {
			"from": "12: 00",
			"to": "15: 00"
		},
		"pay_before": null
	}
}

Tipos de promesa de entrega

Para conocer los diferentes tipos de promesa de entrega deberás hacer el siguiente GET: 

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

known: En el caso de ser una fecha exacta, y con handling time conocido.

[...]
 "estimated_delivery_time": {
        "type": "known",
        "date": "2015-09-10T00:00:00:000-03:00",
        "shipping": 72,
        "handling": 24,
        "unit": "hour",
        "offset": {
          "date": null,
          "shipping": null
        },
        "time_frame": {
          "from":"12:00",
          "to": "15:00"
        },
        "pay_before": null
      },
[...]

Unknown: En el caso de ser una fecha exacta, desconociendo el handling time, expresada en días hábiles.

[...]
 "estimated_delivery_time": {
        "type": "unknown",
        "date": null,
        "shipping": 72,
        "handling": null,
        "unit": "hour",
        "offset": {
          "date": null,
          "shipping": null
        },
        "time_frame": {
          "from":"null",
          "to": "null"
        },
        "pay_before": null
      },
[...]

known_frame: En el caso de ser un rango de fechas específicas, el handling time es conocido.

[...]
 "estimated_delivery_time": {
        "type": "known_frame",
        "date": "2015-09-10T00:00:00:000-03:00",
        "shipping": 72,
        "handling": 24,
        "unit": "hour",
        "offset": {
          "date": "2015-09-12T00:00:00:000-03:00",
          "shipping": 48
        },
        "time_frame": {
          "from":"12:00",
          "to": "15:00"
        },
        "pay_before": null
      },
[...]

unknown_frame: En el caso de ser un rango de días hábiles, desconociendo el handling time.

[...]
 "estimated_delivery_time": {
        "type": "unknown_frame",
        "date": "null",
        "shipping": 72,
        "handling": null,
        "unit": "hour",
        "offset": {
          "date": "null",
          "shipping": 48
        },
        "time_frame": {
          "from":"null",
          "to": "null"
        },
        "pay_before": null
      },
[...]

Consideraciones

  • El rango de días hábiles queda definido por los límites ["shipping", "shipping" + "offset.shipping"]. Ej: Sí "shipping":96 y "offset.shipping":48, entonces el rango estimado de entrega será entre 4 a 6 días hábiles inclusive.
  • Las fechas estimadas de entrega("date" y "offset.date") son siempre días laborables y solo tendrán valores si el tiempo de despacho(handling) es conocido.
  • "time_frame" sólo aplica a carriers que manejan franjas horarias bien definidas.
  • "pay_before" sólo aplica a carriers en los cuales la promesa de entrega está condicionada por la fecha y hora en la que se realiza el pago.
  • Estos cambios impactarán de la misma forma en el GET de Shipments.

Siguiente: Envío gratis.