Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Plataforma de negociação para pedidos

Negocie problemas pós-entrega com clientes — cancelamentos, devoluções e reembolsos através de propostas intermediadas.

Quickstart

Consuma HANDSHAKE_DISPUTE via polling ou webhook
Responda com /accept, /reject, ou /alternative antes de expiresAt
Processe HANDSHAKE_SETTLEMENT confirmando resolução

Requisitos:

Responda obrigatoriamente — sem resposta ativa timeoutAction automaticamente
Uma resposta por disputeId (não reutilizável)
Analise cada negociação individualmente

Cenários

Após entrega: Cancelamento total ou parcial
Durante preparo: Cancelamento total
Entrega atrasada: Cancelamento ou extensão de tempo
Reenvio: Itens faltantes (experimental)

Consulte Guia de implementação para exemplos de fluxo.

Entidades e atributos

HandshakeDispute

Entidade enviada no evento HANDSHAKE_DISPUTE contendo negociação, ação solicitada, evidências, prazo e ação automática de timeout. Inclui DisputeAlternative para reembolsos e Item/GarnishItem para cancelamentos parciais.Identificação e contexto

Atributo	Descrição	Tipo	Obrigatório
id	ID da negociação	`uuid`	✓
parentDisputeId	ID da negociação original (se contraproposta)	`uuid`
createdAt	Data/hora de criação	`DateTime`	✓
message	Justificativa do cliente	`String`	✓

Tipo de negociação

Atributo	Descrição	Tipo	Obrigatório
action	Propósito da negociação	`String`	✓
handshakeType	Tipo de negociação	`String`	✓
handshakeGroup	Classificação	`String`	✓

Valores válidos para action:

CANCELLATION — Cancelamento total
PARTIAL_CANCELLATION — Cancelamento parcial
PROPOSED_AMOUNT_REFUND — Reembolso proposto
PROPOSED_ADDITIONAL_TIME — Extensão de tempo proposta
VOID — Sem ação

Valores válidos para handshakeType:

AFTER_DELIVERY — Cancelamento após cliente receber
DELAY — Cancelamento por entrega atrasada
PREPARATION_TIME — Cancelamento durante preparo
AFTER_DELIVERY_PARTIALLY — Cancelamento parcial após entrega

Prazo e automação

Atributo	Descrição	Tipo	Obrigatório
expiresAt	Prazo para resposta	`DateTime`	✓
timeoutAction	Ação se não responder	`String`	✓

Valores válidos para timeoutAction:

ACCEPT_CANCELLATION — Cancelar automaticamente
REJECT_CANCELLATION — Rejeitar cancelamento automaticamente
VOID — Sem ação automática

Conteúdo da negociação

Atributo	Descrição	Tipo
alternatives	Opções de resposta disponíveis	`List of DisputeAlternative`
metadata.item	Itens para cancelamento parcial	`List of Item`
metadata.garnishItems	Sub-itens (complementos)	`List of GarnishItem`
metadata.evidences	Fotos/mídias do cliente	`List of Media`
metadata.acceptCancellationReasons	Motivos válidos para aceitar	`List of String`

HandshakeSettlement

Entidade enviada no evento HANDSHAKE_SETTLEMENT contendo status e motivo da resolução. Inclui SelectedDisputeAlternative para contrapropostas aceitas.

Atributo	Descrição	Tipo	Obrigatório
id	ID do settlement	`uuid`	✓
disputeId	ID da negociação resolvida	`uuid`	✓
status	Resultado final	`String`	✓
reason	Justificativa de rejeição	`String`
selectedDisputeAlternative	Contraproposta (se status = ALTERNATIVE_REPLIED)	`SelectedDisputeAlternative`

Valores válidos para status:

ACCEPTED — Negociação aceita
REJECTED — Negociação rejeitada
EXPIRED — Sem resposta até prazo
ALTERNATIVE_REPLIED — Contraproposta enviada e aceita

DisputeAlternative

Opções de resolução alternativa acompanhando HandshakeDispute. Valores válidos para type: REFUND, BENEFIT, ADDITIONAL_TIME.

Atributo	Descrição	Tipo	Obrigatório
id	ID da alternativa	`uuid`	✓
type	Tipo de resolução	`String`	✓
metadata.maxAmount	Valor máximo (REFUND/BENEFIT)	`Amount`	Cond
metadata.allowedsAdditionalTimeInMinutes	Opções de extensão (minutos)	`List of Int`	Cond
metadata.allowedsAdditionalTimeReasons	Motivos para atraso	`List of String`	Cond

SelectedDisputeAlternative

Contraproposta aceita acompanhando HandshakeSettlement. Valores válidos para type: REFUND, BENEFIT, ADDITIONAL_TIME.

Atributo	Descrição	Tipo	Obrigatório
id	ID da alternativa	`uuid`	✓
type	Tipo de resolução	`String`	✓
metadata.amount	Valor (REFUND/BENEFIT)	`Amount`	Cond
metadata.additionalTimeInMinutes	Extensão de tempo	`int`	Cond
metadata.reason	Motivo do atraso	`String`	Cond

