Plataforma de Negociação para Pedidos

Introdução

Nesta seção, apresentaremos descrição detalhada das Entidades, Eventos, Payloads e da REST API utilizada no desenvolvimento desta integração. É importante que você tenha uma compreensão completa dos componentes fundamentais que compõem essa integração, possibilitando uma implementação bem-sucedida.

A Plataforma de Negociação para Pedidos é uma ferramenta destinada a facilitar, gerenciar e agilizar negociações entre duas partes, com o propósito de resolver questões relacionadas a PEDIDOS. Ela atua como intermediária e possibilita uma comunicação eficaz entre as partes envolvidas, permitindo a troca de propostas e facilitando a busca por acordos de forma eficaz.

Cenários

Cancelamento de Pedidos

Durante o processo de cancelamento de um pedido, em vez de apenas cancelar o pedido, a plataforma inicia uma negociação entre o Cliente e o Parceiro.

Nessa negociação, o Cliente expressa a sua intenção de cancelar o pedido e a Plataforma de Negociação envia um evento para o Parceiro.

Em seguida, o Parceiro tem a oportunidade de avaliar a situação e se o cancelamento é justificado. Para isso, a Plataforma de Negociação disponibiliza endpoints específicos, nos quais o Parceiro pode aceitar o cancelamento, recusar o cancelamento ou oferecer uma contraproposta, tomando uma decisão com base na negociação realizada.

Atores:

• Parceiro
• Cliente

Reenvio de Itens - Experimental para alguns clientes - Em breve

Após receber o pedido, caso o cliente perceba que um ou mais itens não foram enviados, ele dá início a um processo de solicitação de reenvio por meio da Plataforma de Negociação para pedidos, o que dá início a uma interação entre o Cliente e o Parceiro. Nessa interação, o Cliente comunica sua intenção de receber os itens faltantes, e a Plataforma de Negociação envia um evento ao Parceiro. O Parceiro, por sua vez, tem a oportunidade de avaliar a situação e decidir se reenviar os itens é a melhor solução. Para esse fim, a Plataforma de Negociação oferece endpoints de acesso específicos, nos quais o Parceiro pode aceitar o reenvio dos itens, rejeitar o reenvio dos itens ou oferecer uma contraproposta. Essa decisão é tomada com base na negociação conduzida.

Atores:

• Parceiro
• Cliente

Guia rápido para integração

Nesta seção descrevemos os passos essenciais que devem ser seguidos para que a integração seja bem sucedida. Todos os componentes mencionados neste guia são detalhados no decorrer da documentação.

Certifique-se de implementar a lógica adequada para lidar com esses eventos e suas respectivas ações, garantindo que a integração ocorra de forma correta e eficiente.

Entidades e Atributos

A seguir, apresentamos detalhes sobre as entidades e constantes que são utilizadas nos payloads dos eventos e na REST API.

Entidades

• HandshakeDispute
• HandshakeSettlement
• DisputeAlternative
• SelectedDisputeAlternative
• Media
• Item
• GarnishItem
• Amount

Constantes

• handshakeType
• handshakeGroup
• action
• timeoutAction
• status
• type
• negotiationReasons

Iniciamos com a descrição das entidades principais:

• HandshakeDispute
• HandshakeSettlement

Em seguida, detalhamos as entidades que compõem as entidades principais:

• DisputeAlternative
• SelectedDisputeAlternative
• Media
• Item
• GarnishItem
• Amount

E finalmente, são detalhadas as constantes que serão empregadas durante o fluxo:

HandshakeDispute

• handshakeType
• handshakeGroup
• timeoutAction
• action

HandshakeSettlement

• status

DisputeAlternative

• type

Cada atributo é acompanhado de uma breve explicação sobre seu propósito, o tipo de dado suportado e se o atributo é obrigatório ou opcional.

Para as constantes, são listados os possíveis valores disponíveis e uma breve explicação sobre seu propósito.

É fundamental ressaltar que a inclusão de campos não obrigatórios se justifica pelo fato de serem utilizados somente em fluxos específicos, os quais serão devidamente explorados ao longo deste documento.

Entidades

HandshakeDispute

A entidade HandshakeDispute é utilizada no evento HANDSHAKE_DISPUTE que contém informações essenciais sobre a negociação em execução, por exemplo, o tipo do handshake (handshakeType), agrupamento do handshake (handshakeGroup), o propósito da Dispute (action), as evidências (evidences) e comentários (message) enviados pelo consumidor, o tempo máximo para responder ao evento (expiresAt) e a ação a ser tomada em caso de expiração do tempo de resposta (timeoutAction).

Quando a negociação em execução contemplar a funcionalidade de Proposta de Reembolso, também são fornecidos atributos adicionais, como o DisputeAlternative.

Nas negociações relacionadas a Solicitação de Cancelamento Parcial, são enviados os atributos Items (Item) e/ou GarnishItems (GarnishItem) que detalham os produtos que fazem parte da solicitação.

Campos Obrigatórios

Os campos que não são obrigatórios são utilizados apenas em fluxos específicos. No decorrer da documentação é possível visualizar através de exemplos quando e como esses atributos são recebidos.

HandshakeSettlement

A entidade HandshakeSettlement é utilizada no evento HANDSHAKE_SETTLEMENT contém informações relevantes sobre a Dispute que foi respondida, com o ID da Dispute (id), o status de solução da Dispute (status) e a razão da rejeição da Dispute, caso aplicável (reason).

Quando o fluxo inclui a funcionalidade de Proposta de Reembolso, também são fornecidos atributos adicionais, como o SelectedDisputeAlternative.

Campos Obrigatórios

Os campos que não são obrigatórios são utilizados apenas em fluxos específicos. No decorrer da documentação é possível visualizar através de exemplos quando e como esses atributos são recebidos.

DisputeAlternative

A entidade DisputeAlternative é utilizada em conjunto com a Entidade HandshakeDispute, sendo enviada quando a Dispute, por exemplo, está relacionada a uma negociação que possui a funcionalidade de Proposta de Reembolso.

