Gerenciar orders
Uma ordem é um pedido realizado por um cliente para um anúncio com a intenção de comprar conforme uma série de condições que ele irá escolher no fluxo do processo de compra online (checkout). 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 a serem preenchidas sobre o produto, bem como a possibilidade de reservar e/ou descontar estoque. Saiba mais sobre o fluxo de gerenciamento de orders simples e de carrinho, pagamentos e envios.
A - Recebe a notificação e obtém informações específicas sobre o pedido
B - Verifique se a ordem possui a tag "pack order"
C - Verifique se a ordem tem um envio associado
D - Obtenha os itens de envio (podem corresponder a orders diferentes)
E - Valide a quantidade de orders no envio
F - Obtenha as informações das orders associadas ao envio
G - Consulte as informações do envio
→Receba uma ordem →Alertas de fraude (frenados de envíos) →Calcular o valor total com envio →Informações dos produtos em orders →Consultar orders →Filtrar orders →Ordenar uma ordem →Orders recentes →Orders pendentes →Orders arquivadas →Orders de Mercado Shops →Consultar pedidos de Mercado Shops →Status da ordem →Códigos de erro →Código de resposta HTTP
- Para obter os detalhes de feedback é necessário fazer uma chamada ao recurso /feedbacks/$feedback_id com o id informado na ordem.
-Também pode ser consumida a informação dos feedbacks usando o recurso /orders/$order_id/feedback. Além disto recomendamos ativar o novo tópico de orders feedback para estar atualizado sobre os feedbacks recebidos.
Quando uma nova ordem é criada no usuário, os detalhes podem ser consultados através de uma solicitação ao recurso de orders:
Consulte os dados da billing info do comprador, realizando um GET para / orders / billing_info.
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. Ver os valores possíveis.
status_detail: detalhe do status.
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.
item: publicação específica.
quantity: quantidade de itens comprados.
sale_fee: comissão de vendas.
unit_price: preço unitário.
payments: pagamentos relacionados à ordem.
feedback: ID de feedback relacionadas à ordem.
shipping: ID do envio para esta ordem.
total_amount: valor total da ordem.
currency_id: ID de moeda.
tags: lista das tags selecionadas pelo vendedor, como entregue, pago.
taxes: valor com a soma dos impostos a serem pagos pelo pedido.
cancel_detail: detalhe do cancelamento da venda.
group: agrupamento lógico de cancelamento (mediations, fiscal, buyer, fraud, item, shipment, delivery, seller, internal).
code: código da causa do cancelamento.
description: descrição da causa do cancelamento.
requested_by: quem solicita o cancelamento (buyer, seller, Mercado Livre).
date: data do cancelamento.
application_id: ID da aplicação que solicita o cancelamento.
- Lembre-se de que as comissões são calculadas no momento da acreditação do pagamento, ou seja, quando o pedido fica visível para o vendedor e não quando o pedido é criado.
- Vendas que tiveram o pagamento falho, podem ter o meio de envio original da compra alterado, já que pode ocorrer uma re-compra. Para estes casos onde a compra original tinha un envio asociado, e na recompra o comprador optar por entrega a combinar,o status do envio ficará em status: cancelled, y substatus: closed_by_user, e a venda precisará ser cancelada.
- Para obter as informações de envio é necessário fazer uma chamada ao recurso /shipments/shipping.id com o id informado na ordem. Visite nosso guia de shipments..
-As vendas sempre são atualizadas, mesmo no caso de Fraude, e você poderá reconhecê-la pela tag "fraud_risk_detected" e também te enviaremos uma notificação no tópico "orders".
Após a aprovação de um pagamento, devido ao relacionamento com bancos e emissoras de cartão, podemos receber alertas de que o pedido em questão se trata de uma fraude e que para evitar perda financeira, a mercadoria não deve ser enviada ao comprador.
Neste caso, o pedido é marcado com a tag "fraud_risk_detected" e enviamos uma notificação no topic "orders_v2" com o ID deste pedido.
Após identificado, o pedido deve ser cancelado. Caso o vendedor já tenha enviado a mercadoria, será necessário comprovar o envio através site do Mercado Livre ou Mercado Pago.
Com a resposta obtida na chamada a GET /orders/:id e na GET /shipments/:shipping_id, ambas com o header x-format-new: true, deve realizar o seguinte cálculo:
*Na mesma moeda do item.
O total_amount e taxes.amount se o obtém através do recurso /orders, já o lead_time.cost se obtém em /shipments.
Nos casos em que taxes.currency_id é diferente de items.currency_id é necessário realizar a conversão.
Informações dos produtos em orders
Esta pesquisa mostrará todas as informações do(s) produtos que estão nesse mesmo pedido:
Para os pedidos do Fulfillment, o IMEI está sendo trazido também direto na Nota Fiscal.
Consultar orders
Em 6 de abril não retornaremos as informações pessoais:
- billing_info (obtenha esse dado fazendo um GET a /orders/billing_info)
Voçe pode obter-los fazendo um GET a /orders.
O seguinte recurso vai ajudá-lo a pesquisar cada ordem de usuários (vendedores e compradores). Lembre-se que os pedidos criados são salvos por até 12 meses e se você pesquisar como vendedor, continuará a filtrar os pedidos cancelados.
Filtrar orders
A partir de 17 de junho de 2021, o nó mediations do recurso /orders e /orders/search inclui apenas o campo de id de mediação. Verifique os detalhes da reclamação com o recurso /claims.
Para filtrar seus pedidos com o status de contas "paid" com os seguintes filtros:
tags: pode haver vários estados separados por ','
tags.not: pode haver vários estados separados por ','
q: é um campo genérico que permite pesquisar por:
ID da orden
nickname da contraparte
order.status: pode haver vários estados separados por ','
order.date_last_updated.from : data da última modificação da order
order.date_last_updated.to: data da última modificação da order
mediations.stage: pode haver vários estados separados por ','
mediations.status: pode haver vários estados separados por ','
feedback.status: pode haver vários estados separados por ','
feedback.sale.rating: pode haver vários estados separados por ','
feedback.purchase.rating: pode haver vários estados separados por ','
O filtro "q" não considera os valores first_name, last_name e email ao pesquisar uma orden.
Exemplo para filtrar pedidos por status:
Exemplo para pesquisar por vários critérios:
Exemplo para filtrar pedidos por data:
Usa até a hora e descarta a informação dos minutos, segundos e milissegundos.
Ordenar uma orden
Neste caso, você deve adicionar "sort" com o ID disponível da ordem que quiser aplicar, por exemplo: "date_desc"
Orders recentes
As orders recentes são os geradas mais recentemente para um usuário. A resposta incluirá orders nas quais a data atual for anterior à expiration_date e ainda não tenham sido qualificadas por nenhuma das partes. Pesquisa de orders recentes de um vendedor:
Orders pendentes
Esta pesquisa recuperará todos as orders em status "pendente" e omitirá as canceladas automaticamente. Se você quiser ver as orders de um vendedor, envie o seller_id:
Orders de Mercado Shops
As orders de Mercado Shops também estão disponíveis na API de Mercado Livre.
Para identificar essas orders, você deve utilizar a tag "mshops".
Exemplo de ordem de Mercado Shops:
Orders 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 orders arquivadas:
Pesquisa de orders arquivadas de um vendedor:
Pesquisa de orders arquivadas de um comprador:
Consultar pedidos de Mercado Shops
Para consultar os pedidos de Mercado Shops, basta consultar pela tag mshops como no exemplo a seguir:
confirmed Status inicial de uma ordem; ainda sem ter sido paga.
invalid A ordem foi invalidada por vir de um comprador malicioso.
- Requeria aprovação do pagamento para descontar do estoque, mas, no tempo de processo de aprovação, o item foi pausado/finalizado por falta de estoque, portanto, o pagamento é retornado ao comprador.
- 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.
- Se por alguma razão o vendedor qualificar a operação como não concretizada, a ordem assume o "status = confirmed". Caso exista um pagamento aprovado, este será automaticamente devolvido. Lembre que uma ordem não concretizada pelo vendedor será visualizada como "Cancelada" por front e por api terá "status = confirmed".
order_not_found Pedido não encontrado. $order_id incorreto. O pedido não foi encontrado; verifique se o order_id é o correto.
empty_order_id O ID do pedido deve ser preenchido, ele não pode ficar incompleto. $order_id nulo. O parâmetro order_id não pode ser nulo; consulte a URL utilizada.
invalid_order_id ID do pedido inválido. $order_id incorreto. O parâmetro order_id deve ser um número inteiro. (Para buscar seus pedidos, consulte esse assunto).
not_identified_user Usuário não identificado. Usuário não identificado. Enviar seu token.
not_owned_order O usuário não pode acessar ao pedido. $seller ou $buyer incorreto. Para visualizar um pedido, seu token de acesso deve ser gerado a partir do vendedor ou do comprador.
feedback_not_found O feedback não existe. Erro de resposta. Verifique se existe feeedback para dar uma resposta.
invalid_fulfilled O parâmetro "concluído"deve ser verdadeiro ou falso. Erro ao enviar feedback. Consulte o parâmetro $fulfilled; ele deve ser booleano (elimine as aspas) e verifique se o parâmetro $reason não é nulo, em caso de $fulfilled: falso.
reply_time_expired Tempo de resposta expirado. Há um período de 14 dias para responder ao feedback. Erro ao dar resposta sobre o feedback. A resposta pode ser enviada durante os 14 dias posteriores à data do feedback.
reply_already_exists Já existe resposta para o feedback. Erro ao dar resposta sobre o feedback. O feedback só aceita uma resposta.
Orders começarão a devolver o código http 206 quando não for possível obter algum dado. Tenha em conta que na maioria dos casos a informação recebida será suficiente para que você possa seguir trabalhando.