logo
logo

Docs Merchant-API

Nova Integração iFood Groceries Merchant-API

Olá Integrador,

Temos o prazer de anunciar um novo plano de ação que está sendo liderado pelo time de Integrações iFood Groceries, em colaboração com todos os integradores homologados em nosso processo atual.

Objetivo do Plano

Nosso objetivo é unificar todos os modelos de integração disponibilizados pelo iFood em uma única tecnologia: a API intitulada Merchant-API.

Esta API, já amplamente utilizada pela unidade de negócios de Restaurantes, foi adaptada para atender também as demais unidades de negócio do iFood a partir de módulos que permitem atualização de catálogo e consumo de pedidos nas plataformas iFood Marketplace, iFood SHOP e White Label .

Estado Atual da Integração Groceries

Atualmente, utilizamos duas tecnologias oficiais para a integração de produtos e consumo de pedidos nas plataformas iFood Marketplace, iFood SHOP e White Label:

  • SMI (SiteMercado integrador): Aplicativo instalado no ambiente do parceiro que permite o consumo da base de dados de produtos via consultas no banco dados ou leitura de arquivos (.csv) e a geração de arquivos em diversos formatos (.txt, .csv, .xml) para o consumo de pedidos. Este modelo está descontinuado para novas implementações e será mantido apenas para o legado até a migração completa. Referências ( Produtos banco; Produtos arquivo; Pedidos banco; Pedidos arquivo)

  • Service.API: API oficial utilizada atualmente em Groceries que permite o envio de atualizações de produtos e consumo de pedidos. Referências (Produto; Pedidos)

Novo formato de Integração Groceries

O novo formato de Integração proposto, como dito anteriormente, será através do uso da Merchant-API, esta API é estruturada em módulos que permitem automatizar diversos processos, entre os principais destacamos os novos módulos para atualização de catálogo e consumo de dados dos pedidos que atenderá as plataformas iFood Marketplace, iFood SHOP e White Label, estes módulos já estão publicados no portal Developer iFood e devem substituir as integrações atuais.

CheckList de Desenvolvimento por tipo de integração

Para facilitar o entendimento das integradoras, elaboramos um checklist detalhado dos módulos a serem desenvolvidos, conforme o tipo de integração necessário. Este guia informa claramente quais módulos devem ser desenvolvidos dependendo da integração escolhida:

Tipos de Integração 1 - Integração de Produtos: Somente módulos globais e relacionados a produtos. 2 - Integração de Produtos e Pedidos (com App Separador): Inclui módulos globais,produtos e uso do App Separador para pedidos. 3 - Integração de Produtos e Pedidos (sem App Separador): Inclui módulos globais e pedidos, com uso de ferramenta própria para gerenciamento e separação de pedidos, além de alterações de itens. 4 - Integração Apenas de Pedidos (com App Separador): Foca apenas nas funcionalidades de pedidos utilizando o App Separador. 5 - Integração Apenas de Pedidos (sem App Separador): Inclui módulos de pedidos, com gerenciamento e separação por meio de ferramenta própria, além de alterações de itens.

CheckList

Tipo de IntegraçãoMódulos Necessários
1Merchant, Authentication, Item e Promotion
2Todos exceto Picking
3Todos
4Merchant, Authentication,Order e Events
5Merchant, Authentication,Order, Events e Picking

Descrição e documentação dos novos módulos Merchant-API

Módulos Globais

Módulo Merchant - (opcional) Disponibiliza recursos para leitura das lojas com permissão nas credenciais, detalhes e outros recursos como abertura e fechamento de lojas e status. Minimamente para utilização dos recursos em qualquer cenário de integração de catálogo e pedidos os integradores precisarão consumir este recurso para saber o ID da loja com permissão em suas credenciais e demais recursos para gestão da loja.

Authentication Recurso necessário para uso de todas as requisições em qualquer módulo, com ele é possível gerar um "token" a partir das credenciais ClientID e CLientSecret que ficam disponíveis para requisições em qualquer endpoint durante o período listado no "Expiren in".

Módulo Item Disponibiliza recursos para atualização de catálogo nas plataformas iFood Marketplace, iFood Shop e White Label, como preço, estoque, adições de novos produtos, inativações, entre outros.

Módulo 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, "Lexe 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 muito em breve serão removidas deste módulo, ficando os recursos disponíveis apenas no módulo Promotion, é recomendado que na construção utilizem para atualização de promoções o módulo Módulo Promotion, sejam elas simples ou complexas.

Integração de Pedidos

