Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Endpoints

URL Base

https://merchant-api.ifood.com.br/picking/v1.0

Autenticación

Todas las solicitudes del módulo Picking requieren autenticación vía JWT en un encabezado Authorization.

Authorization: Bearer TU_TOKEN_JWT

Para más detalles sobre autenticación, ver Autenticación.

Operaciones disponibles

Método	Endpoint	Descripción
`POST`	`/orders/{id}/startSeparation`	Iniciar la separación
`POST`	`/orders/{id}/endSeparation`	Finalizar la separación
`POST`	`/orders/{id}/items`	Adicionar ítem
`PATCH`	`/orders/{id}/items/{uniqueId}`	Modificar ítem
`POST`	`/orders/{id}/items/{uniqueId}/replace`	Sustituir ítem
`DELETE`	`/orders/{id}/items/{uniqueId}`	Remover ítem

Edición de ítems

Adicionar ítem

Use POST /orders/{id}/items para adicionar un ítem al pedido.

Cuándo usar

Adicionar ítems que faltaban en la recolección o fueron solicitados después de la apertura del pedido.

Parámetros de path

Parámetro	Tipo	Descripción
`id`	`string` (UUID)	ID del pedido

Cuerpo de la solicitud

Campo	Tipo	Descripción
`quantity`	`number`	Cantidad de unidades
`ean`	`string`	Código EAN del producto

Validaciones

Pedido existente y válido
Producto existe en el catálogo de la tienda
Disponible solo para pedidos White Label

Observaciones

Puede generar cobro adicional después de finalizar separación

Ejemplo

curl -X POST https://merchant-api.ifood.com.br/picking/v1.0/orders/550e8400-e29b-41d4-a716-446655440000/items \
  -H "Authorization: Bearer TU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 2,
    "ean": "1234567890"
  }'

Respuestas

204 No Content - Ítem adicionado correctamente
404 Not Found - Pedido o producto no encontrado
409 Conflict - Conflicto al adicionar ítem
500 Internal Server Error - Error interno del servidor

Modificar ítem

Use PATCH /orders/{id}/items/{uniqueId} para modificar un ítem existente.

Cuándo usar

Ajustar cantidad de ítems después de la recolección (ej: variación de peso).

Parámetros de path

Parámetro	Tipo	Descripción
`id`	`string` (UUID)	ID del pedido
`uniqueId`	`string` (UUID)	ID único del ítem

Cuerpo de la solicitud

Campo	Tipo	Descripción
`quantity`	`number`	Nueva cantidad de unidades

Validaciones

Pedido existente y válido
Ítem no hace parte de combo
Cantidad válida

Observaciones

Puede generar cobro adicional o reembolso después de finalizar separación

Ejemplo

curl -X PATCH https://merchant-api.ifood.com.br/picking/v1.0/orders/550e8400-e29b-41d4-a716-446655440000/items/660e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer TU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 3
  }'

Respuestas

204 No Content - Ítem modificado correctamente
404 Not Found - Pedido o ítem no encontrado
409 Conflict - Conflicto al modificar ítem
500 Internal Server Error - Error interno del servidor

Sustituir ítem

Use POST /orders/{id}/items/{uniqueId}/replace para sustituir un ítem por otro.

Cuándo usar

Cambiar un producto no disponible por una alternativa que atienda mejor al cliente.

Parámetros de path

Parámetro	Tipo	Descripción
`id`	`string` (UUID)	ID del pedido
`uniqueId`	`string` (UUID)	ID único del ítem a sustituir

Cuerpo de la solicitud

Campo	Tipo	Descripción
`quantity`	`number`	Cantidad de unidades del nuevo producto
`ean`	`string`	Código EAN del nuevo producto

Validaciones

Pedido existente y válido
Producto sustituto existe en el catálogo
Reglas de valor conforme método de pago

Observaciones

Puede generar cobro adicional después de finalizar separación

Ejemplo

curl -X POST https://merchant-api.ifood.com.br/picking/v1.0/orders/550e8400-e29b-41d4-a716-446655440000/items/660e8400-e29b-41d4-a716-446655440001/replace \
  -H "Authorization: Bearer TU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 2,
    "ean": "0987654321"
  }'

Respuestas

204 No Content - Ítem sustituido correctamente
404 Not Found - Pedido o ítem no encontrado
409 Conflict - Conflicto al sustituir ítem
500 Internal Server Error - Error interno del servidor

Remover ítem

Use DELETE /orders/{id}/items/{uniqueId} para remover un ítem del pedido.

Cuándo usar

Eliminar ítems no disponibles o que estén en ruptura de inventario.

Parámetros de path

Parámetro	Tipo	Descripción
`id`	`string` (UUID)	ID del pedido
`uniqueId`	`string` (UUID)	ID único del ítem a remover

Validaciones

Pedido existente y válido
Ítem no hace parte de combo

Observaciones

Si es combo, todos los ítems del combo serán removidos
Puede generar reembolso después de finalizar separación

Ejemplo

curl -X DELETE https://merchant-api.ifood.com.br/picking/v1.0/orders/550e8400-e29b-41d4-a716-446655440000/items/660e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer TU_TOKEN_JWT"

Respuestas

204 No Content - Ítem removido correctamente
404 Not Found - Pedido o ítem no encontrado
409 Conflict - Conflicto al remover ítem
500 Internal Server Error - Error interno del servidor

Aplicación de las alteracionesTodas las alteraciones de ítems solo son aplicadas después de finalizar la separación.La finalización puede fallar en casos como:

Reglas específicas de métodos de pago
Cobro adicional no permitido

En estos casos, ajuste el pedido conforme a la regla antes de finalizar.

Acciones del pedido

Iniciar la separación

Use POST /orders/{id}/startSeparation para informar el inicio de la separación.

Cuándo usar

Al comenzar el proceso de recolección de los ítems del pedido.

Parámetros de path

Parámetro	Tipo	Descripción
`id`	`string` (UUID)	ID del pedido

Validaciones

Pedido existente y válido
Pedido no fue cancelado

Observaciones

Anterior al inicio de la separación, el pedido puede sufrir alteraciones por ediciones hechas por el consumidor. Estas alteraciones son indicadas por el evento ORDER_PATCHED. Si este evento ha sido recibido, realice una nueva consulta del pedido para recuperar la información que haya sido actualizada.

Ejemplo

curl -X POST https://merchant-api.ifood.com.br/picking/v1.0/orders/550e8400-e29b-41d4-a716-446655440000/startSeparation \
  -H "Authorization: Bearer TU_TOKEN_JWT"

Respuestas

204 No Content - Separación iniciada correctamente
404 Not Found - Pedido no encontrado
409 Conflict - Conflicto al iniciar separación
500 Internal Server Error - Error interno del servidor

Finalizar la separación

Use POST /orders/{id}/endSeparation para informar el fin de la separación.

Cuándo usar

Después de concluir la recolección y aplicar todas las ediciones necesarias.

Parámetros de path

Parámetro	Tipo	Descripción
`id`	`string` (UUID)	ID del pedido

Validaciones

Pedido existente y válido
Separación fue iniciada
Todas las ediciones son válidas

Observaciones

Al finalizar la separación, se realizan las siguientes validaciones:

Validación de reglas específicas de métodos de pago
Validación de permiso para aplicar cobros adicionales
Consulta de estado del pedido después de la finalización

Próximas acciones después de la finalizaciónSiempre consulte los detalles del pedido después de finalizar la separación para obtener la versión actualizada y confirmar que todos los cambios fueron aplicados.

Ejemplo

curl -X POST https://merchant-api.ifood.com.br/picking/v1.0/orders/550e8400-e29b-41d4-a716-446655440000/endSeparation \
  -H "Authorization: Bearer TU_TOKEN_JWT"

Respuestas

204 No Content - Separación finalizada correctamente
404 Not Found - Pedido no encontrado
409 Conflict - Conflicto al finalizar separación
500 Internal Server Error - Error interno del servidor

¿Esta página fue útil?

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