SelectedDisputeAlternative

A entidade SelectedDisputeAlternative é utilizada em conjunto com a entidade HandshakeSettlement send enviada quando a Dispute foi respondida com ALTERNATIVE_REPLIED. Representa o tipo e contém os metadados relevantes da contraproposta enviada.

Media

A entidade Media é utilizada em conjunto com a entidade HandshakeDispute e contém as mídias enviadas pelo consumidor.

Item

A entidade Item é utilizada em conjunto com a entidade HandshakeDispute e contém informações dos Itens que estão sendo cancelados, por exemplo, durante a execução do fluxo de Solicitação de Cancelamento Parcial.

GarnishItem

A entidade GarnishItem entidade é utilizada em conjunto com a entidade HandshakeDispute e contém informações dos GarnishItems que estão sendo cancelados, por exemplo, durante a execução do fluxo de Solicitação de Cancelamento Parcial.

Amount

A entidade Amount é utilizada em conjunto com as entidades DisputeAlternative e SelectedDisputeAlternative, e contém o valor e a unidade monetária

Constantes

A seguir, apresentamos os valores possíveis para os atributos da entidade HandshakeDispute: handshakeType, handshakeGroup, action e timeoutAction. Além disso, também detalhamos os atributos status presente na entidade HandshakeSettlement e type presente nas entidades DisputeAlternative e DisputeSelectedAlternative.

handshakeType

Identifica qual é o tipo de do handshake. Presente na entidade HandshakeDispute.

handshakeGroup

Classifica o handshake em um grupo. Presente na entidade HandshakeDispute.

action

Identifica o tipo de ação que está sendo negociado na Dispute. Presente na entidade HandshakeDispute.

timeoutAction

Identifica a ação automática que será executada em caso de expiração do tempo de resposta do handshake. O tempo de expiração é definido no atributo expiresAt e ambos estão na entidade HandshakeDispute.

status

Identifica o status da negociação. Presente na entidade HandshakeSettlement.

type

Identifica o tipo do artefato que poderá ser ofertado em uma contraproposta. Presente nas entidades DisputeAlternative e SelectedDisputeAlternative.

negotiationReasons

Lista com motivos padronizados que a loja pode escolher com o intuito de informar o porquê aceitou, recusou ou enviou uma contraproposta ao cancelamento solicitado pelo cliente.

Eventos - Payload

Nesta seção, fornecemos informações detalhadas sobre os eventos HANDSHAKE_DISPUTE e HANDSHAKE_SETTLEMENT, que fazem parte do processo de negociação.

Os payloads apresentados nesta seção contém todos os atributos possíveis, garantindo uma visão completa da sua estrutura, incluindo aqueles que não são obrigatórios sendo aplicáveis apenas em fluxos específicos.

Ao longo da documentação, cada fluxo será detalhado com o payload exato que será propagado. Essa abordagem possibilitará uma compreensão clara do funcionamento de cada evento durante o processo de negociação.

Para obter mais informações sobre os atributos, consulte a seção Entidades e Atributos.

HANDSHAKE_DISPUTE

O evento HANDSHAKE_DISPUTE indica que uma proposta foi realizada e que obrigatoriamente deve ser respondida.

Para responder ao evento HANDSHAKE_DISPUTE, é fundamental utilizar os endpoints accept, reject ou alternative para indicar a decisão sobre a proposta em negociação. Essas opções permitem expressar se a proposta será aceita, rejeitada ou se será apresentada uma contraproposta.

Caso um evento HANDSHAKE_DISPUTE não seja respondido por interação humana num prazo previamente determinado, ele será automaticamente respondido pela Plataforma de Negociação. Para obter maiores detalhes sobre a resposta automática em caso de timeout, consulte a seção Timeout.

Os endpoints mencionados anteriormente serão detalhados ao longo da documentação.

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "message":"Pedido veio errado", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "alternatives":[
      {
        "id":"2d35d0b9-67ae-46d2-8261-f0a40e5d07fd", 
        "type":"REFUND", 
        "metadata":{
          "maxAmount":{
            "value":"6000", 
            "currency":"BRL"
          }
        }
      },
      {
        "id": "c1f76701-994c-4537-8d54-fb2bc2ee511d",
        "type": "ADDTIONAL_TIME",
        "metadata": {
          "allowedsAdditionalTimeInMinutes": [10, 15, 20, 30],
          "allowedsAdditionalTimeReasons": [
            "HIGH_STORE_DEMAND",
            "OPERATIONAL_ISSUES",
            "LACK_OF_DRIVERS",
            "ORDER_OUT_FOR_DELIVERY",
            "DRIVER_IS_ALREADY_AT_THE_ADDRESS"
          ]
        }
      }
    ], 
    "metadata":{
      "acceptCancellationReasons": [
        "HIGH_STORE_DEMAND",
        "STORE_SYSTEM_ISSUES",
        "STORE_INTERNAL_DIFFICULTIES",
        "LACK_OF_DRIVERS",
        "OTHER_REASONS",
        "OPERATIONAL_ISSUES",
        "ORDER_OUT_FOR_DELIVERY"
      ],
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ], 
      "items":[
        {
          "id":"296b1757-4edf-4a4a-9f03-dfc10d4e907a", 
          "uniqueId":"fe3620ad-c475-4f01-93b9-1ed95907a9ab", 
          "externalCode":"73", 
          "index":1, 
          "quantity":1, 
          "amount":{
            "value":"3890", 
            "currency":"BRL"
          }, 
          "reason":"Não veio a batata, apenas as esfihas"
        }
      ], 
      "garnishItems":[
        {
          "id":"ffa2e2f0-361e-4076-8781-e7c8073326e1", 
          "parentUniqueId":"efe73d06-ccfd-4605-a2a5-1b5b64284b47", 
          "externalCode":"MAI-9601273-601273", 
          "quantity":1, 
          "index":2, 
          "amount":{
            "value":"2650", 
            "currency":"BRL"
          }, 
          "reason":"Revirado e faltando o queijo"
        }
      ]
    }, 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

