Última actualización 15/03/2023

Retiro en sucursal

Buscando mejorar la experiencia de nuestros usuarios, sumamos a nuestra plataforma la posibilidad de poder cargar en un ítem las sucursales en las que se encuentra disponible para retiro. Conociendo previamente esta información, el comprador seleccionará por cuál de ellas querrá hacer el retiro y desde Mercado Libre avisaremos al vendedor para que pueda estar preparado.
Para formar parte de esta iniciativa, te sugerimos que entres en contacto con tu asesor comercial.

Asociar sucursales a un usuario

Nota:
La configuración de los usuarios de test, con el modo de envío retirado en sucursal, se debe hacer por medio del equipo de soporte, y para los casos de vendedores reales, la aprobación de este vendedor para que se retire en la tienda se debe realizar con el asesor comercial.

En primer lugar, se deben crear las sucursales que posee un usuario. Los campos latitude y longitude tienen que ser conocidos previamente para poder enviarlos como parámetros.

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/stores

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1234567/stores
{
    "description":"DOT",
    "open_hours": "Lunes a viernes de 8:30 a 12:30 y de 16:30 a 20:30 hs. - Sábado de 9 a 13 y de 16:30 a 20:30 hs.",
    "status": "active" |  "paused" ,
    "phone":
    {
        "area_code":"011",
        "number":"1234"
    },
    "location":
    {
       "address_line": "B de Monteagudo 2833 - Florencio Varela - Buenos Aires",
       "latitude": -24.2344,
       "longitude": -15.122
    }
}

Respuesta:

{
    "id": 1,
    "description":"DOT",
    "date_creation": "2017-02-08T08:40:51.620Z",
    "open_hours": "Lunes a viernes de 8:30 a 12:30 y de 16:30 a 20:30 hs. - Sábado de 9 a 13 y de 16:30 a 20:30 hs.",
    "status": "active" | "paused",
    "phone":
    {
        "area_code":"011",
        "number":"1234"
    },
    "location":
    {
          "address_line": "B de Monteagudo 2833 - Florencio Varela - Buenos Aires",
          "latitude": -24.2344,
          "longitude": -15.122,
    }
}

Consideraciones

  • El parámetro “open_hours” soporta hasta 100 caracteres.
  • El resto de los parámetros permiten hasta 60 caracteres.
  • El campo phone es opcional.

Sugerencias en el formato de los datos para cargar las sucursales

Nombre

Para identificar la sucursal,debe ser una referencia de la ubicación del local, como “Saavedra” o “Shopping DOT”.
Nombre de la sucursal : Description (DOT).


Dirección

Los requisitos en la carga de direcciones a considerar son:

  • Estado: En MLA: Usa siempre CABA (No Ciudad Autónoma de Buenos Aires, ni Capital Federal, ni Cap. Fed., ni Caba). Atención: Córdoba y Tucumán llevan tilde.
  • En MLM: Usa siempre CDMX (Ni Ciudad de México, ni DF).
  • En MLB: Usamos el formato de direcciones de Google: - Calle, Número - Barrio, Ciudad - Estado abreviado. Por ejemplo: R. Regente Feijó, 132 - Centro, Rio de Janeiro - RJ
    Av. São João, 439 - República, São Paulo - SP
    Abreviamos los estados con dos letras en mayúscula:

Acre: AC
Alagoas: AL
Amazonas: AM
Bahía: BA
Ceará: CE
Distrito Federal: DF
Espírito Santo: ES
Goiás: GO
Maranhão: MA
Mato Grosso: MT
Mato Grosso do Sul: MS
Minas Gerais: MG
Pará: PA
Paraíba: PB
Paraná: PR
Pernambuco: PE
Piauí: PI
Río de Janeiro: RJ
Rio Grande do Norte: RN
Rio Grande do Sul: RS
Rondônia: RO
Roraima: RR
Santa Catarina: SC
São Paulo: SP
Sergipe: SE
Tocantins: TO


