Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Guia de negociação de pedidos

Implemente fluxos completos de negociação entre sua loja e clientes. Acompanhe exemplos práticos e procedimentos de teste. Consulte Plataforma de Negociação para referência de API, constantes e entidades.

Fluxo comum de negociação

Todos os cenários de negociação seguem este padrão:

Receba HANDSHAKE_DISPUTE via polling/webhook com action e expiresAt
Responda antes do prazo com /accept, /reject, ou /alternative
Processe HANDSHAKE_SETTLEMENT confirmando a resolução

Abaixo estão exemplos específicos para cada cenário.

Cancelamento após entrega

Negociação iniciada quando cliente solicita cancelamento total ou parcial após receber o pedido. Merchant pode aceitar, rejeitar ou propor reembolso.

Cancelamento total

Aceitar

Setup:

Crie um pedido
Merchant confirma e despacha
Cliente confirma recebimento
Cliente abre app → Ajuda > Pedido veio errado > Selecione todos itens > Envie > "Não quero receber reembolso em saldo iFood"

Event HANDSHAKE_DISPUTE recebido:

{
  "id": "d74ac331-9e5b-467f-96fe-57c143b9177a",
  "code": "HSD",
  "fullCode": "HANDSHAKE_DISPUTE",
  "orderId": "6211e666-2fec-4369-b261-5a422c5ef350",
  "metadata": {
    "action": "CANCELLATION",
    "handshakeType": "AFTER_DELIVERY",
    "expiresAt": "2024-04-25T18:09:46.798698Z",
    "alternatives": [
      {
        "id": "9945f8f1-03ff-4762-8cfd-0f20db66741d",
        "type": "REFUND",
        "metadata": {"maxAmount": {"currency": "BRL", "value": "800"}}
      }
    ]
  }
}

Responda: POST /disputes/{disputeId}/accept

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/2097e3ef-1e0e-46ad-a083-5b39cd615df7/accept" \
  -H "Authorization: Bearer jwt-token" \
  -d ''

Event HANDSHAKE_SETTLEMENT recebido:

{
  "code": "HSS",
  "fullCode": "HANDSHAKE_SETTLEMENT",
  "metadata": {
    "disputeId": "0a2d440f-98f3-4919-ac0b-aa5afe8f4135",
    "status": "ACCEPTED"
  }
}

Rejeitar

Responda: POST /disputes/{disputeId}/reject

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/2097e3ef-1e0e-46ad-a083-5b39cd615df7/reject" \
  -H "Authorization: Bearer jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"reason": "INVENTORY_CHECK"}'

Settlement recebido:

{
  "metadata": {
    "status": "REJECTED",
    "reason": "inventário indisponível"
  }
}

Propor reembolso

Responda: POST /disputes/{disputeId}/alternative

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/2097e3ef-1e0e-46ad-a083-5b39cd615df7/alternative" \
  -H "Authorization: Bearer jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "REFUND",
    "metadata": {
      "amount": {"currency": "BRL", "value": "200"}
    }
  }'

Settlement recebido:

{
  "metadata": {
    "status": "ALTERNATIVE_REPLIED",
    "selectedDisputeAlternative": {
      "type": "REFUND",
      "metadata": {"amount": {"currency": "BRL", "value": "200"}}
    }
  }
}

Merchant recebe outro HANDSHAKE_SETTLEMENT com resposta final do cliente (ACCEPTED, REJECTED, ou EXPIRED).

Cancelamento parcial

Cliente solicita cancelamento de itens específicos. Setup idêntico ao total, mas seleciona alguns itens no app.Event HANDSHAKE_DISPUTE contém:

{
  "metadata": {
    "action": "PARTIAL_CANCELLATION",
    "handshakeType": "AFTER_DELIVERY_PARTIALLY",
    "alternatives": [
      {
        "type": "REFUND",
        "metadata": {"maxAmount": {"currency": "BRL", "value": "2080"}}
      }
    ],
    "metadata": {
      "garnishItems": [
        {
          "id": "2bb737bf-1b72-419d-a77d-8047f07dd144",
          "quantity": 3,
          "amount": {"currency": "BRL", "value": "300"},
          "reason": "Item danificado"
        }
      ]
    }
  }
}

Respostas: Idênticas ao cancelamento total — /accept, /reject, ou /alternative.