HANDSHAKE_SETTLEMENT

O evento HANDSHAKE_SETTLEMENT sinaliza e formaliza que uma proposta foi respondida anteriormente através dos endpoints accept, reject ou alternative

Este evento contém informações sobre o status da Dispute.

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "receivedAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"REJECTED", 
    "reason":"Razão por não aceitar a proposta", 
    "selectedDisputeAlternative":{
      "id":"2d35d0b9-67ae-46d2-8261-f0a40e5d07fd", 
      "type":"REFUND", 
      "metadata":{
        "amount":{
          "value":"1500", 
          "currency":"BRL"
        }
      }
    }, 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }
}

REST API

Nesta seção, fornecemos informações detalhadas sobre a implementação da API REST da Plataforma de Negociação. Esta API segue os princípios da arquitetura REST, que permite a comunicação entre sistemas por meio de solicitações HTTP, seguindo uma abordagem baseada em recursos e utilizando os verbos HTTP (GET, POST) para realizar as operações.

Os desenvolvedores podem acessar os endpoints através de URLs específicas, enviar solicitações e receber respostas no formato JSON.

É importante seguir a documentação da API para montar as solicitações corretas e interpretar as respostas.

Aceitar proposta

Este endpoint permite ACEITAR uma Dispute recebida. Essa Dispute é representada pelo evento HANDSHAKE_DISPUTE.

Ao enviar uma solicitação para este endpoint, o sistema processará a resposta e realizará as ações correspondentes relacionadas ao processo de handshake. É necessário fornecer o ID correto da Dispute para associar a resposta a negociação desejada.

URL

POST order/v1.0/disputes/{disputeId}/accept

Body

Somente é necessário enviar este payload no body da requisição quando no evento HANDSHAKE_DISPUTE for recebido o metadado metadata.acceptCancellationReasons.

{
  "reason":"HIGH_STORE_DEMAND", 
  "detailReason":"Apenas se quiser detalhar o motivo de aceitar o cancelamento"
}

Descrição dos parâmetros

Descrição dos atributos do corpo da mensagem

Código de Status

Quando é feita uma solicitação à API da Plataforma de Negociação, a resposta recebida incluirá códigos de status que indicam o que está acontecendo do lado do servidor. Nesta seção é possível visualizar os códigos de status que encontrará nas respostas, juntamente com o significado de cada um deles.

Response Success

1 - A requisição foi processada com sucesso

Body

{
  "id":"adee6f8d-7112-4d12-b2e8-5ddf01c11a37", 
  "status":"ACCEPTED", 
  "disputeId":"63ddd317-90fd-43ad-830c-532f9848b7f8", 
  "createdAt":"2023-06-23T13:29:49.218951237Z"
}

Response Failure

1 - Não autorizado

2 - Dispute não foi encontrada

Body

{
  "code":"DISPUTE_NOT_FOUND", 
  "message":"Dispute with ID {} was not found"
}

3 - Dispute já foi processada

Body

{
  "code":"DISPUTE_ALREADY_ANSWERED", 
  "message":"Dispute with ID {} has already been answered"
}

4 - Handshake já foi concluído

Body

{
  "code":"HANDSHAKE_ALREADY_CONCLUDED", 
  "message":"Handshake with ID {} and _Dispute_ ID {} has already been concluded"
}

5 - Motivo de cancelamento inexistente ou inválido

Body

{
  "code":"INVALID_CANCELLATION_REASON", 
  "message":"_Dispute_ ID {} requires a valid reason to cancel the order"
}

Rejeitar proposta

Este endpoint permite REJEITAR uma Dispute recebida. Essa Dispute é representada pelo evento HANDSHAKE_DISPUTE.

Ao enviar uma solicitação para este endpoint com o motivo da rejeição, o sistema processará a resposta e realizará as ações correspondentes relacionadas ao processo de handshake.

URL

POST order/v1.0/disputes/{disputeId}/reject

Body

{
  "reason":"Justificativa da Proposta ser rejeitada"
}

É fundamental observar que o campo reason deve ser obrigatoriamente incluído ao fazer essa requisição. Caso esse campo seja omitido, a requisição resultará em uma exceção adequada, contendo uma mensagem de erro explicativa juntamente com o código correspondente.

Descrição dos parâmetros

Descrição dos atributos do corpo da mensagem

Códigos de Status

Quando é feita uma solicitação à API da Plataforma de Negociação, a resposta recebida incluirá códigos de status que indicam o que está acontecendo do lado do servidor. Nesta seção é possível visualizar os códigos de status que encontrará nas respostas da API da Plataforma de Negociação, juntamente com o significado de cada um deles.

Response Success

1 - A requisição foi processada com sucesso

Body

{
  "id":"adee6f8d-7112-4d12-b2e8-5ddf01c11a37", 
  "status":"REJECTED", 
  "reason":"Justificativa para rejeitar a proposta", 
  "disputeId":"63ddd317-90fd-43ad-830c-532f9848b7f8", 
  "createdAt":"2023-06-23T13:29:49.218951237Z"
}

Descrição dos atributos

Response Failure

1 - Não autorizado

2 - Campos obrigatórios não foram enviados

Body

{
  "code":"DISPUTE_REQUIRED_FIELDS_WERE_NOT_SENT", 
  "message":"The request is missing the required field, \"reason\" that needs to be included"
}

3 - Campo reason possui mais caracteres que o permitido

Body

{
  "code":"DISPUTE_FIELD_EXCEEDS_MAXIMUM_LENGTH", 
  "message":"The \"reason\" field exceeds the maximum allowed length. Please ensure that the field does not exceed 250 characters"
}

4 - Dispute não foi encontrada

Body

{
  "code":"DISPUTE_NOT_FOUND", 
  "message":"Dispute with ID {} was not found"
}

5 - Dispute já foi processada

Body