Calles

  • En MLA, MLM and MLB: abrevia Avenidas (Ej: Av. del Libertador, Av. Callao).
  • En MLB: abreviar Rúa con una R. (R. Cantareira, R. Ingaí).

Horarios

Los requisitos en la carga de los horarios son:

  • Informar solamente los horarios de atención (no decimos “Domingo Cerrado”).
  • Escribir los días completos, con todas las letras y en minúscula.
  • Utiliza el sistema 24 hs. sin am/pm, con 1 dígito para 1 hora y con 4 si es ½ hora.
  • No olvidar el “.” final en “hs.”: Ejemplo horario de corrido: de 9 a 19 hs. // de 9 a 19:30 hs.
    Ejemplo horario cortado mañana y tarde: de 9 a 12 y de 15 a 19 hs.
  • Escribir todos los días en minúscula, salvo cuando sea el comienzo de la oración. Ejemplo: Lunes // Lunes a viernes // Lunes a martes y jueves a sábado

Ejemplos de combinaciones de días y horarios:

  • Horarios de corrido: Lunes a viernes de 9 a 19 hs.; Lunes a sábado de 9 a 19 hs.; Lunes a viernes de 9 a 19 hs. - Sábado de 9 a 12:30 hs.; Lunes a miércoles de 9 a 19 hs. - Jueves a sábado de 9 a 12:30 hs.
  • Horarios no corridos: Lunes a viernes de 9 a 12:30 y de 15 a 19:30 hs.; Lunes a sábado de 9 a 12:30 y de 15 a 19:30 hs.; Lunes a viernes de 9 a 12:30 y de 15 a 19:30 hs. - Sábado de 9 a 12:30 y de 15 a 19:30 hs. ; - Lunes a miércoles de 9 a 12:30 y de 15 a 19:30 hs. - Jueves a sábado de 9 a 12:30 y de 15 a 19:30 hs.

Modificar una sucursal

Cuando se quiera modificar la información de una sucursal se deberá mandar solo aquello que se desea actualizar.

Llamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/stores/$STORE_ID

Ejemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1234567/stores/1
{
    "open_hours": "Lunes a sábado de 9 a 20:30 hs.",
}

Pausar una sucursal

Cuando se quiera pausar una sucursal y que los ítems asociados a la misma dejen de ofrecer momentáneamente la opción de retiro, se deberá realizar un PUT al status.

Ejemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1234567/stores/1
{
   "status": "paused"
}
Nota:
Esto hace que los ítems asociados dejen de ofrecer PUIS pero en caso de reactivarse la sucursal, automáticamente los ítems recuperan esa asociación.

Reactivar una sucursal

Cuando se quiera volver a tener disponible una sucursal y que los ítems asociados a la misma vuelvan a ofrecer la opción de retiro, se deberá realizar un PUT al status.

Ejemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1234567/stores/1
{
    "status": "active"
}

Eliminar una sucursal

Cuando se quiere eliminar una sucursal asociada a un usuario se deberá efectuar un delete.

Llamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/stores/$STORE_ID

Ejemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1234567/stores/1
Nota:
Al hacer un delete de la sucursal, la misma no se borra sino que queda bajo el status "inactive" pero ya no podrá ser reactivada.

Consultar una sucursal

Para traer la información cargada en una sucursal propia de un usuario.

Llamada:

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

Ejemplo:

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

Respuesta:

{
	"id": "1",
	"user_id": "221111122",
	"description": "Belgrano",
	"date_creation": "2017-06-27T13:26:52.94790119-04:00",
	"open_hours": "Lun-Sáb: 09:00-20:30. Dom: 12:00-20:30.",

		"area_code": "011",
		"number": "22222222"
	},
	"location": {
		"address_line": "Av. Cabildo 111, Ciudad de Buenos Aires",
		"latitude": -32.562693359870195,
		"longitude": -75.45601654999198,
		"id": "AR-C",
		"type": "state"
	}
}

