API - 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.

Contenidos

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.

POST https://api.mercadolibre.com/users/{user_id}/stores?access_token={access_token}

Ejemplo

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:
    • - Usar 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:
    • - Usar siempre CDMX (No Ciudad de México ni DF).
    • En MLB:
    • - Usamos el formato de direcciones de Google:
      - Calle, Número - Barrio, Ciudad - Estado abreviado
      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 y MLB
    • - Abreviar 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.
    • Utilizar 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

PUT https://api.mercadolibre.com/users/{user_id}/stores/{store_id}?access_token={access_token}

Ejemplo

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

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

{
    "status": "paused"
}

Aclaración: 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

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

DELETE
 
https://api.mercadolibre.com/users/{user_id}/stores/{store_id}?access_token={access_token}

Ejemplo

DELETE
https://api.mercadolibre.com/users/1234567/stores/1?access_token=ACCESS_TOKEN

Aclaración: 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

GET https://api.mercadolibre.com/stores/{store_id}?access_token={access_token}

Ejemplo

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

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

POST 
https://api.mercadolibre.com/items/{item_id}/stores/{store_id}?access_token={access_token}

Ejemplo

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 48hs) Zona 2 (Hasta 72hs) Zona 3 - Resto País (Hasta 96hs)
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:
1 - 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:

POST 
https://api.mercadolibre.com/items/{item_id}/stores/{store_id}?access_token={access_token}

Ejemplo:

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

JSON BODY

{
  "availability_time_in_hours": 72
}

2 - Si el seller quiere poner una disponibilidad distinta para una variación en particular debe hacer un POST. Llamada:

POST 
https://api.mercadolibre.com/items/{item_id}/variations/{variation_id}/stores/{store_id}?access_token={access_token}

Ejemplo:

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

PUT https://api.mercadolibre.com/items/{item_id}/stores/{store_id}?access_token={access_token}

Ejemplo

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. Llamada

DELETE 

https://api.mercadolibre.com/items/{item_id}/stores/{store_id}?access_token={access_token}

Ejemplo

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

GET https://api.mercadolibre.com/items/{item_id}/stores

Ejemplo

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:

"shipping": {
"id": null
},
"pickup_id": 12345667,

Utilizar el recurso pickups

Llamada

GET 
https://api.mercadolibre.com/pickups/{pickup_id}?access_token={access_token}

Ejemplo

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

PUT 
https://api.mercadolibre.com/pickups/{pickup_id}?access_token={access_token}

Ejemplo

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

POST 
https://api.mercadolibre.com/orders/{order_id}/feedback?access_token={access_token)

Ejemplo

POST 
https://api.mercadolibre.com/orders/1766688268/feedback?access_tocken=${access_tocken}

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

Consideraciones:
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. Te invitamos a revisar la siguiente documentación.

Forma parte de nuestra comunidad