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

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