logo
logo

Docs Shelves

Módulo Exclusivo Esse módulo é de uso exclusivo e só está disponível para algumas integradoras. Caso tenha interesse em utilizar funções dessa API, entre em contato com o nosso time de atendimento.

Definições

Grupo de Corredores (Aisle Group) - Modelo de Negócio

O grupo de corredor seria o modelo de negócio (Mercado, Farmácia, Petshop etc) que tem a função de agrupar determinados corredores criados num departamento. Em outras palavras, a forma como os produtos comercializados de um parceiro serão exibidos no aplicativo depende do seu modelo de negócio.

Corredores (Aisles)

Organiza o modo como os produtos comercializados serão dispostos para cada modelo de negócio, especificando a posição que o mesmo ocupará no aplicativo.

Cada corredor representa uma forma de agrupamento de produtos similares. Um exemplo de corredor seria o corredor de BEBIDAS, contemplando refrigerantes, bebidas alcoólicas, água, etc. Em BEBIDAS é possível ainda abstrair subgrupos em corredores mais específicos, como REFRIGERANTES, BEBIDAS ALCOÓLICAS E ÁGUAS. Na parte de ÁGUAS, ainda é possível separar em ÁGUA_COM_GÁS e ÁGUA_SEM_GÁS.

Logo para encontrar o produto 'Água com gás Crystal,' uma sequência lógica de navegação no aplicativo seria:

1 - Clicar em BEBIDAS.
2 - Clicar em ÁGUAS.
3 - Clicar em ÁGUA_COM_GÁS.

Para modelar esse comportamento foram criados os corredores, que podem se associar com uma relação de inclusão. Cada corredor pode estar contido em algum outro mais abrangente, até chegar num nível mais genérico como BEBIDAS.

EX:  BEBIDAS <-- ÁGUAS <-- ÁGUA_COM_GÁS.

Depois da estrutura de corredores ter sido criada, basta adicionar os produtos a elas. Isto é feito adicionando uma relação corredor-produto com o nível mais específico de corredor, no exemplo acima seria ÁGUA_SEM_GÁS.

Observações:

  • Um mesmo produto pode estar presente em vários corredores simultaneamente, mas disposto diferentemente, dependendo do seu modelo de negócio. Um exemplo seria com os modelos de negócio Mercado e Farmácia e com o produto 'Bala Fini Tubes'. No Mercado, esse produto se encontraria em [SNACKS -> BOMBONIERE -> BALAS], enquanto na Farmácia encontraríamos o mesmo produto em [CONVENIÊNCIA <-- DOCES <-- BALAS DE GELATINA].

  • Ao alterar um corredor ou um produto do corredor, todos os itens relacionados ao mesmo serão impactados. Em um caso que um produto é trocado de corredor (exemplo: Bala Fini Tube passar a ser do corredor de Balas de Gelatina), ainda que seja o mesmo, por ter sido modificado causará impacto nos itens associados.

Prateleira (Shelf)

As prateleiras do catálogo são uma forma de gerência de produtos, geralmente industrializados, que não mudam de um estabelecimento para outro. Por exemplo, a Coca-Cola lata (EAN 7894900709841) será a mesma, independente do estabelecimento que a vende. O mesmo vale para refrigerantes latas de outros sabores ou marcas.

Logo é possível criar uma prateleira chamada "REFRIGERANTE_LATAS" para agrupar esse tipo de produto. Também é possível gerir diversas prateleiras, mas agrupando por um domínio ou origem específica. Esse agrupamento pode ser feito através da utilização de um prefixo em comum, como no exemplo abaixo.

Produto de Prateleira

Os produtos de prateleira seguem a mesma estrutura que os produtos descritos nas APIs de catálogo, mas com as seguintes distinções:

  • O parâmetro EAN (European Article Number) é obrigatório e único na base do ifood. Caso tente cadastrar um produto com o ean já existente é possível obter o UUID desse produto pelo endpoint GET /merchants/{merchantId}/shelf/products/{ean}. Em sequência usar o endpoint POST /merchants/{merchantId}/shelf/link/products/{productId} para adicioná-lo à prateleira.

  • O merchant deve ser owner de todas as prateleiras presentes no campo shelfIds no payload do produto a ser criado.

  • Um mesmo produto, com um determinado ean, pode estar presente em várias prateleiras em simultâneo.

Limite de Requisições e Tempo Mínimo para Disponibilização de Mudanças.

