Conceitos

O que é o módulo multi setup?

O módulo Multi Setup tem o propósito de unificar a visão de vários cardápios, ao contrário do módulo base, no Multi Setup, todos os itens serão os mesmos em todos os cardápios, dessa forma o parceiro só precisa ajustar o preço e status de cada cardápio.

O que muda na API?

Para Parceiros que possuem apenas um cardápio

As APIs são retrocompatíveis, ou seja, funcionarão da mesma forma, com exceção à API de pizza que agora passa a ser tratada como um item normal.

Para Parceiros que possuem mais de um cardápio

Agora ao utilizar as APIs públicas, deverá ser passado um novo parâmetro informando o contexto que aquele request irá afetar. O contexto é o serviço ao qual aquele catálogo é destinado. É possível encontrar o contexto no request de listar catálogos.

Dessa forma será possível criar/editar itens, editar status e preços apenas para o contexto informado, caso o contexto não seja informado a alteração será feita globalmente, ou seja, para todos os contextos.

Como isso funciona na prática?

Todas as categorias e itens irão existir em todos os cardápios, caso o parceiro crie um novo item informando um contexto, esse item será criado com o status AVAILABLE apenas no contexto informado, os outros contextos terão o item com o status UNAVAILABLE.

Preços e Status Globais

Nas alterações de preços e status, caso o parâmetro de contexto não seja informado, a alteração terá efeito em todos os contextos.

Informações importantes

O módulo de multi Setup possui APIs exclusivas para a gestão do cardápio. Ainda será possível utilizar as APIs atuais para fazer a gestão do cardápio, mas elas serão depreciadas após todos os parceiros aderirem ao módulo Multi Setup.

As APIs de Pizza NÃO possuem retrocompatibilidade com no módulo Multi Setup, a gestão de itens do tipo Pizza não é mais feita de forma específica. Confira a seção Criando/Editando um item deste documento.

Por que utilizar o módulo Multi Setup?

Com esse módulo ativo os parceiros que têm mais de um cardápio, conseguiram gerenciar mais facilmente seus cardápios, conseguindo reutilizar facilmente os itens com a flexibilidade de customização de preços, status, código PDV e horário de funcionamento por cardápio. As novas APIs são acessíveis através do módulo MultiSetup, veja as novas APIs na seção Multisetup.

Utilizando a API

Criando/Editando um item

A criação de um item disponibilizada pelo módulo Multi Setup é válida 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. O tipo Pizza diferencia-se apenas através do type do item e dos grupos de complementos. É obrigatório que uma item do tipo pizza tenha grupos de complementos dos tipos SIZE, CRUST e EDGE.

Exemplo - Item padrão:

curl --location --request PUT 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/21131c93-0398-4818-aad3-762cab309a26/multisetup/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": "2245a961-849d-443c-a434-0197a7b8116c/202309201054_160d37znvk6.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",
      "imagePath": 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"
    }
  ]
}'

Exemplo - Item Pizza:

curl --location --request PUT 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/21131c93-0398-4818-aad3-762cab309a26/multisetup/items' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "item": {
    "id": "8e82f81f-6b0f-4e7b-9185-b3a5c57d19b0",
    "type": "PIZZA",
    "status": "AVAILABLE",
    "externalCode": "pizza_item_ec",
    "index": 0,
    "productId": "171ad402-1611-4b5f-9af5-3a7ad28a58b6"
  },
  "products": [
    {
      "id": "171ad402-1611-4b5f-9af5-3a7ad28a58b6",
      "externalCode": "pizza_product_ec",
      "name": "Pizza",
      "description": "massa, queijo mussarela e molho de tomate",
      "additionalInformation": "some additional Information",
      "optionGroups": [
        {
          "id":"f24249ff-7f5c-4d53-a170-72f9f32091d9",
          "min": 0,
          "max": 1
        },
        {
          "id":"c24423b4-6b95-4002-a775-b4b3b3037bb6",
          "min": 0,
          "max": 1
        },
        {
          "id":"04bde4c8-28c7-43c9-b240-9205f4e95c26",
          "min": 0,
          "max": 1
        },
        {
          "id":"0b2a2f4d-ce33-4b46-888f-971792837fb2",
          "min": 0,
          "max": 1
        }
      ]
    },
    {
      "id": "8dd12ae1-55a1-431c-ba3a-19ec3d7c35dc",
      "externalCode": "crust_product_ec",
      "name": "Massa Tradicional"
    },
    {
      "id": "d3f65c66-4259-427d-a6bd-30e4df212d46",
      "externalCode": "size_product_ec",
      "name": "Tamanho médio"
    },
    {
      "id": "4b222dbd-aa8d-4f8e-ab7a-df65fb44f7ab",
      "externalCode": "edge_product_ec",
      "name": "Borda Tradicional"
    },
    {
      "id": "4c77015c-820a-495c-82a9-28a111258a37",
      "externalCode": "topping_product_ec",
      "name": "Calabresa"
    }
  ],
  "optionGroups": [
    {
      "id": "f24249ff-7f5c-4d53-a170-72f9f32091d9",
      "name": "Tamanhos",
      "externalCode": "tamanhos_ec",
      "status": "AVAILABLE",
      "index": 0,
      "optionGroupType": "SIZE",
      "optionIds": [
        "1cae92f1-59ad-401c-a889-dd8ce940fd25"
      ]
    },
    {
      "id": "c24423b4-6b95-4002-a775-b4b3b3037bb6",
      "name": "Massas",
      "externalCode": "massas_ec",
      "status": "AVAILABLE",
      "index": 0,
      "optionGroupType": "CRUST",
      "optionIds": [
        "9603ad69-5c48-4da6-a703-21bf7d1232c0"
      ]
    },
    {
      "id": "04bde4c8-28c7-43c9-b240-9205f4e95c26",
      "name": "Bordas",
      "externalCode": "bordas_ec",
      "status": "AVAILABLE",
      "index": 0,
      "optionGroupType": "EDGE",
      "optionIds": [
        "54171c89-dbcb-47ea-89c1-131b32d70307"
      ]
    },
    {
      "id": "0b2a2f4d-ce33-4b46-888f-971792837fb2",
      "name": "Sabores",
      "externalCode": "sabores_ec",
      "status": "AVAILABLE",
      "index": 0,
      "optionGroupType": "TOPPING",
      "optionIds": [
        "c5ed4d9c-0b79-47b6-8333-d50e66e2147a"
      ]
    }
  ],
  "options": [
    {
      "id": "1cae92f1-59ad-401c-a889-dd8ce940fd25",
      "status": "AVAILABLE",
      "productId": "d3f65c66-4259-427d-a6bd-30e4df212d46",
      "price": {
        "value": 4,
        "originalValue": 7
      },
      "fractions": [2,3],
      "externalCode": "medio_option_ec"
    },
    {
      "id": "c5ed4d9c-0b79-47b6-8333-d50e66e2147a",
      "status": "AVAILABLE",
      "index": 0,
      "productId": "4c77015c-820a-495c-82a9-28a111258a37",
      "contextModifiers": [
        {
          "parentOptionId": "1cae92f1-59ad-401c-a889-dd8ce940fd25",
          "catalogContext": "WHITELABEL",
          "status": "AVAILABLE",
          "price": {
            "value": 25,
            "originalValue": 30
          },
          "externalCode": "calabresa_medio_whitelabel_ec"
        }
      ],
      "externalCode": "calabresa_option_ec"
    },
    {
      "id": "54171c89-dbcb-47ea-89c1-131b32d70307",
      "status": "AVAILABLE",
      "productId": "4b222dbd-aa8d-4f8e-ab7a-df65fb44f7ab",
      "price": {
        "value": 4,
        "originalValue": 5
      },
      "externalCode": "borda_option_ec"
    },
    {
      "id": "9603ad69-5c48-4da6-a703-21bf7d1232c0",
      "status": "AVAILABLE",
      "productId": "8dd12ae1-55a1-431c-ba3a-19ec3d7c35dc",
      "price": {
        "value": 2,
        "originalValue": 3
      },
      "externalCode": "massa_option_ec"
    }
  ]
}'

Listando itens

Informando o id de uma categoria existente, serão listados todos os itens, produtos, grupos de complementos e complementos disponíveis na mesma.

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/21131c93-0398-4818-aad3-762cab309a26/multisetup/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":[
            {
               "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",
         "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,
         "optionGroupIds":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"
      }
   ]
}

Deletando uma categoria

A deleção de uma categoria elimina ela e seu conteúdo de todos os contextos.

curl --location --request DELETE 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/21131c93-0398-4818-aad3-762cab309a26/multisetup/categories/' \
--header 'Authorization: Bearer TOKEN'

Alterando preço de complemento

É 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/v1.0/merchants/21131c93-0398-4818-aad3-762cab309a26/multisetup/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 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/v1.0/merchants/21131c93-0398-4818-aad3-762cab309a26/multisetup/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"
    }
  ]
}'

Deletando um grupo de complemento

A deleção de um grupo de complemento remove o grupo e seus complementos de todos os contextos.

curl --location --request DELETE 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/21131c93-0398-4818-aad3-762cab309a26/multisetup/optionGroups/' \
--header 'Authorization: Bearer TOKEN'