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.

Contents

→Asociar sucursales a un usuario
    ↳Consideraciones
→Sugerencias en el formato de los datos para cargar las sucursales
    ↳Nombre
    ↳Dirección
    ↳Calles
    ↳Horarios
→Modificar una sucursal
→Pausar una sucursal
→Reactivar una sucursal
→Eliminar una sucursal
→Consultar una sucursal
→Consultar las sucursales asociadas al usuario
→Asociar una sucursal a una publicación
    ↳Consideraciones sobre el campo availability_time
    ↳Reglas de las horas
→Asociar una sucursal a una publicación con variaciones
→Modificar el tiempo de disponibilidad de una sucursal
→Eliminar una sucursal disponible en un ítem
→Reconocer a un ítem con sucursales asociadas
→Consultar las sucursales asociadas a un ítem
→Reconocer una orden con retiro en una sucursal
→Utilizar el recurso pickups
→Modificar el tiempo de entrega
→Cambiar el status del pickup para delivered
→Estados posibles de un pickup
→Cómo recibir los datos para facturar


Asociar sucursales a un usuario

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 https://api.mercadolibre.com/users/$USER_ID/stores?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X POST https://api.mercadolibre.com/users/1234567/stores?access_token=$ACCESS_TOKEN

{
    "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 https://api.mercadolibre.com/users/$USER_ID/stores/{store_id}?access_token=$ACCESS_TOKEN

Ejemplo:

curl - X PUT https://api.mercadolibre.com/users/1234567/stores/1?access_token=ACCESS_TOKEN

{
    "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 https://api.mercadolibre.com/users/1234567/stores/1?access_token=ACCESS_TOKEN
{
"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 https://api.mercadolibre.com/users/1234567/stores/1?access_token=ACCESS_TOKEN

{
    "status": "active"
}

Eliminar una sucursal

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

Llamada:

curl -X DELETE https://api.mercadolibre.com/users/{user_id}/stores/{store_id}?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X DELETE https://api.mercadolibre.com/users/1234567/stores/1?access_token=$ACCESS_TOKEN
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 https://api.mercadolibre.com/stores/{store_id}?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X GET https://api.mercadolibre.com/stores/1?access_token=$ACCESS_TOKEN

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.",
	"status": "active",
	"tags": [
		"pickup"
	],
	"phone": {
		"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 cuales son todas las sucursales que dio de alta un usuario, se puede hacer la siguiente consulta:


Llamada:

curl -X GET https://api.mercadolibre.com/users/$USER_ID/stores/search?limit={limit}&offset={offset}&status={status}

Ejemplo:

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.",
            "status": "active",
            "phone": 
            {
                "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 https://api.mercadolibre.com/items/$ITEM_ID/stores/{store_id}?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X POST https://api.mercadolibre.com/items/MLA12345678/stores/1?access_token=$ACCESS_TOKEN

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 https://api.mercadolibre.com/items/$ITEM_ID/stores/{store_id}?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X POST https://api.mercadolibre.com/items/MLA12345678/stores/1?access_token=$ACCESS_TOKEN

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 https://api.mercadolibre.com/items/{item_id}/variations/{variation_id}/stores/{store_id}?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X POST https://api.mercadolibre.com/items/{item_id}/variations/{variation_id}/stores/{store_id}?access_token=$ACCESS_TOKEN

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 https://api.mercadolibre.com/items/{item_id}/stores/{store_id}?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X PUT https://api.mercadolibre.com/items/MLA12345678/stores/1?access_token=


{
  "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 https://api.mercadolibre.com/items/{item_id}/stores/{store_id}?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X DELETE https://api.mercadolibre.com/items/MLA12345678/stores/1?access_token=ACCESS_TOKEN

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 https://api.mercadolibre.com/items/$ITEM_ID/stores

Ejemplo:

curl -X GET 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:


Utilizar el recurso pickups

Llamada:

curl -X GET https://api.mercadolibre.com/pickups/$PICKUP_ID?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X GET https://api.mercadolibre.com/pickups/123?access_token=$ACCESS_TOKEN

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 https://api.mercadolibre.com/pickups/{pickup_id}?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X PUT 
https://api.mercadolibre.com/pickups/13092158?access_token=$ACCESS_TOKEN
{
  "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 https://api.mercadolibre.com/orders/$ORDER_ID/feedback?access_token=$ACCESS_TOKEN

Ejemplo:

curl -X POST https://api.mercadolibre.com/orders/1766688268/feedback?access_token=$ACCESS_TOKEN

{ 
    "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.

Forma parte de nuestra comunidad