Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.![circulos azuis em degrade](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevImgs/230801158836-ImgMS--1-.png)
Documentação do
O que é uma devolução?
Uma devolução é o processo através do qual um comprador pode devolver um produto ao vendedor. Este procedimento pode ser ativado por diversas razões, tais como discrepâncias entre a descrição do produto e o seu estado real, problemas de funcionamento, ou até mesmo uma mudança de opinião por parte do comprador. O bom gerenciamento das devoluções é fundamental para manter a confiança e satisfação do cliente, garantindo que qualquer problema seja resolvido de forma transparente e eficiente.
![](https://http2.mlstatic.com/storage/developers-site-cms-admin/187249566846-diagramadevoluciones-mlb.drawio.png)
Gerenciar uma devolução
Para identificar corretamente uma devolução, fazemos as seguintes recomendações:
- Monitorar a notificação da reclamação: Ouça o feed de reclamações (feed claims), que contém as informações do pedido no qual a reclamação se originou.
- Consultar o recurso /claims/$CLAIMS para acessar o campo "related_entities", que oferece uma lista de entidades vinculadas à reclamação. Se existir o valor "return" significa que há uma devolução associada a esta reclamação. Agora você pode consultar o recurso de Returns para obter os detalhes da devolução e tomar as medidas necessárias dentro dos prazos estabelecidos.
Para mais informações, consulte a documentação de Gestão de Reclamações.
Consultar uma devolução
Para consultar uma devolução, faça uma solicitação para post-purchase/v2/claims/$CLAIM_ID/returns, especificando o $CLAIM_ID. Isso fornecerá informações detalhadas sobre a devolução associada à reclamação correspondente.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v2/claims/$CLAIM_ID/returns
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v2/claims/5255026166/returns
Resposta:
{
"last_updated": "2023-02-25T00:02:22.575-04:00",
"shipping": {
"id": 42049162337,
"status": "cancelled",
"tracking_number": "MEL42049162337FMDOR01",
"lead_time": {
"estimated_delivery_time": {
"date": "2023-02-20T00:00:00.000-06:00"
}
},
"status_history": [
{
"status": "handling",
"substatus": null,
"date": "2023-02-15T15:43:14.944-04:00"
},
{
"status": "ready_to_ship",
"substatus": "ready_to_print",
"date": "2023-02-15T15:43:18.377-04:00"
},
{
"status": "cancelled",
"substatus": "return_expired",
"date": "2023-02-25T00:02:20.394-04:00"
}
],
"origin": {
"type": "selling_address",
"sender_id": 1299347553,
"shipping_address": {
"address_id": 1280687101,
"address_line": "Calle Transportes 234",
"street_name": "Calle Transportes",
"street_number": "234",
"comment": "Referencia: NA",
"zip_code": "03940",
"city": {
"id": "TUxNQ0JFTjM2MjQ",
"name": "Benito juárez"
},
"state": {
"id": "MX-DIF",
"name": "Distrito Federal"
},
"country": {
"id": "MX",
"name": "Mexico"
},
"neighborhood": {
"id": null,
"name": "Crédito Constructor"
},
"municipality": {
"id": null,
"name": null
},
"types": [
"default_buying_address"
],
"latitude": 19.365558,
"longitude": -99.179523,
"geolocation_type": "GEOMETRIC_CENTER"
}
},
"destination": {
"name": "seller_address"
}
},
"refund_at": "delivered",
"date_closed": null,
"resource": "order",
"date_created": "2023-02-15T15:43:14.694-04:00",
"claim_id": 5255026166,
"status_money": "retained",
"resource_id": 2000007760636316,
"type": "dispute",
"subtype": null,
"status": "opened",
"warehouse_review": {
"product_condition": "",
"product_destination": "",
"benefited": false
},
"seller_review": {
"status": "",
"reason_id": null
}
}
Campos da resposta:
A resposta de um GET ao recurso v2/claims/$CLAIM_ID/returns fornecerá os seguintes campos:
- last_updated: última atualização da devolução.
- shipping: detalhe do envio da devolução.
- id: número de identificação do envio.
- status: estado em que se encontra o envio.
- tracking_number: número de rastreamento do envio da devolução.
- lead_time
- estimated_delivery_time: tempo estimado de chegada do envio da devolução.
- date: tempo estimado de chegada do envio da devolução.
- status_history: representa o histórico dos estados pelos quais foi passando o envio da devolução.
- status: são os estados pelos quais pode passar o retorno:
- pending: quando se gera o envio.
- ready_to_ship: etiqueta pronta para despachar.
- shipped: enviado.
- not_delivered: não entregue.
- delivered: entregue.
- cancelled: envio cancelado.
- substatus: null
- date: data do estado.
- status: são os estados pelos quais pode passar o retorno:
- origin: endereço de origem do envio de devolução.
- type: tipo de endereço.
- sender_id: código do comprador (buyer_id).
- shipping_address: detalhe do endereço.
- address_id:
- address_line:
- street_name:
- street_number:
- comment:
- zip_code:
- city:
- state:
- country:
- neighborhood:
- municipality:
- types:
- latitude:
- longitude:
- geolocation_type:
- destination: informação do destino da devolução.
- name
- seller_address: destino vendedor.
- warehouse: destino depósito do Mercado Livre.
- name
- refund_at: quando se devolve o dinheiro ao comprador.
- shipped: quando o comprador realiza o despacho do envio da devolução.
- delivered: 3 dias depois de o vendedor receber o envio.
- n/a: para casos low cost que não geram uma devolução.
- date_closed: data em que se fecha a devolução.
- resource: nome do recurso ao qual se associa a devolução.
- date_created: data em que se criou a devolução.
- claim_id: o id da reclamação à qual está associada a devolução.
- status_money: estado em que se encontra o dinheiro da devolução.
- retained: dinheiro na conta, mas não disponível, retido.
- refunded: dinheiro devolvido ao comprador.
- available: dinheiro na conta disponível.
- resource_id: ID do recurso.
- type: tipo de devolução.
- claim: devolução por reclamação.
- dispute: devolução por mediação.
- automatic: devolução automática.
- subtype: o subtipo de devolução.
- low_cost: devolução automática do tipo low cost.
- return_partial: devolução parcial.
- return_total: devolução total.
- status: estados pelos quais pode passar uma devolução.
- opened: quando o comprador inicia uma reclamação no Mercado Livre por uma devolução.
- shipped: devolução enviada, dinheiro retido.
- closed: estado final da devolução ao encerramento da mesma e do claim_id associado.
- delivered: envio em mãos do vendedor.
- not_delivered: devolução não entregue.
- cancelled: devolução cancelada, dinheiro disponível.
- failed: devolução falhada.
- expired: devolução expirada.
- warehouse_review: resultado do processo do triage que é feito no depósito (revisão do produto), este array tem informação unicamente se o atributo “destination” é igual warehouse, do contrário se mostra nulo.
- product_condition
- saleable: significa que o produto está apto para voltar a ser vendido e é feito o restock automaticamente.
- unsaleable: o produto não está em condições para a venda.
- discard: o produto é descartado porque é diferente do que o comprador obteve na transação e devia devolver, por exemplo uma pedra.
- product_destination
- buyer
- seller
- meli
- benefited
- true: se reintegra o dinheiro da venda ao vendedor.
- false: se reintegra o dinheiro da transação ao comprador.
- product_condition
- seller_review: fornece informações sobre a revisão realizada pelo vendedor.
- status: estado da revisão. Pode assumir um dos seguintes valores:
- pending: a devolução está pendente de revisão pelo vendedor.
- claimed: o vendedor revisou o produto e decidiu que ele não está nas condições esperadas.
- failed: o responsável de CX decide que o vendedor é beneficiário (o status anterior é claimed).
- success: o vendedor revisou a devolução e indicou que chegou nas condições esperadas.
- reason_id: Identificador da razão pela qual o vendedor indicou um problema com o produto. Os valores possíveis são os retornados pelo recurso reasons/return-fail. Atualmente, os valores possíveis são:
- null: Quando nenhuma razão é especificada. Este campo é sempre null, exceto quando o status é 'claimed'.
- SRF2: O produto chegou danificado.
- SRF3: A devolução está incompleta.
- SRF4: Foi devolvido um produto diferente do enviado.
- SRF5: O produto não está no pacote.
- SRF6: Reportar outra falha no produto.
- SRF7: Ainda não recebeu o produto.
- status: estado da revisão. Pode assumir um dos seguintes valores:
Revisão OK de uma devolução
Quando uma devolução chega ao vendedor, ele tem a possibilidade de revisar a mesma, indicando se o produto chegou nas condições esperadas ou se há algum problema com ele.
Para realizar uma revisão OK de uma devolução, confirmando que o produto chegou nas condições esperadas, o recurso /claims/$CLAIM_ID/actions/return-review-ok foi habilitado.
Para saber se o vendedor já tem habilitada a opção de fazer uma revisão ok de uma devolução, pode-se utilizar o recurso /claims/$CLAIM_ID. Dentro do array de “players”, buscamos o player “type”: “seller” e validamos que em suas "available_actions" exista "action": "return_review_ok"
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/actions/return-review-ok
Exemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -d
https://api.mercadolibre.com/post-purchase/v1/claims/5255026166/actions/return-review-ok
Resposta:
{
"id":5255026166,
"resource_id": 2000007760636316,
"status": "closed",
"type": "mediations",
"stage": "claim",
"parent_id": null,
"resource": "order",
"reason_id": "PDD9949",
"fulfilled": true,
"quantity_type": "total",
"players": [
{
"role": "complainant",
"type": "buyer",
"user_id": 1277895049,
"available_actions": []
},
{
"role": "respondent",
"type": "seller",
"user_id": 1582937623,
"available_actions": [
{
"action": "return_review_fail",
"mandatory": false,
"due_date": null
},
{
"action": "return_review_ok",
"mandatory": true,
"due_date": "2024-06-03T22:43:00.000-04:00"
}
]
},
{
"role": "mediator",
"type": "internal",
"user_id": 46122402,
"available_actions": []
}
],
"resolution": {
"reason": "item_returned",
"date_created": "",
"benefited": [
"complainant"
],
"closed_by": "mediator",
"applied_coverage": true
},
"site_id": "MLA",
"date_created": "2024-05-29T23:48:32.000-04:00",
"last_updated": "2024-05-29T23:51:26.370-04:00"
}
Campos da resposta
A resposta bem-sucedida de um GET ao recurso /actions/return-review-ok retornará um status code 201 e os seguintes campos:
- id: ID da reclamação
- resource: ID do recurso sobre o qual a reclamação é criada. Depende do “resource”
- status: Status da reclamação
- opened
- closed
- type: Tipo de reclamação
- mediations: reclamação entre comprador e vendedor.
- return: Devolução de produto.
- fulfillment: Reclamação entre comprador e Mercado Livre com origem de compra com envio full.
- ml_case: Cancelamento da compra por parte do comprador devido a envio demorado.
- cancel_sale: Cancelamento de compra por parte do vendedor. Sempre em status: "closed" e stage: "none". O rol complainant sempre vai ser do tipo seller, collector ou sender dependendo do recurso da reclamação.
- cancel_purchase: cancelamento de compra por parte do comprador
- change: Troca de Produto.
- service: Cancelamento de um serviço ordens bundle.
- stage: Etapa da reclamação
- claim: etapa de reclamação onde intervêm o comprador e o vendedor
- dispute: etapa de mediação onde intervém um representante do Mercado Livre
- recontact: etapa na qual uma das partes entra em contato após a reclamação/disputa ser encerrada
- none: não se aplica
- stale: Etapa de reclamação onde intervêm o comprador e o Mercado Livre para reclamações do tipo ml_case.
- parent_id: ID de outra reclamação da qual depende
- resource: Identificador do recurso sobre o qual a reclamação é criada. Interfere nos atores da reclamação
- payment: Pagamento
- order: Ordem
- shipment: Envio
- purchase: Compra
- reason_id: Razão/motivo pelo qual a reclamação foi criada. Interfere diretamente nas soluções que podem ser propostas
- PNR: Produto Não Recebido
- PDD: Produto Diferente ou Defeituoso
- CS: Compra Cancelada
- fulfilled: Indica se a reclamação foi iniciada por um produto entregue ou não
- quantity_type: informa se a reclamação é parcial ou não
- partial: indica que é uma reclamação parcial
- total: indica que é uma reclamação total
- players: Lista dos atores que participam da reclamação com suas respectivas ações e tempos disponíveis
- role: papel na reclamação
- complainant: pessoa que reclama.
- respondent: pessoa a quem é dirigida a reclamação.
- mediator: pessoa que intervém para ajudar a resolver o problema.
- warehouse_dispatcher: pessoa encarregada de revisar o produto nas devoluções ao warehouse.
- type: papel que a pessoa ocupa na operação que está sendo reclamada
- payment: comprador - collector.
- order: comprador - vendedor.
- shipment: receptor - remetente.
- purchase: comprador - Mercado Livre
- user_id: ID do usuário no ML que desempenha o papel
- available_actions: Lista de ações que cada uma das partes envolvidas pode executar
- players: lista dos atores que participam da reclamação com suas respectivas ações e tempos disponíveis.
- action: Nome da ação
- send_message_to_complainant: enviar mensagem para o comprador (com ou sem anexos).
- send_message_to_mediator: enviar mensagem para o mediador (com ou sem anexos).
- recontact (ainda não disponível): reabrir uma reclamação já encerrada, por meio de uma interação, como uma mensagem.
- refund: devolver o dinheiro do comprador. Deve ser realizado pelo front do Mercado Livre ou Mercado Pago.
- open_dispute: iniciar uma mediação.
- send_potential_shipping: enviar uma promessa de envio, uma data.
- add_shipping_evidence: publicar uma evidência de que o produto foi enviado.
- send_attachments: enviar mensagem com anexos.
- allow_return_label: gerar etiqueta de devolução.
- allow_partial_refund: oferecer reembolso parcial do dinheiro ao comprador. Deve ser realizado pelo front do Mercado Livre.
- send_tracking_number: enviar o número de rastreamento (tracking number).
- return_review_fail: realizar uma revisão falhada de uma devolução.
- return_review_ok: realizar uma revisão ok de uma devolução.
- mandatory: tipo de ação
- respondent: pessoa a quem é dirigida a reclamação.
- warehouse_dispatcher: pessoa encarregada de revisar o produto nas devoluções ao warehouse.
- action: Nome da ação
- players: lista dos atores que participam da reclamação com suas respectivas ações e tempos disponíveis.
- role: papel na reclamação
- resolution: Lista dos atores que participam da reclamação com suas respectivas ações e tempos disponíveis
- reason: Motivo de resolução/fechamento
- already_shipped: Produto a caminho
- buyer_claim_opened: Fechamento da devolução por abertura de outra reclamação
- buyer_dispute_opened: Fechamento da devolução por abertura de outra reclamação em disputa (com mediação do Mercado Livre)
- charged_back: Fechamento por chargeback
- coverage_decision: Disputa fechada com cobertura do ML
- found_missing_parts: Comprador encontrou as partes faltantes
- item_returned: Produto devolvido
- no_bg: Fechamento sem cobertura do ML
- not_delivered: Produto não entregue
- opened_claim_by_mistake: Comprador criou a reclamação por engano
- other: Outro caso
- partial_refunded: Reembolso parcial do pagamento ao comprador
- payment_refunded: Pagamento devolvido ao comprador
- preferred_to_keep_product: Comprador preferiu ficar com o produto
- product_delivered: Decisão de um representante do MercadoLibre
- reimbursed: Reembolso
- rep_resolution: Decisão de um representante do MercadoLibre
- respondent_timeout: Vendedor não responde
- return_cancelled: Devolução cancelada pelo comprador
- return_expired: Devolução vencida sem troca ou sem envio
- seller_asked_to_close_claim: Vendedor pediu ao comprador que fechasse a reclamação
- seller_did_not_help: Comprador conseguiu resolver o problema sem a ajuda do vendedor
- seller_explained_functions: Vendedor explicou como o item funcionava
- seller_sent_product: Vendedor enviou o produto
- timeout: Fechamento por tempo limite de ação ao comprador
- warehouse_decision: Fechamento por revisão de produto no Warehouse
- warehouse_timeout: Fechamento por demora na revisão de produto no Warehouse
- worked_out_with_seller: Comprador resolveu com o vendedor fora do ML
- low_cost: Fechamento porque o custo do envio é maior que o do produto
- item_changed: Fechamento porque a troca foi feita internamente
- change_expired: A troca não foi realizada e o tempo permitido foi cumprido
- change_cancelled_buyer: Fechamento de uma troca pelo comprador
- change_cancelled_seller: Fechamento proativo de uma troca pelo vendedor
- change_cancelled_meli: Fechamento de uma troca pela Meli
- shipment_not_stopped: Fechamento porque o envio não pôde ser interrompido
- cancel_installation: Cancelamento de serviço de instalação
- created: Data de resolução/fechamento da reclamação
- benefited: Beneficiários da resolução
- respondent
- closed_by: Ator que fechou a reclamação
- mediator
- buyer
- respondent
- false
- applied_coverage: Pagamento ao comprador
- site_id: ID do site onde a reclamação foi desenvolvida
- date_created: Data de criação/abertura da reclamação
- last_updated: Data da última atualização da reclamação
- reason: Motivo de resolução/fechamento
Revisão falhada de uma devolução
Quando uma devolução chega ao vendedor, este tem a possibilidade de fazer uma revisão da mesma indicando se o produto chegou nas condições esperadas ou se há algum problema com o mesmo.
Para saber se o vendedor já tem habilitada a opção de fazer uma revisão falhada, podemos consultar o recurso /claims/$CLAIM_ID. Dentro do array de “players”, buscamos o player “type”: “seller” e validamos que em suas "available_actions" exista "action": "return_review_fail"
Para realizar uma revisão falhada de uma devolução, indicando que o produto chegou com algum problema, utilizam-se três recursos que se descrevem a seguir:
Obter razões para criar uma revisão falhada de uma devolução
Para criar uma revisão falhada terás que conhecer a razão pela qual o vendedor identifica que o produto não chegou nas condições esperadas.
A lista das possíveis razões que o vendedor pode selecionar se obtêm no recurso returns/reasons/return-fail.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/returns/reasons/return-fail
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/returns/reasons/return-fail
Resposta:
[
{
"id": "SRF2",
"name": "product_damaged",
"detail": "El producto llegó dañado",
"position": 1
},
{
"id": "SRF3",
"name": "return_incomplete",
"detail": "La devolución está incompleta",
"position": 2
},
{
"id": "SRF4",
"name": "returned_product_different",
"detail": "Devolvieron un producto distinto al que envié",
"position": 3
},
{
"id": "SRF5",
"name": "product_not_in_package",
"detail": "El producto no está en el paquete",
"position": 4
},
{
"id": "SRF6",
"name": "another_failure_with_product",
"detail": "Reportar otra falla en el producto",
"position": 5
},
{
"id": "SRF7",
"name": "return_has_not_arrived",
"detail": "Aún no me llegó",
"position": 6
}
]
Campos da resposta
A resposta bem-sucedida de um GET ao recurso /returns/reasons/return-fail retornará um status code 200 e os seguintes campos:
- id: Identificador da reason. Este valor é o que deve ser enviado ao criar uma revisão falhada.
- name: Código da reason
- detail: Motivo da devolução falhada para dar contexto ao vendedor ao escolher a reason
- return_product
- position: Posição recomendada da reason ao mostrar todas as reasons ao vendedor
Obter nome das evidências a anexar na revisão falhada de uma devolução
Ao criar uma revisão falhada, também se habilita o envio de evidências, com o objetivo de fornecer mais informações ao caso. Portanto, você poderá utilizar o recurso de /claims/$CLAIM_ID/returns/attachments para o upload de arquivos.
Como resultado, será obtido o nome do arquivo que será enviado como evidência na revisão..
Este recurso deve ser utilizado para cada evidência que se queira anexar a uma revisão falhada.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/returns/attachments
-F 'file=@"/Users/usuer/Downloads/file.png'
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/5255026166/returns/attachments
-F 'file=@"/Users/usuer/Downloads/file.png'
Resposta:
{
"user_id": 1277895049,
"file_name": "1277895049_9d6b8d38-a2c2-4d17-a68b-f0845bc35fd1.png"
}
Campos da resposta
A resposta bem-sucedida de um GET ao recurso /claims/$CLAIM_ID/returns/attachments retornará um status code 200 e os seguintes campos:
- user_id: identificador do usuário
- file_name: nome do arquivo que poderá ser utilizado ao criar uma revisão falhada
Revisão falhada de devolução
Para criar a revisão falhada de uma devolução, indicando que o produto chegou com algum problema, foi habilitado o recurso /claims/$CLAIM_ID/actions/return-review-fail
Parâmetros
params | Type | Values | Detalhe value |
---|---|---|---|
claim_id | Integer | Identificador único da reclamação para a qual se deseja indicar a revisão falhada da devolução (obrigatório) | |
reson | String | Identificador único da razão pela qual o vendedor indica que o produto não chegou como esperado (obrigatório). Os possíveis valores deste campo são obtidos do recurso returns/reasons |
|
message | String | Mensagem inserida pelo vendedor indicando o motivo da revisão falhada (obrigatório) | |
attachments | Array[String] | Nomes das evidências a serem anexadas na revisão. Os valores deste campo são obtidos do recurso returns/attachments (obrigatório para as reason_id SRF2 e SRF4) |
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
{
"reason" : $REASON_ID,
"message": $MESSAGE,
"attachments": [$ATTACHMENTS]
}
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/actions/return-review-fail
Exemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
{
"reason" : "SRF2",
"message": "Me enviaron el sweater con una mancha",
"attachments": ["1277895049_4d421a16-31ba-444d-hbbf-68b373ed2g32.png"]
}
https://api.mercadolibre.com/post-purchase/v1/claims/5255026166/actions/return-review-fail
Resposta:
{
"id": 5255026166,
"resource_id": 2000007760636316,
"status": "closed",
"type": "mediations",
"stage": "claim",
"parent_id": null,
"resource": "order",
"reason_id": "PDD9949",
"fulfilled": true,
"quantity_type": "total",
"players": [
{
"role": "complainant",
"type": "buyer",
"user_id": 1277895049,
"available_actions": []
},
{
"role": "respondent",
"type": "seller",
"user_id": 1582937623,
"available_actions": [
{
"action": "return_review_fail",
"mandatory": false,
"due_date": null
},
{
"action": "return_review_ok",
"mandatory": true,
"due_date": "2024-06-03T22:43:00.000-04:00"
}
]
},
{
"role": "mediator",
"type": "internal",
"user_id": 46122402,
"available_actions": []
}
],
"resolution": {
"reason": "item_returned",
"date_created": "",
"benefited": [
"complainant"
],
"closed_by": "mediator",
"applied_coverage": true
},
"site_id": "MLA",
"date_created": "2024-05-29T23:48:32.000-04:00",
"last_updated": "2024-05-29T23:51:26.370-04:00"
}
Campos da resposta
A resposta bem-sucedida de um POST ao recurso /claims/$CLAIM_ID/actions/return-review-fail retornará um status code 201 e os seguintes campos:
- id: ID da reclamação
- resource: ID do recurso sobre o qual a reclamação é criada. Depende do “resource”
- status: Status da reclamação
- opened
- closed
- type: Tipo de reclamação
- mediations: reclamação entre comprador e vendedor.
- return: Devolução de produto.
- fulfillment: Reclamação entre comprador e Mercado Livre com origem de compra com envio full.
- ml_case: Cancelamento da compra por parte do comprador devido a envio demorado.
- cancel_sale: Cancelamento de compra por parte do vendedor. Sempre em status: "closed" e stage: "none". O rol complainant sempre vai ser do tipo seller, collector ou sender dependendo do recurso da reclamação.
- cancel_purchase: cancelamento de compra por parte do comprador
- change: Troca de Produto.
- service: Cancelamento de um serviço ordens bundle.
- stage: Etapa da reclamação
- claim: etapa de reclamação onde intervêm o comprador e o vendedor
- dispute: etapa de mediação onde intervém um representante do Mercado Livre
- recontact: etapa na qual uma das partes entra em contato após a reclamação/disputa ser encerrada
- none: não se aplica
- stale: Etapa de reclamação onde intervêm o comprador e o Mercado Livre para reclamações do tipo ml_case.
- parent_id: ID de outra reclamação da qual depende
- resource: Identificador do recurso sobre o qual a reclamação é criada. Interfere nos atores da reclamação
- payment: Pagamento
- order: Ordem
- shipment: Envio
- purchase: Compra
- reason_id: Razão/motivo pelo qual a reclamação foi criada. Interfere diretamente nas soluções que podem ser propostas
- PNR: Produto Não Recebido
- PDD: Produto Diferente ou Defeituoso
- CS: Compra Cancelada
- fulfilled: Indica se a reclamação foi iniciada por um produto entregue ou não
- quantity_type: informa se a reclamação é parcial ou não
- partial: indica que é uma reclamação parcial
- total: indica que é uma reclamação total
- players: Lista dos atores que participam da reclamação com suas respectivas ações e tempos disponíveis
- role: papel na reclamação
- complainant: pessoa que reclama.
- respondent: pessoa a quem é dirigida a reclamação.
- mediator: pessoa que intervém para ajudar a resolver o problema.
- warehouse_dispatcher: pessoa encarregada de revisar o produto nas devoluções ao warehouse.
- type: papel que a pessoa ocupa na operação que está sendo reclamada
- payment: comprador - collector.
- order: comprador - vendedor.
- shipment: receptor - remetente.
- purchase: comprador - Mercado Livre
- user_id: ID do usuário no ML que desempenha o papel
- available_actions: Lista de ações que cada uma das partes envolvidas pode executar
- players: lista dos atores que participam da reclamação com suas respectivas ações e tempos disponíveis.
- action: Nome da ação
- send_message_to_complainant: enviar mensagem para o comprador (com ou sem anexos).
- send_message_to_mediator: enviar mensagem para o mediador (com ou sem anexos).
- recontact (ainda não disponível): reabrir uma reclamação já encerrada, por meio de uma interação, como uma mensagem.
- refund: devolver o dinheiro do comprador. Deve ser realizado pelo front do Mercado Livre ou Mercado Pago.
- open_dispute: iniciar uma mediação.
- send_potential_shipping: enviar uma promessa de envio, uma data.
- add_shipping_evidence: publicar uma evidência de que o produto foi enviado.
- send_attachments: enviar mensagem com anexos.
- allow_return_label: gerar etiqueta de devolução.
- allow_partial_refund: oferecer reembolso parcial do dinheiro ao comprador. Deve ser realizado pelo front do Mercado Livre.
- send_tracking_number: enviar o número de rastreamento (tracking number).
- return_review_fail: realizar uma revisão com falha de uma devolução.
- return_review_ok: realizar uma revisão ok de uma devolução.
- mandatory: tipo de ação
- respondent: pessoa a quem é dirigida a reclamação.
- warehouse_dispatcher: pessoa encarregada de revisar o produto nas devoluções ao warehouse.
- action: Nome da ação
- players: lista dos atores que participam da reclamação com suas respectivas ações e tempos disponíveis.
- role: papel na reclamação
- resolution: Lista dos atores que participam da reclamação com suas respectivas ações e tempos disponíveis
- reason: Motivo de resolução/fechamento
- already_shipped: Produto a caminho
- buyer_claim_opened: Fechamento da devolução por abertura de outra reclamação
- buyer_dispute_opened: Fechamento da devolução por abertura de outra reclamação em disputa (com mediação do Mercado Livre)
- charged_back: Fechamento por chargeback
- coverage_decision: Disputa fechada com cobertura do ML
- found_missing_parts: Comprador encontrou as partes faltantes
- item_returned: Produto devolvido
- no_bg: Fechamento sem cobertura do ML
- not_delivered: Produto não entregue
- opened_claim_by_mistake: Comprador criou a reclamação por engano
- other: Outro caso
- partial_refunded: Reembolso parcial do pagamento ao comprador
- payment_refunded: Pagamento devolvido ao comprador
- preferred_to_keep_product: Comprador preferiu ficar com o produto
- product_delivered: Decisão de um representante do MercadoLibre
- reimbursed: Reembolso
- rep_resolution: Decisão de um representante do MercadoLibre
- respondent_timeout: Vendedor não responde
- return_cancelled: Devolução cancelada pelo comprador
- return_expired: Devolução vencida sem troca ou sem envio
- seller_asked_to_close_claim: Vendedor pediu ao comprador que fechasse a reclamação
- seller_did_not_help: Comprador conseguiu resolver o problema sem a ajuda do vendedor
- seller_explained_functions: Vendedor explicou como o item funcionava
- seller_sent_product: Vendedor enviou o produto
- timeout: Fechamento por tempo limite de ação ao comprador
- warehouse_decision: Fechamento por revisão de produto no Warehouse
- warehouse_timeout: Fechamento por demora na revisão de produto no Warehouse
- worked_out_with_seller: Comprador resolveu com o vendedor fora do ML
- low_cost: Fechamento porque o custo do envio é maior que o do produto
- item_changed: Fechamento porque a troca foi feita internamente
- change_expired: A troca não foi realizada e o tempo permitido foi cumprido
- change_cancelled_buyer: Fechamento de uma troca pelo comprador
- change_cancelled_seller: Fechamento proativo de uma troca pelo vendedor
- change_cancelled_meli: Fechamento de uma troca pela Meli
- shipment_not_stopped: Fechamento porque o envio não pôde ser interrompido
- cancel_installation: Cancelamento de serviço de instalação
- created: Data de resolução/fechamento da reclamação
- benefited: Beneficiários da resolução
- respondent
- closed_by: Ator que fechou a reclamação
- mediator
- buyer
- respondent
- false
- applied_coverage: Pagamento ao comprador
- site_id: ID do site onde a reclamação foi desenvolvida
- date_created: Data de criação/abertura da reclamação
- last_updated: Data da última atualização da reclamação
- reason: Motivo de resolução/fechamento
Erros
A seguir, detalham-se as possíveis mensagens de erro que o recurso pode gerar:
Se o claim não pertence ao vendedor:
{
"code": 400,
"error": "bad_request_error",
"message": "Invalid roleId :12343234 in claim :123454323",
"cause": null
}
Se o claim não existe:
{
"code": 404,
"error": "not_found_error",
"message": "claim id: 5255026166 not found",
"cause": null
}
Se o token não for enviado:
{
"code": 401,
"error": "unauthorized_request_error",
"message": "Invalid caller.id",
"cause": null
}
Se o token expirou ou é inválido:
{
"message": "invalid_token",
"error": "not_found",
"status": 401,
"cause": []
}
Se o token estiver incorreto:
{
"message": "{\"message\":\"Malformed access_token: toke n\",\"error\":\"bad_request\",\"status\":400,\"cause\":[]}",
"error": "",
"status": 400,
"cause": []
}
Se o vendedor não tiver habilitado a revisão de uma devolução:
{
"code": 400,
"error": "bad_request_error",
"message": "Not valid action return_review_ok for player role respondent",
"cause": null
}
Se o formato do arquivo que se deseja anexar não for válido:
{
"code": 400,
"error": "bad_request_error",
"message": "Invalid mime_type",
"cause": null
}
Se o nome do arquivo não for válido:
{
"code": 400,
"error": "bad_request_error",
"message": "Invalid file_name: ",
"cause": null
}
Se o campo "file" não for enviado:
{
"code": 400,
"error": "bad_request_error",
"message": "Current request is not a multipart request",
"cause": null
}
Se algum dos campos obrigatórios não for passado:
{
"code": 400,
"error": "bad_request_error",
"message": "Required request body is missing or incorrect, please see the documentation.",
"cause": null
}