{
  "code":"DISPUTE_ALREADY_ANSWERED", 
  "message":"Dispute with ID {} has already been answered"
}

6 - Handshake já foi concluído

Body

{
  "code":"HANDSHAKE_ALREADY_CONCLUDED", 
  "message":"Handshake with ID {} and _Dispute_ ID {} has already been concluded"
}

Realizar Contraproposta

Este endpoint permite REALIZAR UMA CONTRAPROPOSTA para uma Dispute recebida. Essa Dispute é representada pelo evento HANDSHAKE_DISPUTE.

Ao enviar uma solicitação para este endpoint, o sistema processará a resposta e realizará as ações correspondentes relacionadas ao processo.

URL

POST order/v1.0/disputes/{disputeId}/alternatives/{alternativeId}

Body - REFUND

{
  "type":"REFUND", 
  "metadata":{
    "amount":{
      "value":"1500", 
      "currency":"BRL"
    }
  }
}

Body - BENEFIT

{
  "type":"BENEFIT", 
  "metadata":{
    "amount":{
      "value":"1500", 
      "currency":"BRL"
    }
  }
}

Body - ADDITIONAL_TIME

{
  "type":"ADDITIONAL_TIME", 
  "metadata":{
    "additionalTimeInMinutes": 15,
    "additionalTimeReason": "ORDER_OUT_FOR_DELIVERY"
  }
}

Descrição dos parâmetros

Descrição dos atributos

Códigos de Status

Quando é feita uma solicitação à API da Plataforma de Negociação, a resposta recebida incluirá códigos de status que indicam o que está acontecendo do lado do servidor. Nesta seção é possível visualizar os códigos de status que encontrará nas respostas da API da Plataforma de Negociação, juntamente com o significado de cada um deles.

Response Success

1 - A requisição foi processada com sucesso

Body

{
  "id":"adee6f8d-7112-4d12-b2e8-5ddf01c11a37", 
  "status":"ALTERNATIVE_REPLIED", 
  "disputeId":"63ddd317-90fd-43ad-830c-532f9848b7f8", 
  "createdAt":"2023-06-23T13:29:49.218951237Z"
}

Response Failure

1 - Não autorizado

2 - Dispute não foi encontrada

Body

{
  "code":"DISPUTE_NOT_FOUND", 
  "message":"Dispute with ID {} was not found"
}

3 - Dispute já foi processada

Body

{
  "code":"DISPUTE_ALREADY_ANSWERED", 
  "message":"Dispute with ID {} has already been answered"
}

4 - Alternativa não foi encontrada

Body

{
  "code":"DISPUTE_NOT_FOUND", 
  "message":"Dispute with ID {} was not found"
}

5 - Id da alternativa está incorreto

Body

{
  "code":"DISPUTE_ALTERNATIVE_INVALID", 
  "message":"Alternative with ID {} from _Dispute_ with ID {} was invalid"
}

6 - Tipo da alternativa é inválida

Body

{
  "code":"DISPUTE_ALTERNATIVE_TYPE_INVALID", 
  "message":"Alternative Type {} with ID {} from _Dispute_ with ID {} was invalid. Must be one of the following available types {}"
}

7 - Handshake já foi concluído

Body

{
  "code":"HANDSHAKE_ALREADY_CONCLUDED", 
  "message":"Handshake with ID {} and _Dispute_ ID {} has already been concluded"
}

8 - Motivo da negociação de atraso é inválido

Body

{
  "code":"HANDSHAKE_NEGOTIATION_TIME_INVALID_REASON", 
  "message":"Alternative ID {} was replied with invalid negotiation time reason"
}

9 - Tempo adicional da negociação de atraso é inválido

Body

{
  "code":"HANDSHAKE_NEGOTIATION_TIME_INVALID_TIME_IN_MINUTES", 
  "message":"Alternative ID {} was replied with invalid additional time in minutes"
}

Timeout

Quando ocorre a publicação de um evento HANDSHAKE_DISPUTE e ele não é respondido dentro do prazo estabelecido, uma ação automática é acionada, resultando na geração de um evento HANDSHAKE_SETTLEMENT com o status de EXPIRED, informando a decisão que foi tomada e a negociação encerrada.

O tempo máximo para responder a uma Dispute é definido pelo atributo expiresAt.

A ação automática a ser executada é descrita pelo atributo timeoutAction e poderá ter os seguintes valores:

Casos de Uso - Exemplos

Negociações Disponíveis

A seguir, serão explicadas as opções de negociação disponíveis ao longo do ciclo de vida do pedido. As negociações mencionadas logo abaixo se referem exclusivamente às Solicitações de Cancelamento feitas pelos consumidores.

Proposta de Solicitação de Cancelamento

O cliente tem a opção de solicitar o cancelamento de um pedido. Essa ação é permitida apenas em momentos específicos do ciclo de vida do pedido, como antes da confirmação, durante a preparação, quando o pedido está atrasado e após a conclusão.

Por meio da política de cancelamento definida pelo IFood, é verificado se é permitido iniciar uma negociação através da Plataforma de Negociação para uma determinada Solicitação de Cancelamento antes de efetivar o cancelamento.

Como funciona?

Cancelamento Total

Para os cenários de Solicitação de Cancelamento (Após Conclusão, Durante o Preparo e Atraso na Entrega), antes do cancelamento ser efetivado será iniciado uma negociação na Plataforma de Negociação, oportunizando o Parceiro de Aceitar ou Rejeitar a requisição do cliente.

Nesse cenário de negociação, quando um cliente expressa a intenção de cancelar um pedido, o parceiro, por meio do mecanismo de polling, receberá um evento de HANDSHAKE_DISPUTE que representa uma Dispute.

Para responder a Dispute representada pelo evento HANDSHAKE_DISPUTE, o parceiro deve utilizar os seguintes endpoints:

• /accept - Para ACEITAR a solicitação de cancelamento
• /reject - Para REJEITAR a solicitação de cancelamento

Após a requisição bem-sucedida, a Plataforma de Negociação processará a solicitação de forma assíncrona. E, na próxima verificação de polling, o parceiro receberá os seguintes eventos:

• HANDSHAKE_SETTLEMENT
• CANCELLED ou CANCELLATION_REQUEST_FAILED

Diagrama de Sequência

Sequência de execução de uma Negociação referente a uma Solicitação de Cancelamento executada pela Plataforma de Negociação para os cenários de Durante o Preparo, Atraso na Entrega e Após Conclusão.

Após Conclusão

Na solicitação de cancelamento Após Conclusão antes do cancelamento ser efetivado será iniciado uma Negociação entre Cliente e Parceiro, oportunizando o Parceiro de Aceitar ou Rejeitar a requisição do cliente.

Neste tipo de cancelamento o parceiro irá receber a justificativa do cliente e as imagens evidenciando o problema.

Exemplo dos eventos que serão recebidos:

HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "metadata":{
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ]
    }, 
    "alternatives":null, 
    "message":"pedido feito: canudos Pedido recebido: bolo de laranja", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

HANDSHAKE_SETTLEMENT

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"REJECTED", 
    "reason":"Razão por não aceitar a Dispute", 
    "selectedDisputeAlternative":null, 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Durante o Preparo

Na solicitação de cancelamento Durante o Preparo antes do cancelamento ser efetivado será criado uma negociação na proposta de handshake, oportunizando o Parceiro de Aceitar ou Rejeitar a requisição do cliente.

Neste tipo de cancelamento o parceiro irá receber apenas a justificativa do cliente.

Exemplo dos eventos que serão recebidos:

HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "handshakeType":"PREPARATION_TIME", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "metadata":null, 
    "disputeAlternatives":null, 
    "message":"Horário de entrega muito tarde", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

HANDSHAKE_SETTLEMENT

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "id":"3216ded9-bdee-4440-8c73-b5488e8b1f83", 
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"REJECTED", 
    "reason":"Razão por não aceitar a proposta", 
    "selectedDisputeAlternative":null, 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Atraso na Entrega

Na solicitação de cancelamento por Atraso na Entrega antes do cancelamento ser efetivado será criado uma negociação na proposta de handshake, oportunizando o Parceiro de Aceitar ou Rejeitar a requisição do cliente.

Neste tipo de cancelamento o parceiro irá receber apenas justificativa do cliente.

Exemplos dos eventos que serão recebidos:

HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "handshakeType":"DELAY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"ACCEPT_CANCELLATION", 
    "metadata":null, 
    "disputeAlternatives":null, 
    "message":"Handshake por atraso", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

HANDSHAKE_SETTLEMENT

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"REJECTED", 
    "reason":"Razão por não aceitar a proposta", 
    "selectedDisputeAlternative":null, 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Total com Proposta de Reembolso

Nos cenários de Solicitação de Cancelamento com Proposta de Reembolso, antes que o cancelamento seja efetivado, será iniciada uma negociação na Plataforma de Negociação, permitindo ao Parceiro ACEITAR, REJEITAR e PROPOR REEMBOLSO, com o objetivo de evitar o cancelamento total e, consequentemente, prejuízos financeiros.

Nesse contexto de negociação, quando um Cliente expressa a intenção de cancelar um pedido, o Parceiro por meio do mecanismo de polling, receberá um evento de HANDSHAKE_DISPUTE que representa uma Dispute.

O parceiro irá identificar que a Dispute possui a opção de Proposta de Reembolso, verificando o atributo alternatives. Se ela estiver preenchido, será possível realizar a proposta de reembolso.

Para responder a essa Dispute, o Parceiro poderá utilizar os seguintes endpoints:

• /accept: Para ACEITAR a solicitação de cancelamento.
• /reject: Para REJEITAR a solicitação de cancelamento.
• /alternative: Para enviar um valor monetário como contraproposta de reembolso ao Cliente, visando a resolução da situação e evitar o cancelamento do pedido.

Endpoints ACCEPT ou REJECT

Se o parceiro executar a opção "accept" ou "reject", nenhuma proposta será enviada ao Cliente, e a negociação será encerrada.

Endpoint ALTERNATIVE

Caso o parceiro faça uma requisição no endpoint alternative, o Cliente será notificado e poderá aceitar ou rejeitar a contraproposta. Após o processamento deste endpoint o parceiro receberá um evento HANDSHAKE_SETTLEMENT, formalizando o valor monetário enviado, o qual não requer nenhuma ação adicional e deverá aguardar a resposta do cliente.

Após o cliente responder a proposta de reembolso, independentemente da resposta, o parceiro receberá um novo evento HANDSHAKE_SETTLEMENT informando a decisão tomada pelo Cliente.

Fluxo executado sem Proposta de Reembolso

Caso o parceiro não faça uma proposta de reembolso, o fluxo se encerrará com o aceite ou a recusa do cancelamento.

Diagrama de Sequência

Diagrama de Sequência de uma Proposta de Solicitação de Cancelamento Total executada pela Plataforma de Negociação.

Exemplo dos eventos que serão recebidos:

HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "alternatives":[
      {
        "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
        "type":"REFUND",
        "metadata": {
          "maxAmount": {
            "value": "2400",
            "currency": "BRL"
          }
        }
      }
    ], 
    "metadata":{
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ]
    }, 
    "message":"pedido veio errado", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

HANDSHAKE_SETTLEMENT

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"REJECTED", 
    "reason":"Razão por não aceitar a proposta", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Fluxo executado com Proposta de Reembolso

Caso o parceiro faça uma proposta de reembolso através do endpoint alternative, o cliente irá receber a proposta feita pelo parceiro, e após o cliente responder a contraproposta, o Parceiro irá receber o evento HANDSHAKE_SETTLEMENT informando e formalizando a decisão do Cliente.

Diagrama de Sequência

Diagrama de Sequência de uma Proposta de Solicitação de Cancelamento Total com Proposta de Reembolso executada pela Plataforma de Negociação.

