Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Endpoints

Navegue por todos os endpoints do módulo de Order API organizado por funcionalidade. Para operações de negociação pós-entrega, consulte a Plataforma de negociação.

Gerenciamento de pedidos

Endpoints para consultar, confirmar e atualizar o ciclo de vida de pedidos.

Obter detalhes do pedido

Recupere informações completas de um pedido específico.GET https://merchant-api.ifood.com.br/order/v1.0/orders/{id}Parâmetros de caminho

Parâmetro	Tipo	Descrição
`id`	uuid	ID do pedido

Resposta (200 OK)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "CONFIRMED",
  "orderType": "DELIVERY",
  "category": "FOOD",
  "items": [...],
  "scheduling": {...},
  "total": {...}
}

Leia mais: Estrutura completa do pedido

Confirmar pedido

Confirme um pedido recebido. Obrigatório dentro de 8 minutos.POST https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/confirmParâmetros de caminho

Parâmetro	Tipo	Descrição
`id`	uuid	ID do pedido

Resposta (202 Accepted)

{
  "status": "ACCEPTED"
}

Validação: Verifique o resultado no próximo polling — chegará como evento CONFIRMED ou CANCELLATION_REQUEST_FAILED.Leia mais: Fluxo de confirmação

Iniciar preparação

Inicie a preparação do pedido após confirmação.POST https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/startPreparationParâmetros de caminho

Parâmetro	Tipo	Descrição
`id`	uuid	ID do pedido

Resposta (202 Accepted)

{
  "status": "ACCEPTED"
}

Notas importantes:

Para pedidos agendados, respeite preparationStartDateTime
Lojas com "Preparo Inteligente" recebem RECOMMENDED_PREPARATION_START

Para pedidos agendados, respeite preparationStartDateTime. Lojas com Preparo Inteligente recebem o evento RECOMMENDED_PREPARATION_START indicando o momento ideal.

Leia mais: Fluxo de preparação

Notificar pedido pronto

Notifique que o pedido está pronto para retirada ou entrega.Obrigatoriedade:

TAKEOUT e DINE_IN: Obrigatório
DELIVERY: Opcional

POST https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/readyToPickupParâmetros de caminho

Parâmetro	Tipo	Descrição
`id`	uuid	ID do pedido

Resposta (202 Accepted)

{
  "status": "ACCEPTED"
}

Leia mais: Fluxo de notificação de pronto

Despachar pedido

Notifique que o pedido saiu para entrega própria.POST https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/dispatchParâmetros de caminho

Parâmetro	Tipo	Descrição
`id`	uuid	ID do pedido

Body

{
  "deliveredBy": "MERCHANT"
}

Resposta (202 Accepted)

{
  "status": "ACCEPTED"
}

Quando usar: Apenas para entrega própria (DELIVERY com deliveredBy = MERCHANT)Leia mais: Fluxo de despacho

Cancelamento de pedidos

Endpoints para solicitar e gerenciar cancelamentos.

Obter motivos válidos de cancelamento

Recupere os motivos de cancelamento aceitos para um pedido específico.GET https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/cancellationReasonsParâmetros de caminho

Parâmetro	Tipo	Descrição
`id`	uuid	ID do pedido

Resposta (200 OK)

{
  "reasons": [
    {
      "code": "501",
      "description": "Erro no sistema"
    },
    {
      "code": "502",
      "description": "Pedido duplicado"
    }
  ]
}

Códigos comuns:

501 — Sistema
502 — Duplicado
503 — Indisponível
504 — Sem entregador
505 — Cardápio
506 — Fora de área
507 — Fraudulento
508 — Fora de horário
509 — Erro interno
511 — Risco
512 — Abre depois

Leia mais: Fluxo de cancelamento

Solicitar cancelamento

Solicite o cancelamento de um pedido com motivo válido.POST https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/requestCancellationParâmetros de caminho

Parâmetro	Tipo	Descrição
`id`	uuid	ID do pedido

Body

{
  "reason": "501"
}

Resposta (202 Accepted)

{
  "status": "ACCEPTED"
}

Validação: Verifique o resultado no próximo polling:

CANCELLED — Cancelamento aceito
CANCELLATION_REQUEST_FAILED — Cancelamento rejeitado

