Docs Primeiros Passos
Integração iFood Groceries Merchant-API
Olá Integrador,A Merchant-API é a API pública disponibilizada para os parceiros integrarem seus sistemas com a plataforma iFood. Já amplamente utilizada pela unidade de negócios de Restaurantes, ela está agora disponível para as demais unidades de negócio do iFood, possibilitando a gestão de produtos e de pedidos de Groceries nas plataformas iFood Marketplace, iFood SHOP e White Label.Esta API substitui a antiga API de Mercado, que será descontinuada em breve. O objetivo é termos um modelo de integração unificado para todos os negócios do iFood.
Estrutura modular
A Merchant API é estruturada em módulos que permitem automatizar diversos processos, entre os principais destacamos a atualização de produtos e o consumo de dados de pedidos.Esta estrutura possibilita um controle de acesso mais granular dos recursos de diferentes contextos (módulos), permitindo restringir o escopo das aplicações que se integram à plataforma iFood. Com isso, é possível autorizar uma aplicação para integrar apenas produtos, enquanto os pedidos sejam integrados por outra aplicação.Escopo de Integração
Elaboramos um guia para orientar os desenvolvedores sobre quais módulos são necessários conforme o escopo de integração, tornando o processo de desenvolvimento mais claro e objetivo. São eles:- Produtos: Inclui módulos para gestão de produtos.
- Produtos e Pedidos (com App Separador): Inclui módulos para gestão de produtos e consumo de pedidos para uso com o App Separador.
- Produtos e Pedidos (sem App Separador): Inclui módulos para gestão de produtos e gestão completa dos pedidos para uso com ferramenta própria ou terceira.
- Pedidos (com App Separador): Inclui módulos apenas para consumo de pedidos para uso com o App Separador.
- Pedidos (sem App Separador): Inclui módulos para gestão completa de pedidos para uso com ferramenta própria ou terceira.
| Escopo de Integração | Módulos Necessários |
|---|---|
| 1 | Authentication, Merchant, Item e Promotion |
| 2 | Authentication, Merchant, Item, Promotion, Order e Events |
| 3 | Authentication, Merchant, Item, Promotion, Order, Events e Picking |
| 4 | Authentication, Merchant, Order e Events |
| 5 | Authentication, Merchant, Order, Events e Picking |
Descrição dos módulos
Módulos Comuns
Authentication Recurso necessário para realizar requisições em qualquer módulo. Com ele é possível gerar o token de acesso a partir das credenciais clientId e clientSecret utilizando os fluxos de credencial por aplicativo ou código de autorizaçãoMerchant (opcional) Disponibiliza recursos para listar as lojas com permissão nas credenciais, obter detalhes de loja e outras ações como abertura, fechamento e status. Tanto na integração de produtos como de pedidos, este recurso se faz necessário para conhecer o ID das lojas que a aplicação tem acesso.Integração de Produtos
Item Disponibiliza recursos para atualização de produtos nas plataformas iFood Marketplace, iFood Shop e White Label, como preço, estoque, adições de novos produtos, inativações, entre outros.Promotion Disponibiliza recursos para atualização de mecânicas promocionais em produtos das plataformas iFood Marketplace, desde as mais simples como "De x Por" e Atacarejo, como as complexas, "Leve X Pague Y", Porcentagem, entre outras.Atenção - Promoções
Atualmente no módulo Item existem funcionalidades para atualização de promoções "De x Por" e Atacarejo que podem ser aplicadas aos produtos, mas estas serão removidas deste módulo muito em breve, ficando os recursos disponíveis apenas no módulo Promotion. É recomendada a utilização do módulo Promotion para atualização de promoções, sejam elas simples ou complexas.
Integração de Pedidos
Order Disponibiliza recursos para leitura dos detalhes dos pedidos emitidos nas plataformas iFood Marketplace, iFood SHOP e White Label.Events Disponibiliza recursos de polling e webhook para o consumo de eventos referentes a atualização de status e outras informações relacionadas ao pedido em cada etapa.Picking Disponibiliza recursos para a gestão completa do pedido, como avanço de status de separação e edição de itens. Este módulo é destinado a integradores previamente mapeados que não utilizam a ferramenta oficial App Separador.Atenção
O módulo PICKING é exclusivo para integração de pedidos quando o integrador parceiro não utiliza o App Separador, que é a ferramenta de gestão de pedidos do iFood para Groceries.
Passo a Passo para Integrar
Passo 1 - Cadastro.
Acesse o portal Developer iFood e clique no botão Cadastrar.
O perfil será solicitado após inserido os dados iniciais, selecione a opção "Perfil Profissional".
Ao selecionar o "Perfil Profissional" será solicitado o preenchimento dos dados da empresa. Somente CNPJs com CNAEs correspondentes a empresas de tecnologia tem permissão para cadastro.
Atenção
Caso a área técnica de sua rede seja a responsável pelo desenvolvimento do processo de integração e o CNPJ da loja não possua CNAE válido, deve ser feita uma solicitação de liberação através da aba Suporte no portal informando os dados de cadastro. A partir da abertura do chamado, a área responsável fará a liberação do cadastro que após concluído deve ser informado novamente ao time para retorno do bloqueio.
Por fim, conclua o cadastro antes de seguir para o passo 2.Passo 2 - Acesso ao ambiente de testes e credenciais
Logo após o cadastro você terá acesso a área do Desenvolvedor com alguns recurso disponíveis no menu lateral. Os principais recursos estão descritos abaixo.Menu Usuários
Fornece recursos para adicionar ou remover usuários no ambiente de desenvolvimento.
Menu Meus Apps
Este é o principal recurso disponível neste ambiente, pois fornece acesso às credenciais com permissão a todos os módulos na Merchant-API e permissão em ao menos uma loja teste. Os recursos neste ambiente são disponibilizados através do conceito de Aplicativo, com a disponibilização logo após o cadastro do Aplicativo Centralizado e Aplicativo Distribuído.
O Aplicativo Centralizado possibilita o acesso a múltiplas lojas com a mesma credencial. Este modelo permite o uso de Webhook para recebimento de eventos. Para mais detalhes, assista ao vídeo explicando o modelo.O Aplicativo Distribuído possibilita autenticações por loja e o Webhook não está disponível nesta modalidade. Para mais detalhes, assista ao vídeo explicando o modelo.Observação
Sugerimos que o processo de desenvolvimento utilize os aplicativos de testes disponíveis. No momento da homologação será solicitada a criação de um aplicativo oficial, onde será configurado os detalhes do aplicativo, como módulos e finalidade para visualização dos lojistas. Este aplicativo ficará disponível somente após a homologação para habilitar as lojas da plataforma.
Credenciais de acesso
As chaves clientId e clientSecret necessárias para autenticação na Merchant-API ficam disponíveis na aba credenciais ao selecionar os aplicativos de teste. Todos os detalhes de como executar a autenticação no App centralizado e distribuído estão descritas na documentação Authentication.Permissões
Na aba Permissões está listada a loja teste com permissão no aplicativo. O ID da loja, que é a chave para realizar as requisições por loja, está descrito na opção Ver Detalhes.WebHook
Opção disponível apenas em aplicativos do tipo Centralizado. Nesta aba é possível ativar e configurar o recurso de Webhook que permitirá o disparo de eventos relacionados aos status dos pedidos para os serviços dos parceiros. Webhook DOCMenu Testes
Disponibiliza acesso a recursos que permitem gerar pedidos de teste nas lojas testes disponíveis no ambiente. Para mais detalhes de como gerar pedidos de testes, acesse Gerar pedidos teste.Passo 3 - Desenvolvimento da aplicação
Token de acesso
Para realizar as requisições na API, obtenha o token de acesso através do endpoint de autenticação.Consumo de eventos
Consuma os eventos dos pedidos a partir do polling ou webhook.Filtros: Ao usar filtros, os eventos fora do escopo são removidos (Auto-Acknowledgment). Eventos desaparecem do polling após 8 horas. Para redes grandes, useheader x-polling-merchants para filtrar até 500 lojas por vez, separando requisições de 100 em 100 para mais lojas.O consumo de eventos deve atender aos critérios de homologação definidos para polling ou webhook, conforme o modelo escolhido.Detalhe do pedido
O detalhe do pedido de Groceries é disponibilizado através do endpoint/orders/{id}/virtual-bag.Considerações Importantes- Valores monetários são expressos em centavos, divida por 100 para o valor real.
- Consuma dados apenas dos itens disponíveis, excluindo rupturados.
- Valores integrados são listados nos itens, já os subsídios do iFood em Benefícios.
- Mantenha visibilidade do campo Benefícios e seu funcionamento.
- Certifique-se de consumir a plataforma utilizada corretamente.
- Em "ITEMS" virá o preço cheio do item, sem desconto.
- O Desconto virá separado em "BENEFITS". Saiba Mais
- Caso queira saber o preço com desconto, necessário efetuar subtração entre eles.
Passo 4 - Processo de homologação
Todos os módulos possuem recursos detalhados e pontos de atenção que devem ser considerados e ficam descritos nos Critérios de Homologação.Após efetuado o desenvolvimento, os integradores devem solicitar via portal através da aba Suporte uma agenda para validação e efetivação do processo. Nesta agenda serão validados os fluxos desenvolvidos a partir dos módulos citados neste documento e utilizando a loja de teste.Caso aprovado, será acompanhada a criação de um aplicativo novo dentro do ambiente com os módulos e detalhes desenvolvidos. Este aplicativo será homologado e a partir desta alteração o integrador terá autonomia para habilitar o aplicativo em lojas de produção.IMPORTANTE
Para conectar o aplicativo desenvolvido, a solicitação de permissão deve ser aceita no portal do parceiro por um usuário gerencial, preferencialmente com permissão de "Dono". Se esse usuário for desativado ou excluído, a integração será interrompida e será necessário reenviar a solicitação.