logo
logo

Docs Catalog Catalog API v2

Definições

O que mudou?

Na nova versão da API, tornamos a estrutura do catálogo unificada e compartilhada entre os contextos(cardápios), permitindo modificações de preço e status distintos para cada contexto.

O que isso significa? Se a sua loja possui mais de um serviço iFood (por exemplo Sob Demanda e Cardápio Digital), a gestão de ambos os contextos foi facilitada.

Os itens e complementos são compartilhados entre os contextos sem a necessidade de criar ou editar dois catálogos diferentes. Foi adicionado o parâmetro catalogContext nos endpoints relacionados a itens e complementos, para informar em qual contexto a operação deve ser realizada. Caso o parâmetro não seja informado, a alteração será refletida em todos os contextos.

Foi feita uma adição importante: agora, no retorno das entidades que representam itens, incluímos um novo objeto chamado contextModifier. Esse objeto contém os IDs que serão associados a esse item em diferentes contextos. Por exemplo, o itemContextId do contexto DEFAULT será o ID usado quando houver um pedido daquele item no contexto de Entrega. Exemplo do objeto:

"contextModifiers": [
    {
        "catalogContext": "WHITELABEL",
        "itemContextId": "83cd029d-d833-42dd-bbd6-017c12312968"
    },
    {
        "catalogContext": "DEFAULT",
        "itemContextId": "d2e6820e-cc5c-42e3-99db-c180c2bcf4ad"
    }
]

Outra novidade é o endpoint de criação e edição de um Item Completo, onde é possível criar um item e seus complementos com uma única requisição.

Por último, a Pizza foi remodelada e não possui mais endpoints exclusivos. Agora, ela é um item com características pré-definidas. Portanto as APIs de Pizza NÃO possuem retrocompatibilidade com a V2 e a gestão de itens do tipo Pizza não é mais feita por endpoints específicos para Pizza. Você pode checar a seção de Pizza para mais informações.

Você pode checar um resumo dessas mudanças no YouTube:

Atualizando a versão da API

Para utilizar a nova versão da API, é necessário atualizar a versão do catálogo da loja.

A versão atual do catálogo pode ser conferida através do endpoint GET Version.

A versão do catálogo pode ser atualizada através do endpoint Upgrade Version, o retorno é um batch ID visto que o processo é feito de forma assíncrona e deve ser acompanhado pelo endpoint GET Batch.

É possível escolher se o processo deve limpar todo o catálogo ou se os itens devem ser mantidos através do query param cleanMigration.

Os itens mantidos podem ter seus IDs alterados, portanto, após a migração, é recomendado recriar os itens na base da integradora utilizando o endpoint de listagem por categorias incluindo os itens Listando categorias. Lembre-se de que o campo contextModifier retornará os IDs de cada contexto, que serão apresentados nas orders.

Revertendo atualização da versão da API

Caso seja necessário retornar a loja para a versão 1.0, com a gestão separada de cada cardápio, é possível reverter o procedimento com o endpoint Downgrade Version.

Replicação de cardápio

Não será possível fazer replicações entre cardápios que estão em versões diferentes.

Arquitetura da informação

A arquitetura é baseada em catálogos e eles podem ser utilizados em contextos diferentes. Hoje possuímos 2 contextos pré-definidos (Entrega, Cardápio Digital), porém novos contextos podem ser criados. Temos as categorias, os tipos de itens, grupos de complementos e complementos. Caso um item ou complemento seja disponibilizado apenas em um contexto, deve-se deixá-lo indisponível nos demais.

Visão simplificada

Para lojas que contratam apenas um serviço, como por exemplo Sob Demanda, a visão pode ser simplificada como visto a seguir.

Múltiplos catálogos

Para lojas que contratam mais de um serviço como Cardápio Digital e Sob Demanda, é possível gerir o catálogo com modificações para cada tipo de operação. Isso permite ter preços e status diferentes, com as mesmas disponibilidades, categorias e itens.

Categoria

Categoria é a entidade em que a loja possui para organizar seus itens a fim de facilitar para o usuário encontrar o que deseja comprar. As categorias possuem status de venda como pausada e ativada.

Pausada Quando uma categoria está pausada, todos os itens contidos nessa categoria serão pausados automaticamente e ela não é mostrada para o consumidor final.

Quando uma categoria possui todos os seus itens pausados separadamente, ela automaticamente é pausada.

Ativada Quando uma categoria é ativada, ela passa a ser mostrada ao consumidor final, porém os itens contidos possuem seus próprios status de venda.

Quando uma categoria possui itens com status de vendas variados, ao ser pausada todos os itens passam a ser pausados também, e ao ser novamente ativada, os itens voltam aos seus estados originais (pausado ou ativado, como anteriormente).

Categoria de itens

Categoria de itens é uma categoria formada por itens genéricos que podem, ou não, possuir grupos de complementos e complementos

Categoria de pizza

Categoria de pizza é uma categoria, no portal do parceiro, para um tipo específico de item: pizza. A pizza precisa obrigatoriamente de grupos de complementos dos tipos tamanho, massa, borda e sabor. Para integrações, é necessário utilizar o endpoint PUT item omitindo o id da categoria na criação do item, assim a categoria do tipo pizza é criada automaticamente.

Produto

Produto é a entidade de catálogo que carrega todas as informações gerais. Elas são: Nome, descrição, código externo, imagem, disponibilidade em turnos, tamanho, restrições alimentares e EAN (European Article Number), utilizado principalmente por mercados. O produto pode ser oferecido em um catálogo como um item principal ou complemento. E, para uma mesma loja, pode ser reutilizado até mesmo em diferentes catálogos.

Quantas pessoas servem O tamanho do produto é essencial para saber para que tamanho de fome ele é, por exemplo: Esse produto é ideal para 1, 2, 3 ou 4 pessoas? Existe o caso que esse tamanho não se aplica para o produto também, como por exemplo bebidas.

Grupo de complementos

O grupo de complementos é a entidade utilizada para agrupar customizações de um produto, por exemplo: “Escolha sua bebida:”

Um grupo de complemento pode ser compartilhado por vários itens, desde que estejam contidos na mesma categoria.

Obrigatoriedade O grupo de complementos pode ser obrigatório, ou opcional.

Obrigatório Em casos de grupos de complementos obrigatórios, o usuário final deve selecionar pelo menos a quantidade mínima configurada de opções dentro do grupo para conseguir efetuar a compra. Complementos obrigatórios possuem quantidade mínima e máxima, sendo que a máxima é obrigatória ser um número maior que a mínima.

Opcional Em casos de grupo de complementos opcionais, o usuário consegue comprar o produto sem que nenhuma opção esteja relacionada. Complementos opcionais não possuem quantidade mínima mas possuem quantidade máxima.

Complemento

Complementos são as opções de um Grupo de Complemento. Pode ser definido como: “Um produto relacionado a um grupo de complemento”. O complemento possui seu próprio status de venda, sendo possível pausar ou ativar quando necessário. É possível que um complemento seja R$ 0,00 independente se é obrigatório ou opcional.

Restrições alimentares

O produto pode ser caracterizado com base em algumas restrições alimentares, como por exemplo:

  • Vegano
  • Vegetariano
  • Orgânico
  • Sem glúten
  • Sem açúcar
  • Zero lactose

As restrições alimentares são informações opcionais e o produto pode conter mais de uma opção selecionada.

Disponibilidade em turnos

Para produtos que são vendidos somente em alguns períodos da semana, é possível configurar sua disponibilidade em turnos. Por exemplo: A feijoada só é vendida às quartas-feiras das 10:00 às 16:00

Sempre disponível Quando um item está selecionado como sempre disponível, ele será visualizado sempre que a loja estiver aberto e o status de venda (Como item principal ou complemento) é ativado.

Disponível em dias e horários específicos Quando um item está selecionado como disponível em dias e horários específicos, o usuário pode selecionar em quais dias o item estará disponível, em quais horários e/ou criar turnos.