Exemplos dos eventos que serão recebidos:

HANDSHAKE_DISPUTE

Evento recebido com opção de proposta de reembolso. Gerado após a utilização do endpoint

alternative.

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "alternatives":[
      {
        "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
        "type":"REFUND",
        "metadata": {
          "amount": {
            "value": "2312",
            "currency": "BRL"
          }
        }
      }
    ], 
    "metadata":{
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ]
    }, 
    "message":"pedido veio errado", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

HANDSHAKE_SETTLEMENT

Quando a Dispute é respondida através do endpoint alternative será gerado um evento HANDSHAKE_SETTLEMENT formalizando a proposta de reembolso enviada para o cliente.

{
   "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
   "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
   "code":"HSS", 
   "fullcode":"HANDSHAKE_SETTLEMENT", 
   "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
   "createdAt":"2023-06-23T13:09:06.287636Z", 
   "metadata":{
      "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
      "status":"ALTERNATIVE_REPLIED", 
      "reason":"Razão por não aceitar a proposta", 
      "selectedDisputeAlternative":{
         "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
         "type":"REFUND",
         "metadata": {
            "amount": {
              "value": "2312",
              "currency": "BRL"
            }
        }
      }, 
      "createdAt":"2023-06-23T13:06:50.448434Z"
   }, 
   "receivedAt":"2023-06-23T13:09:06.287636Z"
}

HANDSHAKE_SETTLEMENT

Quando a Dispute for respondida pelo cliente, será gerado um Evento HANDSHAKE_SETTLEMENT formalizando e informando a resposta do cliente em relação a proposta do reembolso feita pelo parceiro.

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"ACCEPTED", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Negociação de atraso na entrega

Nesse contexto de negociação, de solicitação de cancelamento total por atraso, antes do cancelamento ser efetivado será iniciado uma negociação na plataforma de handshake, oportunizando o Parceiro de aceitar o cancelamento ou propor um novo tempo de entrega ao cliente.

Deste modo, o objetivo dessa negociação é evitar que o cliente cancele o pedido por atraso, através de um novo prazo de entrega proposto pelo parceiro.

Quando um cliente expressa a intenção de cancelar um pedido, o parceiro, por meio do mecanismo de polling, receberá um evento de HANDSHAKE_DISPUTE que representa uma Dispute.

Para responder a essa Dispute, o parceiro deve utilizar os seguintes endpoints:

• /accept: Para ACEITAR a solicitação de cancelamento.
• /alternative: Para negociar um novo tempo de entrega do pedido.

Endpoint ACCEPT

Se o parceiro executar a opção "accept", nenhuma proposta será enviada ao Cliente, a negociação será encerrada e o pedido cancelado.

Endpoint ALTERNATIVE

Caso o parceiro faça uma requisição no endpoint alternative, o Cliente será notificado e poderá aceitar ou rejeitar a negociação de atraso do pedido. Após o processamento deste endpoint o parceiro receberá um evento HANDSHAKE_SETTLEMENT, formalizando a quantidade de minutos a ser acrescido no tempo de entrega e o motivo disto, o qual não requer nenhuma ação adicional e deverá aguardar a resposta do cliente.

Após o cliente responder à negociação de atraso na entrega, independentemente da resposta, o parceiro receberá um novo evento HANDSHAKE_SETTLEMENT informando a decisão tomada pelo Cliente, ou seja, se o cliente aceitou ou não esperar pelo tempo de entrega negociado.

Endpoint REJECT

Receberá o seguinte erro:

Body

{
  "code":"CANCELLATION_WHILE_NEGOTIATION_TIME_CANNOT_BE_REJECTED", 
  "message":"Cancellation while negotiation time cannot be rejected"
}

Fluxo executado sem Negociação de atraso

Caso o parceiro não faça uma proposta de reembolso, o fluxo se encerrará com o aceite da solicitação de cancelamento.

Vale ressaltar que neste cenário é necessário enviar um motivo do aceite do cancelamento, assim como descrito aqui.

Diagrama de Sequência

Diagrama de Sequência de uma Proposta de Solicitação de Cancelamento Total executada pela Plataforma de Negociação.

Exemplo dos eventos que serão recebidos:

HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "handshakeType":"DELAY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "alternatives":[
      {
        "id": "c1f76701-994c-4537-8d54-fb2bc2ee511d",
        "type": "ADDTIONAL_TIME",
        "metadata": {
          "allowedsAdditionalTimeInMinutes": [10, 15, 20, 30],
          "allowedsAdditionalTimeReasons": [
            "HIGH_STORE_DEMAND",
            "OPERATIONAL_ISSUES",
            "LACK_OF_DRIVERS",
            "ORDER_OUT_FOR_DELIVERY",
            "DRIVER_IS_ALREADY_AT_THE_ADDRESS"
          ]
        }
      }
    ],
    "metadata":{
      "acceptCancellationReasons": [
        "HIGH_STORE_DEMAND",
        "STORE_SYSTEM_ISSUES",
        "STORE_INTERNAL_DIFFICULTIES",
        "LACK_OF_DRIVERS",
        "OTHER_REASONS",
        "OPERATIONAL_ISSUES",
        "ORDER_OUT_FOR_DELIVERY"
      ]
    }, 
    "message":"pedido veio errado", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

HANDSHAKE_SETTLEMENT

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"ACCEPTED", 
    "reason":"OTHER_REASONS",
    "detailReason": "This is your detail reason, it is optional",
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Fluxo executado com Negociação de atraso

Caso o parceiro faça uma negociação de atraso através do endpoint alternative, o cliente irá receber a proposta feita pelo parceiro, e após o cliente responder a negociação de atraso, o Parceiro irá receber o evento HANDSHAKE_SETTLEMENT informando e formalizando a decisão do Cliente.

Diagrama de Sequência

Diagrama de Sequência de uma Solicitação de Cancelamento Total com Negociação de atraso na entrega executada pela Plataforma de Negociação.

Exemplos dos eventos que serão recebidos:

HANDSHAKE_DISPUTE

Evento recebido com opção de negociação de atraso na entrega.

alternative.

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c",
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8",
  "code":"HSD",
  "fullcode":"HANDSHAKE_DISPUTE",
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8",
  "createdAt":"2023-06-23T13:09:06.287636Z",
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83",
    "action":"CANCELLATION",
    "handshakeType":"DELAY",
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT",
    "timeoutAction":"REJECT_CANCELLATION",
    "alternatives":[
      {
        "id": "c1f76701-994c-4537-8d54-fb2bc2ee511d",
        "type": "ADDTIONAL_TIME",
        "metadata": {
          "allowedsAdditionalTimeInMinutes": [10, 15, 20, 30],
          "allowedsAdditionalTimeReasons": [
            "HIGH_STORE_DEMAND",
            "OPERATIONAL_ISSUES",
            "LACK_OF_DRIVERS",
            "ORDER_OUT_FOR_DELIVERY",
            "DRIVER_IS_ALREADY_AT_THE_ADDRESS"
          ]
        }
      }
    ],
    "metadata":{
      "acceptCancellationReasons": [
        "HIGH_STORE_DEMAND",
        "STORE_SYSTEM_ISSUES",
        "STORE_INTERNAL_DIFFICULTIES",
        "LACK_OF_DRIVERS",
        "OTHER_REASONS",
        "OPERATIONAL_ISSUES",
        "ORDER_OUT_FOR_DELIVERY"
      ]
    },
    "message":"pedido veio errado",
    "expiresAt":"2023-06-23T13:15:06.287636Z",
    "createdAt":"2023-06-23T13:06:50.448434Z"
  },
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

HANDSHAKE_SETTLEMENT

Quando a Dispute é respondida através do endpoint alternative será gerado um evento HANDSHAKE_SETTLEMENT formalizando a negociação com a quantidade de minutos a ser acrescido ao tempo de entrega e o motivo disto.

{
   "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
   "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
   "code":"HSS", 
   "fullcode":"HANDSHAKE_SETTLEMENT", 
   "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
   "createdAt":"2023-06-23T13:09:06.287636Z", 
   "metadata":{
      "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
      "status":"ALTERNATIVE_REPLIED",
      "selectedDisputeAlternative":{
         "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
         "type":"ADDITIONAL_TIME",
         "metadata": {
           "additionalTimeInMinutes":15,
           "additionalTimeReason":"ORDER_OUT_FOR_DELIVERY"
        }
      }, 
      "createdAt":"2023-06-23T13:06:50.448434Z"
   }, 
   "receivedAt":"2023-06-23T13:09:06.287636Z"
}

HANDSHAKE_SETTLEMENT

Quando a Dispute for respondida pelo cliente, será gerado um Evento HANDSHAKE_SETTLEMENT formalizando e informando a resposta do cliente em relação a negociação de atraso na entrega feita pelo parceiro.

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"ACCEPTED", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Cancelamento Parcial

Para os cenários de Solicitação de Cancelamento Parcial Após Conclusão, antes do cancelamento ser efetivado será iniciado uma negociação na Plataforma de Negociação, oportunizando o Parceiro de Aceitar ou Rejeitar a requisição do cliente.

Nesse cenário de negociação, quando um cliente expressa a intenção de cancelar um pedido, o parceiro, por meio do mecanismo de polling, receberá um evento de HANDSHAKE_DISPUTE que representa uma Dispute.

Para responder a Dispute representada pelo evento HANDSHAKE_DISPUTE, o parceiro deve utilizar os seguintes endpoints:

• /accept - Para ACEITAR a solicitação de cancelamento parcial
• /reject - Para REJEITAR a solicitação de cancelamento parcial

Após a requisição bem-sucedida, a Plataforma de Negociação processará a solicitação de forma assíncrona. E, na próxima verificação de polling, o parceiro receberá os seguintes eventos:

• HANDSHAKE_SETTLEMENT

Diagrama de Sequência

Sequência de execução de uma Negociação referente a uma Solicitação de Cancelamento para os cenários de Cancelamento Parcial Após Conclusão.

Parcial Após Conclusão

Ao solicitar um Cancelamento Parcial Após Conclusão, antes que o cancelamento seja efetivado, será iniciada uma negociação entre o Cliente e o Parceiro. Isso permite ao Parceiro ter a oportunidade de ACEITAR ou REJEITAR a requisição do Cliente.

Nesse tipo de negociação, o Parceiro receberá a justificativa do Cliente, bem como as imagens que evidenciam os itens (Item) e/ou subItens (GarnishItem) envolvidos na solicitação de cancelamento parcial.

Exemplo dos eventos que serão recebidos:

HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"PARTIAL_CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY_PARTIALLY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "alternatives":null, 
    "metadata":{
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ], 
      "items":[
        {
          "id":"296b1757-4edf-4a4a-9f03-dfc10d4e907a", 
          "uniqueId":"fe3620ad-c475-4f01-93b9-1ed95907a9ab", 
          "externalCode":"73", 
          "index":1, 
          "quantity":1, 
          "amount":{
            "value":"3890", 
            "currency":"BRL"
          }, 
          "reason":"Não veio a batata, apenas as esfihas"
        }
      ], 
      "garnishItems":[
        {
          "id":"ffa2e2f0-361e-4076-8781-e7c8073326e1", 
          "parentUniqueId":"efe73d06-ccfd-4605-a2a5-1b5b64284b47", 
          "externalCode":"MAI-9601273-601273", 
          "quantity":1, 
          "index":2, 
          "amount":{
            "value":"2650", 
            "currency":"BRL"
          }, 
          "reason":"Revirado e faltando o queijo"
        }
      ]
    }, 
    "message":"Cancelamento parcial", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

HANDSHAKE_SETTLEMENT

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"REJECTED", 
    "reason":"Razão por não aceitar a proposta", 
    "selectedDisputeAlternative":null, 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Parcial com Proposta de Reembolso - Em Breve

