Trocas - Changes & Allow Replace

O fluxo de trocas/cambios permite que os compradores realizem a troca de suas compras no Mercado Livre. Esta documentação apresenta a solução desenvolvida para integrar esse processo, detalhando os endpoints disponíveis, o modelo de dados e as validações necessárias para uma implementação eficiente.

Nos próximos tópicos, exploraremos a estrutura do serviço, os requisitos técnicos e as melhores práticas para garantir uma integração fluida, permitindo que os sellers gerenciem as trocas de forma automatizada e sem fricções.

Changes

O recurso /changes garante que os integradores possam acessar as informações de trocas relacionadas às suas vendas, incluindo acesso a dados gerais dos pedidos correspondentes e a verificação da existência de trocas nas reclamações associadas, garantindo uma gestão mais precisa e automatizada.

Como identificar uma troca?

Inscreva-se no feed de reclamações, assim você será notificado sobre todas as reclamações geradas para a conta do vendedor. Consulte o recurso /claims/$CLAIM_ID e verifique o campo "related_entities". Se o valor "changes" estiver presente, há uma troca associada. Utilize o recurso /changes para obter os detalhes.

Consultar uma troca:

Para consultar uma troca, utilize o recurso /post-purchase/v1/claims/$CLAIM_ID/changes, como no exemplo abaixo:

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/changes

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/post-purchase/v1/claims/5255498215/changes

Resposta:

{
   "paging": {
       "offset": 0,
       "limit": 1,
       "total": 1
   },
   "data": [
       {
           "claim_id": 1234567890,
           "resource": "order",
           "resource_id": 2000001234567890,
           "items": [
               {
                   "id": "MLM1965897079",
                   "quantity": 1,
                   "price": 900.61,
                   "price_at_creation": 900.61,
                   "variation_id": 179014252922,
                   "currency_id": "MXN"
               }
           ],
           "seller_id": 10000000,
           "buyer_id": 2000000,
           "return": {
               "id": 37350682
           },
           "new_orders_ids": [1000000],
           "new_orders_shipments": [
               {
                   "id": 43176542122
               }
           ],
           "site_id": "ABC",
           "status": "changed",
           "status_detail": null,
           "type": "change",
           "estimated_exchange_date": {
               "from": "2024-03-11T00:00:00.000-04:00",
               "to": "2024-03-19T00:00:00.000-04:00"
           },
           "date_created": "2024-03-08T12:52:45.161-04:00",
           "last_updated": "2024-03-08T13:15:37.095-04:00"
       }
   ]
}

Campos da Resposta

Campos de Resposta: Estados

Breve descrição dos estados relacionados ao processo bem-sucedido de trocas.

Status Pending e Descrições Detalhadas

• pending: Primeiro passo, onde uma nova entidade de troca é criada com todas as informações.
• pending / return_pending: O status indica que a entidade de devolução foi criada, mas o envio ainda está em processo de criação.
• pending / return_created: A devolução foi notificada com o status "label-generated".
• pending / payment_required: O novo pedido foi criado e aguarda pagamento.
• pending / money_granted: O empréstimo para a troca foi aplicado.
• pending / purchase_payment_done: O pagamento da compra foi executado.

Status de Processamento e Entrega

• generated: A troca foi criada com sucesso e o envio avança para "ready-to-ship".
• purchase_shipped: O envio foi notificado como "shipped".
• [NOVO] purchase_delayed/by_expiration: O status expira após P+4 (P = data da promessa original) e pode transicionar para "ready" ou "change_failed / purchase_returning".
• [NOVO] purchase_delayed/by_notification: Um atraso foi notificado no envio. Se não houver novas atualizações, expira em P+2 e transiciona para "change_failed" com substatus apropriado.
• ready: O envio foi notificado como "shipped / waiting-for-withdraw", pronto para a troca.
• changed: O comprador realizou o processo de troca e o envio foi entregue.
• return_shipped: O envio da devolução foi despachado.
• change_return_delivered: A devolução foi entregue ao centro de distribuição.
• change_return_delivered / return_triage_success: O processo de triagem foi concluído com sucesso.

Definição de Estados - Falha

Breve descrição dos estados de falhas (change_failed) técnicas ou funcionais.

• failed: O pagamento da nova compra falhou.
• purchase_pay_failed: Erro ao processar o pagamento.
• change_failed: Problemas ao criar entidades ou dificuldades logísticas durante o transporte.
• coverage_not_aplied: O pedido não atende aos critérios da política de trocas/devoluções.
• mediator_closed: Troca encerrada pelo mediador.
• purchase_failed: Erro na criação da nova compra.
• purchase_return_lost: O envio foi perdido.
• shipment_return_stole: O envio foi roubado.
• shipment_returned: O envio foi devolvido ao centro de distribuição.
• purchase_returning: O envio está em "not_delivered - returning_to_warehouse".
• return_failed: A devolução falhou.
• return_no_label_generated: A etiqueta de devolução não foi gerada.
• shipment_fw_cancel_seller: Cancelado pelo vendedor.
• shipment_fw_cancelled: Cancelado pelo centro de distribuição ou durante o transporte.
• shipment_fw_fraudulent: Cancelado por fraude.
• shipment_fw_lost: Envio não entregue - perdido.
• shipment_fw_stolen: Envio não entregue - roubado.
• shipment_fw_unfulfillable: Pedido impossível de ser atendido.