Arquitetura da informação - Produto

Item

O item pode ser considerado a oferta de um produto. Análogo ao complemento, o item é um produto relacionado à categoria.
Item Tags tem como propósito fornecer informações sobre características do Item, diferentemente de uma product tag, a Item tag pode ser transitiva, ou seja, um mesmo produto pode ser vendido gelado ou não.

Disponibilidade O item possui dois estados, ativado e pausado, e podem ser diferentes em catálogos de contextos diferentes. Por exemplo: Nhoque está ativo no catálogo de Entrega e pausado no Cardápio digital.

Eles são configurados para definir se o item deve ou não aparecer à venda.

Em caso de item pausado, mesmo se configurado uma disponibilidade por turnos, o item não aparecerá à venda.

Inventário

Permite adicionar uma quantidade máxima que um determinado produto pode ser vendido. Caso um inventário seja criado para um produto com quantidade 10, apenas 10 itens que estejam relacionados a esse produto podem ser vendidos. Após 10 produtos poderem ser vendidos, o produto será marcado como 'Fora de Stock' e não poderá mais ser vendido.

Código externo (integração)

O código externo, também conhecido como PDV, é a identificação que a loja pode adicionar nos seus itens para, no momento que receberem o pedido, conseguirem realizar algum tipo de integração, por exemplo, controle de estoque.

O código externo é único entre os produtos da loja, ou seja, caso seja criado um produto com o mesmo external_code de um produto existente na loja, o produto já existente é reutilizado ao invés de criar o produto informado no request. Essa regra se aplica também ao endpoint PUT item.

Precificação

A venda de um produto está sempre relacionada ao seu preço. Esse preço pode variar dependendo de onde esse produto se encontra (Como item principal ou complemento), ou adicionando preços promocionais ao item. Também é possível que os preços de um item sejam diferentes dependendo do contexto em que ele está sendo ofertado (Entrega ou Cardápio Digital).

Item

O preço do item se dá na oferta de um produto em uma categoria.

Preço por atacado

Feature Exclusiva Essa feature não está disponível para restaurantes atualmente. No caso de um parceiro que seja um restaurante tentar usar essa feature, um erro de permissão negada (403) será emitido. Caso tenha interesse em utilizar funções dessa API, entre em contato com o nosso time de atendimento.

Além do preço normal, também é possível atribuir preços customizados que dependem da quantidade comprada do item. Para utilizar a feature de preço por atacado, basta adicionar o campo abaixo ao body nas APIs de criação e edição de item.

"scale_prices": [
        {
          "min": 1,
          "value": 9.99
        },
        {
          "min": 10,
          "value": 8.99
        }
  ]

De acordo com o exemplo acima, o preço do item será R$ 9.99 se o cliente comprar uma quantidade de até 9 deste item. Caso o cliente comprar mais de 9 o preço passará a ser R$ 8.99.

Complemento

O preço do complemento se dá na oferta de um produto em um grupo de complementos. Diferente do item, ele não possui a funcionalidade de preço promocional

Pizza

Pizza é um produto que tem 4 grupos de complementos obrigatórios, sendo estes: Tamanhos, massas, bordas e sabores.

O produto de pizza pode ser associado apenas a uma categoria do tipo PIZZA. Através do portal, essa associação é automática, porém para integrações é necessário utilizar o endpoint PUT item omitindo o id da categoria na criação do item, assim a categoria do tipo pizza é criada automaticamente.

A precificação e disponibilidade de sabores segue a mesma lógica de outros complementos da V2, podendo ser personalizados por contexto.

Tamanho

O tamanho da pizza é definido por alguns aspectos:

  • Nome, tradicionalmente “Pequena”, “Média” e “Grande”, mas pode ser customizado.
  • Quantidade de pedaços em que cada um dos tamanhos é cortado.
  • Quantidade de frações, ou seja, esse tamanho pode ser vendido ½ sabor 1 e ½ sabor 2. Sendo possível dividir em até 4 frações

Massa

A massa é uma customização da pizza, exemplo: “Tradicional”, “Integral” e pode ter um preço adicional no custo da pizza, se configurado.

Borda

A borda, assim como a massa, é uma customização da pizza, exemplo: “Borda de Catupiry” e pode ter um preço adicional no custo da pizza, se configurado.

Sabor

O sabor define quais tipos de pizza são vendidas. Os sabores possuem um preço para cada tamanho, por exemplo: Grande Calabresa - R$50,00 Pequena Calabresa - R$25,00

Em diferentes catálogos os sabores podem ter preços diferentes para cada tamanho

Utilizando a API

Listando catálogos

O primeiro passo nas APIs de catálogo é a listagem de catálogos, através da API GET /merchants/{merchantId}/catalogs. Atualmente possuímos os catálogos DEFAULT e INDOOR, indicando que esse catálogo é de Entrega

Requisição:

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/catalogs' \
--header 'Authorization: Bearer TOKEN

Resposta

[
  {
    "catalogId": "10e0fbbe-7279-4ee3-9a2f-caf1f93f7b8e",
    "context": ["DEFAULT"],
    "status": "AVAILABLE",
    "modifiedAt": 1597350642.71608
  }
]

Listando categorias

Com o id do catálogo em mãos, é possível listar todas as categorias e itens de um catálogo através da API GET /merchants/{merchantId}/catalogs/{catalogId}/categories.

Requisição:

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/catalogs/10e0fbbe-7279-4ee3-9a2f-caf1f93f7b8e/categories?include_items=true \
--header 'Authorization: Bearer TOKEN

Resposta:

[]

Como ainda não adicionamos nada no nosso catálogo, ele voltará uma lista vazia! Seguindo os próximos passos você aprenderá como montar seu catálogo

Aqui temos um exemplo do retorno desse endpoint com um item já criado

Exemplo Resposta:

[
  {
    "id": "a8533d43-aec8-467c-adf6-8a24791829a0",
    "name": "Lanches",
    "status": "AVAILABLE",
    "sequence": 0,
    "index": 0,
    "template": "DEFAULT",
    "items": [
      {
        "id": "16ae5fc9-7e34-4623-8a0c-722d12fd49e9",
        "name": "X-Burguer",
        "description": "Pão, carne, queijo e salada",
        "externalCode": "xburguer_wl",
        "status": "AVAILABLE",
        "sequence": 0,
        "index": 0,
        "productId": "fdb50f52-7b62-46f7-a574-f3bc00c3f673",
        "imagePath": "",
        "price": {
          "value": 10,
          "originalValue": 15,
          "scalePrices": [
            
          ]
        },
        "shifts": [
          {
            "startTime": "00:00",
            "endTime": "20:59",
            "monday": true,
            "tuesday": true,
            "wednesday": true,
            "thursday": true,
            "friday": true,
            "saturday": true,
            "sunday": true
          }
        ],
        "serving": "SERVES_2",
        "dietaryRestrictions": [
          
        ],
        "optionGroups": [
          {
            "id": "13736a09-ac48-4f8f-bcb1-56d6a5dcdf33",
            "name": "Acompanhamentos",
            "min": 0,
            "max": 1,
            "sequence": 0,
            "index": 0,
            "status": "AVAILABLE",
            "options": [
              {
                "id": "105f9323-0afb-41a1-b8af-13851424c603",
                "name": "Batata Frita",
                "description": "200 g",
                "externalCode": "option_fritas_wl",
                "productId": "38cea6cb-19d5-42b4-87b9-f46c90e7bc1d",
                "status": "UNAVAILABLE",
                "sequence": 0,
                "index": 0,
                "price": {
                  "value": 20,
                  "scalePrices": [
                    
                  ]
                }
              },
              {
                "id": "78490bf7-a924-4eb2-94a3-4489eadd4f3c",
                "name": "Onion Rings",
                "description": "200 g",
                "externalCode": "option_onion_ring_wl",
                "productId": "0f309165-3c72-468c-bdf5-637b272bc09c",
                "status": "AVAILABLE",
                "sequence": 1,
                "index": 1,
                "price": {
                  "value": 3,
                  "scalePrices": [
                    
                  ]
                }
              }
            ]
          }
        ],
        "hasOptionGroups": true,
        "contextModifiers": [
            {
                "catalogContext": "WHITELABEL",
                "itemContextId": "83cd029d-d833-42dd-bbd6-017c12312968"
            },
            {
                "catalogContext": "DEFAULT",
                "itemContextId": "d2e6820e-cc5c-42e3-99db-c180c2bcf4ad"
            }
        ]
      }
    ]
  }
]

Criando uma categoria (itens simples)

Como explicado anteriormente, a categoria é um agrupador de itens. Então vamos criar nossa primeira categoria. Para isto, vamos utilizar a API POST /merchants/{merchantId}/catalogs/{catalogId}/categories.

Requisição

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/catalogs/10e0fbbe-7279-4ee3-9a2f-caf1f93f7b8e/categories' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "Lanches",
   "status": "AVAILABLE",
   "template": "DEFAULT",
   "sequence": 0
}'

Resposta:

{
  "id": "4e6d3f79-f003-4992-8d4f-4c48d7ac5284",
  "name": "Lanches",
  "sequence": 0,
  "status": "AVAILABLE",
  "template": "DEFAULT"
}

Criando/Editando um item completo

O endpoint PUT item é válido para todos os tipos de itens, incluindo pizza. Cria-se o item com todas as dependências que o compõem: produtos, grupos de complementos e complementos. Se os ids informados já existirem na base, as entidades serão atualizadas.

Note que, se informados, os valores dentro do contextModifiers terão precedência sobre os valores do item ou do complemento, por exemplo, se for informado um price na context modifier, o preço do item será sobrescrito naquele contexto.

Para criar um item com imagem veja o tópico upload de imagem.

Requisição:

curl --location --request PUT 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/items' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "item": {
    "id": "cff648d8-fc31-41b0-b80e-81fc3651ca7a",
    "type": "DEFAULT",
    "categoryId": "beab216d-33dc-4ce4-8b35-5372e135093d",
    "status": "AVAILABLE",
    "price": {
      "value": 11.00,
      "originalValue": 12.50
    },
    "externalCode": "public_item",
    "index": 0,
    "productId": "62133b9f-5542-401d-8743-49ec7da8c847",
    "shifts": null,
    "tags": null,
    "contextModifiers": [
      {
        "catalogContext": "WHITELABEL",
        "status": "AVAILABLE",
        "price": {
          "value": 13,
          "originalValue": 16
        },
        "externalCode": "whitelabel_ec2"
      },
      {
        "catalogContext": "INDOOR",
        "status": "AVAILABLE",
        "price": {
          "value": 13,
          "originalValue": 17
        },
        "externalCode": "indoor_ec"
      }
    ]
  },
  "products": [
    {
      "id": "62133b9f-5542-401d-8743-49ec7da8c847",
      "externalCode": "item_product_ec2",
      "name": "X-Burguer",
      "description": "Pão, carne, queijo e salada",
      "additionalInformation": "some additional Information",
      "imagePath": "7a27e4ac-c370-4adb-b395-397f503386cc/202311161149_3y9mdsnr8a9.png",
      "ean": "EAN112233414",
      "serving": "SERVES_2",
      "dietaryRestrictions": null,
      "quantity": null,
      "optionGroups": [
        {
            "id":"1e5e5eb5-84c7-4eca-b0c1-921860434f70",
            "min": 0,
            "max": 1
        }
      ]
    },
    {
      "id": "713713e7-641e-44fd-bd92-13ba43daf6a8",
      "externalCode": "option_product_ec2",
      "name": "Batata Frita",
      "description": "200 g",
      "additionalInformation": "some additional Information",
      "image": null,
      "ean": "EAN112253553344",
      "serving": "SERVES_1",
      "dietaryRestrictions": null,
      "quantity": null,
      "optionGroups": null
    }
  ],
  "optionGroups": [
    {
      "id": "1e5e5eb5-84c7-4eca-b0c1-921860434f70",
      "name": "Acompanhamentos",
      "externalCode": "option_group_ec2",
      "status": "AVAILABLE",
      "index": 0,
      "optionGroupType": "DEFAULT",
      "optionIds": [
        "d3e31829-a215-47e3-9576-3fddec9417ec"
      ]
    }
  ],
  "options": [
    {
      "id": "d3e31829-a215-47e3-9576-3fddec9417ec",
      "status": "AVAILABLE",
      "index": 0,
      "productId": "713713e7-641e-44fd-bd92-13ba43daf6a8",
      "price": {
        "value": 4,
        "originalValue": 7
      },
      "contextModifiers": [
        {
          "parentOptionId": null,
          "catalogContext": "WHITELABEL",
          "status": "AVAILABLE",
          "price": {
            "value": 5,
            "originalValue": 6
          },
          "externalCode": "op_whitelabel_ec"
        }
      ],
    "fractions": null,
    "externalCode": "option_ec"
    }
  ]
}'

Listando itens

Através do endpoint GET Items, informando o id de uma categoria existente, serão listados todos os itens, produtos, grupos de complementos e complementos disponíveis na mesma. O formato do json retornado é similar ao utilizado na criação de item completo.

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/categories/beab216d-33dc-4ce4-8b35-5372e135093d/items' \
--header 'Authorization: Bearer TOKEN'

Resposta:

{
   "categoryId": "beab216d-33dc-4ce4-8b35-5372e135093d",
   "items":[
      {
         "id":"cff648d8-fc31-41b0-b80e-81fc3651ca7a",
         "type":"DEFAULT",
         "categoryId":"beab216d-33dc-4ce4-8b35-5372e135093d",
         "status":"AVAILABLE",
         "price":{
            "value":11.00,
            "originalValue":12.50
         },
         "externalCode":"public_item",
         "index":0,
         "productId":"62133b9f-5542-401d-8743-49ec7da8c847",
         "shifts":null,
         "tags":null,
         "contextModifiers":[
            {
              "itemContextId": "600308db-437f-4ec5-84de-aef08d7729d2",
               "catalogContext":"WHITELABEL",
               "status":"AVAILABLE",
               "price":{
                  "value":13,
                  "originalValue":16
               },
               "externalCode":"whitelabel_ec2"
            },
            {
              "itemContextId": "bb4be583-c4d0-4091-bb6b-6e4a552993bf",
               "catalogContext":"INDOOR",
               "status":"AVAILABLE",
               "price":{
                  "value":13,
                  "originalValue":17
               },
               "externalCode":"indoor_ec"
            }
         ]
      }
   ],
   "products":[
      {
         "id":"62133b9f-5542-401d-8743-49ec7da8c847",
         "externalCode":"item_product_ec2",
         "name":"X-Burguer",
         "description":"Pão, carne, queijo e salada",
         "additionalInformation":"some additional Information",
         "image":null,
         "ean":"EAN112233414",
         "serving":"SERVES_2",
         "dietaryRestrictions":null,
         "quantity":null,
         "optionGroups":[
           {
             "id":"1e5e5eb5-84c7-4eca-b0c1-921860434f70",
             "min": 0,
             "max": 1
           }
         ]
      },
      {
         "id":"713713e7-641e-44fd-bd92-13ba43daf6a8",
         "externalCode":"option_product_ec2",
         "name":"Batata Frita",
         "description":"200 g",
         "additionalInformation":"some additional Information",
         "image":null,
         "ean":"EAN112253553344",
         "serving":"SERVES_1",
         "dietaryRestrictions":null,
         "quantity":null,
         "optionGroups":null
      }
   ],
   "optionGroups":[
      {
         "id":"1e5e5eb5-84c7-4eca-b0c1-921860434f70",
         "name":"Acompanhamentos",
         "externalCode":"option_group_ec2",
         "status":"AVAILABLE",
         "index":0,
         "optionGroupType":"DEFAULT",
         "optionIds":[
            "d3e31829-a215-47e3-9576-3fddec9417ec"
         ]
      }
   ],
   "options":[
      {
         "id":"d3e31829-a215-47e3-9576-3fddec9417ec",
         "status":"AVAILABLE",
         "index":0,
         "productId":"713713e7-641e-44fd-bd92-13ba43daf6a8",
         "price":{
            "value":4,
            "originalValue":7
         },
         "contextModifiers":[
            {
               "parentOptionId":null,
               "catalogContext":"WHITELABEL",
               "status":"AVAILABLE",
               "price":{
                  "value":5,
                  "originalValue":6
               },
               "externalCode":"op_whitelabel_ec"
            }
         ],
         "fractions":null,
         "externalCode":"option_ec"
      }
   ]
}

Listando um item

Semelhante ao endpoint acima, é possível listar os recursos que compõem um único item através de seu id com o GET Item flat. O formato do json retornado é o mesmo utilizado na criação de item completo.

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/items/af983271-3981-46fa-94eb-46cb81c439e2/flat' \
--header 'Authorization: Bearer TOKEN'

Resposta:

{
    "item": {
        "id": "af983271-3981-46fa-94eb-46cb81c439e2",
        "type": "DEFAULT",
        "categoryId": "ea2c31a9-472f-443b-ae8f-72331153915c",
        "status": "AVAILABLE",
        "price": {
            "value": 11,
            "originalValue": 12.5
        },
        "externalCode": "public_item_code",
        "index": 0,
        "productId": "f40ac7e7-da05-4800-90b2-2ee85f486d75",
        "shifts": [
            {
                "startTime": "00:00",
                "endTime": "23:59",
                "monday": true,
                "tuesday": true,
                "wednesday": true,
                "thursday": true,
                "friday": true,
                "saturday": true,
                "sunday": true
            }
        ],
        "contextModifiers": [
            {
                "catalogContext": "WHITELABEL",
                "externalCode": "item_code_for_whitelabel",
                "price": {
                    "value": 13,
                    "originalValue": 16
                },
                "status": "AVAILABLE",
                "itemContextId": "12798f58-ce7b-4195-b719-7ae49d1b2f34"
            },
            {
                "catalogContext": "DEFAULT",
                "status": "AVAILABLE",
                "itemContextId": "78a6faea-1628-4f66-896b-627bc91251bc"
            }
        ]
    },
    "optionGroups": [
        {
            "id": "d65789c8-cc81-47bc-b741-6847d0390fc6",
            "name": "Option Group Name",
            "status": "AVAILABLE",
            "optionGroupType": "DEFAULT",
            "optionIds": [
                "0e1a8e32-0a49-4c15-8b96-d8b7c5c4dc78",
                "b7da158f-4e05-4e2c-9e22-e042baea2a49"
            ]
        },
        {
            "id": "d7955b3a-3cc8-4cd3-983c-31954cee8cff",
            "name": "Option Group Name3",
            "status": "AVAILABLE",
            "optionGroupType": "DEFAULT",
            "optionIds": [
                "d8957077-36d0-476f-8766-81bac38a69cc"
            ]
        },
        {
            "id": "17532d15-2a2e-4e19-8fc7-3c7cec8bc30c",
            "name": "Option Group Name 2",
            "status": "AVAILABLE",
            "optionGroupType": "DEFAULT",
            "optionIds": [
                "abecc2d8-f91a-4cc7-b66f-59d406748ffb",
                "4034fa88-8804-46c9-8dec-92c8244ec932"
            ]
        }
    ],
    "options": [
        {
            "id": "0e1a8e32-0a49-4c15-8b96-d8b7c5c4dc78",
            "status": "AVAILABLE",
            "index": 0,
            "productId": "220f1d53-3eef-44b1-9f6d-ba2e48d26fd4",
            "price": {
                "value": 4,
                "originalValue": 7
            },
            "externalCode": "option_code",
            "contextModifiers": [
                {
                    "catalogContext": "WHITELABEL",
                    "externalCode": "option_code_for_whitelabel",
                    "price": {
                        "value": 5,
                        "originalValue": 6
                    },
                    "status": "AVAILABLE"
                },
                {
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE"
                }
            ]
        },
        {
            "id": "b7da158f-4e05-4e2c-9e22-e042baea2a49",
            "status": "AVAILABLE",
            "index": 0,
            "productId": "abed1844-7220-40b2-abda-fbf86e331209",
            "price": {
                "value": 4,
                "originalValue": 7
            },
            "externalCode": "option_code2",
            "contextModifiers": [
                {
                    "catalogContext": "WHITELABEL",
                    "externalCode": "option_code_for_whitelabel2",
                    "price": {
                        "value": 5,
                        "originalValue": 6
                    },
                    "status": "AVAILABLE"
                },
                {
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE"
                }
            ]
        },
        {
            "id": "d8957077-36d0-476f-8766-81bac38a69cc",
            "status": "AVAILABLE",
            "index": 0,
            "productId": "eec65205-110d-43aa-9729-e4ebcf9f8106",
            "price": {
                "value": 4,
                "originalValue": 7
            },
            "externalCode": "option_code5",
            "contextModifiers": [
                {
                    "catalogContext": "WHITELABEL",
                    "externalCode": "option_code_for_whitelabel5",
                    "price": {
                        "value": 5,
                        "originalValue": 6
                    },
                    "status": "AVAILABLE"
                },
                {
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE"
                }
            ]
        },
        {
            "id": "abecc2d8-f91a-4cc7-b66f-59d406748ffb",
            "status": "AVAILABLE",
            "index": 0,
            "productId": "2b9da9a4-e4f4-46cb-8d29-687fbd3a7f6f",
            "price": {
                "value": 4,
                "originalValue": 7
            },
            "externalCode": "option_code3",
            "contextModifiers": [
                {
                    "catalogContext": "WHITELABEL",
                    "externalCode": "option_code_for_whitelabel3",
                    "price": {
                        "value": 5,
                        "originalValue": 6
                    },
                    "status": "AVAILABLE"
                },
                {
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE"
                }
            ]
        },
        {
            "id": "4034fa88-8804-46c9-8dec-92c8244ec932",
            "status": "AVAILABLE",
            "index": 0,
            "productId": "7c878419-e240-417d-a322-5c32f06f47c6",
            "price": {
                "value": 4,
                "originalValue": 7
            },
            "externalCode": "option_code4",
            "contextModifiers": [
                {
                    "catalogContext": "WHITELABEL",
                    "externalCode": "option_code_for_whitelabel4",
                    "price": {
                        "value": 5,
                        "originalValue": 6
                    },
                    "status": "AVAILABLE"
                },
                {
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE"
                }
            ]
        }
    ],
    "products": [
        {
            "id": "f40ac7e7-da05-4800-90b2-2ee85f486d75",
            "name": "Default name",
            "description": "Default description",
            "ean": "EAN112233414",
            "serving": "SERVES_2",
            "dietaryRestrictions": [],
            "optionGroups": [
                {
                    "id":"d65789c8-cc81-47bc-b741-6847d0390fc6",
                    "min": 0,
                    "max": 1
                },
                {
                    "id":"d7955b3a-3cc8-4cd3-983c-31954cee8cff",
                    "min": 1,
                    "max": 1
                },
                {
                    "id":"17532d15-2a2e-4e19-8fc7-3c7cec8bc30c",
                    "min": 0,
                    "max": 1
                }
            ]
        },
        {
            "id": "220f1d53-3eef-44b1-9f6d-ba2e48d26fd4",
            "name": "Option name",
            "externalCode": "option_product_code",
            "description": "Default description",
            "ean": "EAN112253553344",
            "serving": "SERVES_1",
            "dietaryRestrictions": [],
            "optionGroups": []
        },
        {
            "id": "abed1844-7220-40b2-abda-fbf86e331209",
            "name": "Option name2",
            "externalCode": "option_product_code2",
            "description": "Default description",
            "ean": "EAN112253553344",
            "serving": "SERVES_1",
            "dietaryRestrictions": [],
            "optionGroups": []
        },
        {
            "id": "eec65205-110d-43aa-9729-e4ebcf9f8106",
            "name": "Option name5",
            "externalCode": "option_product_code5",
            "description": "Default description",
            "ean": "EAN112253553344",
            "serving": "SERVES_1",
            "dietaryRestrictions": [],
            "optionGroups": []
        },
        {
            "id": "2b9da9a4-e4f4-46cb-8d29-687fbd3a7f6f",
            "name": "Option name3",
            "externalCode": "option_product_code3",
            "description": "Default description",
            "ean": "EAN112253553344",
            "serving": "SERVES_1",
            "dietaryRestrictions": [],
            "optionGroups": []
        },
        {
            "id": "7c878419-e240-417d-a322-5c32f06f47c6",
            "name": "Option name4",
            "externalCode": "option_product_code4",
            "description": "Default description",
            "ean": "EAN112253553344",
            "serving": "SERVES_1",
            "dietaryRestrictions": [],
            "optionGroups": []
        }
    ]
}

Criando um item com um produto já existente

O produto, como citado acima, carrega todas as informações principais dos itens ou complementos que vão à venda. Segue um exemplo de criação de produto, que pode ser realizada através da API POST /merchants/{merchantId}/products.

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/products' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
 "name": "X-Burger",
 "description": "Pão, carne e queijo",
 "externalCode": "BG-1",
 "image": "",
 "shifts": [
   {
     "startTime": "00:00",
     "endTime": "23:59",
     "monday": true,
     "tuesday": true,
     "wednesday": true,
     "thursday": true,
     "friday": true,
     "saturday": true,
     "sunday": true
   }
 ],
 "serving": "SERVES_1",
 "dietaryRestrictions": [
   "ORGANIC"
 ],
 "ean": ""
}'

Resposta:

{
  "id": "ec16fb62-7bdd-43e4-940c-10b5a2845f13",
  "name": "X-burger",
  "description": "Pão, carne e queijo",
  "externalCode": "BG-1",
  "image": "",
  "shifts": [
    {
      "startTime": "00:00",
      "endTime": "23:59",
      "monday": true,
      "tuesday": true,
      "wednesday": true,
      "thursday": true,
      "friday": true,
      "saturday": true,
      "sunday": true
    }
  ],
  "serving": "SERVES_1",
  "dietaryRestrictions": ["ORGANIC"],
  "ean": ""
}

Com o produto criado, é possível enviar apenas seu id no PUT item, se não for necessária nenhuma atualização no produto, é possível omití-lo no corpo da requisição, por exemplo:

Requisição:

curl --location --request PUT 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/items' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "item": {
    "id": "6266d832-1e6c-4418-ac50-3cf5e4390d72",
    "type": "DEFAULT",
    "categoryId": "beab216d-33dc-4ce4-8b35-5372e135093d",
    "status": "AVAILABLE",
    "price": {
      "value": 11.00,
      "originalValue": 12.50
    },
    "externalCode": "item_BG-1",
    "index": 0,
    "productId": "ec16fb62-7bdd-43e4-940c-10b5a2845f13",
    "shifts": null,
    "tags": null,
    "contextModifiers": [
      {
        "catalogContext": "WHITELABEL",
        "status": "AVAILABLE",
        "price": {
          "value": 13,
          "originalValue": 16
        },
        "externalCode": "item_BG-1_whitelabel"
      },
      {
        "catalogContext": "INDOOR",
        "status": "AVAILABLE",
        "price": {
          "value": 13,
          "originalValue": 17
        },
        "externalCode": "item_BG-1_indoor"
      }
    ]
  },
  "products": null,
  "optionGroups": null,
  "options": null
}'

O conceito de reutilizar entidades já existentes é possível apenas em produtos e grupos de complementos, o complemento pode ser associado a somente um grupo de complemento. Caso o id informado já exista e for enviado no corpo da requisição, o recurso é atualizado.

Descobrindo os itens que não estão a venda no catálogo e entendendo o motivo

Esse endpoint retorna todos os itens que não estão a venda no cardápio com o motivo da restrição: GET /merchants/{merchantId}/catalogs/{catalogId}/unsellableItems

curl --location --request https://merchant-api.ifood.com.br/catalog/v2.0/merchants/1cdfa2d0-6c89-4ca8-a544-3b39009fe03c/catalogs/1cdfa2d0-6c89-4ca8-a544-3b39009fe03c/unsellableItems --header 'Authorization: Bearer TOKEN

Resposta:

{
  "categories": [
    {
      "id": "ccf719e9-8fc3-4264-8dff-832ae9e901a8",
      "status": "AVAILABLE",
      "template": "DEFAULT",
      "restrictions": [],
      "unsellableItems": [
        {
          "id": "32545e4b-6664-411f-83c3-524771750fbd",
          "productId": "400c9fc5-f1bb-4538-a2b5-a6d4a98d1a01",
          "restrictions": [
            "ITEM_PAUSED"
          ]
        },
        {
          "id": "fb3cc740-d1ff-43cf-87ef-22491fe2381b",
          "productId": "a22f334e-90c8-4474-8dfe-48ff3a4affe3",
          "restrictions": [
            "ITEM_PAUSED"
          ]
        },
        {
          "id": "7cb6cc89-bebe-489d-9866-7ff4689b2771",
          "productId": "16744979-0280-473b-ae2b-b671de7ffe9c",
          "restrictions": [
            "ITEM_PAUSED"
          ]
        }
      ]
    },
    {
      "id": "86cbba43-51f7-439c-a3c6-ecd0a7c9f402",
      "status": "UNAVAILABLE",
      "template": "DEFAULT",
      "restrictions": [
        "CATEGORY_PAUSED"
      ],
      "unsellableItems": [
        {
          "id": "a6a608e4-6548-442c-8b9f-9fcb6bcb9ef3",
          "productId": "3a9d9df9-18c7-48d0-b0c6-92fc4b5b2a19",
          "restrictions": [
            "CATEGORY_PAUSED",
            "ITEM_PAUSED"
          ]
        },
        {
          "id": "044abde5-dba4-44f0-b039-0da51ddde2a1",
          "productId": "4b31bae7-e415-42f1-b023-dad5083c1cb2",
          "restrictions": [
            "CATEGORY_PAUSED",
            "ITEM_PAUSED"
          ]
        }
      ]
    }
  ]
}

As restrições possíveis são:

RestriçãoMotivo
CATEGORY_HAS_VIOLATIONFoi detectado algum tipo violação de regras do iFood na categoria
CATEGORY_PAUSEDCategoria pausada
ITEM_PAUSEDItem pausado
ITEM_HAS_VIOLATIONFoi detectado algum tipo violação de regras do iFood no item
ITEM_PRICE_MISSINGItem sem preço
ITEM_AND_OPTIONS_PRICES_MISSINGO valor do item com seus complementos obrigatórios pode ser zero
ITEM_OUT_OF_STOCKItem fora de estoque
INVALID_OPTION_GROUP_MAX_QUANTITYValor máximo de complementos do grupo é menor ou igual a zero
OPTION_GROUP_WITHOUT_AVAILABLE_OPTIONSGrupo de complemento sem complementos vendíveis
OPTION_GROUP_MAX_SMALLER_THAN_MINValor máximo de complementos do grupo é menor que o mínimo
OPTION_GROUP_PAUSEDGrupo de complementos pausado
OPTION_PAUSEDComplemento pausado
OPTION_OUT_OF_STOCKComplemento fora de estoque

Criando um inventário para um produto

curl -X POST "https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/inventory"
-H "accept: application/json" -H "Content-Type: application/json"
-d "{\"productId\":\"ec16fb62-7bdd-43e4-940c-10b5a2845f13\",\"amount\":10}"