Normalmente quando um produto normal é atualizado, isso gera alguns eventos que disparam o fluxo de disponibilização de conteúdo do catálogo, para cada atualização em um item, temos um evento correspondente. Quando baixamos um pouco o nível do produto, se o mesmo for compartilhado, mais de um evento pode ser gerado. Entretanto, isso não era um problema porque produtos só podiam ser compartilhados dentro de um mesmo merchant, limitando a quantidade de eventos. Com a adição de produtos de prateleira, produtos agora podem ser compartilhados entre vários merchants. Isso implica que a atualização de um único produto pode gerar uma grande quantidade de eventos. De acordo com uma análise no piloto de produtos de prateleira, o número de eventos pode ser algo em torno de 20 mil.

Para garantir o funcionamento do fluxo normal de disponibilização do catálogo, rate limiters podem ser aplicados com objetivo de controlar o impacto que os fluxos de atualização de produto de prateleira podem causar, além de garantir uma quantidade de eventos dentro do que o catálogo consegue processar. Em adição, alterações de produto terão uma menor prioridade e um tempo mínimo de 10 minutos até que os resultados se tornem live.

  • APIs com rate limiters
    • PUT /merchants/{merchantId}/shelf/products/{productId}
    • PUT /merchants/{merchantId}/aisle
    • POST /merchants/{merchantId}/aisle/{aisleId}/link/products/{productId}
    • DELETE /merchants/{merchantId}/aisle/{aisleId}/link/products/{productId}

Utilizando a API - Aisles

Para exemplificar vamos mostrar como criar corredores com níveis de profundidade e atribuí-los a um grupo de corredores

Criando Grupo de Corredores - Modelo de Negócio

Requisição:

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v1.0/{merchantId}/aisle/group' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Mercado"
}'

Resposta:

{
  "id": "a434c6ba-5f41-4197-8c6b-4174061e218c",
  "name": "Mercado"
}

Criando e Associando Corredores

  • Criando os Corredores [BEBIDAS <- ÁGUAS <- ÁGUA COM GÁS] no Aisle Group Mercado

Requisição:

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v1.0/{merchantId}/aisle' \
--header 'Content-Type: application/json' \
--data-raw '{
    "aisleGroupId": "a434c6ba-5f41-4197-8c6b-4174061e218c",
    "upperAisleId": null,
    "name": "BEBIDAS"
}'

Resposta:

{
  "id": "93577a52-909f-43e2-852b-5255ce3c867c",
  "name": "BEBIDAS",
  "aisleGroupId": "a434c6ba-5f41-4197-8c6b-4174061e218c"
}

Requisição:

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v1.0/{merchantId}/aisle' \
--header 'Content-Type: application/json' \
--data-raw '{
    "aisleGroupId": "a434c6ba-5f41-4197-8c6b-4174061e218c",
    "upperAisleId": "93577a52-909f-43e2-852b-5255ce3c867c",
    "name": "ÁGUAS"
}'

Resposta:

{
  "id": "af5532cb-027f-4dc8-bdfc-e3d70057a6a7",
  "name": "ÁGUAS",
  "aisleGroupId": "a434c6ba-5f41-4197-8c6b-4174061e218c",
  "upperAisleId": "93577a52-909f-43e2-852b-5255ce3c867c"
}

Requisição:

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v1.0/{merchantId}/aisle' \
--header 'Content-Type: application/json' \
--data-raw '{
    "aisleGroupId": "a434c6ba-5f41-4197-8c6b-4174061e218c",
    "upperAisleId": "af5532cb-027f-4dc8-bdfc-e3d70057a6a7",
    "name": "ÁGUA COM GÁS"
}'

Resposta:

{
  "id": "1c521d36-82d6-47f8-b3cf-43168224130d",
  "name": "ÁGUA COM GÁS",
  "aisleGroupId": "a434c6ba-5f41-4197-8c6b-4174061e218c",
  "upperAisleId": "af5532cb-027f-4dc8-bdfc-e3d70057a6a7"
}
  • Criando os Corredores [BEBIDAS <- REFRIGERANTES <- LATA] no Aisle Group Mercado

Requisição:

Note que o corredor BEBIDAS (93577a52-909f-43e2-852b-5255ce3c867c) já está criado, então vamos utilizá-lo.

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v1.0/{merchantId}/aisle' \
--header 'Content-Type: application/json' \
--data-raw '{
    "aisleGroupId": "a434c6ba-5f41-4197-8c6b-4174061e218c",
    "upperAisleId": "93577a52-909f-43e2-852b-5255ce3c867c",
    "name": "REFRIGERANTES"
}'

Resposta:

{
  "id": "85a44db5-49c3-4aaa-8f71-1ecd3b926d19",
  "name": "REFRIGERANTES",
  "aisleGroupId": "a434c6ba-5f41-4197-8c6b-4174061e218c",
  "upperAisleId": "93577a52-909f-43e2-852b-5255ce3c867c"
}

Requisição:

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v1.0/{merchantId}/aisle' \
--header 'Content-Type: application/json' \
--data-raw '{
    "aisleGroupId": "a434c6ba-5f41-4197-8c6b-4174061e218c",
    "upperAisleId": "85a44db5-49c3-4aaa-8f71-1ecd3b926d19",
    "name": "LATA"
}'

Resposta:

{
  "id": "ec28299e-615f-4517-83ea-35b9cacbbd3e",
  "name": "LATA",
  "aisleGroupId": "a434c6ba-5f41-4197-8c6b-4174061e218c",
  "upperAisleId": "af5532cb-027f-4dc8-bdfc-e3d70057a6a7"
}

Associando um Catálogo a um Aisle Group.

Através do endpoint de PUT de catálogo, são passados o UUID do catálogo e do grupo de corredores que se deseja associar.

Requisição:

curl --location -g --request PUT 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/{{merchantId}}/catalog/{{catalogId}}?aisleGroupId=a434c6ba-5f41-4197-8c6b-4174061e218c' \
--header 'Authorization: Bearer {{accessToken}}'

Utilizando a API - Shelves

Para exemplificar vamos mostrar como cadastrar 3 prateleiras, criar e associar alguns produtos nas prateleiras.

Criando Prateleiras

Requisição:

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/shelf' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "name": "SM_REFRIGERANTE_LATA",
        "merchantIds": ["411347fb-adc5-456f-95be-03cf10a5b8b5"]
    },
    {
        "name": "SM_REFRIGERANTES",
        "merchantIds": ["411347fb-adc5-456f-95be-03cf10a5b8b5"]
    },
        {
        "name": "SM_SALGADOS",
        "merchantIds": ["411347fb-adc5-456f-95be-03cf10a5b8b5"]
    },
        {
        "name": "SM_LATICINIOS",
        "merchantIds": ["411347fb-adc5-456f-95be-03cf10a5b8b5"]
    }
]'

Resposta

[
  {
    "shelfId": "5e3620fa-b284-4e11-8212-219cc454899c",
    "name": "SM_REFRIGERANTE_LATA",
    "merchantIds": ["411347fb-adc5-456f-95be-03cf10a5b8b5"]
  },
  {
    "shelfId": "57979638-1245-4fae-afa2-106b1a3cd4fc",
    "name": "SM_REFRIGERANTES",
    "merchantIds": ["411347fb-adc5-456f-95be-03cf10a5b8b5"]
  },
  {
    "shelfId": "2f7bacdf-dce0-49ff-aa86-32bb1146e2f0",
    "name": "SM_SALGADOS",
    "merchantIds": ["411347fb-adc5-456f-95be-03cf10a5b8b5"]
  },
  {
    "shelfId": "4200f0be-4f0c-491d-9bec-4dc795a8c2f9",
    "name": "SM_LATICINIOS",
    "merchantIds": ["411347fb-adc5-456f-95be-03cf10a5b8b5"]
  }
]

Listando as Prateleiras com Prefixo 'SM'.

Requisição:

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/shelf?prefixName=SM'

Resposta:

[
  {
    "shelfId": "5e3620fa-b284-4e11-8212-219cc454899c",
    "name": "SM_REFRIGERANTE_LATA",
    "merchantIds": ["411347fb-adc5-456f-95be-03cf10a5b8b5"]
  },
  {
    "shelfId": "57979638-1245-4fae-afa2-106b1a3cd4fc",
    "name": "SM_REFRIGERANTES",
    "merchantIds": ["411347fb-adc5-456f-95be-03cf10a5b8b5"]
  },
  {
    "shelfId": "2f7bacdf-dce0-49ff-aa86-32bb1146e2f0",
    "name": "SM_SALGADOS",
    "merchantIds": ["411347fb-adc5-456f-95be-03cf10a5b8b5"]
  },
  {
    "shelfId": "4200f0be-4f0c-491d-9bec-4dc795a8c2f9",
    "name": "SM_LATICINIOS",
    "merchantIds": ["411347fb-adc5-456f-95be-03cf10a5b8b5"]
  }
]

Criando Produtos nas Prateleiras.

Para propósito de teste, todos os EANs utilizados são fakes e não correspondem aos produtos descritos.

  • SM_REFRIGERANTE_LATA

