Item
Módulo exclusivo
Esse módulo é de uso exclusivo de parceiros que operam com canais de mercado e não está disponível para todos os desenvolvedores.
Caso tenha interesse em utilizar funções dessa API, entre em contato com time de atendimento.
Integração de Item
Como Funciona?
O envio dos produtos é realizado através dos endpoints disponibilizados para integração de Item. Após recebermos os produtos, todos os dados serão processados passando por nossas regras de disponibilidade e posteriormente enviados ao APP.Métodos de envio
Existem duas formas de fazer a integração do Item, via POST com todos os dados dos produtos e via PATCH onde é possível enviar apenas as informações que precisam ser atualizadas.Envio completo dos dados
Para fazer o envio completo dos dados dos produtos utilize a rota: POST ingestion/{merchantId}?reset=falseEssa rota é recomendada para enviar novos produtos a serem integrados ou ativar um produto que foi anteriormente desativado.Considerações importantes
Propriedades em que o valor é obrigatório:barcodename
- É necessário o envio de todas as propriedades, mesmo que o valor seja
null - Caso alguma propriedade seja enviada como
nullou valor em branco, será sobrescrito e o produto passará a ter esse valor enviado.
Carga Reset (usar com parcimônia)
- Ao enviar o parâmetro na query de
reset=trueos produtos que não estão no payload serão identificados e desativados, caso nenhum seja identificado o processo deresetnão irá acontecer. - Essa é uma ação destrutiva, portanto deve ser utilizada somente com o intuito de limpar testes da base ou eliminar itens integrados indevidamente.
Exemplo
[
{
"barcode": "123",
"name": "Produto de exemplo",
"plu": null,
"active": true,
"inventory": {
"stock": 1.5
},
"details": {
"categorization": {
"department": null,
"category": null,
"subCategory": null
},
"brand": null,
"unit": null,
"volume": null,
"imageUrl": null,
"description": null,
"nearExpiration": true,
"family": null
},
"prices": {
"price": 0,
"promotionPrice": null
},
"scalePrices": null,
"multiple": null,
"channels": null
}
]Envio parcial dos dados
Para fazer o envio parcial dos dados dos produtos utilize a rota: PATCH ingestion/{merchantId}Essa rota é recomendada caso o produto já tenha sido enviado anteriormente e não tenha alterações em todos os campos, podendo enviar apenas a alteração e os campos obrigatórios.Considerações importantes
Não utilizar o PATCH para ativar um produto.
Para isso é necessário a utilização da rota POST, pois precisamos de todas as informações atualizadas do mesmo.
Exemplo
O payload é o mesmo do POST a diferença é que irá enviar somente os campos que deseja alterar[
{
"barcode": "123",
"name": "Alterando nome do produto de exemplo",
}
]Informação dos campos
Campos
| Nome | Descrição |
|---|---|
| barcode | EAN para industrializados não-pesáveis ou código de balança para produção própria, verduras e/ou legumes, carnes e frutas |
| name | Nome do produto |
| plu | Código interno PLU |
| active | Define se o item está ativo para venda |
| inventory.stock | Quantidade do estoque atual |
| details.categorization.department | Nome do departamento |
| details.categorization.category | Nome da categoria |
| details.categorization.subCategory | Nome da subcategoria |
| details.brand | Nome da marca |
| details.unit | Unidade de medida (Ex: G, KG, UN) |
| details.volume | Quantidade da unidade de medida do item (Ex: 180g, 5kg, 1un) |
| details.imageUrl | URL da imagem |
| details.description | Descrição do item |
| details.nearExpiration | Indicador se está perto da validade |
| prices.price | Valor base de venda |
| prices.promotionPrice | Valor promocional do item com desconto fixo |
| scalePrices[0].quantity | Quantidade de itens para definir quando o produto deve assumir o valor promocional |
| scalePrices[0].price | Valor promocional do item vendido como atacado |
| multiple.originalEan | EAN original do múltiplo - Exclusivo para canal iFood Shop |
| multiple.quantity | Quantidade do múltiplo - Exclusivo para canal iFood Shop |
| channels[*] | Lista de channels do produto (ifood-app, ifood-shop, plano-whitelabel) |
Promoções
"DE - POR"
Para que seja representado no aplicativo o valor promocional "DE - POR" é necessário o envio dos dois valores nos seguintes campos:prices.price: Valor do produto.
prices.promotionPrice: Valor do produto em promoção.Para que a representação visual do DE - POR seja exibida no App, o valor promocional deve ser pelo menos 5% menos que o valor base.Caso o produto não esteja em promoção o campo prices.promotionPrice não deve ser inserido no payload ou ele deve ser passado com valor null para remoção da promoção.Lembrando que o valor de venda será representado pelo menor enviado nos campos.Exemplo de "DE - POR"
[
{
"barcode": "123",
"name": "Produto de exemplo",
"plu": null,
"active": true,
"inventory": {
"stock": 1.5
},
"details": {
"categorization": {
"department": null,
"category": null,
"subCategory": null
},
"brand": null,
"unit": null,
"volume": null,
"imageUrl": null,
"description": null,
"nearExpiration": true,
"family": null
},
"prices": {
"price": 4.99,
"promotionPrice": 3.99
},
"scalePrices": null,
"multiple": null,
"channels": null
}
]Atacarejo
Esta funcionalidade possibilita aos lojistas aplicar descontos no valor unitário do produto a partir da compra de uma quantidade de itens.Para que isto ocorra é necessário que dois campos sejam preenchidos no processo de integração realizado em sua loja:scalePrices[0].price: O valor do item no atacado.
scalePrices[0].quantity: Quantidade utilizada para definir quando o produto deve assumir o valor promocional no atacado.Apesar do atributo scalePrices ser uma lista, ele deve ser preenchido com apenas um item. A inclusão de mais de um item na lista pode gerar comportamentos inconsistentes na aplicação do valor promocionado.Caso o produto não esteja em promoção o campo scalePrices não deve ser enviado ou ele deve ser passado com valor null para remoção da promoção.Exemplo de Atacarejo
[
{
"barcode": "123",
"name": "Produto de exemplo",
"plu": null,
"active": true,
"inventory": {
"stock": 1.5
},
"details": {
"categorization": {
"department": null,
"category": null,
"subCategory": null
},
"brand": null,
"unit": null,
"volume": null,
"imageUrl": null,
"description": null,
"nearExpiration": true,
"family": null
},
"prices": {
"price": 3.99,
"promotionPrice": null
},
"scalePrices": [
{
"price": 3.49,
"quantity": 3
}
],
"multiple": null,
"channels": null
}
]Cuidados com o uso de mecânicas promocionais em itens
No módulo de Item as promoções não precisam ter datas de início e de fim, basta enviar as informações dos descontos que eles já passarão a valer. Para alterar a promoção, envie novamente o mesmo item (mesmobarcode) com um valor diferente de promoção. Para tirar o item de promoção envie os campos anteriores como nulos.Você pode conferir se a promoção realmente foi inserida, buscando pelo item na seção de catálogo do Portal do Parceiro.No módulo de Order, o preço de venda do item já será o preço promocional (preço “por” ou preço de atacado, a depender da promoção).Outras mecânicas promocionaisCaso precise enviar outras mecânicas promocionais mais complexas, como por exemplo "Leve 3, Pague 2", use o módulo Promotion.
Exclusivo para canal iFood Shop
Múltiplos
Mecânica específica do canal iFood Shop para vender embalagens com múltiplos produtos EAN, o campo será ignorado na integração para outros canais.Alguns campos precisam ser preenchidos para aplicar a mecânica:multiple.originalEan - Indica o EAN do produto unitário vendido no pacote com múltiplos itens.
multiple.quantity - Indica a quantidade de produtos unitários que compõem o pacote.
- Se o valor for menor ou igual a 1 a integração do múltiplo será ignorada.
barcode- O código base do item enviado na integração pode ser um código EAN referente ao pacote ou um código interno da loja
plu - Obrigatório para indicar o código interno do produto para controle do pacote
- Nesse tipo de item o PLU deve conter underline no final do código junto à quantidade (Ex.: 7896045506217_12 ou 1234_12)
Canais
O campochannels[*] permite o envio de uma lista de canais previamente contratados pelo parceiro que devem receber a integração de item.Os valores válidos são:- ifood-app
- ifood-shop
- plano-whitelabel
Todos os canais citados terão a inclusão ou alteração do item com os mesmos valores.
Se o campo
channels for enviado como null ou não for mencionado na chamada os valores enviados serão aplicados a todos canais configurados para o merchant.Migração da integração legada
SiteMercado Service API
Para parceiros que já integram seus itens pela SiteMercado Service API a migração para a Merchant API traz muitas similaridades que facilitam a mudança de integração.De-Para payloads
| Campo Service API | Campo Merchant API |
|---|---|
| idLoja | Na URL: ingestion/{merchantId} |
| codigoBarra | barcode |
| nome | name |
| plu | plu |
| ativo | active |
| quantidadeEstoqueAtual | inventory.stock |
| departamento | details.categorization.department |
| categoria | details.categorization.category |
| subcategoria | details.categorization.subCategory |
| marca | details.brand |
| unidade | details.unit |
| volume | details.volume |
| imageURL | details.imageUrl |
| descricao | details.description |
| validadeProxima | details.nearExpiration |
| valor | prices.price |
| valorPromocao | prices.promotionPrice |
| listaEscalaPreco.quantidade | scalePrices[0].quantity |
| quantidadeAtacado | scalePrices[0].quantity |
| listaEscalaPreco.preco | scalePrices[0].price |
| valorAtacado | scalePrices[0].price |
| multiploEanOriginal | multiple.originalEan |
| multiploQtd | multiple.quantity |
ADICIONADO | channels[*] |
| familia | REMOVIDO |
| caracteristicas | REMOVIDO |
| quantidadeEstoqueMinimo | REMOVIDO |