Gerenciamento de reservas
Conteúdos
→Benefícios
→Receba uma ordem
→Pesquisa de ordens
→Ordens recentes
→Ordens arquivadas
→Ordens pendentes
→Status da ordem
→Fluxo de Mercado Pago obrigatório (somente para países com MP)
→Como seu app sabe de uma compra?
→Receber notificação
→Receber ou criar mensagens
→Pagamentos
→Cenário de múltiplos pagamentos
→Como posso saber se existem dois pagamentos?
→Como obter informação de um pagamento?
→Como obter informação do pagamento sendo vendedor?
→Notas de ordens
→Como adicionar uma nota a uma ordem?
→Visualize notas de ordens
→Como alterar uma nota
→Elimine notas
→Bloquear ofertas
→Como bloqueio ofertas de um usuário específico?
→Consulta sua lista negra
→Elimine um usuário de sua lista negra
→Entregar ou devolver reserva
Benefícios
- Melhora posicionamento: Por cada reserva bem sucedida, as reservas estarão melhor posicionadas no listado.
- O vendedor contará com reputação: Se oferece uma boa experiência, será diferenciado dos concorrentes.
- Não tem custos adicionais.
Para conhecer em detalhe como funciona esta nova funcionalidade nos vendedores, convidamos você a clicar aqui.
Receba uma ordem
Quando uma nova ordem é criada no usuário, os detalhes podem ser consultados através de uma solicitação ao recurso de ordens.
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID
Resposta:
{
"id": 768570754,
"status": "paid",
"status_detail": null,
"date_created": "2013-05-27T10:01:50.000-04:00",
"date_closed": "2013-05-27T10:04:07.000-04:00",
"order_items": - [
- {
"item": - {
"id": "MLB12345678",
"title": "Nissan March MARCH 1.0 S 12V FLEX 4P MANUAL",
"category_id": "MLB1234",
"variation_id": null,
"variation_attributes": [],
},
"quantity": 1,
"unit_price": 499,
"full_unit_price": 25000,
"currency_id": "BRL",
}
],
"total_amount": 499,
"currency_id": "BRL",
"buyer": - {
"id": "123456789",
"nickname": "COMPRADORTESTE",
"email": "b@b.com",
"phone": - {
"area_code": "11",
"number": "12345678",
"extension": null,
},
"first_name": "Comprador de testes",
"last_name": "da Silva",
"billing_info": - {
"doc_type": "CPF",
"doc_number": "12345678910",
},
},
"seller": - {
"id": "123456789",
"nickname": "VENDEDORTESTES",
"email": "a@a.com",
"phone": - {
"area_code": null,
"number": "11 12345678",
"extension": "11",
},
"first_name": "Vendedor de Testes",
"last_name": "testes de documentacao",
},
"payments": - [
- {
"id": "596707837",
"transaction_amount": 499,
"currency_id": "BRL",
"status": "approved",
"date_created": null,
"date_last_modified": null,
},
],
"feedback": - {
"purchase": null,
"sale": null,
},
"shipping": - {
"status": "to_be_agreed"
},
"tags": - [
"reservation",
"paid",
"not_delivered"],
}
Há grande número de atributos conforme a ordem. A seguir, vamos ver uma descrição dos campos mais importantes.
id Identificador único da ordem.
date_created Data de criação da ordem.
date_closed Data de confirmação da ordem. Quando uma ordem muda pela primeira vez de status é definida como: confirmed / paid e descontada do estoque do item.
expiration_date Prazo limite para o usuário qualificar; após essa data, o feedback se torna visível, os pagamentos são emitidos (caso houver) e os encargos são criados.
status Status da ordem.
status_detail Detalhe do status, caso a ordem seja cancelada.
code Código do status.
description Descrição do status.
comprador Informações do comprador.
vendedor Informações do vendedor.
order_items Publicações na ordem.
unit_price Preço da reserva.
full_unit_price Preço total do item.
payments Pagamentos relacionados à ordem.
feedback Informações de feedback relacionadas à ordem.
total_amount Valor total da ordem.
currency_id ID de moeda.
tags Lista das tags selecionadas pelo vendedor, como entregue, pago, além da tag “reservation” que marca a ordem como reserva.
Pesquisa de ordens
O recurso de pesquisa de ordens vai ajudá-lo a pesquisar cada ordem de usuários com token válido.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?buyer=$BUYER_ID
No search a orders os campos “available_filters” e “available_sorts” estão disponíveis. Leve em conta que o search não mostra as ordens com status Payment_required.
Como filtrar?
Para filtrar suas ordens com status “paid”, encontrará entre os “available_filters” disponíveis o ID “order.status” e, dentro dele, o value com ID “paid”.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=$SELLER_ID&order.status=paid
Caso deseje filtrar suas ordens por data, deverá fazê-lo da forma a seguir:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=&order.date_created.from=2015-07-01T00:00:00.000-00:00&order.date_created.to=2015-07-31T00:00:00.000-00:00
Como ordenar?
Neste caso, você deve adicionar “sort” com o ID disponível da ordem que quiser aplicar, por exemplo: “date_desc”.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search?seller=$SELLER_ID&order.status=paid&sort=date_desc
Ordens recentes
As ordens recentes são as geradas mais recentemente para um usuário. A resposta incluirá ordens nas quais a data atual for anterior à expiration_date e ainda não tenham sido marcadas como entregue o veículo. Pesquisa de ordens recentes de um vendedor:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/recent?seller=$SELLER_ID
Pesquisa de ordens recentes de um comprador:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/recent?buyer=$BUYER_ID
Ordens arquivadas
Se você procurar uma ordem com expiration_date posterior à data atual ou que foi qualificada por ambas as partes, pode utilizar o recurso de pesquisa em ordens arquivadas:
Pesquisa de ordens arquivadas de um vendedor:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/archived?seller=$SELLER_ID
Pesquisa de ordens arquivadas de um comprador:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/archived?buyer=$BUYER_ID
Ordens pendentes
Esta pesquisa recuperará todos as ordens em status "pendente" e omitirá as canceladas automaticamente. Se você quiser ver as ordens de um vendedor, envie o seller_id:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/pending?seller=$SELLER_ID
Para pesquisar por comprador, substitua os parâmetros como é mostrado a seguir:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/search/pending?buyer=$USER_ID
Status da ordem
Os status da ordem são:
payment_required
O pagamento da ordem deve ter sido confirmado para exibir as informações do usuário.
payment_in_process
Há um pagamento relacionado à ordem, mais ainda não foi creditado.
partially_paid
A ordem tem um pagamento associado creditado, porém, insuficiente.
paid
A ordem tem um pagamento associado creditado.
cancelled
Por alguma razão, a ordem não foi completada.*
Fluxo de Mercado Pago obrigatório (somente para países com MP)
Como saber se um site tem Mercado Pago ativo?
Para obter essa informação, você deve realizar a seguinte chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA
Caso você obtenha "MLAMP" como resposta dentro dos "payment_method_ids", poderá trabalhar sem problemas com este fluxo. Aclaração: MLAMP é o ID do método de pagamento Mercado Pago:
curl-X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/payment_methods/MLAMP
Dentro da nossa plataforma, você vai encontrar ordens que podem entrar pelo fluxo obrigatório de Mercado Pago como único meio de pagamento e outras que não. Os cenários apresentados a seguir são aqueles em que você pode encontrar esta opção de maneira obrigatória:
- Todos as ordens de MLB.
- Todos as ordens de MLA e MLM por venda de produtos com "condition": "new".
- Anúncios de Lojas Oficiais em todos os países com Mercado Pago.
- Categorias com Mercado Pago como única opção (Mais informações em: “Categorias com pagamento imediato”).
- Usuário automaticamente marcado para que suas operações vão por este fluxo, com a marca “immediate_payment” na API de users.
- Vendedor "auto" marcado para que suas vendas vão por este fluxo.
Agora vamos explicar como é o funcionamento geral das ordens, estejam elas dentro deste fluxo ou não:
1) Ordens dentro deste fluxo são criadas em status “payment_required”. Nesse momento, têm as seguintes características:
- Não são visíveis para o seller.
- O estoque não é descontado do item.
- Não têm o campo date_closed estabelecido.
- Não têm dados da contraparte.
- Somente é enviada a notificação do topic "create_orders".
2) Quando o pagamento é creditado pelo valor total da venda, a ordem passa do status "payment_required" para "paid". Nesse momento:
- Passam a ser visíveis para o seller.
- O campo date_closed é estabelecido.
- São adicionados os dados da contraparte.
- Também começam a ser enviadas as notificações do topic "orders".
Como seu app sabe de uma compra?
A criação de uma ordem é um evento que se produz do lado do Mercado Livre, portanto, você deverá se cadastrar no nosso feed de orders para saber em tempo real quando esse evento ocorre. Vá para o nosso Gerenciador de Aplicativos e edite as Configurações de Notificações de seu aplicativo. Mais informações sobre criar e configurar um novo aplicativo neste link. Você deve selecionar um Callback URL: configure a URL pública do domínio onde você quiser receber todas as notificações do Mercado Livre. Por exemplo: “https://backend.soleorigami.com/notification”.