Listando o inventário de um produto

curl -X GET "https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/inventory/ec16fb62-7bdd-43e4-940c-10b5a2845f13"
-H "accept: application/json""

Deletando o inventário de um produto

curl -X POST "https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/inventory/batchDelete"
-H "accept: */*" -H "Content-Type: application/json"
-d "{\"productIds\":[\"ec16fb62-7bdd-43e4-940c-10b5a2845f13\"]}"

Alterando preço de itens e complementos em batch - Async

É possível editar o preço em batch pelo productId ou pelo externalCode. O exemplo abaixo utiliza o externalCode, mas caso deseje utilizar o productId basta substituir o campo "externalCode":"burguerX43" por "productId":"058dd32f-3b26-41e9-aa39-30a64d3f2b81". Caso sejam informados o externalCode e productId, a alteração será efetuada apenas considerando o externalCode. Existe o parâmetro opcional catalogContext para informar em qual contexto a alteração será realizada. Caso o parâmetro não seja informado, a alteração será efetivada em todos os contextos que correspondam ao productId ou externalCode informado.

Requisição

    curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/products/price' \
    --header 'accept: application/json' \
    --header 'Content-Type: application/json' \
    --data-raw '[{
	    "externalCode":"burguerX43",
	    "price": {
		    "value":25,
		    "originalValue":30
	    },
	    "resources":["ITEM", "OPTION"]
    }]'
  • Para atualizar apenas ITEM, o campo de resources deve ser igual a "resources":["ITEM"]. O mesmo vale para a OPTIONS.

Resposta

{
  "batchId": "311afcf1-541a-41af-a9a5-4651d676731e",
  "url": "/v2.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/batch/311afcf1-541a-41af-a9a54651d676731e"
}

Alterando status de itens e complementos em batch - Async

É possível editar o status em batch pelo productId ou pelo externalCode. O exemplo abaixo utiliza o externalCode, mas caso deseje utilizar o productId basta substituir o campo "externalCode":"burguerX43" por "productId":"058dd32f-3b26-41e9-aa39-30a64d3f2b81". Caso sejam informados o externalCode e productId, a alteração será efetuada apenas considerando o externalCode. Existe o parâmetro opcional catalogContext para informar em qual contexto a alteração será realizada. Caso o parâmetro não seja informado, a alteração será efetivada em todos os contextos que correspondam ao productId ou externalCode informado.

Requisição

    curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/products/status' \
    --header 'accept: application/json' \
    --header 'Content-Type: application/json' \
    --data-raw '[{
	    "externalCode":"burguerX43",
	    "status": "UNAVAILABLE",
	    "resources":["ITEM", "OPTION"]
    }]'
  • Para atualizar apenas ITEM, o campo de resources deve ser igual a "resources":["ITEM"]. O mesmo vale para a OPTIONS.

Resposta

{
  "batchId": "6762714f-6d58-4eac-8f0f-9b878c8b6c30",
  "url": "/v2.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/batch/6762714f-6d58-4eac-8f0f-9b878c8b6c30"
}

Acompanhando operações em batch

Operações em batch podem ser feitas em situações como, por exemplo, atualização de muitos produtos. Para checar quais operações foram bem sucedidas ou não, e se todo o batch já foi processado, utilizamos a API de listagem de resultados das operações em batch GET /merchants/{merchantId}/batch/{batchId}

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/batch/bca9a293-b121-4027-b3e3-bce675581fbd' \
--header 'Authorization: Bearer TOKEN'

Resultado:

{
  "batchStatus": "COMPLETED",
  "results": [
    {
      "resourceId": "fd1c993b-4882-44e7-8c21-aa7d637ccdf8",
      "result": "SUCCESS"
    },
    {
      "resourceId": "ec16fb62-7bdd-43e4-940c-10b5a2845f13",
      "result": "SUCCESS"
    }
  ]
}

Alterando preço de complemento

Com o endpoint PATCH Option Price é possível editar globalmente o preço de um complemento ao passar o campo de price com o valor desejado, como também para alterá-lo em um cardápio específico, o campo priceByCatalog deve ser preenchido respectivamente com seus valores e o contexto do cardápio alterado.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/options/price' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "optionId": "d3e31829-a215-47e3-9576-3fddec9417ec",
  "price": {
    "value": 5,
    "originalValue": 7,
    "scalePrices": [
      {
        "minQuantity": 5,
        "price": 10
      }
    ]
  },
  "parentCustomizationOptionId": null,
  "priceByCatalog": [
    {
      "value": 5,
      "originalValue": 7,
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Alterando status de complemento

Com comportamento semelhante à alteração de preço, é possível editar globalmente o status de um complemento com o PATCH Option Status ao passar o campo de status com a condição desejada, como também para alterá-lo em um cardápio específico, o campo statusByCatalog deve ser preenchido respectivamente com o estado e o contexto do cardápio alterado.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/options/status' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "optionId": "d3e31829-a215-47e3-9576-3fddec9417ec",
  "status": "AVAILABLE",
  "parentCustomizationOptionId": null,
  "statusByCatalog": [
    {
      "status": "UNAVAILABLE",
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Alterando código externo de complemento

Através do PATCH Option External Code É possível editar globalmente o código externo de um complemento ao passar o campo externalCode com o código desejado, como também para alterá-lo em um cardápio específico, o campo externalCodeByCatalog deve ser preenchido respectivamente com o código e o contexto do cardápio alterado.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/options/externalCode' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "optionId": "d3e31829-a215-47e3-9576-3fddec9417ec",
  "externalCode": "tst-external-code",
  "parentCustomizationOptionId": null,
  "externalCodeByCatalog": [
    {
      "externalCode": "tst-external-code2",
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Alterando preço de item

Semelhante ao endpoint de complementos, é possível editar globalmente o preço de um item com o PATCH Item Price ao passar o campo de price com o valor desejado, como também para alterá-lo em um cardápio específico, o campo priceByCatalog deve ser preenchido respectivamente com seus valores e o contexto do cardápio alterado.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/items/price' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "itemId": "1621d43c-1ac0-4407-9d79-50e974bbcc90",
  "price": {
    "value": 25,
    "originalValue": 30
  },
  "priceByCatalog": [
    {
      "value": 23,
      "originalValue": 27,
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Alterando status de item

Com comportamento semelhante à alteração de preço, é possível editar globalmente o status de um item através do PATCH Item Status ao passar o campo de status com a condição desejada, como também para alterá-lo em um cardápio específico, o campo statusByCatalog deve ser preenchido respectivamente com o estado e o contexto do cardápio alterado.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/items/status' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "itemId": "1621d43c-1ac0-4407-9d79-50e974bbcc90",
  "status": "AVAILABLE",
  "statusByCatalog": [
    {
      "status": "UNAVAILABLE",
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Alterando código externo de item

Com o endpoint PATCH Item External Code é possível editar globalmente o código externo de um item ao passar o campo externalCode com o código desejado, como também para alterá-lo em um cardápio específico, o campo externalCodeByCatalog deve ser preenchido respectivamente com o código e o contexto do cardápio alterado.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/items/externalCode' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "itemId": "d3e31829-a215-47e3-9576-3fddec9417ec",
  "externalCode": "tst-external-code",
  "externalCodeByCatalog": [
    {
      "externalCode": "tst-external-code2",
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Upload de imagens

Para adicionar imagens ao seu produto nos endpoints de POST ou PUT de produto e no endpoint de PUT de item é preciso enviar o campo imagePath do produto preenchido com o retorno do endpoint abaixo: Upload Image:

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/image/upload/' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "image": "data:image/png;base64,imageBase64"
}'

Fazendo o upload da sua imagem por esse endpoint você conseguirá reaproveitar a mesma imagem em vários produtos.
O upload de imagens a partir do campo image com um base64 também continua funcionando para os endpoints de POST e PUT de produto.

Os formatos de imagem suportados são: 'jpg', 'jpeg' e 'png'.

Tamanho da imagem

O tamanho limite de arquivos de imagem (independente do formato) é de 5MB. Requisições (tanto no endpoint de Upload de imagens quanto em outros endpoints) com um corpo de requisição maior que 5MB retornarão com status 413 (Entity Too Large).

Combo

A partir de hoje (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ídeo

Neste 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á apenas em 10/MAR/2025 , após adaptação das integradoras.

As integradoras terão até 16/MAR/2025 para se adaptarem ao combo 3º nível. 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.

Prazos para implementação

  • Integradas de Order + Catálogo: para operar combos de 3º nível a integração de ORDER deve estar preparada para realizar a leitura correta do 3º nível.
  • A partir de Dez/24, caso as duas integrações já estejam adaptadas, será possível solicitar a liberação da feature no Portal.
  • Integrados apenas de Catálogo: a partir de Dez/24, caso a integração de catalogo já esteja atualizada, será possível solicitar a liberação da feature no Portal.

Liberação antecipada - Envio de evidências

O fluxo completo poderá ser testado pela integradora com o MERCHANT TESTE Para finalizar a homologação, basta abrir um ticket enviando a resposta do PUT /merchants/{merchantId}/items ao criar um combo 3º com nível.

image.png

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é MAR/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 API de Catálogo será atualizada em produção até 13/12/2024. A adaptação das integradoras ocorrerá até MAR/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.

Pizza

A API permite utilizar as categorias com template PIZZA assim como é feito no portal do parceiro. Abaixo será apresentado o passo a passo de como cadastrar sua primeira pizza na plataforma do iFood

Estrutura de um item tipo pizza

Um item do tipo pizza contém obrigatoriamente os seguintes grupos de complemento:

  • Tamanhos
    • optionGroupType = SIZE
  • Sabores
    • optionGroupType = TOPPING
  • Massas
    • optionGroupType = CRUST
  • Boardas
    • optionGroupType = EDGE

A alteração dos complementos da Pizza é explicada nas seções:

Relação de sabores e tamanhos

Especificamente para os complementos de sabor é preciso preencher o campo parentCustomizationOptionId ao editar seu preço, status ou código externo.
Esse campo deve ser preenchido com o option.id do tamanho onde o sabor deve ser configurado.

Por exemplo, no endpoint de edição de status de complementos poderíamos fazer essa request:

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/options/status' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "optionId": "c5ed4d9c-0b79-47b6-8333-d50e66e2147a",
  "parentCustomizationOptionId": "1cae92f1-59ad-401c-a889-dd8ce940fd25",
  "statusByCatalog": [
    {
      "status": "UNAVAILABLE",
      "catalogContext": "WHITELABEL"
    },
    {
      "status": "AVAILABLE",
      "catalogContext": "DEFAULT"
    }
  ]
}'

Considerando 1cae92f1-59ad-401c-a889-dd8ce940fd25 como o id da option "Tamanho Grande" e c5ed4d9c-0b79-47b6-8333-d50e66e2147a como o id da option "Calabresa", essa chamada ao endpoint configura o sabor "Calabresa" disponível no "Tamanho Grande" no contexto DEFAULT e indisponível no contexto WHITELABEL.

Na documentação do endpoint PATCH Option ExternalCode disponibilizamos exemplos de requests para alterar external code dos complementos de pizza. A mesma lógica presente lá pode ser reaproveitada para status e preço.

Criando/Editando um item tipo pizza

O endpoint PUT item pode ser utilizado para criar e alterar itens do tipo pizza. Cria-se o item com todas as dependências que o compõem: produtos, grupos de complementos e complementos.

Como mencionado anteriormente, a pizza é um item do tipo PIZZA e deve possuir obrigatoriamente grupos de complementos dos tipos SIZE, CRUST, EDGE e TOPPING. Na criação do item basta omitir o id da categoria que a categoria do tipo pizza é criada automaticamente.

curl --location --request PUT 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/items' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "item": {
        "id": "91de1e0f-3dac-41d2-b9c5-e7de2fa2c20e",
        "type": "PIZZA",
        "status": "AVAILABLE",
        "externalCode": "pizza_item_code",
        "index": 0,
        "productId": "51b644cc-a90c-4456-992f-f86631176796"
    },
    "products": [
        {
            "id": "51b644cc-a90c-4456-992f-f86631176796",
            "externalCode": "pizza_trd_prd_code",
            "name": "Pizzas Tradicionais",
            "optionGroups": [
                {
                    "id": "15af8bd9-6d54-43f2-8c74-43d5d4da32d8",
                    "min": 0,
                    "max": 1
                },
                {
                    "id": "26b1a876-7ee4-4f15-9bb1-d33c840c5049",
                    "min": 0,
                    "max": 1
                },
                {
                    "id": "668a93a9-704e-4036-a515-11e4ddbe4129",
                    "min": 0,
                    "max": 1
                },
                {
                    "id": "d1eed8e6-c1f0-4f09-a235-2d459bb33cbb",
                    "min": 0,
                    "max": 1
                }
            ]
        },
        {
            "id": "9f72cd07-4463-4bfc-8fc1-97129c775e21",
            "externalCode": "massa_trd_prd_code",
            "name": "Massa Tradicional"
        },
        {
            "id": "c8eff6c6-f3c5-48ec-9a5b-aa5b3eeec582",
            "externalCode": "massa_fin_prd_code",
            "name": "Massa fina"
        },
        {
            "id": "27fa98cd-e119-432d-9b0a-8f99a65be1b7",
            "externalCode": "t_m_prd_code",
            "name": "Tamanho médio",
            "quantity": 8,
            "imagePath": "41a3aa60-4b00-4da1-a3c6-c4eaa9544f07/202406201149_4y1nlgnr7a10.png"
        },
        {
            "id": "932e18a2-396d-40d2-8de4-da0cf8f95faf",
            "externalCode": "t_g_prd_code",
            "name": "Tamanho Grande",
            "quantity": 12,
            "imagePath": "41a3aa60-4b00-4da1-a3c6-c4eaa9544f07/202406201150_5z2uxvlq5b34.png"
        },
        {
            "id": "e4ac0247-33ed-476a-ae69-363f27fe0df7",
            "externalCode": "brd_trd_prd_code",
            "name": "Borda Tradicional"
        },
        {
            "id": "eb021b00-0fef-434b-9da5-77e4dbca047e",
            "externalCode": "brd_rech_prd_code",
            "name": "Borda Recheada"
        },
        {
            "id": "d6ae0c15-4db9-454e-868b-a9ec7719da5e",
            "externalCode": "calabresa_prd_code",
            "name": "Calabresa"
        },
        {
            "id": "b4a093cc-7e4a-49d2-909a-fed1cc58c572",
            "externalCode": "marguerita_prd_code",
            "name": "Marguerita"
        }
    ],
    "optionGroups": [
        {
            "id": "15af8bd9-6d54-43f2-8c74-43d5d4da32d8",
            "name": "Tamanhos",
            "externalCode": "tamanhos_code",
            "status": "AVAILABLE",
            "index": 0,
            "optionGroupType": "SIZE",
            "optionIds": [
                "945ef3bc-7741-4bec-a0ce-4660c09a564f",
                "2587c76e-3aa3-45e6-95d9-35c21ac19f9d"
            ]
        },
        {
            "id": "26b1a876-7ee4-4f15-9bb1-d33c840c5049",
            "name": "Massas",
            "externalCode": "massas_code",
            "status": "AVAILABLE",
            "index": 0,
            "optionGroupType": "CRUST",
            "optionIds": [
                "7fb0eac3-43e5-41c6-860e-a38793db4988",
                "d0d0df88-b276-4a21-ab14-063e8f0c3c5d"
            ]
        },
        {
            "id": "668a93a9-704e-4036-a515-11e4ddbe4129",
            "name": "Bordas",
            "externalCode": "bordas_code",
            "status": "AVAILABLE",
            "index": 0,
            "optionGroupType": "EDGE",
            "optionIds": [
                "cc71b438-523f-49ac-918a-82df71244f9b",
                "df8728b2-7773-486b-aa93-47627bdd0c54"
            ]
        },
        {
            "id": "d1eed8e6-c1f0-4f09-a235-2d459bb33cbb",
            "name": "Sabores",
            "externalCode": "sabores_code",
            "status": "AVAILABLE",
            "index": 0,
            "optionGroupType": "TOPPING",
            "optionIds": [
                "0d58a046-1871-433d-bd8d-2b33abfbfa70",
                "a4eb62d0-ca33-459e-82b1-4de25997ba9e"
            ]
        }
    ],
    "options": [
        {
            "id": "945ef3bc-7741-4bec-a0ce-4660c09a564f",
            "status": "AVAILABLE",
            "productId": "27fa98cd-e119-432d-9b0a-8f99a65be1b7",
            "fractions": [
                1
            ],
            "externalCode": "medio_option_code"
        },
        {
            "id": "2587c76e-3aa3-45e6-95d9-35c21ac19f9d",
            "status": "AVAILABLE",
            "productId": "932e18a2-396d-40d2-8de4-da0cf8f95faf",
            "fractions": [
                1,
                2
            ],
            "externalCode": "grande_option_code"
        },
        {
            "id": "0d58a046-1871-433d-bd8d-2b33abfbfa70",
            "status": "AVAILABLE",
            "index": 0,
            "productId": "d6ae0c15-4db9-454e-868b-a9ec7719da5e",
            "contextModifiers": [
                {
                    "parentOptionId": "945ef3bc-7741-4bec-a0ce-4660c09a564f",
                    "catalogContext": "WHITELABEL",
                    "status": "AVAILABLE",
                    "price": {
                        "value": 26,
                        "originalValue": 30
                    },
                    "externalCode": "calabresa_medio_whitelabel_code"
                },
                {
                    "parentOptionId": "2587c76e-3aa3-45e6-95d9-35c21ac19f9d",
                    "catalogContext": "WHITELABEL",
                    "status": "AVAILABLE",
                    "price": {
                        "value": 25,
                        "originalValue": 29
                    },
                    "externalCode": "calabresa_grande_whitelabel_code"
                },
                {
                    "parentOptionId": "945ef3bc-7741-4bec-a0ce-4660c09a564f",
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE",
                    "price": {
                        "value": 24,
                        "originalValue": 28
                    },
                    "externalCode": "calabresa_medio_default_code"
                },
                {
                    "parentOptionId": "2587c76e-3aa3-45e6-95d9-35c21ac19f9d",
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE",
                    "price": {
                        "value": 23,
                        "originalValue": 27
                    },
                    "externalCode": "calabresa_grande_default_code"
                }
            ],
            "externalCode": "calabresa_option_code"
        },
        {
            "id": "a4eb62d0-ca33-459e-82b1-4de25997ba9e",
            "status": "AVAILABLE",
            "index": 0,
            "productId": "b4a093cc-7e4a-49d2-909a-fed1cc58c572",
            "contextModifiers": [
                {
                    "parentOptionId": "945ef3bc-7741-4bec-a0ce-4660c09a564f",
                    "catalogContext": "WHITELABEL",
                    "status": "AVAILABLE",
                    "price": {
                        "value": 23,
                        "originalValue": 28
                    },
                    "externalCode": "marguerita_medio_whitelabel_code"
                },
                {
                    "parentOptionId": "2587c76e-3aa3-45e6-95d9-35c21ac19f9d",
                    "catalogContext": "WHITELABEL",
                    "status": "AVAILABLE",
                    "price": {
                        "value": 20,
                        "originalValue": 25
                    },
                    "externalCode": "marguerita_grande_whitelabel_code"
                },
                {
                    "parentOptionId": "945ef3bc-7741-4bec-a0ce-4660c09a564f",
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE",
                    "price": {
                        "value": 22,
                        "originalValue": 27
                    },
                    "externalCode": "marguerita_medio_default_code"
                },
                {
                    "parentOptionId": "2587c76e-3aa3-45e6-95d9-35c21ac19f9d",
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE",
                    "price": {
                        "value": 24,
                        "originalValue": 26
                    },
                    "externalCode": "marguerita_grande_default_code"
                }
            ],
            "externalCode": "marguerita_option_ec"
        },
        {
            "id": "cc71b438-523f-49ac-918a-82df71244f9b",
            "status": "AVAILABLE",
            "productId": "e4ac0247-33ed-476a-ae69-363f27fe0df7",
            "price": {
                "value": 0,
                "originalValue": 0
            },
            "externalCode": "borda_trad_option_code"
        },
        {
            "id": "df8728b2-7773-486b-aa93-47627bdd0c54",
            "status": "AVAILABLE",
            "productId": "eb021b00-0fef-434b-9da5-77e4dbca047e",
            "price": {
                "value": 4,
                "originalValue": 5
            },
            "externalCode": "borda_rec_option_code"
        },
        {
            "id": "7fb0eac3-43e5-41c6-860e-a38793db4988",
            "status": "AVAILABLE",
            "productId": "9f72cd07-4463-4bfc-8fc1-97129c775e21",
            "price": {
                "value": 2,
                "originalValue": 3
            },
            "externalCode": "massa_trad_option_code"
        },
        {
            "id": "d0d0df88-b276-4a21-ab14-063e8f0c3c5d",
            "status": "AVAILABLE",
            "productId": "c8eff6c6-f3c5-48ec-9a5b-aa5b3eeec582",
            "price": {
                "value": 2,
                "originalValue": 3
            },
            "externalCode": "massa_fin_option_code"
        }
    ]
}'

Alterando preço de complemento de pizza

Através do endpoint PATCH Option Price é possível editar globalmente o preço de um complemento ao passar o campo de price com o valor desejado, como também para alterá-lo em um cardápio específico, o campo priceByCatalog deve ser preenchido respectivamente com seus valores e o contexto do cardápio alterado. Para alterar o preço de um sabor em determinado tamanho, basta informar o parentCustomizationOptionId.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/options/price' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "optionId": "a4eb62d0-ca33-459e-82b1-4de25997ba9e",
  "parentCustomizationOptionId": "945ef3bc-7741-4bec-a0ce-4660c09a564f",
  "priceByCatalog": [
    {
      "value": 5,
      "originalValue": 7,
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Alterando status de complemento de pizza

Com comportamento semelhante à alteração de preço, é possível editar globalmente o status de um complemento com o PATCH Option Status ao passar o campo de status com a condição desejada, como também para alterá-lo em um cardápio específico, o campo statusByCatalog deve ser preenchido respectivamente com o estado e o contexto do cardápio alterado. Para alterar o preço de um sabor em determinado tamanho, basta informar o parentCustomizationOptionId.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/options/status' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "optionId": "a4eb62d0-ca33-459e-82b1-4de25997ba9e",
  "status": "AVAILABLE",
  "parentCustomizationOptionId": "945ef3bc-7741-4bec-a0ce-4660c09a564f",
  "statusByCatalog": [
    {
      "status": "UNAVAILABLE",
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Alterando código externo de complemento de pizza

Utilizando o PATCH Option External Code é possível editar globalmente o código externo de um complemento da pizza ao passar o campo externalCode com o código desejado, como também para alterá-lo em um cardápio específico, o campo externalCodeByCatalog deve ser preenchido respectivamente com o código e o contexto do cardápio alterado. Para alterar o código de um sabor em determinado tamanho, basta informar o parentCustomizationOptionId.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/options/externalCode' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "optionId": "d3e31829-a215-47e3-9576-3fddec9417ec",
  "externalCode": "tst-external-code",
  "parentCustomizationOptionId": null,
  "externalCodeByCatalog": [
    {
      "externalCode": "tst-external-code2",
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Critérios de homologação