Recursos Cross
Explora los recursos principales de nuestras APIs
Documentación
Puedes usar esta documentación para las siguientes unidades de negocio:
Última actualización 03/08/2024
Gestionar Mercado Envíos 2
Tipos de logísticas
Los diferentes tipos de logísticas de envíos para Mercado Envíos 2 son:
- Mercado Envíos Drop_off
- Mercado Envíos Colectas (cross_docking) y Places (xd_drop_off)
- Mercado Envíos Flex (self_service)
Agregar ME2 a un ítem
Utiliza POST para publicar el ítem. Asegúrate de informar los atributos obligatorios requeridos por la categoría y los atributos requeridos por el dominio.
Ejemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
"title": "Item de teste",
"category_id": "MLA91727",
"price": 1200,
"currency_id": "ARS",
"available_quantity": 2,
"buying_mode": "buy_it_now",
"listing_type_id": "bronze",
"condition": "new",
"description": "test",
"pictures": [
{
"source": "http://upload.wikimedia.org/wikipedia/commons/f/fd/Ray_Ban_Original_Wayfarer.jpg"
},
{
"source": "http://en.wikipedia.org/wiki/File:Teashades.gif"
}
],
"shipping": {
"mode": "me2",
"local_pick_up": false,
"free_shipping": false,
"free_methods": []
}
}
https://api.mercadolibre.com/itemsRecuerda que para publicar en categorías que marcadas como Frágil, el usuario también deberá estar marcado como "frágil", para esto deberá tener un acuerdo comercial. En las siguientes llamadas de la API deberás validar los campos que se muestran a continuación:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/shipping_preferences
{
"local_pick_up": false,
"modes": [
"custom",
"not_specified",
"me1",
"me2"
],
"trusted_user": true,
"custom_calculator": false,
"picking_type": "cross_docking",
"thermal_printer": null,
"option": "in",
"tags": [
],
"carrier_pickup": false,
"items_combination": "enabled",
"services": [
311,
591,
671,
801,
881,
1181,
1191,
136261
],
"logistics": [
{
"mode": "me1",
"types": [
{
"type": "default",
"carrier_pickup": [],
"services": [
21,
23,
22,
11
],
"default": true
}
]
},
{"mode": "me2",
"types": [
{
"type": "cross_docking",
"carrier_pickup": [
17501840
],
"services": [
311,
591,
671,
801,
881,
1181,
1191
],
"default": false
},
{
"type": "self_service",
"carrier_pickup": [
],
"services": [
136261
],
"default": false
}
]
},
{
"mode": "custom",
"types": [
{
"type": "custom",
"carrier_pickup": [
],
"services": null,
"default": true
}
]
},
{
"mode": "not_specified",
"types": [
{
"type": "not_specified",
"carrier_pickup": [
],
"services": null,
"default": true
}
]
}
],
"content_declaration_disabled": false,
"conciliation": {
"type": null
},
"mandatory_invoice_data": false,
"site_id": "MLA",
"free_configurations": [
{
"condition": {
"value": null,
"type": "all"
},
"rule": {
"default": true,
"free_mode": "country",
"value": null
}
}
],
"mandatory_settings": {
}
}"restricted": true (API category)
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/MCO7159/shipping_preferences
{
"category_id": "MCO7159",
"dimensions": {
"weight": 50000,
"height": 20,
"width": 60,
"length": 130
},
"logistics": [
{
"types": [
"default"
],
"mode": "me1"
},
{
"types": [
"drop_off",
"xd_drop_off",
"cross_docking",
"fulfillment"
],
"mode": "me2"
},
{
"types": [
"not_specified"
],
"mode": "not_specified"
},
{
"types": [
"custom"
],
"mode": "custom"
}
],
"restricted": true
}Atributos requeridos por dominio
Deberás validar cuáles son los atributos que acorde al dominio serán requeridos informar de manera obligatoria para poder determinar si el ítem es candidato a ser envíado por me2 o no.
Llamada:
curl -X GET 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/catalog_domains/$DOMAIN_ID/shipping_attributesEjemplo de llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_domains/MLB-AUTOMOTIVE_TIRES/shipping_attributesEjemplo de respuesta:
{
"domain_id": "MLB-AUTOMOTIVE_TIRES",
"attributes": [
{
"id": "RIM_DIAMETER",
"type": "NUMBER_UNIT",
"unit": "\"",
"index": 1,
"ranges": null
},
{
"id": "TIRES_NUMBER",
"type": "INTEGER",
"unit": "",
"index": 2,
"ranges": null
},
{
"id": "SECTION_WIDTH",
"type": "NUMBER_UNIT",
"unit": "mm",
"index": 3,
"ranges": null
}
],
"client_id": 3536736322237473,
"date_created": "2022-03-29T13:04:27.912-03:00",
"last_modified": "2023-07-18T11:31:20.092-03:00"
}Los campos indicarán:
- domain_id: ID del dominio consultado.
- attributes: arreglo que contiene los atributos que deben ser informados de manera obligatoria al momento de crear o modificar un ítem y que ayudarán a determinar si el ítem es candidato a ser envíados por me2.
Consultar fecha de envío del producto
Para evitar sobrepasar la capacidad de los transportistas (carriers) y que los compradores reciban los productos a tiempo, es necesario que consultes la fecha de envío de los productos. Identifica los envíos de este tipo realizando un GET a /shipments, incorporando el header 'X-Format-New: true' verificando el nodo “buffering”.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'X-Format-New: true' https://api.mercadolibre.com/shipments/$SHIPMENT_IDEjemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'X-Format-New: true' https://api.mercadolibre.com/shipments/40173236996Respuesta:
{
"id":40173236996,
"external_reference":null,
"status":"pending",
"substatus":"buffered",
"date_created":"2020-10-20T10:08:30.000-04:00",
"last_updated":"2020-10-20T15:09:22.000-04:00",
"declared_value":7000,
"dimensions":{
"height":14,
"width":19,
"length":38,
"weight":950
},
"logistic":{
"direction":"forward",
"mode":"me2",
"type":"xd_drop_off"
},
[]
"lead_time":{
"option_id":3628548109,
"shipping_method":{
"id":510545,
"name":"Express a domicilio",
"type":"two_days",
"deliver_to":"address"
},
"currency_id":"ARS",
"cost":0,
"list_cost":504.99,
"cost_type":"free",
"service_id":831,
"delivery_type":"estimated",
"estimated_schedule_limit":{
"date":null
},
"buffering":{
"date":"2020-10-21T20:18:26.000Z" ---> Fecha que podrá realizar el envío
},
"estimated_delivery_time":{
"type":"known",
"date":"2020-10-22T00:00:00.000-03:00",
"unit":"hour",
"offset":{
"date":null,
"shipping":null
},
"time_frame":{
"from":null,
"to":null
},
"pay_before":"2020-10-21T00:00:00.000-03:00",
"shipping":24,
"handling":24,
"schedule":null
},
"estimated_delivery_limit":{
"date":null,
"offset":null
},
"estimated_delivery_final":{
"date":null,
"offset":null
},
"estimated_delivery_extended":{
"date":null,
"offset":null
},
"estimated_handling_limit":{
"date":"2020-10-21T00:00:00.000-03:00"
}
},
"tags":[
"test_shipment"
]
}En el campo buffering “date” del nodo “buffering” estará la fecha correspondiente que se tiene que despachar el paquete y ese mismo día disponibilizaremos la etiqueta para la impresión.
Imprimir etiquetas de envío
Cuando un comprador completa su compra, es crucial que el vendedor pueda generar rápidamente la etiqueta de envío para agilizar el proceso de despacho.
Validaciones de tipos de logística:
Antes de intentar obtener la etiqueta, es esencial verificar los campos "mode" y "type" dentro del nodo logístico para garantizar que la etiqueta esté disponible.
Mode: siempre debe ser “me2”.
Logistic_type: indica los tipos de logística aceptados tales como:
- “drop_off”
- “xd_drop_off”
- “cross_docking”
- “self_service”
Validaciones de estado de envío:
Es importante validar que el estado sea "ready_to_ship" y el subestado "ready_to_print" para poder imprimir la etiqueta. En casos o estados distintos, la impresión de etiquetas no será posible y generará un error.
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/43308302844Respuesta:
[
{
...
"mode": "me2",
...
"substatus": "ready_to_print",
...
"status": "ready_to_ship",
"logistic_type": "self_service"
}
]Etiquetas:
Este endpoint permite generar etiquetas de envío de forma rápida y eficiente para Mercado Envíos 2.
Llamada para formato PDF:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipment_labels?shipment_ids=$SHIPPING_ID1,$SHIPPING_ID2&response_type=pdfEjemplo para formato PDF:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipment_labels?shipment_ids=43308302844&response_type=pdfLlamada para formato ZPL:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipment_labels?shipment_ids=$SHIPPING_ID1,$SHIPPING_ID2&response_type=zpl2Ejemplo para formato ZPL:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipment_labels?shipment_ids=43308302844&response_type=zpl2Códigos de Estado de respuesta:
| Código | Mensaje | Descripción | Recomendación |
|---|---|---|---|
| 200 - OK | - | Se obtuvo correctamente la consulta. | - |
| 400 - Bad Request | invalid_shipment_caller | No existe el usuario. | Validar el valor del seller_id y access_token. |
| 400 - Bad Request | not_printable_status | Estado no permitido para la impresión de etiquetas. | Validar que el estado sea "ready_to_ship" y el subestado "ready_to_print". |
| 400 - Bad Request | shipment_ids | Límite de etiquetas excedido. | Validar que se envíen como máximo 50 shipment_ids. |
| 400 - Bad Request | invalid_shipment_ff_public | Shipment de fulfillment. | Validar el logistic_type. |
| 400 - Bad Request | invalid_shipment_mode | Shipment fuera de me2. | Validar el shipping mode. |
| 404 - Not Found | Missing a valid shipment id value | Shipment no encontrado. | Validar el valor del shipment_id. |
Algunas validaciones adicionales son las siguientes:
- Consulta máximo 50 (cincuenta) shipment_ids en un mismo GET para evitar errores. Si superas esta cantidad máxima permitida, recibirás un error 400.
- En todos los países, las medidas estándar para imprimir etiquetas son de 15 cm de alto x 10 cm de ancho, con la excepción de México, donde las medidas son de 20 cm de alto x 10 cm de ancho.
- Para los países de 10x15 cm, las etiquetas en PDF se pueden reducir a 9x15 cm para que puedan caber tres por hoja A4, lo que permite optimizar el uso de recursos y reducir costos.
- Cuando imprimas etiquetas de envío en formato PDF,te recomendamos utilizar una hoja A4 para garantizar una impresión precisa y eficiente. Asegúrate de calibrar tu impresora para las dimensiones acotadas anteriormente..
- Para reimprimir la etiqueta, simplemente realiza el mismo GET. Sin embargo, asegúrate de cumplir con las validaciones previas para evitar errores.
- Las etiquetas en el estado "ready_to_ship" y el subestado "ready_to_print" o “printed” pueden reimprimirse según sea necesario.
- Es importante destacar que no se permite crear etiquetas personalizadas para ningún vendedor.
- Para imprimir etiquetas Zebra, es necesario contar con una impresora térmica compatible con el lenguaje Zebra (ZPL).
- Exclusivamente para Brasil: Ten en cuenta que las notas fiscales tienen las mismas dimensiones que las etiquetas. Solo podrás imprimir las notas fiscales después de haberlas generado. En ese momento, podrás imprimir las notas fiscales de forma independiente o junto con la etiqueta.
Consultar envíos de carrito
Con la actual estructura del JSON de orders, la información del envío no está más disponible, solo estará la identificación. De esta manera, puedes conseguir la información adicional en el recurso /shipments.
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.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_IDEjemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/2053577644Respuesta:
{
"id": 2053577644,
"date_created": "2019-06-13T09:20:02.000-04:00",
"date_closed": "2019-06-13T09:20:08.000-04:00",
"last_updated": "2019-06-13T09:20:08.000-04:00",
"manufacturing_ending_date": null,
"feedback": {
"sale": null,
"purchase": null
},
"mediations": [],
"comments": null,
"pack_id": 2000000101334825,
"pickup_id": null,
"order_request": {
"return": null,
"change": null
},
"fulfilled": null,
"total_amount": 9.99,
"paid_amount": 9.99,
"coupon": {
"id": null,
"amount": 0
},
"expiration_date": "2019-07-11T09:20:08.000-04:00",
"order_items": [
"item": {
"id": "MLB1226730704",
"title": "Produto Teste - Não Ofertar",
"category_id": "MLB11742",
"variation_id": null,
"seller_custom_field": null,
"variation_attributes": [],
"warranty": "12 months",
"condition": "new",
"seller_sku": null
},
"quantity": 1,
"unit_price": 9.99,
"full_unit_price": 9.99,
"currency_id": "BRL",
"manufacturing_days": null
],
"currency_id": "BRL",
"payments": [
"id": 4863317779,
"order_id": 2053577644,
"payer_id": 419067349,
"collector": {
"id": 419059118
},
"card_id": null,
"site_id": "MLB",
"reason": "Produto Teste - Não Ofertar",
"payment_method_id": "account_money",
"currency_id": "BRL",
"installments": 1,
"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": [
"refund"
],
"status": "approved",
"status_code": null,
"status_detail": "accredited",
"transaction_amount": 9.99,
"taxes_amount": 0,
"shipping_cost": 0,
"coupon_amount": 0,
"overpaid_amount": 0,
"total_paid_amount": 9.99,
"installment_amount": null,
"deferred_period": null,
"date_approved": "2019-06-13T09:20:07.000-04:00",
"authorization_code": null,
"transaction_order_id": null,
"date_created": "2019-06-13T09:20:07.000-04:00",
"date_last_modified": "2019-06-13T09:20:07.000-04:00"
],
"shipping": {
"id": 27987243797
},
"status": "paid",
"status_detail": null,
"tags": [
"test_order",
"pack_order",
"paid"
],
"buyer": {
"id": 419067349,
"nickname": "TT763866",
"email": "ttest.6hqmq6+2-ogiydkmzvg43tmobx@mail.mercadolivre.com", },
"first_name": "Test",
"last_name": "Test",
"billing_info": {
"doc_type": "CPF",
"doc_number": "78525276200"
},
"seller": {
"id": 419059118,
"nickname": "TETE8288849",
"email": "ttest.hpz2z6q+2-ogiydkmzvg43tmobs@mail.mercadolivre.com",
"phone": {
"area_code": "01",
"extension": "",
"number": "1111-1111",
"verified": false
},
"alternative_phone": {
"area_code": "",
"extension": "",
"number": ""
},
"first_name": "Test",
"last_name": "Test"
},
"taxes": {
"amount": null,
"currency_id": null
}La respuesta no devuelve el campo total_amount_with_shipping, el cual debe ser calculado. Para entender a qué hace referencia cada uno de los parámetros realiza la siguiente llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID?optionsCalcular monto total con envío
Con nuestro recurso orders puedes calcular el monto total con envío.
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.
- El campo "pack_id" muestra el número de carrito al cual pertenece la orden.
- 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.
- 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.
Posibles errores
400: validaciones de consistencia:
- Los campos obligatorios están incompletos.
- El formato de los IDsids es incorrecto.
401: token invalido.
403: falta de permisos.
404: Bad Request - el ítem, los productos o los dominios especificados no existen.
Siguiente: Costos de envío y handling time.