Esta configuração permite que você interaja com as notificações do Mercado Livre. Todos os eventos (como pagamento e envio) relacionados a uma ordem serão notificados a seu callback URL.
Receber notificação
Mercado Livre vai enviar notificações através de uma mensagem POST contendo informações. O atributo mais importante da mensagem é o user_id, relacionado à notificação; o segundo em importância é o recurso. O recurso é o elemento atualizado ou criado.
{
"user_id": 1234,
"resource": "/orders/731867397",
"topic": "orders",
"received": "2011-10-19T16:38:34.425Z",
"application_id" : 14529
"sent" : "2011-10-19T16:40:34.425Z",
"attempts" : 0
}
Após receber a notificação, você deve enviar um aviso de recepção [acknowledgment] (ACK 200) para Mercado Livre a fim de não receber mais notificações.
Receber ou criar mensagens
Para trabalhar com Mensagens de pós venda sugerimos ler nossa documentação.
Pagamentos
Mercado Pago é a plataforma de pagamentos de Mercado Livre. Se você quiser integrar uma solução de pagamentos em sua plataforma, deve consultar o site de desenvolvedores de Mercado Pago.
Cenário de múltiplos pagamentos
Em alguns casos, quando o pagamento é rejeitado porque o cartão de crédito atinge o limite, permitimos que os usuários adicionem outro pagamento com um segundo cartão de crédito.
Como posso saber se existem dois pagamentos?
Quando você faz uma solicitação GET para a API de pedidos, poderá ver que dentro do conjunto de pagamentos existem dois ID com os detalhes de cada pagamento.
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/893431118
Resposta:
{
"buyer": {
"alternative_phone": {
"area_code": null,
"extension": null,
"number": ""
},
"billing_info": {
"doc_number": "67045427794",
"doc_type": "CPF"
},
"email": "test_user_21963158@testuser.com",
"first_name": "Test",
"id": 160903317,
"last_name": "Test",
"nickname": "TETE2022123",
"phone": {
"area_code": "01",
"extension": null,
"number": "1111-1111"
}
},
"coupon": {
"amount": 0,
"id": null
},
"currency_id": "BRL",
"date_closed": null,
"date_created": "2014-10-26T22:46:18.000-04:00",
"feedback": {
"purchase": null,
"sale": null
},
"id": 893431118,
"last_updated": "2014-10-26T22:50:10.000-04:00",
"mediations": [],
"order_items": [
{
"currency_id": "BRL",
"item": {
"id": "MLB600034093",
"title": "Item De Testeo, Por Favor No Ofertar --kc:off",
"category_id": "MLB1234",
"variation_attributes": [],
"variation_id": null
},
"quantity": 1,
"unit_price": 591,
"full_unit_price": 25000,
}
],
"paid_amount": 591,
"payments": [
{
"activation_uri": null,
"atm_transfer_reference": {
"company_id": null,
"transaction_id": null
},
"available_actions": [],
"card_id": null,
"collector": {
"id": 169648308
},
"coupon_amount": 0,
"coupon_id": null,
"currency_id": "BRL",
"date_created": "2014-10-26T22:48:46.000-04:00",
"date_last_modified": "2014-10-27T00:51:53.000-04:00",
"id": 885920310,
"installments": 1,
"issuer_id": "25",
"operation_type": "regular_payment",
"order_id": 893431118,
"overpaid_amount": 0,
"payer_id": 160903317,
"payment_method_id": "visa",
"payment_type": "credit_card",
"reason": "Item De Testeo, Por Favor No Ofertar --kc:off",
"shipping_cost": 0,
"site_id": "MLB",
"status": "approved",
"status_code": null,
"status_detail": "accredited",
"total_paid_amount": 296,
"transaction_amount": 296
},
{
"activation_uri": null,
"atm_transfer_reference": {
"company_id": null,
"transaction_id": null
},
"available_actions": [],
"card_id": null,
"collector": {
"id": 169648308
},
"coupon_amount": 0,
"coupon_id": null,
"currency_id": "BRL",
"date_created": "2014-10-26T22:50:10.000-04:00",
"date_last_modified": "2014-10-26T22:50:21.000-04:00",
"id": 885920410,
"installments": 3,
"issuer_id": "25",
"operation_type": "regular_payment",
"order_id": 893431118,
"overpaid_amount": 0,
"payer_id": 160903317,
"payment_method_id": "visa",
"payment_type": "credit_card",
"reason": "Item De Testeo, Por Favor No Ofertar --kc:off",
"shipping_cost": 0,
"site_id": "MLB",
"status": "approved",
"status_code": null,
"status_detail": "accredited",
"total_paid_amount": 315.62,
"transaction_amount": 295
}
],
"seller": {
"alternative_phone": {
"area_code": null,
"extension": null,
"number": ""
},
"email": "test_user_70385259@testuser.com",
"first_name": "Test",
"id": 169648308,
"last_name": "Test",
"nickname": "TETE6072468",
"phone": {
"area_code": "01",
"extension": null,
"number": "1111-1111"
}
},
"shipping": {
"status": "to_be_agreed"
},
"status": "paid",
"status_detail": null,
"tags": [
"not_delivered",
"paid"
],
"total_amount": 591,
"total_amount_with_shipping": 591
}
Como obter informação de um pagamento?
Para obter informação do pagamento de um comprador utilizando o token, você deverá recorrer ao recurso “payments”.
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/payments
Como obter informação do pagamento sendo vendedor?
Para obter informação do pagamento desde o rol de vendedor, o recurso ao qual você deverá recorrer com o payment_id é “collections”.
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/collections/$COLLECTION_ID
Notas de ordens
Uma nota é uma anotação que os vendedores podem adicionar às ordens. As notas podem ter até 300 caracteres e, após terem sido publicadas, é possível alterá-las ou eliminá-las.
Como adicionar uma nota a uma ordem?
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d '{
"note": "test",
}'
https://api.mercadolibre.com/orders/$ORDER_ID/notes
Visualize notas de ordens
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID/notes
Como alterar uma nota
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d '{
"note": "test2",
}'
https://api.mercadolibre.com/orders/$ORDER_ID/notes/$NOTE_ID
Elimine notas
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/orders/$ORDER_ID/notes/$NOTE_ID
Bloquear ofertas
Embora estejam disponíveis uma prestação e fluxos de prevenção de fraude para manter a segurança de compradores e vendedores, em alguns casos, você pode encontrar usuários que, por algum motivo, ofertam nos anúncios. Estes casos podem ser enviados para a lista negra, a fim de evitar que voltem a ofertar.
Como bloqueio ofertas de um usuário específico?
Faça uma solicitação POST com o cust_id do usuário que você quer bloquear no JSON e o seu na url, como no exemplo a seguir:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d { user_id: {cust_id} } https://api.mercadolibre.com/users/$CUST_ID/order_blacklist
Consulta sua lista negra
Se você quiser saber quais são os usuários de sua lista negra, faça uma solicitação GET para a API com seu cust_id na url:curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$CUST_ID/order_blacklist
Elimine um usuário de sua lista negra
Se você não quer continuar bloqueando um usuário para ele fazer ofertas, pode eliminá-lo de sua lista negra realizando uma solicitação DELETE para a API com seu cust_id e o cust_id do usuário.
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$YOUR_CUST_ID/order_blacklist/$CUST_ID
Entregar ou devolver reserva
De acordo com as regras de negócios do Mercado Livre, uma vez completada a reserva, o vendedor deve informar a entrega do veículo. Compradores e vendedores consolidam suas reputações com base na quantidade de veículos reservados ou entregues conforme o caso.
- Veículo entregue
- Devolver reserva
Se a reserva foi concretizada e o veículo entregue, deverá realizar uma solicitação POST para a ordem, como mostrado abaixo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d
'{
"fulfilled": true,
"rating": "positive"
}'
"https://api.mercadolibre.com/orders/$ORDER_ID/feedback"
Após o comprador confirmar que recebeu o veículo, o dinheiro da reserva será liberado na sua conta.
Para devolver uma reserva, realize uma solicitação POST para a ordem, como mostrado abaixo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d
'{
"fulfilled": false,
"rating": "neutral"
}'
"https://api.mercadolibre.com/orders/$ORDER_ID/feedback"
Para devolver uma reserva, realize uma solicitação POST para a ordem, como mostrado abaixo:
Descrição de recursos
Completado Verdadeiro ou Falso. Informa se a entrega do veículo foi concretizada. Obrigatório.
Qualificação É 'neutro' em caso de 'completado': 'falso' ou 'positivo' em caso de 'completado': 'verdadeiro'. Obrigatório.