Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Plataforma de negociación de órdenes

Negocie problemas post-entrega con clientes — cancelaciones, devoluciones, reembolsos a través de propuestas mediadas.

Inicio rápido

Consuma HANDSHAKE_DISPUTE vía polling o webhook
Responda con /accept, /reject, o /alternative antes de expiresAt
Procese HANDSHAKE_SETTLEMENT confirmando resolución

Requisitos:

Debe responder a cada disputa — sin respuesta activa timeoutAction automáticamente
Una respuesta por disputeId (no reutilizable)
Analice cada negociación individualmente

Escenarios

Después de entrega: Solicitud de cancelación total o parcial
Durante preparación: Solicitud de cancelación total
Entrega atrasada: Cancelación o solicitud de extensión de tiempo
Reenvío: Items faltantes (experimental)

Ver guía de implementación para ejemplos de flujo.

Entidades y atributos

HandshakeDispute

Entidad enviada en evento HANDSHAKE_DISPUTE conteniendo negociación, acción solicitada, evidencia, plazo y acción automática de timeout. Incluye DisputeAlternative para reembolsos e Item/GarnishItem para cancelaciones parciales.Identificación y contexto

Atributo	Descripción	Tipo	Requerido
id	ID de negociación	`uuid`	✓
parentDisputeId	ID de negociación original (si contrapropuesta)	`uuid`
createdAt	Marca de tiempo de creación	`DateTime`	✓
message	Justificación del cliente	`String`	✓

Tipo de negociación

Atributo	Descripción	Tipo	Requerido
action	Propósito de negociación	`String`	✓
handshakeType	Tipo de negociación	`String`	✓
handshakeGroup	Clasificación	`String`	✓

Valores válidos para action:

CANCELLATION — Cancelación total
PARTIAL_CANCELLATION — Cancelación parcial
PROPOSED_AMOUNT_REFUND — Reembolso propuesto
PROPOSED_ADDITIONAL_TIME — Extensión de tiempo propuesta
VOID — Sin acción

Valores válidos para handshakeType:

AFTER_DELIVERY — Cancelación después de que el cliente recibe
DELAY — Cancelación por entrega atrasada
PREPARATION_TIME — Cancelación durante preparación
AFTER_DELIVERY_PARTIALLY — Cancelación parcial después de entrega

Plazo y automatización

Atributo	Descripción	Tipo	Requerido
expiresAt	Plazo para respuesta	`DateTime`	✓
timeoutAction	Acción si no responde	`String`	✓

Valores válidos para timeoutAction:

ACCEPT_CANCELLATION — Aceptar automáticamente cancelación
REJECT_CANCELLATION — Rechazar automáticamente cancelación
VOID — Sin acción automática

Contenido de negociación

Atributo	Descripción	Tipo
alternatives	Opciones de respuesta disponibles	`List of DisputeAlternative`
metadata.item	Items para cancelación parcial	`List of Item`
metadata.garnishItems	Sub-items (complementos)	`List of GarnishItem`
metadata.evidences	Fotos/medios del cliente	`List of Media`
metadata.acceptCancellationReasons	Razones válidas para aceptar	`List of String`

HandshakeSettlement

Entidad enviada en evento HANDSHAKE_SETTLEMENT conteniendo estado de resolución y razón. Incluye SelectedDisputeAlternative para contrapropostas aceptadas.

Atributo	Descripción	Tipo	Requerido
id	ID de liquidación	`uuid`	✓
disputeId	ID de negociación resuelta	`uuid`	✓
status	Resultado final	`String`	✓
reason	Justificación de rechazo	`String`
selectedDisputeAlternative	Contrapropuesta (si status = ALTERNATIVE_REPLIED)	`SelectedDisputeAlternative`

Valores válidos para status:

ACCEPTED — Negociación aceptada
REJECTED — Negociación rechazada
EXPIRED — Sin respuesta hasta el plazo
ALTERNATIVE_REPLIED — Contrapropuesta enviada y aceptada

DisputeAlternative

Opciones de resolución alternativa acompañando HandshakeDispute. Valores válidos para type: REFUND, BENEFIT, ADDITIONAL_TIME.

Atributo	Descripción	Tipo	Requerido
id	ID de alternativa	`uuid`	✓
type	Tipo de resolución	`String`	✓
metadata.maxAmount	Cantidad máxima (REFUND/BENEFIT)	`Amount`	Cond
metadata.allowedsAdditionalTimeInMinutes	Opciones de extensión (minutos)	`List of Int`	Cond
metadata.allowedsAdditionalTimeReasons	Razones para demora	`List of String`	Cond

SelectedDisputeAlternative

Contrapropuesta aceptada acompañando HandshakeSettlement. Valores válidos para type: REFUND, BENEFIT, ADDITIONAL_TIME.

Atributo	Descripción	Tipo	Requerido
id	ID de alternativa	`uuid`	✓
type	Tipo de resolución	`String`	✓
metadata.amount	Cantidad (REFUND/BENEFIT)	`Amount`	Cond
metadata.additionalTimeInMinutes	Extensión de tiempo	`int`	Cond
metadata.reason	Razón de demora	`String`	Cond

Media

Foto enviada por cliente.

Atributo	Tipo
url	`String` (requiere autenticación)
contentType	`String` (tipo MIME)

Item

Item para cancelación parcial.

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

GarnishItem

Sub-item (complemento) para cancelación parcial.

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

Amount

Valor monetario conforme ISO 4217.

Atributo	Descripción	Tipo
value	Cantidad sin decimales ($1.00 = 100)	`String`
currency	Código de moneda (ej: USD)	`String`

Constantes

`handshakeType`

