Retirada em loja
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
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
Examplo:
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
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 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.; 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.; MSegunda 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"
}
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
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 días (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 | 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 |
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 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 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 o Retirada em Loja em um usuário teste, carregue os dados do seu usuário de teste nesse formulário.