API - Retirada em loja

Visando melhorar a experiência dos nossos usuários, a plataforma agora oferece a possibilidade de carregar no produto as lojas disponíveis para sua retirada. Conhecendo previamente esta informação, o comprador selecionará em qual delas quer retirar o produto e ML informará o vendedor para ele ter tudo pronto. Para formar parte desta iniciativa, sugerimos você entrar em contato com seu assessor comercial.

Conteúdos

Associar lojas a um usuário

Primeiramente, devem ser criadas as lojas do usuário. Os campos latitude e longitude devem ser previamente conhecidos para poder enviá-los como parâmetros.

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

Exemplo

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

Resposta

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

Considerações

  • O parâmetro “open_hours” suporta até 100 caracteres.
  • Os demais parâmetros permitem até 60 caracteres.
  • O campo phone é opcional

Associar uma sucursal a uma publicação com variações

Uma vez que um item possui variações, poderá associá-las sucursais nas quais poderá retirar o produto.
Regras:
1 - O item base (sem variação) tem que estar associado a uma sucursal com disponibilidade de entrega. Esta disponibilidade será utilizada como "default" para todas as variações do produto. Para isso, deve-se utilizar o mesmo POST que faz a associação sem variações. Chamada:

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

Exemplo:

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

JSON BODY

{
  "availability_time_in_hours": 72
}

2 - Se o seller quer adicionar disponibilidade diferentes para as variações, então deve utilizar o POST abaixo. Chamada:

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

Exemplo:

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

JSON BODY

{
  "availability_time_in_hours": 72
}

Exemplo: Um item "Camiseta" com 3 variações (tamanhos: P, M, G), se associa ao item (sem especificar as variações) a disponibilidade de 48 horas para 5 sucurcais, então:
- Todas as variações possuem 48 horas para o produto estar disponível.
- Caso seja realizado o POST para a variação "tamanho M", na sucursal 3 de 72 horas, então ficará configurado 48 horas para todas as sucursais em todos os tamanhos, exceto para o tamanho M na sucursal 3, que neste caso será exibida a disponibilidade em 72 horas.

Sugestões no formato de dados para carregar filiais

Nome
Para identificar a filial, deve haver uma referência sobre a localização da loja, como "Saavedra" ou "Shopping DOT".
Nome da filial: Description (DOT)

Endereço
Os requisitos a serem considerados na entrada de endereços são:

    • Estado: No MLA:
    • - Usar sempre CABA (Não Cidade Autônoma de Buenos Aires, nem Capital Federal, nem Cap. Fed., nem Caba).
      - Atenção: Córdoba e Tucumán têm acento.
    • No MLM:
    • - Usar sempre CDMX (Não Cidade do México nem DF).
    • No MLB:
    • - Usamos o formato de endereços do Google:
      - Rua, Número - Bairro, Cidade - Estado abreviado
      Exemplo:
      R. Regente Feijó, 132 - Centro, Rio de Janeiro - RJ
      Av. São João, 439 - República, São Paulo - SP
      - Abreviamos os estados com duas letras maiúsculas:


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

Ruas

    • No MLA, MLM e MLB
    • - Abreviar Avenidas (Ex.: Av. del Libertador, Av. Callao).
    • No MLB
    • - Abreviar Rua com um R. (R. Cantareira, R. Ingaí).

Horários
Os requisitos para a entrada de horários são:

    • Informar somente os horários de atendimento (não dizemos "Fechado aos Domingos").
    • Escrever dias completos, com todas as letras e em minúsculo.
    • Utilizar sistema 24 hs. sem am/pm, com 1 dígito para 1 hora e com 4 se for ½ hora.
    • Não esquecer o “.” final em “hs.”
    • - Exemplo horário corrido: das 9 às 19 hs. // das 9 às 19:30 hs.
      - Exemplo horário dividido manhã e tarde: das 9 às 12 e das 15 às 19 hs.
    • Escrever todos os dias em minúsculo, com exceção de início de oração.
    • - Exemplo: Segunda // Segunda a sexta // Segunda a terça e quinta a sábado
      Exemplos de combinações de dias e horários:
    • Horários corridos
    • - Segunda a sexta das 9 às 19 hs.
      - Segunda a sábado das 9 às 19 hs.
      - Segunda a sexta das 9 às 19 hs. - Sábado das 9 às 12:30 hs.
      - Segunda a quarta das 9 às 19 hs. - Quinta a sábado das 9 às 12:30 hs.
    • Horários divididos
    • - Segunda a sexta das 9 às 12:30 e das 15 às 19:30 hs.
      - Segunda a sábado das 9 às 12:30 e das 15 às 19:30 hs.
      - Segunda a sexta das 9 às 12:30 e das 15 às 19:30 hs. - Sábado das 9 às 12:30 e das 15 às 19:30 hs.
      - Segunda a quarta das 9 às 12:30 e das 15 às 19:30 hs. - Quinta a sábado das 9 às 12:30 e das 15 às 19:30 hs.

Alterar uma loja

Caso haja a necessidade de alterar as informações de uma loja, somente deverá enviar aquilo que quiser atualizar. Chamada

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

Exemplo

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 uma loja

Caso haja a necessidade de pausar uma loja e que os itens associados a ela deixem de oferecer momentaneamente a opção de retirada, deve ser realizado um PUT no status da loja. Exemplo

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

{
    "status": "paused"
}

Observação: Este recurso faz com que os itens associados a loja deixem oferecer a opção de retirada, mas em caso de reativa-la, os itens voltam a oferecer retirada automaticamente.

Reativar uma loja

Se quiser reativar a loja e que os itens associados a ela voltem a oferecer a opção de retirada em loja, deve ser realizado um PUT no status da loja. Ejemplo

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

