Gerenciamento de reservas

Em todo anúncio do tipo “veículo” é possível encontrar o botão de reserva disponível, para que o comprador possa garantir a compra, reservando o veículo pagando um sinal, via Mercado Pago. Sempre que há uma reserva, é gerada uma ordem de pagamento. Uma ordem é um pedido realizado por um cliente para um anúncio com a intenção de reservar um automóvel e pode terminar em uma venda conforme combinado com o vendedor. Estas condições são detalhadas na ordem, que será replicada nas contas do comprador e do vendedor. A ordem contém grande quantidade de informações sobre o automóvel, bem como a possibilidade de reservar e/ou descontar estoque. Ou seja, o integrador pode ler estas reservas (ordens) para o seu sistema e avisar o cliente que seu anúncio recebeu uma reserva. E mais: também é possível implementar as ações do vendedor de entrega/cancelamento da reserva. Todos estes pontos estão explicados nas seções abaixo.

Nota:

Essa funcionalidade está disponível na Argentina e no Brasil na fase inicial, isto é, a reserva é notificada ao vendedor via e-mail por tempo limitado.

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.

Nota:

Da mesma forma que acontece cada vez que é atualizada a informação de uma ordem, caso seja descoberto que a compra foi fraudulenta, será marcada com a tag “fraud_risk_detected” e enviaremos uma notificação com o assunto “orders” e a ID dessa ordem.

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

Nota:

Para filtrar por data apenas é utilizada até a hora. A informação dos minutos, segundos e milissegundos é descartada.

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

Nota:

Por default, uma ordem date_asc já vem aplicada. A data segundo a qual é organizada é:

Sellers por date_closed.
Buyers por date_created.

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

Notas:

Uma ordem pode ser cancelada pelos seguintes motivos:

Requeria pagamento, mas, após certo tempo, não foi paga, por isso é automaticamente cancelada.
Após uma transação ter sido efetuada, o vendedor é proibido no site por alguma razão.
Caso o vendedor devolva a reserva, a ordem passará ao “status = cancelled” e status_detail.code = feedback. Caso exista um pagamento aprovado, este será devolvido automaticamente.
Caso o vendedor confirme que entregou o veículo e o comprador diz que não o tem, a ordem toma o “status = cancelled” e status_detail.code = buyer. Caso exista um pagamento aprovado, este será devolvido automaticamente.
Outra opção é a expiração da ordem, portanto, também será tomada com o “status = cancelled” e status_detail.code = expired_order. Caso exista um pagamento aprovado, este será devolvido automaticamente.

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

Nota:

Se quiser tomar a ordem da reserva, selecione a opção “orders_v2”.

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

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.

Devolver reserva

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.