# Aceitar parcial
curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/2bb737bf-1b72-419d-a77d-8047f07dd144/accept" \
  -H "Authorization: Bearer jwt-token" \
  -d ''

# Rejeitar parcial
curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/2bb737bf-1b72-419d-a77d-8047f07dd144/reject" \
  -H "Authorization: Bearer jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"reason": "INVENTORY_CHECK"}'

# Propor reembolso parcial
curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/2bb737bf-1b72-419d-a77d-8047f07dd144/alternative" \
  -H "Authorization: Bearer jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "REFUND",
    "metadata": {"amount": {"currency": "BRL", "value": "150"}}
  }'

Cancelamento durante preparo

Cliente solicita cancelamento enquanto pedido está sendo preparado. Merchant pode apenas aceitar ou rejeitar — sem contraproposta.

Respostas

Setup:

Crie um pedido
Merchant confirma (não despacha)
Cliente abre app → Ajuda > Comprei sem querer > Cancelar pedido > Preencha e envie

Event HANDSHAKE_DISPUTE contém:

{
  "metadata": {
    "action": "CANCELLATION",
    "handshakeType": "PREPARATION_TIME",
    "expiresAt": "2024-04-25T19:51:10.252389Z",
    "alternatives": []
  }
}

Respostas:

# Aceitar
curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/b1cab1e3-d4fd-4808-b9eb-5789b04870f2/accept" \
  -H "Authorization: Bearer jwt-token" \
  -d ''

# Rejeitar
curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/b1cab1e3-d4fd-4808-b9eb-5789b04870f2/reject" \
  -H "Authorization: Bearer jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"reason": "PREPARATION_IN_PROGRESS"}'

Cancelamento por atraso

Cliente solicita cancelamento porque pedido está atrasado. Merchant pode aceitar ou propor tempo adicional.Requisito: Config LC_OPS_ORDER_LATE_MARKETPLACE_CHAT_HANDSHAKE_ENABLED = SSetup:

Crie um pedido
Merchant confirma
Aguarde pedido ficar atrasado
Cliente abre app → Preciso de ajuda > (chat) > Não chegou > "Quero uma nova previsão"

Event HANDSHAKE_DISPUTE contém:

{
  "metadata": {
    "action": "CANCELLATION",
    "handshakeType": "DELAY",
    "expiresAt": "2024-04-25T20:36:49.420595Z",
    "alternatives": [
      {
        "type": "ADDITIONAL_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"
      ]
    }
  }
}

Respostas

Aceitar cancelamento por atraso

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/2097e3ef-1e0e-46ad-a083-5b39cd615df7/accept" \
  -H "Authorization: Bearer jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"reason": "STORE_SYSTEM_ISSUES"}'

Propor tempo adicional

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/c95c9885-a0ac-447e-863c-158f97dffd08/alternative" \
  -H "Authorization: Bearer jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ADDITIONAL_TIME",
    "metadata": {
      "additionalTimeInMinutes": 30,
      "additionalTimeReason": "OPERATIONAL_ISSUES"
    }
  }'

Settlement recebido:

{
  "metadata": {
    "status": "ALTERNATIVE_REPLIED",
    "selectedDisputeAlternative": {
      "type": "ADDITIONAL_TIME",
      "metadata": {
        "additionalTimeMinutes": 10,
        "additionalTimeReason": "HIGH_STORE_DEMAND"
      }
    }
  }
}

Merchant recebe outro settlement com resposta final do cliente.

Visualizar evidências de cancelamento

Algumas negociações incluem fotos enviadas pelo cliente (campo metadata.evidences[X].url).

const urlImagem = "https://merchant-api.ifood.com.br/order/v1.0/orders/{orderId}/cancellationEvidences/{imageId}";

fetch(urlImagem, {
  method: 'GET',
  headers: { 'Authorization': 'Bearer jwt-token' }
})
.then(response => response.blob())
.then(blob => {
  const img = document.createElement('img');
  img.src = URL.createObjectURL(blob);
  document.body.appendChild(img);
});

Esta página foi útil?

Avalie sua experiência no novo Developer portal:

Nesta página

Guia de negociação de pedidos

Fluxo comum de negociação

Cancelamento após entrega

Cancelamento total

Cancelamento parcial

Cancelamento durante preparo

Respostas

Cancelamento por atraso

Respostas

Visualizar evidências de cancelamento

Conteúdo lido0%