Replace

O Replace é um subfluxo dentro do processo de changes, permitindo a troca do mesmo produto e da mesma variação (exemplo: cor ou tamanho) em casos de produtos danificados. Diferente do fluxo de troca convencional, onde o comprador pode optar por outra variação, o replace somente permite a troca pelo mesmo item.

Diferença entre Change e Replace

• Replace: Refere-se à troca do mesmo produto e da mesma variação.
• Change convencional: Permite a substituição por uma variação diferente (exemplo: tamanho ou cor). Replace não permite essa troca.
• Replace: É oferecido pelo vendedor, enquanto Change convencional pode ser iniciado diretamente pelo comprador, sem ação do vendedor.

Como verificar se o Replace está disponível?

Para saber se um pedido está elegível para replace, o vendedor deve consultar o endpoint Get Claim e verificar se a ação allow_replace está disponível.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID

Se a ação allow_replace estiver habilitada no retorno da API, o vendedor poderá seguir com a solicitação de replace.

Como executar a ação de allow_replace?

Caso a ação esteja disponível, o vendedor pode realizar um POST no endpoint de reemplazo para iniciar o processo.

Chamada:

curl  --location --request POST 'https://api.mercadolibre.com/post-purchase/v1/claims/:CLAIM_ID/expected-resolutions/allow-replace' \
--header 'Authorization: Bearer {{token}}'

Exemplo de resposta bem-sucedida:

[
   {
       "player_role": "complainant",
       "user_id": 1802660952,
       "expected_resolution": "return_product",
       "details": [],
       "date_created": "2024-10-16T11:27:03.000-04:00",
       "last_updated": "2024-10-16T11:27:03.000-04:00",
       "status": "pending"
   }
]

Se o comprador aceitar a troca, o fluxo seguirá o processo de changes, gerando um ID de allow_replace, que será utilizado para a execução da ação.

Casos de Uso - Funcionalidade de Replace

Esta seção apresenta exemplos práticos de uso da funcionalidade de Replace, detalhando fluxos de integração para diferentes cenários:

Caso de Uso 1: Replace Disponível

Descrição: Um integrador deseja integrar a funcionalidade de replace em sua API para automatizar o processo de troca de produtos danificados.

Pré-condições: O pedido está elegível para replace.

Fluxo Principal

• O Vendedor realiza uma solicitação GET ao endpoint de Claim para verificar se a ação allow_replace está disponível.
• Se disponível, o vendedor envia uma solicitação POST ao endpoint de replace para oferecer a troca ao comprador.
• O sistema confirma que o replace foi oferecido. (Status: 200)
• O comprador pode aceitar ou recusar a troca.
• Se o comprador aceitar, o sistema atualiza a resolução esperada do integrador, conforme a resposta:

[
   {
       "player_role": "complainant",
       "user_id": 1802660952,
       "expected_resolution": "return_product",
       "details": [],
       "date_created": "2024-10-16T11:27:03.000-04:00",
       "last_updated": "2024-10-16T11:27:03.000-04:00",
       "status": "rejected"
   },
   {
       "player_role": "complainant",
       "user_id": 1802660952,
       "expected_resolution": "change_product",
      {
   "id": 5308212444,
   "resource_id": 2000009575852844,
   "status": "opened",
   "type": "mediations",
   "stage": "claim",
   "parent_id": null,
   "resource": "order",
   "reason_id": "PDD9965",
   "fulfilled": true,
   "quantity_type": "total",
"details": [],
       "date_created": "2024-10-16T11:32:56.000-04:00",
       "last_updated": "2024-10-16T11:32:56.000-04:00",
       "status": "accepted"
   }
]

{
   "id": 5308275481,
   "resource_id": 2000009577898632,
   "status": "opened",
   "type": "mediations",
   "site_id": "MLM",
   "date_created": "2024-10-16T14:44:11.000-04:00",
   "last_updated": "2024-10-16T14:48:08.000-04:00",
   "related_entities": [
       "return",
       "change"
   ]
}

"id": 5308212444,
   "resource_id": 2000009575852844,
   "status": "opened",
   "type": "mediations",
   "stage": "claim",
   "parent_id": null,
   "resource": "order",
   "reason_id": "PDD9965",
   "fulfilled": true,
   "quantity_type": "total",
{
   "id": 5304741170,
   "resource_id": 2000009456954248,
   "status": "closed",
   "type": "mediations",
   "related_entities": [
       "return",
       "change"
   ]
}

Caso de Uso 2: Ação de Reemplazo Não Disponível

Descrição: Integrador verifica as ações disponíveis e constata que a ação allow_replace não está habilitada.

Fluxo Principal

• O Vendedor realiza uma solicitação GET ao endpoint de Claim.
• O retorno não contém a ação allow_replace, indicando que o reemplazo não está disponível.
• O vendedor tenta realizar um POST para oferecer o reemplazo, mas recebe um erro.
• O sistema responde com um erro 400 indicando que a ação não é permitida.



Pós-condições: O vendedor está ciente de que não pode oferecer o replace para esse pedido e deve buscar alternativas, como reembolso ou outras formas de mediação.