Media

Foto enviada pelo cliente.

Atributo	Tipo
url	`String` (requer autenticação)
contentType	`String` (MIME type)

Item

Item para cancelamento parcial.

Atributo	Tipo
id	`uuid`
uniqueId	`uuid`
externalCode	`String`
quantity	`int`
index	`int`
amount	`Amount`
reason	`String`

GarnishItem

Sub-item (complemento) para cancelamento parcial.

Atributo	Tipo
id	`uuid`
parentUniqueId	`uuid`
externalCode	`String`
quantity	`int`
index	`int`
amount	`Amount`
reason	`String`

Amount

Valor monetário conforme ISO 4217.

Atributo	Descrição	Tipo
value	Valor sem decimais (R$1,00 = 100)	`String`
currency	Código de moeda (ex: BRL)	`String`

Constantes

`handshakeType`

Valor	Descrição
`AFTER_DELIVERY`	Cancelamento após cliente receber
`DELAY`	Cancelamento por entrega atrasada
`PREPARATION_TIME`	Cancelamento durante preparo
`AFTER_DELIVERY_PARTIALLY`	Cancelamento parcial após entrega

`handshakeGroup`

Valor	Descrição
`CUSTOMER_ORDER_SUPPORT`	Negociação iniciada por cliente

`action`

Valor	Descrição
`CANCELLATION`	Cancelamento total
`PARTIAL_CANCELLATION`	Cancelamento parcial
`PROPOSED_AMOUNT_REFUND`	Cancelamento com opção de reembolso

`timeoutAction`

Valor	Ação
`ACCEPT_CANCELLATION`	Cancelar automaticamente
`REJECT_CANCELLATION`	Rejeitar cancelamento automaticamente
`VOID`	Sem ação automática

`status`

Valor	Descrição
`ACCEPTED`	Negociação aceita
`REJECTED`	Negociação rejeitada
`EXPIRED`	Sem resposta até prazo
`ALTERNATIVE_REPLIED`	Contraproposta enviada e aceita

`type`

Valor	Descrição
`REFUND`	Reembolso em dinheiro
`BENEFIT`	Crédito/benefício
`ADDITIONAL_TIME`	Extensão de tempo

`negotiationReasons`

Motivos para decisões de negociação. Use em corpos de requisição quando necessário.

Motivo	Contexto
`HIGH_STORE_DEMAND`	Loja em capacidade máxima
`UNKNOWN_ISSUE`	Problema não especificado
`CUSTOMER_SATISFACTION`	Satisfação do cliente
`INVENTORY_CHECK`	Verificação de disponibilidade
`SYSTEM_ISSUE`	Problema técnico
`WRONG_ORDER`	Pedido incorreto
`PRODUCT_QUALITY`	Qualidade do produto
`LATE_DELIVERY`	Entrega atrasada
`CUSTOMER_REQUEST`	Solicitação do cliente

Endpoints da API

Aceitar proposta

POST https://merchant-api.ifood.com.br/order/v1.0/disputes/{disputeId}/acceptParâmetros:

Nome	Tipo	Descrição
`disputeId`	`uuid`	ID da dispute (URL)
`reason`	`string`	Motivo de `metadata.acceptCancellationReasons`
`detailReason`	`string`	Descrição (250 chars máx)

Exemplo de requisição:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/dispute_001/accept" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "CUSTOMER_SATISFACTION", "detailReason": "Reembolso por cortesia"}'

Resposta (201 Created):

{
  "id": "settlement_001",
  "status": "ACCEPTED",
  "disputeId": "dispute_001",
  "createdAt": "2024-04-25T18:05:00Z"
}

Erros comuns:

Status	Código	Motivo
401	-	Token inválido
404	`DISPUTE_NOT_FOUND`	Dispute não encontrada
422	`DISPUTE_ALREADY_ANSWERED`	Já respondida
400	`INVALID_REASON`	Motivo inválido

Rejeitar proposta

POST https://merchant-api.ifood.com.br/order/v1.0/disputes/{disputeId}/rejectParâmetros:

Nome	Tipo	Descrição
`disputeId`	`uuid`	ID da dispute (URL)
`reason`	`string`	Motivo de `negotiationReasons`

Exemplo de requisição:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/dispute_002/reject" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "INVENTORY_CHECK"}'

Resposta (201 Created):

{
  "id": "settlement_002",
  "status": "REJECTED",
  "disputeId": "dispute_002",
  "createdAt": "2024-04-25T18:08:00Z"
}

Erros comuns:

Status	Código	Motivo
401	-	Token inválido
404	`DISPUTE_NOT_FOUND`	Dispute não encontrada
422	`DISPUTE_ALREADY_ANSWERED`	Já respondida
400	`INVALID_REASON`	Motivo inválido

Fazer contraproposta

POST https://merchant-api.ifood.com.br/order/v1.0/disputes/{disputeId}/alternativeParâmetros:

Nome	Tipo	Descrição
`disputeId`	`uuid`	ID da dispute (URL)
`type`	`string`	`REFUND`, `BENEFIT` ou `ADDITIONAL_TIME`
`metadata.amount`	`Amount`	Valor (REFUND/BENEFIT)
`metadata.additionalTimeInMinutes`	`int`	Minutos (ADDITIONAL_TIME)
`metadata.reason`	`string`	Motivo do atraso (ADDITIONAL_TIME)

Exemplos por tipo:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/dispute_001/alternative" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "REFUND",
    "metadata": {
      "amount": {
        "value": "5000",
        "currency": "BRL"
      }
    }
  }'

Resposta (201 Created):

{
  "id": "settlement_003",
  "status": "ALTERNATIVE_REPLIED",
  "disputeId": "dispute_003",
  "selectedDisputeAlternative": {
    "id": "alt_001",
    "type": "ADDITIONAL_TIME",
    "metadata": {
      "additionalTimeInMinutes": 30,
      "reason": "HIGH_STORE_DEMAND"
    }
  },
  "createdAt": "2024-04-25T18:12:00Z"
}

Erros comuns:

Status	Código	Motivo
401	-	Token inválido
404	`DISPUTE_NOT_FOUND`	Dispute não encontrada
422	`DISPUTE_ALREADY_ANSWERED`	Já respondida
400	`INVALID_AMOUNT`	Valor fora do intervalo

Matriz de negociações

Cenário	handshakeType	action	Respostas
Total após entrega	AFTER_DELIVERY	CANCELLATION	Aceitar / Rejeitar / REFUND
Total durante preparo	PREPARATION_TIME	CANCELLATION	Aceitar / Rejeitar
Total (atraso)	DELAY	CANCELLATION	Aceitar / Rejeitar / ADDITIONAL_TIME
Parcial após entrega	AFTER_DELIVERY_PARTIALLY	PARTIAL_CANCELLATION	Aceitar / Rejeitar / REFUND

Consulte Guia de implementação para exemplos completos.

Timeout

Sem resposta até expiresAt, timeoutAction é executada:

ACCEPT_CANCELLATION: Pedido cancelado
REJECT_CANCELLATION: Cancelamento rejeitado
VOID: Sem ação

Gera HANDSHAKE_SETTLEMENT com status: EXPIRED.

Referência de Eventos

HANDSHAKE_DISPUTE

Publicado quando cliente inicia negociação elegível (cancelamento com critérios de negociação).Estrutura do evento

Atributo	Tipo
id	`string`
code	`string` (sempre "HSD")
fullCode	`string` (sempre "HANDSHAKE_DISPUTE")
orderId	`uuid`
merchantId	`uuid`
createdAt	`DateTime`
metadata	`HandshakeDispute`

Exemplos por cenário:

{
  "id": "evt_001",
  "code": "HSD",
  "fullCode": "HANDSHAKE_DISPUTE",
  "orderId": "ord_12345",
  "merchantId": "merchant_001",
  "createdAt": "2024-04-25T18:02:46.921Z",
  "metadata": {
    "id": "dispute_001",
    "action": "CANCELLATION",
    "handshakeType": "AFTER_DELIVERY",
    "handshakeGroup": "CUSTOMER_ORDER_SUPPORT",
    "message": "Comida chegou fria",
    "expiresAt": "2024-04-25T18:09:46Z",
    "timeoutAction": "REJECT_CANCELLATION",
    "createdAt": "2024-04-25T18:02:46Z",
    "alternatives": [
      {
        "id": "alt_001",
        "type": "REFUND",
        "metadata": {
          "maxAmount": {
            "currency": "BRL",
            "value": "5000"
          }
        }
      }
    ],
    "acceptCancellationReasons": ["PRODUCT_QUALITY", "CUSTOMER_SATISFACTION"],
    "evidences": [
      {
        "url": "https://merchant-api.ifood.com.br/orders/ord_12345/evidences/abc123",
        "contentType": "image/jpeg"
      }
    ]
  }
}

HANDSHAKE_SETTLEMENT

Publicado quando negociação é resolvida (aceita, rejeitada, contraproposta ou timeout).Estrutura do evento

Atributo	Tipo
id	`string`
code	`string` (sempre "HSS")
fullCode	`string` (sempre "HANDSHAKE_SETTLEMENT")
orderId	`uuid`
merchantId	`uuid`
createdAt	`DateTime`
metadata	`HandshakeSettlement`

Exemplos por resultado:

{
  "id": "evt_settlement_001",
  "code": "HSS",
  "fullCode": "HANDSHAKE_SETTLEMENT",
  "orderId": "ord_12345",
  "merchantId": "merchant_001",
  "createdAt": "2024-04-25T18:05:00Z",
  "metadata": {
    "id": "settlement_001",
    "disputeId": "dispute_001",
    "status": "ACCEPTED",
    "reason": "CUSTOMER_SATISFACTION",
    "createdAt": "2024-04-25T18:05:00Z"
  }
}

Próximos passos

Guia de implementação — Exemplos de fluxo
Polling de eventos — Configuração
Workflow — Estados de pedidos

Esta página foi útil?

Avalie sua experiência no novo Developer portal: