Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Pedidos na plataforma iFood

Use esta documentação para solicitar entregadores iFood para pedidos que já existem na plataforma com orderId. Este fluxo é ideal para usar logística iFood como backup ou para expandir sua capacidade de entrega.

Como funciona

O fluxo consiste em três etapas:

Verificar disponibilidade - Confirme que a entrega está disponível para o endereço
Solicitar entregador - Aloque um entregador iFood para o pedido
Cancelar (opcional) - Cancele a solicitação antes do aceite do entregador

1. Verificar disponibilidade

Antes de solicitar um entregador, verifique se a entrega está disponível para o pedido. Este endpoint retorna a cotação com preço e tempo estimado.

Endpoint

GET /shipping/v1.0/orders/{orderId}/deliveryAvailabilities

Parâmetros

Parâmetro	Localização	Tipo	Obrigatório	Descrição
`orderId`	path	uuid	Sim	ID do pedido existente na plataforma

Exemplo de requisição

curl -X GET "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/deliveryAvailabilities" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Resposta `200 OK`

A cotação foi obtida com sucesso. Use o id como quoteId na próxima etapa. A cotação é válida por ~24 horas.

Campos da resposta

Campo	Tipo	Descrição
`id`	uuid	ID da cotação (use como `quoteId` na próxima etapa)
`expirationAt`	datetime	Validade da cotação em UTC
`createdAt`	datetime	Data de criação da cotação em UTC
`distance`	integer	Distância de entrega em metros
`quote.grossValue`	decimal	Valor bruto em reais
`quote.discount`	decimal	Desconto em reais
`quote.netValue`	decimal	Valor final (grossValue - discount)
`deliveryTime.min`	integer	Tempo mínimo estimado em segundos
`deliveryTime.max`	integer	Tempo máximo estimado em segundos
`hasPaymentMethods`	boolean	Indica se há formas de pagamento
`paymentMethods[].id`	uuid	ID do método de pagamento
`paymentMethods[].brand`	string	Bandeira do cartão
`paymentMethods[].liability`	string	Responsável pelo pagamento
`paymentMethods[].paymentType`	string	Tipo de pagamento (ex: OFFLINE)
`paymentMethods[].method`	string	CREDIT ou DEBIT

Exemplo de resposta

{
  "id": "57cd1046-2e06-446f-a2dd-18a518212c3c",
  "expirationAt": "2023-08-18T19:49:06Z",
  "createdAt": "2023-08-17T19:49:06Z",
  "distance": 3000,
  "quote": {
    "grossValue": 7.99,
    "discount": 0,
    "netValue": 7.99
  },
  "deliveryTime": {
    "min": 1200,
    "max": 1800
  },
  "hasPaymentMethods": true,
  "paymentMethods": [
    {
      "id": "21c65a8c-f29e-463f-b0bd-240edeb593c4",
      "brand": "Visa",
      "liability": "IFOOD",
      "paymentType": "OFFLINE",
      "method": "CREDIT"
    }
  ]
}

Neste exemplo: distância de 3km, preço de R$ 7,99, tempo estimado de 20-30 minutos, e 1 método de pagamento disponível.

Erros `400 Bad Request`

A entrega não está disponível. Verifique o código de erro para entender o motivo e a ação recomendada.

Para soluções detalhadas de cada erro, consulte Boas práticas e troubleshooting.

Códigos de erro

Código	Descrição	Ação
`BadRequest`	Problema na requisição	Verifique se o `orderId` está no formato correto
`BadRequestMerchant`	Sua loja está indisponível	Verifique o status da loja no painel
`DeliveryDistanceTooHigh`	Endereço a mais de ~10km	Confirme o endereço com o cliente
`OffOpeningHours`	Fora do horário de operação	Tente novamente no horário comercial
`OriginNotFound`	Loja não encontrada	Registre sua loja nas áreas iFood
`ServiceAreaMismatch`	Endereço fora da cobertura	Confirme se a região tem entrega iFood
`HighDemand`	Logística saturada	Tente novamente em alguns minutos
`MerchantStatusAvailability`	Sua conta tem pendências	Contate o suporte
`InvalidPaymentMethods`	Forma de pagamento não suportada	Use outro método
`SaturatedOfflinePayment`	Pagamento na entrega indisponível	Altere para outro método
`NRELimitExceeded`	Limite de entregadores atingido	Aguarde conclusão de entregas

Exemplo de erro

{
  "code": "DeliveryDistanceTooHigh",
  "message": "Sob Demanda indisponível: o endereço da entrega está a mais de 10 km da sua loja.",
  "details": ["Delivery distance too high"]
}

Erro `500 Internal Server Error`

Erro temporário no servidor. Implemente retry automático com backoff exponencial. Após 3-5 tentativas, registre em log e notifique o suporte.

{
  "code": "InternalServerError",
  "message": "Ops. Houve uma falha. Tente novamente em alguns instantes.",
  "details": ["Internal server error"]
}

2. Solicitar entregador

Com a cotação obtida, solicite a alocação de um entregador iFood. Este é uma operação assíncrona que retorna 202 Accepted imediatamente e aloca o entregador em background.

Operação assíncrona: A resposta 202 Accepted indica apenas que a requisição foi recebida. Monitore os eventos para saber o resultado final (sucesso ou falha).

Endpoint

POST /shipping/v1.0/orders/{orderId}/requestDriver

Parâmetros

Parâmetro	Localização	Tipo	Obrigatório	Descrição
`orderId`	path	uuid	Sim	ID do pedido existente na plataforma
`quoteId`	body	uuid	Sim	ID da cotação obtida na etapa anterior (válida por ~24h)

Exemplo de requisição

curl -X POST "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/requestDriver" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "57cd1046-2e06-446f-a2dd-18a518212c3c"
  }'

Body:

{
  "quoteId": "57cd1046-2e06-446f-a2dd-18a518212c3c"
}

Resposta `202 Accepted`

A requisição foi registrada com sucesso. Monitore os eventos para obter o resultado:

Evento	Significado
`REQUEST_DRIVER`	Requisição registrada
`REQUEST_DRIVER_SUCCESS`	Entregador alocado com sucesso
`REQUEST_DRIVER_FAILED`	Falha na alocação

O processamento é assíncrono e pode levar minutos.

Erros `400 Bad Request`

Requisição inválida ou serviço indisponível.

Para soluções detalhadas de cada erro, consulte Boas práticas e troubleshooting.

Código	Descrição	Ação
`BadRequest`	Dados inválidos	Valide `orderId` e `quoteId`
`BadRequestCustomer`	Cliente indisponível	Verifique dados do cliente
`BadRequestMerchant`	Sua loja está indisponível	Verifique status da loja
`DeliveryDistanceTooHigh`	Endereço fora da cobertura	Confirme endereço com o cliente
`HighDemand`	Logística saturada	Tente novamente em minutos
`MerchantEasyDeliveryDisabled`	Serviço não habilitado	Ative no painel
`OffOpeningHours`	Fora do horário	Tente durante horário comercial
`OriginNotFound`	Loja não localizada	Registre sua loja nas áreas iFood
`ServiceAreaMismatch`	Endereço fora da área	Verifique cobertura iFood
`MerchantStatusAvailability`	Sua conta tem restrições	Contate o suporte
`InvalidPaymentMethods`	Forma de pagamento não suportada	Use outro método
`SaturatedOfflinePayment`	Pagamento na entrega indisponível	Altere para outro método
`NRELimitExceeded`	Limite de entregadores atingido	Aguarde conclusão de entregas

Exemplo de erro

{
  "code": "HighDemand",
  "message": "A logística iFood está temporariamente indisponível. Tente novamente mais tarde.",
  "details": ["High demand"]
}

Para erros transientes como HighDemand ou OffOpeningHours, implemente retry automático com backoff exponencial.

3. Cancelar solicitação

Cancele a alocação de entregador sem cancelar o pedido em si. Use este endpoint quando a preparação foi mais rápida ou lenta que o esperado.

Restrições críticas:

Só é possível cancelar antes do aceite do entregador
Após o entregador aceitar, siga as regras de Cancelamento de pedido
Sem taxa para cancelamentos antes do aceite
A ação é permanente e irreversível

Endpoint

POST /shipping/v1.0/orders/{orderId}/cancelRequestDriver

Parâmetros

Parâmetro	Localização	Tipo	Obrigatório	Descrição
`orderId`	path	uuid	Sim	ID do pedido a cancelar entrega

Exemplo de requisição

curl -X POST "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/cancelRequestDriver" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Resposta `202 Accepted`

A solicitação de cancelamento foi registrada. Monitore os eventos para confirmação:

Evento	Significado
`DELIVERY_CANCELLATION_REQUESTED`	Cancelamento solicitado
`DELIVERY_CANCELLATION_REQUEST_ACCEPTED`	Cancelamento concluído, sem taxa
`DELIVERY_CANCELLATION_REQUEST_REJECTED`	Entregador já aceitou

Para mais detalhes, consulte Eventos de entrega.

Erros `400 Bad Request`

Requisição inválida. Verifique se o orderId é um UUID válido.

{
  "code": "BadRequest",
  "message": "Houve um problema ao solicitar o cancelamento. Verifique as informações enviadas.",
  "details": ["Campo 'OrderID' deve estar no formato uuid."]
}

Erro `500 Internal Server Error`

Erro temporário no servidor. Implemente retry automático com backoff exponencial. Após 3-5 tentativas, registre em log e notifique o suporte.

{
  "code": "InternalServerError",
  "message": "Ops. Houve uma falha. Tente novamente em alguns instantes.",
  "details": ["Internal server error"]
}

Próximos passos

Implemente polling de eventos para monitorar status em tempo real
Consulte a guia de rastreamento para informações de localização
Explore a referência completa de endpoints

Esta página foi útil?

Avalie sua experiência no novo Developer portal:

Pedidos na plataforma iFood

Como funciona

1. Verificar disponibilidade

Endpoint

Parâmetros

Exemplo de requisição

Resposta 200 OK

Campos da resposta

Exemplo de resposta

Erros 400 Bad Request

Códigos de erro

Exemplo de erro

Erro 500 Internal Server Error

2. Solicitar entregador

Endpoint

Parâmetros

Exemplo de requisição

Resposta 202 Accepted

Erros 400 Bad Request

Exemplo de erro

3. Cancelar solicitação

Endpoint

Parâmetros

Exemplo de requisição

Resposta 202 Accepted

Erros 400 Bad Request

Erro 500 Internal Server Error

Próximos passos

Resposta `200 OK`

Erros `400 Bad Request`

Erro `500 Internal Server Error`

Resposta `202 Accepted`

Erros `400 Bad Request`

Resposta `202 Accepted`

Erros `400 Bad Request`

Erro `500 Internal Server Error`