Buscar na documentação
ctrl+4K
Módulos
Authentication
Merchant
Catalog
Order
Events
Logistics
Shipping
Review
Financial
Soluções

Combo

A partir de (16/12), a API de integração de catálogo do iFood permite diferenciar itens que representam combos, classificar os tipos de complementos e criar customizações até o 3º nível. As mudanças serão incrementais e, portanto, não haverá quebra de contrato ou impacto imediato.tl;dr : vídeoNeste documento você encontra:
  1. Conceitos
  2. O que muda na API?
  3. Processo de Homologação
  4. FAQ - Perguntas Frequentes

Conceitos

Novo tipo de item (Combos)

Itens de combos trazem alguns benefícios como uma melhoria da classificação por modelos de IA do iFood e a possibilidade da utilização do terceiro nível da oferta (mais informações abaixo).Atualmente a API de integração de catálogo apenas suporta dois tipos de item: DEFAULT e PIZZA. Para contemplar itens que representam combos, um novo tipo de item estará disponível chamadoCOMBO_V2.Pontos de atenção: Para criar um combo usando o novo type, será obrigatório:
  • Definir um (e apenas um) Grupo de Complemento Principal no combo,
  • Declarar o Tipo de Grupo de Complemento para todos os Grupos de Complementos

Grupo de Complemento Principal do Combo

Ao criar um item de combo será necessário informar qual o Grupo de Complemento que representa o produto principal do combo. Isto é necessário para que os modelos de IA do iFood consigam inferir informações relacionadas ao combo de forma correta e assim fazer com que o item seja elegível para campanhas promocionais automáticas. Para realizar esta marcação um novo campo chamado associationType será acionado a entidade que vincula um Product a um OptionGroup. Os únicos valores possíveis para este campo serão MAIN ou null.

Tipos de Grupo de Complemento

Agora é possível categorizar os grupos de complemento. Essa categorização facilita a gestão dos grupos de complemento no Portal do Parceiro e ajuda a diferenciar múltiplos grupos. Os tipos disponíveis são:
  • OFFER_UNIT - Indica que o grupo de complementos contém uma oferta secundária/cross sell de um outro item já disponível no cardápio.
  • CUTLERY - Indica que o grupo de complementos contém opções de escolha de talheres, guardanapos entre outros descartáveis.
  • SPECIFICATION - Indica que o grupo de complementos contém opções que alteram o modo de preparo de um produto, como por exemplo: Qual o ponto da carne?, Maçaricado?
  • INGREDIENTS - Indica que o grupo de complementos contém opções que alteram os ingredientes de um produto, como por exemplo: Deseja adicionar algum ingrediente?, Deseja adicionar algum molho?
A tipagem é obrigatória para itens de combo pois apenas grupos de complementos do tipo SPECIFICATION e INGREDIENTSserão exibidos no 3º nível no app!

Terceiro Nível da Oferta

Até hoje o iFood apenas trabalhou com dois níveis da oferta no catálogo, o item principal (1º nível da oferta) e os grupos de complemento (2º nível da oferta):
Combo hamburger e refrigerante (item)
├── Escolha seu hamburger (Grupo de Complemento)
│   ├── Hamburger de salada (Complemento)
│   ├── Hamburger de bacon (Complemento)
│   └── Cheeseburger (Complemento)
└── Escolha o seu refrigerante (Grupo de Complemento)
    ├── Refrigerante de laranja (Complemento)
    └── Refrigerante de uva (Complemento)
O terceiro nível da oferta não é nada mais que uma nova ‘fatia’ de Grupos de Complemento que são atrelados a um complemento:
Combo hamburger e refrigerante (item)
├── Escolha seu hamburger (Grupo de Complemento)
│   ├── Hamburger de salada (Complemento)
│   │   ├── Deseja retirar um ingrediente? (Grupo de complemento)
│   │   │   ├── Tomate (Complemento)
│   │   │   └── Queijo (Complemento)
│   │   └── Deseja algum adicional (Grupo de complemento)
│   │       ├── Mais queijo (Complemento)
│   │       └── Bife extra (Complemento)
│   ├── Hamburger de bacon (Complemento)
│   │   ├── Deseja retirar um ingrediente? (Grupo de complemento)
│   │   │   ├── Tomate (Complemento)
│   │   │   ├── Queijo (Complemento)
│   │   │   └── Bacon (Complemento)
│   │   └── Deseja algum adicional (Grupo de complemento)
│   │       ├── Mais queijo (Complemento)
│   │       ├── Mais bacon (Complemento)
│   │       └── Bife extra (Complemento)
│   └── Cheeseburger (Complemento)
│       ├── Deseja retirar um ingrediente? (Grupo de complemento)
│       │   └── Queijo (Complemento)
│       └── Deseja algum adicional (Grupo de complemento)
│           ├── Mais queijo (Complemento)
│           ├── Bacon (Complemento)
│           └── Bife extra (Complemento)
└── Escolha o seu refrigerante (Grupo de Complemento)
    ├── Refrigerante de laranja (Complemento)
    └── Refrigerante de uva (Complemento)