{
    "status": "active"
}

Remover uma loja

Caso haja a necessidade de remover uma loja associada a um usuário, deverá realizar um delete. Chamada

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

Exemplo

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

Observação: Ao fazer um delete da loja, esta não será apagada, mas passará a ter status "inactive" mas não poderá ser reativada .

Consultar uma loja

Para trazer as informações carregadas em uma loja própria de um usuário. Chamada

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

Exemplo

GET GET https://api.mercadolibre.com/stores/1?access_token=ACCESS_TOKEN

Resposta

{
  "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 as lojas associadas ao usuário

Para saber quais são todas as lojas criadas por um usuário, é possível realizar a seguinte consulta: Chamada

GET https://api.mercadolibre.com/users/{user_id}/stores/search?limit={limit}&offset={offset}&status={status}

Exemplo

https://api.mercadolibre.com/users/1234567/stores/search?limit=100&offset=0&status=active,paused

Resposta

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

Associar uma loja a um anúncio

Tendo sido criado o produto, será possível associar a ele lojas, previamente carregadas, nas quais o produto vai estar disponível para sua retirada. O campo a seguir será enviado pelo json "availability_time_in_hours", indicando a partir de que momento o comprador poderá retirar o produto. O tempo postado não poderá ser maior a 5 días (120 horas). Chamada

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

Exemplo

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

JSON BODY

{
  "availability_time_in_hours": 72
}

Considerações sobre o campo availability_time:

  • Serão contabilizadas as horas de dias úteis incluindo sábado. À data/hora da ordem serão adicionadas as horas predefinidas.
  • Quando a disponibilidade for 00:00h e a ordem seja gerada após 18:00h, diremos "A partir de amanhã". Caso contrário, será "Hoje". Isto é assim definido para aplicar uma regra geral para todas as lojas da região.
  • Por enquanto não serão levados em conta feriados para o cálculo da data de retirada.

Alterar o tempo de disponibilidade de uma sucursal

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

Exemplo

PUT
https://api.mercadolibre.com/items/MLA12345678/stores/1?access_token={access_token}


{
  "availability_time_in_hours": 48
}

Remover uma loja disponível em um produto

Para remover a associação de uma loja disponível para um anúncio, será necessário realizar um delete. Chamada

DELETE 

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

Exemplo

DELETE 

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

Reconhecer um produto com lojas associadas

Atualmente, um produto indica que oferece, ou não, “Retirada em Loja” da seguinte maneira: local_pick_up: true | false De maneira independente, vamos adicionar o campo que indicará se há lojas específicas associadas ao produto: store_pick_up: true | false

Consultar sucursais associadas a um item

Para saber quais são todas as sucursais associadas a um item, pode ser feita a consulta a saber: Chamada

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

Exemplo

GET https://api.mercadolibre.com/items/MLX123456789/stores

Resposta

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

Reconhecer um pedido com retirada em uma loja

Dentro do JSon de uma order, poderá ser reconhecido se o comprador escolheu ou não a opção de retirar em loja. Para isto, existirá o atributo “pickup_id”, que permitirá recorrer ao novo endpoint /pickups, o qual conterá a loja que o comprador escolheu para fazer a retirada. Se a Order tiver um envio associado, quer dizer que não existe PickUpinStore, e o pickup_id virá nulo. Quando existe uma retirada:

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

Utilizar o recurso pickups

Chamada

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

Exemplo

GET 
https://api.mercadolibre.com/pickups/123?access_token=ACCESS_TOKEN

Resposta

{
"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: O estado inicial de um pickup é sempre “active”. Quando estiver pronto para ser retirado por sucursal, levando em conta o campo "availability_time_in_hours”, mudará automaticamente para “ready_for_pickup”.

Alterar o tempo de entrega

O tempo de entrega de um produto poderá ser alterado para adiantar ou demorar o tempo de retirada na filial.
Disponibilizamos o campo "date_override" para casos extraordinários em que for necessário sobrescrever o valor em “availability_time_in_hours”.
O comprador receberá uma notificação na qual será informada a demora ou que o produto já está pronto para ser retirado. Chamada

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

Exemplo

PUT 
https://api.mercadolibre.com/pickups/13092158?access_token=ACCESS_TOKEN
{
  "date_override": "2018-06-30T10:42:11-04:00"
} 

Resposta

{
    "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": "Nome e sobrenome"
    }
}

Considerações:

  • O formato do campo "date_override" é: "2017-11-09T10:42:11-04:00".
  • O recurso/pickups só será mostrado fazendo um GET ao campo "date_override" quando este tiver um valor diferente de null.
  • O PUT poderá ser realizado desde que o status do pickup for "active".
  • No campo date_ready mantém a data original de quando se criou o pick-up. O date_override ao ter um valor diferente de nulo, será o que determina quando estará disponível o produto na filial.

Regras das horas

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

Mudar o status do pick-up para delivered

Para mudar o status do pick-up para delivered é necessário fazer a qualificação seguindo o fluxo de feedback tradicional, e dizer, realizando o PUT à ordem. Uma vez realizado, se atualiza automaticamente o estado no recurso pick-up. Llamada

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

Exemplo

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 possíveis de um pick-up

Active: é o estado inicial do pick-up.
Ready for pick-up: é apresentado quando cumpre o prazo definido no campo “availability_time_in_hours”.
Delivered: é apresentado quando o vendedor indica que já entregou o pedido mas o comprador ainda não confirmou.
Finished: é apresentado quando ambas partes que o pedido foi entregue.

Como receber os dados para faturamento

Para conhecer como receber os dados para faturar contamos com um novo recurso que permite receber os dados do comprador para poder fazer o faturamento. Convidamos você revisar a seguinte documentação.

Faça parte da nossa comunidade