Consultar las sucursales asociadas al usuario

Para saber cuáles son las sucursales dadas de alta de un usuario, realiza la siguiente consulta:


Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/stores/search?limit=$LIMIT&offset=$OFFSET&status=$STATUS

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1234567/stores/search?limit=100&offset=0&status=active,paused

Respuesta:

{
    "paging":
    {
        "limit": 10,
        "offset": 10,
        "total": 1495
    },
    "results":
    [
        {
            "id": 1,
            "description":"DOT",
            "date_creation": "2017-02-08T08:40:51.620Z",
            "open_hours": "Lunes a sábado de 9 a 20:30 hs.",

            {
                "area_code":"011",
                "number":"1234"
            },
            "location":
            {
                "address_line": "B de Monteagudo 2833 - Florencio Varela - Buenos Aires"
                "latitude": -24.2344
                "longitude": -15.122
            }
        },
        {
            "id": 2,
            "description":"DOT 2",
            "date_creation": "2017-02-08T08:40:51.620Z",
            "open_hours": "Lunes a sábado de 9 a 20:30 hs.",
            "status": "paused",
            "phone":
            {
                "area_code":"011",
                "number":"1234"
            },
            "location":
            {
                "address_line": "B de Monteagudo 2833 - Florencio Varela - Buenos Aires"
                "latitude": -24.2344
                "longitude": -15.122
            }
        }
    ]
}

Asociar una sucursal a una publicación

Una vez creado un ítem se le podrá asociar sucursales, dadas de alta previamente, en las cuales está disponible el producto para ser retirado. En el json se enviará el campo "availabilty_time_in_hours", que indica a partir de cuando el comprador podrá retirar el producto. El tiempo posteado no podrá superar los 5 días (120 horas).


Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/stores/$STORE_ID

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA12345678/stores/1

JSON body

{
  "availability_time_in_hours": 72
}

Consideraciones sobre el campo availability_time

  • Se contabilizarán las horas de días hábiles incluyendo el sábado. A la fecha/hora de la orden se le sumarán las horas predefinidas.
  • Cuando la disponibilidad sea 0hs y la orden se genere después de las 18hs, diremos "A partir de mañana". Sino, será "Hoy". Esto se define así para aplicar una regla general a todos los comercios de la región.
  • Por el momento no se tienen en cuenta los feriados para el cálculo de la fecha de retiro.

Reglas de las horas

Zona 1 (Hasta 48 hs) Zona 2 (Hasta 72 hs) Zona 3 - Resto país (Hasta 96 hs)
MLB SP (Capital) SP (Estado - Zona 1) RJ (capital). El resto del país.
MLM CDMX (Ciudad) - Estado de México (Ciudad). Guadalajara - (Ciudad) Monterrey (Ciudad). El resto del país.
MCO Bogota (Ciudad) - Medellin (Ciudad). Barranquilla (Ciudad) - Cali (Ciudad). El resto del país.
MLU Montevideo (Departamento) - Canelones (Departamento) Maldonado (Departamento). El resto del país. -
MLC Santiago Viña del Mar / Valparaíso - Concepción - La Serena. El resto del país.
MLA CABA y Gran Buenos Aires. Ciudad de Rosario y Ciudad de Santa Fé - Ciudad de Córdoba - Ciudad de Mendoza. El resto del país.

Asociar una sucursal a una publicación con variaciones

Una vez que un ítem tenga variaciones se le podrá asociar sucursales, dadas de alta previamente, en las cuales está disponible el producto para ser retirado.

Reglas:

  • El item base (sin variación) tiene que tener la asociación a la sucursal con una disponibilidad. Son los tiempos que se van a mostrar por "default" para todas las variaciones. Para eso se utiliza el mismo POST tal como hace para las asociaciones sin variación.

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/stores/$STORE_ID

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA12345678/stores/1