Esta nova ‘fatia’ adiciona um novo nível de customização da oferta permitindo que seja apresentado ao cliente a possiblidade de modificar certos aspectos dos produtos ofertados dentro de um combo.

O que muda na API?

As mudanças na API pública são minímas, as mudanças que ocorrerão no endpoint de PUT /merchants/{merchantId}/items são:
  • Novo valor para o campo type na entidade Item: COMBO_V2
    {
	...
  "item": {
    ...
    "type": "COMBO_V2"
    ...
  }
  ...
}
  • Novo campo de type para a entidade OptionGroup:
    {
	...
  "optionGroups": [
    {
      ...
      "type": "OFFER_UNIT"
      ...
    }
  ]
  ...
}
  • Novo campo de associationType para a entidade OptionGroupRelation:
    {
	...
  "products": [
    {
      ...
      "optionGroups": [
        {
	        ...
          "associationType": "MAIN"
          ...
        }
      ]
      ...
    }
  ]
  ...
}
A criação do terceiro nível da oferta é realizada através do vínculo de um grupo de complemento a um produto utilizado em um complemento. Atualmente este vínculo já é permitido pela API mas não reflete em nenhuma estrutura no app. A única mudança será que para itens do tipo COMBO_V2 este vínculo irá começar a ser considerado até o 3º nível!

Exemplos de criação de combos

Neste exemplo será construído um Item com a seguinte estrutura:
Combo hamburger e refrigerante (item)  
├── Escolha seu hamburger (Grupo de Complemento)
│   ├── Hamburger de salada (Complemento) 
│   │   ├── Deseja retirar um ingrediente? (Grupo de complemento)
│   │   │   ├── Tomate (Complemento)
│   │   │   └── Queijo (Complemento)
│   │   ├── Deseja algum adicional? (Grupo de complemento)
│   │   │   ├── Mais queijo (Complemento)
│   │   │   ├── Bife extra (Complemento)
│   │   │   └── Bacon extra (Complemento)
│   │   └── Qual o ponto da carne? (Grupo de complemento)
│   │       ├── Mal passada (Complemento)
│   │       ├── Ao ponto (Complemento)  
│   ├── Hamburger de bacon (Complemento)
│   └── Cheeseburger (Complemento)
└── Escolha o seu refrigerante (Grupo de Complemento)
    ├── Refrigerante de laranja (Complemento)
    └── Refrigerante de uva (Complemento)
Por questões de manter o exemplo curto, estamos criando o 3º nível da oferta em apenas uma das opções - Hamburger de Salada.Para este exemplo temos o seguinte payload para o endpoint PUT /merchants/{merchantId}/items:
{
  "item": {
    "id": "{{itemId}}",
    "categoryId": "{{categoryId}}",
    "productId": "{{itemProductId}}",
    "type": "COMBO_V2",
    "status": "AVAILABLE",
    "price": {
      "value": 30.00
    }
  },
  "products": [
    {
      "id": "{{itemProductId}}",
      "name": "Combo hamburger e refrigerante",
      "optionGroups": [
        {
          "id": "{{burgerTypeOptionGroupId}}",
          "min": 1,
          "max": 1,
          "index": 0,
          "associationType": "MAIN"
        },
        {
          "id": "{{sodaTypeOptionGroupId}}",
          "min": 1,
          "max": 1,
          "index": 1
        }
      ]
    },
    {
      "id": "{{saladBurgerProductId}}",
      "name": "Hamburger de salada",
      "optionGroups": [
        {
          "id": "{{meatSpecificationOptionGroupId}}",
          "min": 1,
          "max": 1,
          "index": 0
        },
        {
          "id": "{{removeIngredientOptionGroupId}}",
          "min": 0,
          "max": 2,
          "index": 1
        },
        {
          "id": "{{extraIngredientOptionGroupId}}",
          "min": 0,
          "max": 2,
          "index": 2
        }
      ]
    },
    {
      "id": "{{baconBurgerProductId}}",
      "name": "Hamburger de bacon"
    },
    {
      "id": "{{cheeseBurgerProductId}}",
      "name": "Cheeseburger"
    },
    {
      "id": "{{removeTomatoProductId}}",
      "name": "Retirar tomate"
    },
    {
      "id": "{{removeCheeseProductId}}",
      "name": "Retirar queijo"
    },
    {
      "id": "{{extraCheeseProductId}}",
      "name": "Queijo extra"
    },
    {
      "id": "{{extraBaconProductId}}",
      "name": "Bacon extra"
    },
    {
      "id": "{{extraMeatProductId}}",
      "name": "Bife extra"
    },
    {
      "id": "{{grapeSodaProductId}}",
      "name": "Refrigerante de Uva"
    },
    {
      "id": "{{orangeSodaProductId}}",
      "name": "Refrigerante de Laranja"
    },
    {
      "id": "{{wellDoneMeatProductId}}",
      "name": "Ao ponto"
    },
    {
      "id": "{{rareMeatProductId}}",
      "name": "Mal passada"
    }
  ],
  "optionGroups": [
    {
      "id": "{{burgerTypeOptionGroupId}}",
      "name": "Escolha seu Hamburger",
      "status": "AVAILABLE",
      "optionIds": [
        "{{saladBurgerOptionId}}",
        "{{baconBurgerOptionId}}",
        "{{cheeseBurgerOptionId}}"
      ],
      "optionGroupType": "OFFER_UNIT"
    },
    {
      "id": "{{sodaTypeOptionGroupId}}",
      "name": "Escolha o seu refrigerante",
      "status": "AVAILABLE",
      "optionIds": [
        "{{orangeSodaOptionId}}",
        "{{grapeSodaOptionId}}"
      ],
      "optionGroupType": "OFFER_UNIT"
    },
    {
      "id": "{{removeIngredientOptionGroupId}}",
      "name": "Deseja retirar um ingrediente?",
      "status": "AVAILABLE",
      "optionIds": [
        "{{removeTomatoOptionId}}",
        "{{removeCheeseOptionId}}"
      ],
      "optionGroupType": "INGREDIENTS"
    },
    {
      "id": "{{extraIngredientOptionGroupId}}",
      "name": "Deseja algum adicional?",
      "status": "AVAILABLE",
      "optionIds": [
        "{{extraCheeseOptionId}}",
        "{{extraBaconOptionId}}",
        "{{extraMeatOptionId}}"
      ],
      "optionGroupType": "INGREDIENTS"
    },
    {
      "id": "{{meatSpecificationOptionGroupId}}",
      "name": "Qual o ponto da carne?",
      "status": "AVAILABLE",
      "optionIds": [
        "{{rareMeatOptionId}}",
        "{{wellDoneMeatOptionId}}"
      ],
      "optionGroupType": "SPECIFICATION"
    }
  ],
  "options": [
    {
      "id": "{{saladBurgerOptionId}}",
      "productId": "{{saladBurgerProductId}}",
      "status": "AVAILABLE",
      "index": 0,
      "price": {
        "value": 5
      }
    },
    {
      "id": "{{baconBurgerOptionId}}",
      "productId": "{{baconBurgerProductId}}",
      "status": "AVAILABLE",
      "index": 0,
      "price": {
        "value": 8
      }
    },
    {
      "id": "{{cheeseBurgerOptionId}}",
      "productId": "{{cheeseBurgerProductId}}",
      "status": "AVAILABLE",
      "index": 0,
      "price": {
        "value": 3
      }
    },
    {
      "id": "{{removeTomatoOptionId}}",
      "productId": "{{removeTomatoProductId}}",
      "status": "AVAILABLE",
      "index": 0
    },
    {
      "id": "{{removeCheeseOptionId}}",
      "productId": "{{removeCheeseProductId}}",
      "status": "AVAILABLE",
      "index": 1
    },
    {
      "id": "{{extraCheeseOptionId}}",
      "productId": "{{extraCheeseProductId}}",
      "status": "AVAILABLE",
      "index": 0
    },
    {
      "id": "{{extraBaconOptionId}}",
      "productId": "{{extraBaconProductId}}",
      "status": "AVAILABLE",
      "index": 1
    },
    {
      "id": "{{extraMeatOptionId}}",
      "productId": "{{extraMeatProductId}}",
      "status": "AVAILABLE",
      "index": 2
    },
    {
      "id": "{{grapeSodaOptionId}}",
      "productId": "{{grapeSodaProductId}}",
      "status": "AVAILABLE",
      "index": 1
    },
    {
      "id": "{{orangeSodaOptionId}}",
      "productId": "{{orangeSodaProductId}}",
      "status": "AVAILABLE",
      "index": 2
    },
    {
      "id": "{{wellDoneMeatOptionId}}",
      "productId": "{{wellDoneMeatProductId}}",
      "status": "AVAILABLE",
      "index": 1
    },
    {
      "id": "{{rareMeatOptionId}}",
      "productId": "{{rareMeatProductId}}",
      "status": "AVAILABLE",
      "index": 2
    }
  ]
}
Pontos de atenção:
  • O 3º nível da oferta é construído através do vínculo de um OptionGroup com o Product que está sendo usado dentro de uma Option.
  • O optionGroupType dos OptionGroup utilizados no 3º nível da oferta são todos SPECIFICATION.

Processo de Homologação

Para evitar inconsistências, a liberação do Combo 3º Nível para o Portal do Parceiro, App do Parceiro e Gestor de Pedidos ocorrerá somente após a criação de pelo menos um combo pela integradora ou ao final do prazo de adaptação . Não se preocupe, antes da liberação vamos notificá-los previamente via e-mail.A atualização da API deverá ser realizada até o dia 30/05/2025, respeitando o prazo mínimo de 60 dias para mudanças opcionais com impacto. O fluxo completo poderá ser testado pela integradora com o MERCHANT TESTE.Nesta data a feature será liberada para todos os merchants integrados também via Portal do Parceiro. Assegure-se de que seu sistema está preparado para reconhecer e processar o novo fluxo dentro do prazo. Caso a integração não seja ajustada, teremos inconsistência na gestão do catálogo e na visualização dos pedidos pela operação, gerando possíveis reclamações e cancelamentos.

FAQ - Perguntas Frequentes

É possível enviar outros níveis de oferta além do 3º nível?Não, outros níveis serão ignorados na requisição. O item será criado com sucesso, mas apenas será considerado e exibido até o 3º nível de oferta. É possível gerir estoque de um complemento no 3º Nível?Todos os atributos atrelados a um produto estão disponível no 3º nível, como estoque, status e código pdv. O Combo 3º Nível está disponível para V1 ou Single Setup?As novidades - combo, tipos de GC e 3º nível, estão disponíveis apenas para V2 - Multisetup. Quais são os passos necessários para criar um item do tipo Combo Nível 3?
  • Definir o item, type = COMBO_V2
  • Definir um (e apenas um) Grupo de Complemento Principal no combo,
  • Declarar o Tipo de Grupo de Complemento para todos os Grupos de Complementos
Esse terceiro nível terá um campo para definir o código PDV?Sim, pelo endpoint  PUT /merchants/{merchantId}/items ao enviar a lista de products você enviará também os que estão contidos no 3º nível e poderá listar o código PDV como é feito hoje.Quais das alterações são obrigatórias e quais não são? Quais os impactos caso não sejam implantadas?São alterações incrementais, os combos criados como itens regulares continuam operando normalmente. As integradoras terão até MAI/2025 para se adaptarem ao combo 3º nível - nesta data a feature será liberada no Portal do Parceiro para todos os merchants integrados. Caso a integração não esteja ajustada, teremos inconsistência na gestão do catálogo e na visualização dos pedidos pela operação, gerando possíveis reclamações e cancelamentos.Os pontos já estão disponíveis em ambiente de testes? Não teremos ambiente de teste, visto que são alterações incrementais. A feature será liberada no merchant teste para que possam validar o fluxo completo em produção.Quais os prazos para cada mudança? A adaptação das integradoras ocorrerá até MAI/2025. A partir daí a feature será liberada no Portal do Parceiro para todos os merchants integrados.Será alterada a forma de cadastrar um produto que é combo? A forma usada hoje, com um item default, se mantém e os combos já criados continuam operando normalmente. Utilizar o novo tipo de item combo, no entanto, oferece aos parceiros a possibilidade de aumentar a conversão, ticket médio e visibilidade dos itens no app.
Esta página foi útil?
Avalie sua experiência no novo Developer portal:
Nesta página
Combo
Conceitos
Novo tipo de item (Combos)
Grupo de Complemento Principal do Combo
Tipos de Grupo de Complemento
Terceiro Nível da Oferta
O que muda na API?
Exemplos de criação de combos
Processo de Homologação
FAQ - Perguntas Frequentes
Conteúdo lido0%