Nos cenários de Solicitação de Cancelamento Parcial com Proposta de Reembolso, antes que o cancelamento seja efetivado, será iniciada uma negociação na Plataforma de Negociação, permitindo ao Parceiro ACEITAR, REJEITAR e PROPOR REEMBOLSO, com o objetivo de evitar o cancelamento parcial e, consequentemente, prejuízos financeiros.

Nesse contexto de negociação, quando um Cliente expressa a intenção de cancelar alguns itens de um pedido, o Parceiro por meio do mecanismo de polling, receberá um evento de HANDSHAKE_DISPUTE que representa uma Dispute.

O parceiro irá identificar que a Dispute possui a opção de Proposta de Reembolso, verificando o atributo alternatives. Se ela estiver preenchido, será possível realizar a proposta de reembolso.

Para responder a essa Dispute, o Parceiro poderá utilizar os seguintes endpoints:

• /accept: Para ACEITAR a solicitação de cancelamento parcial
• /reject: Para REJEITAR a solicitação de cancelamento parcial.
• /alternative: Para enviar um valor monetário como contraproposta de reembolso ao Cliente, visando a resolução da situação e evitar o cancelamento do pedido parcial do pedido

Endpoints ACCEPT ou REJECT

Se o parceiro executar a opção accept ou reject, nenhuma proposta será enviada ao Cliente, e a negociação será encerrada.

Endpoint ALTERNATIVE

Caso o parceiro faça uma requisição no endpoint alternative, o Cliente será notificado e poderá aceitar ou rejeitar a contraproposta. Após o processamento deste endpoint o parceiro receberá um evento HANDSHAKE_SETTLEMENT, formalizando o valor monetário enviado, o qual não requer nenhuma ação adicional e deverá aguardar a resposta do cliente.

Após o cliente responder a proposta de reembolso, independentemente da resposta, o parceiro receberá um novo evento HANDSHAKE_SETTLEMENT informando a decisão tomada pelo Cliente.

Fluxo executado SEM proposta de reembolso

Caso o parceiro não faça uma proposta de reembolso, o fluxo se encerrará com o aceite ou a recusa do cancelamento.

Diagrama de Sequência

Diagrama de Sequência de uma Proposta de Solicitação de Cancelamento Parcial.

Exemplos dos eventos que serão recebidos:

HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"PARTIAL_CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY_PARTIALLY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "alternatives":[
      {
        "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
        "type":"REFUND",
        "metadata": {
          "maxAmount": {
            "value": "2400",
            "currency": "BRL"
          }
        }
      }
    ], 
    "metadata":{
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ], 
      "items":[
        {
          "id":"296b1757-4edf-4a4a-9f03-dfc10d4e907a", 
          "uniqueId":"fe3620ad-c475-4f01-93b9-1ed95907a9ab", 
          "externalCode":"73", 
          "index":1, 
          "quantity":1, 
          "amount":{
            "value":"3890", 
            "currency":"BRL"
          }, 
          "reason":"Não veio a batata, apenas as esfihas"
        }
      ], 
      "garnishItems":[
        {
          "id":"ffa2e2f0-361e-4076-8781-e7c8073326e1", 
          "parentUniqueId":"efe73d06-ccfd-4605-a2a5-1b5b64284b47", 
          "externalCode":"MAI-9601273-601273", 
          "quantity":1, 
          "index":2, 
          "amount":{
            "value":"2650", 
            "currency":"BRL"
          }, 
          "reason":"Revirado e faltando o queijo"
        }
      ]
    }, 
    "message":"Cancelamento parcial", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

HANDSHAKE_SETTLEMENT

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"ACCEPTED", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Fluxo executado com proposta de reembolso

Caso o parceiro faça uma proposta de reembolso através do endpoint alternative, o cliente irá receber a proposta feita pelo parceiro, e após o cliente responder a contraproposta, o Parceiro irá receber o evento HANDSHAKE_SETTLEMENT informando e formalizando a decisão do Cliente.

Diagrama de Sequência

Diagrama de Sequência de uma Proposta de Solicitação de Cancelamento Parcial executada pela Plataforma de Negociação.

Exemplos dos eventos que serão recebidos:

HANDSHAKE_DISPUTE

Evento recebido com opção de proposta de reembolso. Gerado após a utilização do endpoint

alternative.

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"PARTIAL_CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY_PARTIALLY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "alternatives":[
      {
        "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
        "type":"REFUND",
        "metadata": {
          "maxAmount": {
            "value": "2400",
            "currency": "BRL"
          }
        }
      }
    ], 
    "metadata":{
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ], 
      "items":[
        {
          "id":"296b1757-4edf-4a4a-9f03-dfc10d4e907a", 
          "uniqueId":"fe3620ad-c475-4f01-93b9-1ed95907a9ab", 
          "externalCode":"73", 
          "index":1, 
          "quantity":1, 
          "amount":{
            "value":"3890", 
            "currency":"BRL"
          }, 
          "reason":"Não veio a batata, apenas as esfihas"
        }
      ], 
      "garnishItems":[
        {
          "id":"ffa2e2f0-361e-4076-8781-e7c8073326e1", 
          "parentUniqueId":"efe73d06-ccfd-4605-a2a5-1b5b64284b47", 
          "externalCode":"MAI-9601273-601273", 
          "quantity":1, 
          "index":2, 
          "amount":{
            "value":"2650", 
            "currency":"BRL"
          }, 
          "reason":"Revirado e faltando o queijo"
        }
      ]
    }, 
    "message":"Cancelamento parcial", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

HANDSHAKE_SETTLEMENT

Evento recebido com opção de proposta de reembolso. Gerado após a utilização do endpoint alternative.

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"ALTERNATIVE_REPLIED", 
    "reason":"Razão por não aceitar a proposta", 
    "selectedDisputeAlternative":{
      "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
      "type":"REFUND", 
      "metadata" : {
        "amount": {
          "value": "2000",
          "currency": "BRL"
        }
      }
    }, 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}