Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Endpoints

Referência completa da API Picking para gerenciar a separação de pedidos.Base URL: https://merchant-api.ifood.com.br/picking/v1.0Autenticação: Todas as requisições requerem um token OAuth 2.0 no header Authorization: Bearer {JWT_TOKEN}. Veja a documentação de autenticação para detalhes.

Operações

Método	Endpoint	Descrição
`POST`	`/orders/{id}/startSeparation`	Iniciar a separação
`POST`	`/orders/{id}/endSeparation`	Finalizar a separação
`POST`	`/orders/{id}/items`	Adicionar item
`PATCH`	`/orders/{id}/items/{uniqueId}`	Modificar item
`POST`	`/orders/{id}/items/{uniqueId}/replace`	Substituir item
`DELETE`	`/orders/{id}/items/{uniqueId}`	Remover item

Edição de itens

Adicionar item

Use POST /orders/{id}/items para adicionar itens que faltaram na coleta ou foram solicitados após a abertura do pedido.

Parâmetros de path

Parâmetro	Tipo	Descrição
`id`	`string` (UUID)	ID do pedido

Corpo da requisição

Campo	Tipo	Descrição
`quantity`	`number`	Quantidade de unidades
`ean`	`string`	Código EAN do produto

Validações e notas

Pedido existe e é válido
Produto existe no catálogo
Disponível apenas para pedidos White Label
Pode gerar cobrança adicional após finalizar separação

Exemplo

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

Respostas

204 No Content — Item adicionado com sucesso
404 Not Found — Pedido ou produto não encontrado
409 Conflict — Conflito ao adicionar item
500 Internal Server Error — Erro interno do servidor

Modificar item

Use PATCH /orders/{id}/items/{uniqueId} para ajustar quantidade após a coleta (ex: variação de peso).

Parâmetros de path

Parâmetro	Tipo	Descrição
`id`	`string` (UUID)	ID do pedido
`uniqueId`	`string` (UUID)	ID único do item

Corpo da requisição

Campo	Tipo	Descrição
`quantity`	`number`	Nova quantidade de unidades

Validações e notas

Pedido existe e é válido
Item não faz parte de combo
Quantidade válida
Pode gerar cobrança adicional ou estorno após finalizar separação

Exemplo

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 SEU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 3
  }'

Respostas

204 No Content — Item modificado com sucesso
404 Not Found — Pedido ou item não encontrado
409 Conflict — Conflito ao modificar item
500 Internal Server Error — Erro interno do servidor

Substituir item

Use POST /orders/{id}/items/{uniqueId}/replace para trocar um produto indisponível por uma alternativa.

Parâmetros de path

Parâmetro	Tipo	Descrição
`id`	`string` (UUID)	ID do pedido
`uniqueId`	`string` (UUID)	ID único do item a substituir

Corpo da requisição

Campo	Tipo	Descrição
`quantity`	`number`	Quantidade de unidades do novo produto
`ean`	`string`	Código EAN do novo produto

Validações e notas

Pedido existe e é válido
Produto substituto existe no catálogo
Respeita regras de valor conforme método de pagamento
Pode gerar cobrança adicional após finalizar separação

Exemplo

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 SEU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 2,
    "ean": "0987654321"
  }'

Respostas

204 No Content — Item substituído com sucesso
404 Not Found — Pedido ou item não encontrado
409 Conflict — Conflito ao substituir item
500 Internal Server Error — Erro interno do servidor

Remover item

Use DELETE /orders/{id}/items/{uniqueId} para remover itens indisponíveis ou em ruptura de estoque.

Parâmetros de path

Parâmetro	Tipo	Descrição
`id`	`string` (UUID)	ID do pedido
`uniqueId`	`string` (UUID)	ID único do item a remover

Validações e notas

Pedido existe e é válido
Item não faz parte de combo
Se for combo, todos os itens são removidos
Pode gerar estorno após finalizar separação

Exemplo

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 SEU_TOKEN_JWT"

Respostas

204 No Content — Item removido com sucesso
404 Not Found — Pedido ou item não encontrado
409 Conflict — Conflito ao remover item
500 Internal Server Error — Erro interno do servidor

Iniciar separação

Use POST /orders/{id}/startSeparation ao começar o processo de coleta dos itens do pedido.

Parâmetros de path

Parâmetro	Tipo	Descrição
`id`	`string` (UUID)	ID do pedido

Validações e notas

Pedido existe e é válido
Pedido não foi cancelado
O pedido pode sofrer alterações antes da separação iniciar (evento ORDER_PATCHED). Se receber este evento, faça uma nova GET no pedido para obter as informações atualizadas.

Exemplo

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

Respostas

204 No Content — Separação iniciada com sucesso
404 Not Found — Pedido não encontrado
409 Conflict — Conflito ao iniciar separação
500 Internal Server Error — Erro interno do servidor

Finalizar separação

Use POST /orders/{id}/endSeparation após concluir a coleta e aplicar todas as edições necessárias.

Parâmetros de path

Parâmetro	Tipo	Descrição
`id`	`string` (UUID)	ID do pedido

Validações e notas

Pedido existe e é válido
Separação foi iniciada
Todas as edições são válidas
Ao finalizar, valida regras de pagamento, permissão de cobranças adicionais e calcula preços
Sempre consulte o pedido após finalizar para confirmar que todas as mudanças foram aplicadas

Exemplo

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

Respostas

204 No Content — Separação finalizada com sucesso
404 Not Found — Pedido não encontrado
409 Conflict — Conflito ao finalizar separação
500 Internal Server Error — Erro interno do servidor

Esta página foi útil?

Avalie sua experiência no novo Developer portal: