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
    ↳Considerações
→Associar uma loja a uma publicação com variações
→Sugestões no formato de dados para carregar filiais
    ↳Nome
    ↳Endereço
    ↳Ruas
    ↳Horários
→Alterar uma loja
→Pausar uma loja
→Reativar uma loja
    ↳Remover uma loja
→Consultar uma loja
→Consultar as lojas associadas ao usuário
→Associar uma loja a um anúncio
    ↳Considerações sobre o campo availability_time
→Alterar o tempo de disponibilidade de uma loja
→Remover uma loja disponível em um produto
→Reconhecer um produto com lojas associadas
→Consultar lojas associadas a um item
→Reconhecer um pedido com retirada em uma loja
→Utilizar o recurso pickups
    ↳Considerações
    ↳Regras das horas
→Alterar o tempo de entrega
→Mudar o status do pick-up para delivered
→Estados possíveis de um pick up
→Como receber os dados para faturamento
→Configurar Retirada em Loja para usuários teste


Associar lojas a um usuário

Nota:
A configuração de usuários de teste, com o modo de envio retirada em loja, deve ser feito via solicitação junto a equipe de suporte, e para casos de sellers reais, a aprovação deste seller para ter retirada em loja deve ser feita com ao assessor comercial.

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.

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

Exemplo:

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

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.

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
Bahia: 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
Rio 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 and 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.
  • 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.
  • 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:

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

Exemplo:

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

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1234567/stores/1
{
   "status": "paused"
}
Nota:
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.

Exemplo:

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

Remover uma loja

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

Chamada:

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

Exemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1234567/stores/1
Nota:
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:

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

Exemplo:

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

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:

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

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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 dias (120 horas).


Chamada:

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

Exemplo:

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

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.

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 Bogotá (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

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

Uma vez que um item possui variações, poderá associá-las lojas nas quais poderá retirar o produto.

Regras:

  • O item base (sem variação) tem que estar associado a uma loja 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:

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

Exemplo:

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

JSON body:

{
  "availability_time_in_hours": 72
}
  • Se o seller quer adicionar disponibilidade diferentes para as variações, então deve utilizar o POST abaixo.

Chamada:

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

Exemplo:

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
}

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 lojas, 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 loja 3 de 72 horas, então ficará configurado 48 horas para todas as lojas em todos os tamanhos, exceto para o tamanho M na loja 3, que neste caso será exibida a disponibilidade em 72 horas.

Alterar o tempo de disponibilidade de uma loja

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

Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA12345678/stores/1
{
  "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:

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

Exemplo:

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

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 lojas associadas a um item

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

Chamada:

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

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 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:

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

Exemplo:

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

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 loja, 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:

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

Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/pickups/13092158
{
  "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": "Nombre y apellido"
    }
}

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.

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.

Chamada:

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

Exemplo:

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

Resposta:

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

As opções para os campos são:

  • fulfilled -> "true", "false",
  • rating -> "positive", "negative", "neutral"

Estados possíveis de um pick-up

ACTIVE: é o estado inicial do pick-up.
READY FOR PICKUP: é 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.


Configurar Retirada em Loja para usuários teste

Para começar a utilizar a Retirada em Loja em um usuário teste, carregue os dados do seu usuário de teste nesse formulário.


ou registre-se para receber as últimas notícias sobre nossa API