Cancelamentos excessivos geram penalidades e podem resultar em fechamento temporário da loja.

Rastreamento e validação

Endpoints para rastrear entregas e validar códigos de coleta.

Rastrear entregador

Obtenha a localização em tempo real do entregador iFood. Disponível apenas após receber o evento ASSIGN_DRIVER.GET https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/trackingLeia mais: Rastreamento de entregaParâmetros de caminho

Parâmetro	Tipo	Descrição
`id`	uuid	ID do pedido

Resposta (200 OK)

{
  "latitude": -23.5505,
  "longitude": -46.6333,
  "expectedDelivery": "2024-04-25T18:30:00Z",
  "pickupEtaStart": 120,
  "deliveryEtaEnd": 600,
  "trackDate": "2024-04-25T18:15:00Z"
}

Campos retornados

Campo	Tipo	Descrição
`latitude`	float	Latitude atual
`longitude`	float	Longitude atual
`expectedDelivery`	datetime	ETA estimada de entrega
`pickupEtaStart`	int	Segundos até coleta
`deliveryEtaEnd`	int	Segundos até entrega
`trackDate`	datetime	Timestamp da consulta

Limitações:

Apenas para deliveredBy = "IFOOD"
Máximo uma requisição a cada 30 segundos
Pode retornar 404 antes de estar disponível

Leia mais: Rastreamento de entrega

Validar código de coleta

Valide o código de coleta fornecido pelo entregador.POST https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/validatePickupCodeParâmetros de caminho

Parâmetro	Tipo	Descrição
`id`	uuid	ID do pedido

Body

{
  "code": "123456"
}

Resposta (200 OK)

{
  "valid": true
}

Validação: Compare o código contra pickupCode nos detalhes do pedido.Disponibilidade: Apenas quando habilitado e para deliveredBy = "IFOOD".Leia mais: Validação de coleta

Confirmar entrega ou retirada

Valide e confirme a entrega ou retirada do pedido.POST https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/verifyDeliveryCodeParâmetros de caminho

Parâmetro	Tipo	Descrição
`id`	uuid	ID do pedido

Body

{
  "code": "654321"
}

Resposta (200 OK)

{
  "valid": true
}

Casos de uso:

Entrega iFood: Entregador confirma via app (automático)
Entrega própria: Use o localizador (phone.localizer) da comanda

Leia mais: Confirmação de entrega

Gerenciamento de eventos

Endpoints para consumir e confirmar eventos de pedidos.

Consumir eventos (Polling)

Consulte eventos novos. Recomendado a cada 30 segundos.GET https://merchant-api.ifood.com.br/order/v1.0/orders:pollingParâmetros de query

Parâmetro	Tipo	Descrição
`limit`	int	Máximo de eventos (padrão: 100)

Resposta (200 OK)

{
  "events": [
    {
      "id": "evt_123",
      "code": "CONFIRMED",
      "fullCode": "ORDER_CONFIRMED",
      "orderId": "ord_456",
      "createdAt": "2024-04-25T18:00:00Z",
      "metadata": {...}
    }
  ]
}

Próximos passos: Processe cada evento e confirme a leitura com /orders:acknowledgment.Leia mais: Consumo de eventos

Confirmar leitura de eventos

Confirme que processou eventos com sucesso.POST https://merchant-api.ifood.com.br/order/v1.0/orders:acknowledgmentBody

{
  "acknowledgedEventIds": [
    "evt_123",
    "evt_124"
  ]
}

Resposta (202 Accepted)

{
  "status": "ACCEPTED"
}

Importante: Confirme apenas eventos processados com sucesso. Eventos não confirmados serão retornados no próximo polling.Leia mais: Confirmação de eventos

Busca por caso de uso

Não sabe por onde começar? Use este índice:

Cenário	Endpoints	Guia
Receber novo pedido	`/orders:polling`	Workflow completo
Confirmar e processar	`POST /confirm`	Fluxo de confirmação
Preparar e notificar	`POST /startPreparation`, `POST /readyToPickup`	Fluxo de preparação
Rastrear entrega	`GET /tracking`	Rastreamento em tempo real
Cancelar pedido	`GET /cancellationReasons`, `POST /requestCancellation`	Fluxo de cancelamento
Resolver disputa	Ver Plataforma de negociação	Guia de implementação