Módulo Order Disponibiliza recursos para leitura dos dados detalhados dos pedidos emitidos nas plataformas iFood Marketplace, iFood SHOP e White Label.

Módulo Events Disponibiliza recursos de polling e WebHook onde os parceiros pode visualizar eventos que informam os status dos pedidos em cada etapa.

Módulo Adicional - (Integração de pedidos sem AppSeparador)

O Módulo PICKING é exclusivo somente para integração de pedidos quando o integrador parceiro não utiliza o AppSeparador para separação e gestão dos pedidos

Módulo Picking Este módulo é exclusivo para alguns integradores previamente mapeados que não farão a gestão de avanço dos pedidos e edição de itens através de nossa ferramenta oficial App Separador, todos os demais integradores devem utilizar como recurso para separação o App Separador.

Atenção O Módulo Picking não deve ser utilizado ou desenvolvido pelos parceiros que usarão o AppSeparador.

Critérios de Homologação para Pedidos

Módulo Events: Para garantir a operação eficaz das lojas no app, é essencial validar o uso dos endpoints, filtros e seguir as boas práticas.

Endpoints - Utilizando Polling

  • GET /events:polling: Lista todos os eventos de pedidos das lojas selecionadas. Este processo é crucial para manter sua loja ativa.
  • POST /acknowledgment: Remove os eventos listados no polling.

Pontos de Atenção Polling: Execute a cada 30 segundos para consumir todos os pedidos e manter a loja aberta.

Filtros: Ao usar filtros, eventos fora do escopo são removidos (Auto-Acknowledgment). Eventos desaparecem do polling após 8 horas. Para redes grandes, use header x-polling-merchants para filtrar até 500 lojas por vez, separando requisições de 100 em 100 para mais lojas.

Eventos Cancelados: Sempre valide eventos de pedidos cancelados, pois o cancelamento pode ocorrer a qualquer momento.

Acknowledgment: Remoção de Eventos

  • Envie o ACK para eventos SPE somente após garantir que o pedido foi consumido em seu sistema, evitando perdas de dados.
  • Limpe todos os eventos não utilizados para evitar recebê-los novamente.
  • Cada request suporta até 2000 IDs; divida em várias requisições, se necessário.

Order: Detalhes do Pedido

  • GET /orders/{id}/virtual-bag: Lista todos os detalhes do pedido.

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.

Siga estas diretrizes para otimizar a integração e operação contínua e eficaz com o sistema iFood.

Preços com promoção Importante ressaltar que as promoções (mesmo as de preço fixo) aparecem da seguinte forma na integração de pedidos:

  • 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.

Saiba mais em Introdução aos detalhes de pedidos

AppSeparador - Gestor de Pedidos do iFood Marketplace

Descubra as vantagens do App Separador, a ferramenta nativa do iFood que simplifica o gerenciamento de pedidos. Com ele, todas as etapas de separação e gerenciamento de pedidos são automatizadas, incluindo eventos e alterações de status, economizando tempo e reduzindo a chance de erros.

Por que investir em desenvolvimento interno quando o App Separador já oferece uma solução eficaz e integrada? Compatível com as plataformas iFood Marketplace, iFood SHOP e White Label, ele se adapta perfeitamente ao seu ambiente de teste, utilizando o mesmo usuário de cadastro no portal.

Experimente a eficiência do App Separador e concentre-se no que realmente importa: expandir seu negócio.

Vídeo Introdução ao App Separador

Vídeo Processo de separação App Separador

Passo a Passo para homologação Merchant-API módulos Groceries

Passo 1 - Cadastro.

Acesse o portal Developer iFood e clique no botão Cadastrar

portal developer

Após inserido os dados iniciais será solicitado o perfil, selecione a opção "Perfil Profissional"

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.

CNAE tecnologia

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.

Após o cadastro da empresa será solicitado o tipo de ambiente que deseja utilizar, selecione a opção Mercado que trará recursos para homologação de integrações voltadas para as plataformas iFood Marketplace, iFood SHOP e White Label.

perfil Mercado

Conclua o cadastro

Passo 2 - Acesso a ambientes testes e credenciais

Logo após o cadastro você terá acesso a área do Desenvolvedor com alguns recurso disponíveis no menu lateral abaixo a descrição dos principais recursos:

Passo 3 - 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 o desenvolvimento a partir dos módulos citados neste documento e utilizando as lojas 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 recurso 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.

Tutorial em vídeo

Veja no vídeo abaixo, o passo a passo de como se cadastrar: Clique aqui para assistir o vídeo.

© Copyright 2025 - iFood - Todos os direitos reservados iFood com Agência de Restaurantes Online S.A.