Cómo funciona

Entienda las etapas, flujo de operaciones y puntos críticos de la API Picking.

Ciclo de vida de la separación

La separación de un pedido pasa por diferentes etapas, desde la confirmación hasta la entrega:

Pedido confirmado (CONFIRMED)
- El cliente finalizó la compra
- Recibe el pedido y puede comenzar la preparación
- Próxima acción: Iniciar la separación
Separación iniciada (SEPARATION_STARTED)
- Notificó a iFood que comenzó a recopilar los artículos
- Es en este momento que puede editar artículos (agregar, remover, modificar, sustituir)
- Las ediciones se registran pero aún no se aplican
Separación finalizada (SEPARATION_ENDED)
- Completó la recopilación de todos los artículos
- En este momento, todas las ediciones se validan y aplican al pedido
- Se realizan cálculos de precios y ajustes
Pedido despachado (DISPATCHED)
- El pedido ha sido liberado para entrega
- No se permiten ediciones a partir de este punto
Cancelado (CANCELLED)
- El pedido fue cancelado en cualquier momento

Flujo de operaciones

Secuencia correcta

La integración debe seguir esta secuencia obligatoria:

Iniciar separación (POST /startSeparation)

Pedido cambia de CONFIRMED → SEPARATION_STARTED

Editar ítems (Adicionar, Modificar, Remover, Sustituir)

Solo durante SEPARATION_STARTED
Las ediciones se registran pero NO se aplican aún

Finalizar separación (POST /endSeparation)

Pedido cambia de SEPARATION_STARTED → SEPARATION_ENDED
TODAS las ediciones se validan y aplican

Consultar pedido actualizado (GET order details)

Obtenga la versión final del pedido con todos los cambios

El orden es críticoCualquier desviación de esta secuencia resultará en errores 409 Conflict. No está permitido:

Editar ítems antes de iniciar la separación
Finalizar la separación sin haberla iniciado
Editar ítems después de finalizar la separación

Ciclo de vida de una edición

Adicionar/Modificar/Remover ítem

1. Solicitud recibida → Validación básica
   ¿Pedido existe?
   ¿Separación fue iniciada?
   ¿Producto existe (para add/replace)?

2. Validación aplicada → Estado pendiente
   Ítem agregado a lista de ediciones
   NO afecta el precio aún

3. Finalización de separación → Validaciones finales
   Reglas de método de pago
   Permiso para cobros adicionales
   Cálculo de ajustes de precio

4. Aplicación → Pedido actualizado
   Ediciones confirmadas
   Precios ajustados
   Inventario reflejado

¿Qué ocurre con el precio?

Los cambios de precio solo se calculan al finalizar la separación, no durante las ediciones.

Operación	Efecto en la finalización
Adicionar ítem	Cobro adicional (precio del producto)
Remover ítem	Reembolso (precio original)
Aumentar cantidad	Cobro adicional
Disminuir cantidad	Reembolso
Sustituir por ítem más caro	Cobro adicional
Sustituir por ítem más barato	Reembolso

Idempotencia y errores

¿Qué pasa si llamo al mismo endpoint 2 veces?

Iniciar separación dos veces:

1er intento: 204 No Content
2do intento: 409 Conflict (Separation already started)

La operación no es idempotente. La segunda llamada fallará.Solución: Siempre verifique el estado actual del pedido antes de llamar a startSeparation.

¿Y si la solicitud se cae?

Si no recibe respuesta:

Espere unos segundos
Haga un GET en el pedido para verificar el estado actual
Si SEPARATION_STARTED: Continúe editando (no repita startSeparation)
Si CONFIRMED: Intente iniciar nuevamente

Manejo de eventos

ORDER_PATCHED

Antes de iniciar la separación, el cliente puede editar el pedido (cancelar ítems, agregar más).Cuando esto sucede, recibe el evento ORDER_PATCHED.Qué hacer:

¿Recibió ORDER_PATCHED? Haga un nuevo GET en el pedido
Actualice su vista local de los ítems
Proceda normalmente con startSeparation

# Ejemplo: Antes de iniciar, siempre consulte el pedido
GET /orders/{id}
# Confirme los ítems actuales antes de llamar a startSeparation

Restricciones por método de pago

Algunos métodos de pago tienen reglas especiales para ediciones:

Método	Adicionar ítems	Remover ítems	Modificar cantidad
Crédito	Sí	Sí	Sí
Débito	Limitado	Sí	Sí
Pix	Sí	Sí	Restringido
Efectivo	Restringido	Sí	Sí

Consulte la documentación de métodos de pago para reglas específicas antes de editar ítems.

Combinados (combos)

Un combo es un agrupamiento de ítems vendidos juntos.

Reglas para combos:

No puede modificar ítems individuales de un combo
Remover un ítem de un combo remueve el combo completo
Adicionar ítems no afecta combos existentes

# Ejemplo: Combo con bebida + sándwich
# Si remueve la bebida:
DELETE /orders/{id}/items/{drink_id}
# Resultado: El combo completo se remueve
# (el sándwich también se remueve)