Visão geral

Este guia apresenta práticas recomendadas para integrar com as APIs do iFood. Siga estas recomendações para criar integrações robustas, eficientes e seguras.

Práticas gerais

Conexão e tolerância a falhas

Timeout: Teste a concectividade automaticamente quando ocorrer timeout. Notifique o usuário sobre problemas de conexão.
Erros 5XX: Implemente retry automático para erros de servidor (500, 502, 503, 504). Se o problema persistir por mais de 5 minutos, contate o suporte.
Monitoramento: Configure alertas para identificar problemas recorrentes.

Processamento

Paralelização: Processe cada merchant isoladamente para evitar que falhas ou alto volume afetem outros usuários.
Campos desconhecidos: Configure sua aplicação para aceitar novos enums sem quebrar. Descarte eventos com enums desconhecidos em vez de interromper o processamento.

Rate Limit

Todos os endpoints têm limites de requisições por período. Respeite esses limites para evitar bloqueios temporários.

Autenticação

Gerenciamento de token

Reutilize tokens: Solicite novo token apenas quando o atual estiver prestes a expirar.
Erro 401: Verifique se o token expirou. Se sim, solicite um novo token.
Erro 403: Confirme se você tem acesso autorizado ao merchant e se não há solicitações pendentes.

Pedidos

Polling

Frequência: Execute polling a cada 30 segundos para manter o merchant ativo na plataforma.
Filtros: Use o header x-polling-merchants para filtrar eventos por merchant, tipo ou grupo.
Limites de merchants: Para aplicações com mais de 500 merchants, use obrigatoriamente o header x-polling-merchants. Implemente o header quando atingir 100 merchants.

Processamento de eventos

Frequência: Persista eventos antes de enviar acknowledgment. Se a persistência falhar, você receberá o evento novamente no próximo polling.
Duplicação: Use o ID único para garantir que pedidos e eventos não sejam processados mais de uma vez.
Eventos desconhecidos: Envie acknowledgment e descarte eventos desconhecidos. Continue processando eventos subsequentes.

Operações com pedidos

Consulta obrigatória: Consulte os detalhes do pedido antes de confirmar ou cancelar.
Confirmação assíncrona: A confirmação restorna status 202 (assíncrono). O pedido só é efetivamente confirmado quando o evento de confirmação aparece no polling.
Uma consulta apenas: Consulte os detalhes do pedido apenas uma vez. Os detalhes são imutáveis.
Pedido antigos: Não consulte nem atualize pedidos após 8 horas do horário de entrega. A API não é um backup de dados.

Webhook

Para garantir o recebimento confiável de eventos e notificações em tempo real, utilize webhooks seguindo as recomendações de segurança, validação e resiliência. Confira o guia completo de melhores práticas para webhooks neste link.

Esta página foi útil?

Avalie sua experiência no novo Developer portal:

Nesta página