JSON body

{
  "availability_time_in_hours": 72
}
  • Si el seller quiere poner una disponibilidad distinta para una variación en particular debe hacer un POST.

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/variations/$VARIATION_ID/stores/$STORE_ID

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA12345678/variations/123456789/stores/1

JSON body

{
  "availability_time_in_hours": 72
}

Ejemplo:

Un item "Remera" con 3 variaciones (Talles: S, M, L), se le asocia al item (sin especificar variación como se hace actualmente) la disponibilidad 48hs en 5 sucursales, entonces:

  • Todas las variaciones tienen 48hs de disponibilidad.
  • Si además hace el POST para la variación "talle M" a la sucursal 3 de 72hs, se va a ver 48hs para todas las sucursales de todos los talles salvo para el talle M de sucursal 3 (ahí vamos a mostrar 72hs).

Modificar el tiempo de disponibilidad de una sucursal

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/stores/$STORE_ID

Ejemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA12345678/stores/1
{
  "availability_time_in_hours": 48
}

Eliminar una sucursal disponible en un ítem

Para quitar la asociación de una sucursal disponible para una publicación, se deberá realizar un delete.

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/stores/$STORE_ID

Ejemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA12345678/stores/1

Reconocer a un ítem con sucursales asociadas

Hoy en día, un ítem indica que ofrece, o no, “Retiro en Sucursal” de la siguiente manera: local_pick_up: true | false De manera independiente, agregaremos el campo que indicará si existen sucursales específicas asociadas al ítem: store_pick_up: true | false.


Consultar las sucursales asociadas a un ítem

Para saber cuales son todas las sucursales que un ítem tiene asociadas, se puede hacer la siguiente consulta:

Llamada:

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

Ejemplo:

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

Respuesta:

{
	"paging": {
		"limit": 50,
		"offset": 0,
		"total": 1
	},
	"results": [{
		"id": "16666000",
		"user_id": "144999999",
		"description": "Test",
		"date_creation": "2017-09-24T16:00:40.327726325-04:00",
		"open_hours": "Lunes a sábados de 9 a 20:30 hs.",
		"status": "active",
		"phone": {
			"area_code": "11",
			"number": "2222-2222"
		},
		"location": {
			"address_line": "Av. 9 de Julio 1000",
			"latitude": -10.660000,
			"longitude": -50.720000,
			"availability_time_in_hours": 120
		}
	}]
}

Reconocer una orden con retiro en una sucursal

Dentro del json de una orden, se podrá reconocer si el comprador eligió, o no, la opción de retiro en sucursal. Para eso, existirá el atributo “pickup_id”, que permitirá recurrir al nuevo endpoint /pickups, el cual contendrá la sucursal que eligió el comprador para hacer el retiro. En caso de que la orden tenga un envío asociado, es decir que no haya retiro en sucursal, el pickup_id vendrá nulo. Cuando exista un pickup in store creado para esa order:

[...]
   "shipping": {
   "id": null
               },
   "pickup_id": 12345667,
[...]

Utilizar el recurso pickups

Llamada:

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

Ejemplo:

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

Respuesta:

{
	"id": "12345667",
	"store_id": 11332211,
	"order_id": 1510999999,
	"item_id": "MLA555555555",
	"buyer_id": 111111222,
	"date_created": "2017-10-20T16:57:26.543801741-04:00",
	"date_ready": "2017-10-23T16:57:53-04:00",
	"status": "ready_for_pickup",
	"store_info": {
		"id": "11332211",
		"user_id": "166663322",
		"description": "DOT",
		"date_creation": "2017-10-20T08:39:27.689379203-04:00",
		"open_hours": "Lunes a viernes de 11 a 21 hs.",
		"status": "active",
		"phone": {
			"area_code": "011",
			"number": "3333 4444"
		},
		"location": {
			"address_line": "Dirección de Test",
			"latitude": -34.1111111,
			"longitude": -52.2222222
		}
	},
	"pickup_person": {
		"full_name": "Juan Gutierrez"
	}
}

Status: El estado inicial de un pickup es siempre “active”. Una vez que ya esté listo para ser retirado por sucursal, teniendo en cuenta el campo “availability_time_in_hours”, cambiará automáticamente a “ready_for_pickup”.


Modificar el tiempo de entrega

Se podrá cambiar el tiempo de entrega de un producto, ya sea para adelantar o atrasar el tiempo de retiro en sucursal. Disponibilizamos el campo "date_override" para casos extraordinarios donde sea necesario sobrescribir el valor en “availability_time_in_hours”. El comprador recibirá una notificación donde se le informa la demora o que el producto ya está listo para ser retirado.


Llamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/pickups/$PICKUP_ID

Ejemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/pickups/13092158
{
  "date_override": "2018-06-30T10:42:11-04:00"
}

Respuesta:

{
    "id": "13092158",
    "store_id": 12859008,
    "order_id": 1745150310,
    "item_id": "MLB997548861",
    "buyer_id": 311800820,
    "date_created": "2018-06-26T20:50:46Z",
    "date_ready": "2018-06-28T08:50:47Z",
    "date_override": "2018-06-30T10:42:11-04:00",
    "status": "active",
    "store_info": {
        "id": "",
        "description": null,
        "date_creation": "0001-01-01T00:00:00Z",
        "open_hours": null,
        "status": null,
        "phone": null,
        "location": null
    },
    "pickup_person": {
        "full_name": "Nombre y apellido"
    }
}

Consideraciones

  • El formato del campo "date_override" es: "2017-11-09T10:42:11-04:00"
  • El recurso /pickups solo mostrará al hacer un GET el campo "date_override" cuando éste tenga un valor distinto a null.
  • El PUT se podrá realizar siempre que el status del pickup sea "active".
  • El campo date_ready mantiene la fecha original a cuando se creó el pickup. El date_override al tener un valor distinto a nulo, será el que determine cuando está disponible el producto en la sucursal.

Cambiar el status del pickup para delivered

Para cambiar el status del pickup para "delivered" es necesario hacer la calificación siguiendo el flujo de feedback tradicional, es decir realizando un PUT a la orden. Una vez realizado, se actualiza automáticamente el status en el recurso pickups.

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID/feedback

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/1766688268/feedback
{
    "fulfilled": "true",
    "rating": "positive"
}

Respuesta:

{
    "status": "hidden",
    "reason": null,
    "site_id": "MLB",
    "date_created": "2018-07-25T15:18:44.571-04:00",
    "cust_role": "seller",
    "reply_status": null,
    "order_id": 1766688268,
    "id": 9040862017153,
    "message": "",
    "cust_from": 305860144,
    "fulfilled": true,
    "reply_date": null,
    "visibility_date": null,
    "reply": null,
    "cust_to": 311800820,
    "rating": "POSITIVE"
}

Las opciones para los campos son:

  • fulfilled: "true", "false".
  • rating: "positive", "negative", "neutral".

Estados posibles de un pickup

ACTIVE: es el status inicial del pickup.
READY FOR PICKUP: se presenta cuando se cumple el plazo definido en el campo “availability_time_in_hours”.
DELIVERED: se presenta cuando el vendedor indica que ya entregó el pedido pero el comprador todavía no confirmó.
FINISHED: se presenta cuando ambas partes confirman que el pedido fue entregado.


Cómo recibir los datos para facturar

Para conocer cómo recibir los datos para facturar contamos con un nuevo recurso que permite recibir los datos del comprador para poder facturar.


Configurar Retiro en Sucursal para usuarios de prueba

Para comenzar a usar Retiro en Sucursal con un usuario de prueba, envía los datos de tu usuario de prueba en este formulario.



Siguiente: Envío personalizado.