Boas práticas com as APIs do iFood

No dia-a-dia, muitos parceiros nos pedem recomendações quando estão desenvolvendo a integração com as nossas APIs. Muitos acabam compartilhando também vários cases legais. Compilamos aqui nesse artigo algumas dessas dicas enviadas tanto pelos desenvolvedores que utilizam nossas APIs quanto pelos desenvolvedores internos que constróem essas APIs.

Dicas Gerais

• Conexão com internet: Caso ocorra timeout em alguma requisição, verifique automaticamente a conexão com a internet e em caso de problema, notifique o usuário do seu aplicativo. Uma forma simples de testar a conexão do usuário é fazendo um ping em algum provedor de alta disponibilidade (Ex: Google).
• Paralelize o processamento (fairness): Se o seu aplicativo recebe pedidos e eventos de vários merchants, paralelize e isole o processamento de cada merchant/usuário de forma a evitar que qualquer volume inesperado de um merchant ou algum erro impacte outros usuários.
• Erro de servidor 5XX: Sempre que obtiver um erro 5XX (500, 502, 503, 504, etc) tente novamente em alguns instantes e caso o problema se prolongue por mais de 5 minutos, acione nosso time de suporte.
• Tolerância a falhas: Complementando o ponto acima, é importante desenvolver uma aplicação que seja resiliente e tolerante a falhas. Para poder identificar problemas recorrentes, uma sugestão seria criar alertas e monitoramentos das funcionalidades do sistema.
• Mapeamento de Campos: Na medida do possível, sua aplicação deve suportar novas enumerações (enums) que acabam sendo criados e enviados conforme o negócio evolui, então evite atrelar a sua aplicação a apenas enums existentes para evitar a perda de pedidos. É claro que algo provavelmente precisará ser feito para que o novo enum seja utilizado corretamente, mas, por exemplo, é melhor descartar um evento com enum desconhecido do que fazer com que a aplicação quebre por conta dele.
• Rate limit: todos os endpoints possuem uma quantidade máxima de requisições em um determinado período de tempo. Caso exceda o limite de requisições, o aplicativo pode ser bloqueado temporariamente.

Autenticação

• Evite solicitar um novo token desnecessariamente. Todo token tem um tempo de expiração. Você só precisa obter um novo token quando o atual estiver prestes a expirar.
• Sempre que receber um erro 401 em algum endpoint, verifique se o token usado não está expirado. Nesse caso, solicite um novo token.
• Sempre que receber um erro 403 em algum endpoint, verifique se você está requisitando dados de um merchant autorizado (verifique se não há solicitações de acesso pendentes).

Pedidos

• Faça polling regularmente a cada 30 segundos para não perder nenhum pedido. Isso garante que o merchant fique aberto na plataforma.
• Filtros no polling: Utilize o header x-polling-merchants sempre que precisar filtrar eventos de um ou mais merchants. Também é possível filtrar os eventos que deseja receber por tipo e por grupo.
• Credenciais com muitas lojas: Se o seu aplicativo é centralizado (client_credential) e esse aplicativo possui acesso a mais de 500 merchants, é obrigatório utilizar o header x-polling-merchants pois o limite no polling é de 500 merchants. Esse limite existe para dar um período para a integração se adaptar à utilização do header. Assim que o aplicativo passar de 100 merchants já considere utilizar o header e não deixar para quando tiver mais do que 500 merchants. Lembre-se que, como desenvolvedor, você provavelmente não terá controle na velocidade com que merchants estarão utilizando sua plataforma.
• Ao receber novos eventos através do polling, garanta que esse evento foi persistido corretamente pela sua aplicação e somente depois envie o acknowledgment desses eventos, pois, caso ocorra alguma falha no momento de persistir o evento, você o receberá novamente na request seguinte de polling caso ainda não tenha enviado o ack para esse evento;
• Eventos e Pedidos duplicados: Garanta a unicidade dos pedidos e eventos através do id único. É possível que a API retorne um mesmo pedido ou evento mais de uma vez.
• Eventos não tratados: Caso seu aplicativo receba um evento desconhecido, envie ack para esse evento e descarte-o mas continue processando os eventos seguintes. Se não enviar o ack, ficará recebendo o evento novamente nos próximos polling e esse looping pode prejudicar o desempenho da sua aplicação. É importante ter logs dessas ocorrências para que você possa identificar e tratar esses novos eventos.
• Certifique-se de que seu aplicativo consultou os detalhes do pedido antes de confirmar ou cancelá-lo. A confirmação ou cancelamento só é permitida depois de consultar os detalhes do pedido. Repare que a confirmação retorna 202, e não 200, o que indica que a confirmação é assíncrona, e que o pedido pode não ter sido realmente confirmado. O pedido só será efetivamente confirmado se o aplicativo obtiver os detalhes do pedido. Um pedido só é efetivamente confirmado se o evento de confirmação for retornado no polling. Isso vale para qualquer evento. Portanto, não deixe seu aplicativo travado esperando algum evento.
• Não consulte os detalhes de um pedido mais de uma vez. Os detalhes do pedido são imutáveis, não havendo portanto necessidade de consultar mais de uma vez. Caso isso ocorra existe o risco de ser bloqueado por rate limit.
• Não consulte nem tente atualizar o status de um pedido muito antigo. Os pedidos são mantidos na API somente por algumas horas após o horário de entrega do pedido (8hrs). A plataforma iFood não deve ser considerada um backup de dados de seu aplicativo. É importante que você persista esses dados recebidos na sua aplicação.

E você? Já desenvolveu alguma integração com as nossas APIs? Mande aí suas dicas nos comentários pra gente compartilhar com todos os desenvolvedores.