Requisição:

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/shelf/products' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Refrigerante Lata Coca Cola",
"serving": "SERVES_1",
"ean": "7894900910015",
"shelfIds": ["5e3620fa-b284-4e11-8212-219cc454899c"],
"externalCode": "PDV-1",
"image": ""
}'

Resposta:

{
  "id": "829fc9ba-8d75-4afb-bb6f-19c22b107f3d",
  "name": "Refrigerante Lata Coca Cola",
  "externalCode": "PDV-1",
  "shelfIds": ["5e3620fa-b284-4e11-8212-219cc454899c"],
  "image": "",
  "serving": "SERVES_1",
  "dietaryRestrictions": [],
  "ean": "9022916495672",
  "shifts": []
}
  • SM_SALGADOS

Requisição:

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/shelf/products' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Ruffles",
"serving": "SERVES_1",
"ean": "3458466482644",
"shelfIds": ["2f7bacdf-dce0-49ff-aa86-32bb1146e2f0"],
"externalCode": "PDV-2",
"image": ""
}'

Resposta:

{
  "id": "b402166d-d094-4e94-9b5f-f8f9ce573311",
  "name": "Ruffles",
  "externalCode": "PDV-2",
  "shelfIds": ["2f7bacdf-dce0-49ff-aa86-32bb1146e2f0"],
  "image": "",
  "serving": "SERVES_1",
  "dietaryRestrictions": [],
  "ean": "3458466482644",
  "shifts": []
}

Requisição:

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/shelf/products' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Manteiga",
"ean": "4960608528039",
"shelfIds": ["4200f0be-4f0c-491d-9bec-4dc795a8c2f9"],
"externalCode": "PDV-3",
"image": ""
}'

Resposta:

{
  "id": "b402166d-d094-4e94-9b5f-f8f9ce573311",
  "name": "Manteiga",
  "externalCode": "PDV-2",
  "shelfIds": ["4200f0be-4f0c-491d-9bec-4dc795a8c2f9"],
  "image": "",
  "dietaryRestrictions": [],
  "ean": "4960608528039",
  "shifts": []
}

Buscando um EAN Existente para Linkar em 'SM_REFRIGERANTES'.

Vamos supor que queremos adicionar o produto 'Refrigerante Lata Coca Cola' com EAN 7894900910015, mas ele já está cadastrado. Tentar cadastrar o mesmo produto 2 vezes retornaria erro de conflito. Nesse caso basta saber qual o UUID do produto com esse EAN e adicioná-lo à prateleira SM_REFRIGERANTES.

  • Buscar o UUID do produto

Requisição:

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/shelf/products/7894900910015' \

Resposta:

[{ "productId": "719932a7-f340-4077-84bd-d01c7a2399c1", "shelfIds": ["c3309cdf-b9de-4fc9-b5c7-ca04faaabb08"] }]
  • Adicionar o produto na prateleira SM_REFRIGERANTES

Requisição:

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/shelf/link/products/719932a7-f340-4077-84bd-d01c7a2399c1' \
--header 'Content-Type: application/json' \
--data-raw '[
    "57979638-1245-4fae-afa2-106b1a3cd4fc"
]'

Resposta:

{
  "linked": ["719932a7-f340-4077-84bd-d01c7a2399c1"],
  "failed": []
}

Editando um Produto.

Através do endpoint de PUT é possível atualizar um produto. Porém alguns campos não podem ser mudados, como o EAN.

curl --location --request PUT 'https://merchant-api.ifood.com.br/catalog/v1.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/shelf/products' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": "829fc9ba-8d75-4afb-bb6f-19c22b107f3d",
"name": "Refrigerante Lata Coca Cola 350ml",
"serving": "SERVES_1",
"ean": "7894900910015",
"shelfIds": ["5e3620fa-b284-4e11-8212-219cc454899c"],
"aislesIds": ["ec28299e-615f-4517-83ea-35b9cacbbd3e"],
"description": "Novo Design",
"externalCode": "PDV-333",
"image": ""
}'

Resposta:

{
  "id": "829fc9ba-8d75-4afb-bb6f-19c22b107f3d",
  "name": "Refrigerante Lata Coca Cola 350ml",
  "externalCode": "PDV-333",
  "shelfIds": ["5e3620fa-b284-4e11-8212-219cc454899c"],
  "image": "",
  "serving": "SERVES_1",
  "description": "Novo Design",
  "dietaryRestrictions": [],
  "ean": "9022916495672",
  "aislesIds": ["ec28299e-615f-4517-83ea-35b9cacbbd3e"],
  "shifts": []
}