Valor	Descripción
`AFTER_DELIVERY`	Cancelación después de recibir
`DELAY`	Cancelación por entrega atrasada
`PREPARATION_TIME`	Cancelación durante preparación
`AFTER_DELIVERY_PARTIALLY`	Cancelación parcial después de entrega

`handshakeGroup`

Valor	Descripción
`CUSTOMER_ORDER_SUPPORT`	Negociación iniciada por cliente

`action`

Valor	Descripción
`CANCELLATION`	Cancelación total
`PARTIAL_CANCELLATION`	Cancelación parcial
`PROPOSED_AMOUNT_REFUND`	Cancelación con opción de reembolso

`timeoutAction`

Valor	Acción
`ACCEPT_CANCELLATION`	Cancelar automáticamente
`REJECT_CANCELLATION`	Rechazar cancelación automáticamente
`VOID`	Sin acción automática

`status`

Valor	Descripción
`ACCEPTED`	Negociación aceptada
`REJECTED`	Negociación rechazada
`EXPIRED`	Sin respuesta antes de plazo
`ALTERNATIVE_REPLIED`	Contrapropuesta enviada y aceptada

`type`

Valor	Descripción
`REFUND`	Reembolso en dinero
`BENEFIT`	Crédito/beneficio
`ADDITIONAL_TIME`	Extensión de tiempo

`negotiationReasons`

Razones para decisiones de negociación. Use en cuerpos de solicitud cuando sea necesario.

Razón	Contexto
`HIGH_STORE_DEMAND`	Tienda en capacidad máxima
`UNKNOWN_ISSUE`	Problema no especificado
`CUSTOMER_SATISFACTION`	Satisfacción del cliente
`INVENTORY_CHECK`	Verificación de disponibilidad
`SYSTEM_ISSUE`	Problema técnico
`WRONG_ORDER`	Pedido incorrecto
`PRODUCT_QUALITY`	Preocupación de calidad
`LATE_DELIVERY`	Entrega atrasada
`CUSTOMER_REQUEST`	Solicitud del cliente

Endpoints de API

Aceptar propuesta

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

Nombre	Tipo	Descripción
`disputeId`	`uuid`	ID de disputa (URL)
`reason`	`string`	Razón de `metadata.acceptCancellationReasons`
`detailReason`	`string`	Descripción (máx 250 caracteres)

Ejemplo de solicitud:

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 cortesía"}'

Respuesta (201 Created):

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

Errores comunes:

Estado	Código	Razón
401	-	Token inválido
404	`DISPUTE_NOT_FOUND`	Disputa no encontrada
422	`DISPUTE_ALREADY_ANSWERED`	Ya respondida
400	`INVALID_REASON`	Razón inválida

Rechazar propuesta

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

Nombre	Tipo	Descripción
`disputeId`	`uuid`	ID de disputa (URL)
`reason`	`string`	Razón de `negotiationReasons`

Ejemplo de solicitud:

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"}'

Respuesta (201 Created):

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

Errores comunes:

Estado	Código	Razón
401	-	Token inválido
404	`DISPUTE_NOT_FOUND`	Disputa no encontrada
422	`DISPUTE_ALREADY_ANSWERED`	Ya respondida
400	`INVALID_REASON`	Razón inválida

Hacer contrapropuesta

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

Nombre	Tipo	Descripción
`disputeId`	`uuid`	ID de disputa (URL)
`type`	`string`	`REFUND`, `BENEFIT` o `ADDITIONAL_TIME`
`metadata.amount`	`Amount`	Cantidad (REFUND/BENEFIT)
`metadata.additionalTimeInMinutes`	`int`	Minutos (ADDITIONAL_TIME)
`metadata.reason`	`string`	Razón de demora (ADDITIONAL_TIME)

Ejemplos 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"
      }
    }
  }'

Respuesta (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"
}

Errores comunes:

Estado	Código	Razón
401	-	Token inválido
404	`DISPUTE_NOT_FOUND`	Disputa no encontrada
422	`DISPUTE_ALREADY_ANSWERED`	Ya respondida
400	`INVALID_AMOUNT`	Cantidad fuera de rango

Matriz de negociaciones

Escenario	handshakeType	action	Respuestas
Total después de entrega	AFTER_DELIVERY	CANCELLATION	Aceptar / Rechazar / REFUND
Total durante preparación	PREPARATION_TIME	CANCELLATION	Aceptar / Rechazar
Total (atrasado)	DELAY	CANCELLATION	Aceptar / Rechazar / ADDITIONAL_TIME
Parcial después de entrega	AFTER_DELIVERY_PARTIALLY	PARTIAL_CANCELLATION	Aceptar / Rechazar / REFUND

Ver guía de implementación para ejemplos completos.

Timeout

Si no hay respuesta antes de expiresAt, timeoutAction se ejecuta:

ACCEPT_CANCELLATION: Pedido cancelado
REJECT_CANCELLATION: Cancelación rechazada
VOID: Sin acción

Genera HANDSHAKE_SETTLEMENT con status: EXPIRED.

Referencia de Eventos

HANDSHAKE_DISPUTE

Publicado cuando cliente inicia negociación elegible (cancelación que cumple criterios).Estructura del evento

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

Ejemplos por escenario:

{
  "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 llegó fría",
    "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 cuando negociación se resuelve (aceptada, rechazada, contrapropuesta o timeout).Estructura del evento

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

Ejemplos 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 pasos

Guía de implementación — Ejemplos de flujo
Polling de eventos — Configuración
Workflow de órdenes — Estados de pedidos

¿Esta página fue útil?

Evalúa tu experiencia en el nuevo portal de desarrolladores: