Novo iFood Developer Portal

Acesse a nova versão do portal do desenvolvedor iFood

Ativar nova versão

Promotion

Módulo exclusivo Esse módulo é de uso exclusivo de parceiros que operam com 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.

As promoções do tipo DE - POR e ATACAREJO devem ser feitas pelo módulo Item.Mais detalhes da aplicação das mecânicas de promoção no módulo Item podem ser obtidas aqui.

Criação de Promoções

A criação de promoções será realizada utilizando a rota POST /merchants/{merchantId}/promotions. Ao realizar a solicitação para a rota, o fluxo realizará as validações necessárias e processamento, e posteriormente as promoções serão enviadas ao APP.

Atenção A rota POST /merchants/{merchantId}/promotions somente adiciona novas promoções de itens à loja em questão. As promoções ficarão válidas durante todo o período informado, deixando de estar ativas apenas após a data final. Caso uma nova requisição seja feita, as promoções de itens enviadas no payload se somarão às promoções enviadas nas chamadas anteriores. Caso necessite atualizar as promoções anteriormente enviadas, recomendamos usar o “reset”. Saiba mais aqui.

Envio dos dados

Exemplo para promoções do tipo PERCENTAGE

{
    "aggregationTag": "123456",
    "promotions": [
        {
            "promotionName": "Promoção  teste",
            "channels": [
                "IFOOD-APP"
            ],
            "items": [
                {
                    "ean": "3213434343",
                    "discountValue": 20.0,
                    "initialDate": "2024-10-23",
                    "finalDate": "2024-10-30",
                    "promotionType": "PERCENTAGE",
                }
            ]
        }
    ]
}

Exemplo para promoções do tipo: LXPY (leve X pague Y)

{
    "aggregationTag": "123456",
    "promotions": [
        {
            "promotionName": "Promoção teste do tipo LXPY",
            "channels": [
                "IFOOD-APP"
            ],
            "items": [
                {
                    "ean": "3213434343",
                    "discountValue": null,
                    "initialDate": "2024-10-23",
                    "finalDate": "2024-10-30",
                    "promotionType": "LXPY",
                    "progressiveDiscount": {
                        "quantityToBuy": 3,
                        "quantityToPay": 2
                    }
                }
            ]
        }
    ]
}

Exemplo para promoções do tipo: PERCENTAGE_X_UNIT_DISCOUNT (X% off na Y unidade)

{
    "aggregationTag": "123456",
    "promotions": [
        {
            "promotionName": "Promoção teste - 50% de desconto na 3 unidade",
            "channels": [
                "IFOOD-APP"
            ],
            "items": [
                {
                    "ean": "3213434343",
                    "discountValue": 50.0,
                    "initialDate": "2024-10-23",
                    "finalDate": "2024-10-30",
                    "promotionType": "PERCENTAGE_PER_X_UNITS",
                    "progressiveDiscount": {
                        "quantityToBuy": 3
                    }
                }
            ]
        }
    ]
}

Informações dos campos

Nome	Tipo	Opcional	Descrição	Exemplo
aggregationTag	String	SIM	Identificador do pedido de integração	Número/código para identificação de solicitação de criação de promoção.
promotion.promotionName	String	SIM	Nome da promoção	Promoção de verão
channels	Array	NÃO	Canais onde as promoções serão vinculadas	IFOOD-APP
promotions.items.ean	String	NÃO	EAN do item	3213434343
promotions.items.discountValue	Double	SIM	Valor do desconto a ser concedido, pode ser passado valor em R$ ou %	29.99
promotions.items.initialDate	Date	NÃO	Data em que a promoção deve começar	2024-10-23
promotions.items.finalDate	Date	NÃO	Data em que a promoção deve finalizar	2024-10-30
promotions.items.promotionType	String	NÃO	Tipo da promoção	PERCENTAGE, LXPY ou PERCENTAGE_PER_X_UNITS
promotions.items.progressiveDiscount.quantityToBuy	Integer	SIM¹	Quantidade a comprar	2
promotions.items.progressiveDiscount.quantityToPay	Integer	SIM²	Quantidade a pagar	2

¹ Obrigatório para promoções dos tipos LPXY e PERCENTAGE_PER_X_UNITS.² Obrigatório para promoções do tipo LPXY.

Tipos de promoções

Tipos de promoções (promotionType) suportados pela integração.
- PERCENTAGE: determina o valor do desconto do item em porcentagem.
- LXPY: determina o valor de desconto dado um combo de itens.
- PERCENTAGE_PER_X_UNITS: aplica o desconto percentual a cada x quantidade do item.

Campos usados em conjunto

Para promoções do tipo: PERCENTAGE deve ser enviado promotionType e o discountValue. EX:

{
        "promotionType": "tipo da promoção",
        "discountValue": "valor do desconto ou valor do item"
}

Para promoções do tipo LXPY deve ser enviado o promotionType e o progressiveDiscount (objeto completo) EX:

    {
        "promotionType": "LXPY", 
        "progressiveDiscount":{
            "quantityToBuy": 3, 
            "quantityToPay": 2
        }
    }

Para promoções do tipo PERCENTAGE_PER_X_UNITS deve ser enviado o promotionType, o progressiveDiscount.quantityToBuy e o discountValue EX:

    {
        "promotionType": "PERCENTAGE_PER_X_UNITS", 
        "discountValue": "valor do desconto aplicado a cada x unidades do item",
        "progressiveDiscount":{
            "quantityToBuy": 3, 
        }
    }

Exemplo de utilização:

Em um exemplo que o item tem o valor R$ 10,00

Entrada	Valor do item com desconto
{"promotionType": "PERCENTAGE", "discountValue": 10}	R$ 9,00
{"promotionType": "LXPY", "progressiveDiscount": {"quantityToBuy": 3, "quantityToPay": 2}}	Os 3 itens sairão por R$ 20,00, cada um por aproximadamente R$ 6,66
{"promotionType": "PERCENTAGE_PER_X_UNITS", "discountValue": 50, "progressiveDiscount": {"quantityToBuy": 2}}	Ao adicionar 2 unidades do item no carrinho, a segunda receberá 50% de desconto. Ficando um valor total de R$ 15,00

Importante A fim de evitar qualquer tipo de erro ou fraude, permitimos descontos de no máximo 70% em relação ao preço de catálogo. Para mecânicas como "Leve X Pague Y" e "Percentual de desconto na Nª unidade" consideramos que o desconto dado no combo de itens comprados não deve passar dos mesmos 70% (ex. Leve 10 Pague 2 não é permitido, pois há um desconto de 80% nas 10 unidades compradas). Itens enviados com desconto maior que o permitido serão ignorados.

Retorno da requisição

Sucesso

HTTP status code 202

Response body

{
"aggregationId": "String",
"message": "We have successfully received your request to create promotions"
}

aggregationId O aggregationId retornado, será o identificador para acompanhamento do seu pedido de criação de promoção, portanto mantenha o registro dessa informação.

O processo de validação e criação de promoções é assíncrono, ou seja, ter recebido o status code 202 não significa que todos os itens promocionais enviados já foram criados com sucesso. O processo de promocionamento pode demorar alguns minutos e alguns itens podem apresentar algum problema. Especialmente durante o processo de desenvolvimento e homologação, recomendamos fortemente o uso do endpoint de GET para a verificação do status real de cada item promocional enviado no payload. Saiba mais aqui. Após validar que a promoção está ativa no endpoint de GET, recomendamos ainda uma conferência final no App do iFood.

Erro

Quando ocorrer algum erro ao realizar o processamento, será retornado o HTTP status code 400 ou 422

{
"type": "Business Exception || Unprocessable Entity",
"title": "Business Exception || Unprocessable Entity",
"status": 400 || 422,
"detail": "Detail error",
"instance": "07228dab-644c-4bec-b8a3-073397a839a0"
}

Quando ocorrer algum erro em algum parâmetro ou no body, será retornado o HTTP status code 412 HTTP status code 412

{
"type": "Precondition Failed || Invalid Argument",
"title": "Invalid Request Body || Invalid Argument",
"status": 412,
"detail": "Detail error",
"instance": "07228dab-644c-4bec-b8a3-073397a839a0"
}

Atualização de Promoções

Caso necessite atualizar a lista de promoções atualmente vigentes na loja, você deve utilizar a estratégia de reset. Para isso, basta chamar o endpoint de POST, da mesma forma que falado na seção anterior, porém adicionando um parâmetro ?reset=true ao final da rota, que ficará da seguinte forma:POST /merchants/{merchantId}/promotions?reset=trueO payload enviado segue o mesmo formato citado aqui.O comportamento do “reset” de promoções é o mesmo do “reset” do módulo de Item. Quando o POST é chamado com o modo de “reset”, os itens promocionais enviados no payload substituirão tudo o que já foi enviado anteriormente para aquela loja. Após o processamento, passará a valer apenas o que foi enviado pela última vez.Mais especificamente, o que irá acontecer é o seguinte:

Os itens promocionais novos serão criados;
Nada será feito em relação aos itens promocionais que já tiverem sido enviados anteriormente exatamente iguais;
Os itens promocionais que estavam ativos anteriormente, porém não apareceram mais na nova chamada de reset, serão desativados.

Assim como no módulo de Item, o “reset” de Promotion deve ser usado com moderação. Recomendamos o envio diário (fora do horário comercial) ou somente quando o seu sistema identificar que houve alguma alteração. Existe um limite de no máximo 10 mil itens promocionais no payload.

Consulta de Promoções

O Endpoint GET /merchants/{merchantId}/promotions/{aggregationId}/items retorna os detalhes dos itens da promoção enviada. Retorna uma listagem paginada com os dados enviados no método post, mais o status atual dentro do ambiente de promotion do iFood. Em caso de erro, retorna o detalhamento do mesmo.Importante salientar que o processo de criação de promoção é assincrono, ou seja, caso seja realizada uma requisição GET imediatamente após uma requisição POST, é possível que retorne uma lista vazia devido ao processo de criação ainda não estar completo em todo o ambiente iFood.

Detalhamento dos filtros possíveis

Alguns campos são diponibilizados, via queryString.

Campo	Especificação	Explicação
`ean`	Texto	mesmo encaminhado no body do post
`promotionName`	Texto	mesmo encaminhado no body do post
`promotionType`	Texto	mesmo encaminhado no body do post
`status`	Texto	ver detalhamento do campo nos exemplos de retorno
`offset`	Inteiro	número da primeira da listagem desejada
`limit`	Inteiro	número de itens a serem retornados¹

¹ máximo de 1000 itens

Tabela de valores para o campo status

Status	Detalhamento
PROCESSING	Retornado logo após o dado ser recebido, via endpoint de post, e está sendo validada pelos sistemas iFood para poderem ser promocionadas
SCHEDULED	Essa situação indica que o os itens da promoção foram validados, porem a data de inicio da promoção é futura e a mesma aguarda o dia agendado
ACTIVE	Promoção validada e em operação
DUPLICATE	Ocorre quando enviado um item promocional duplicado, ou seja, um item promocional que já foi enviado exatamente da mesma forma em chamadas anteriores (mesmo produto, mecânica, descontos e datas de vigência)
FINISHING	Ocorre quando um pedido de remoção do item foi realizado (seja por solicitação especifica do item ou por ter chegado na data final da promoção) e aguarda sua efetivação em todos os sistemas iFood
FINISHED	Recebido o OK da remoção do item em todos os sistemas iFood, o item não está mais promocionado
ERROR	Ocorre quando algum problema foi detectado durante alguma etapa do processo de promocionamento e/ou despromocionamento, nesse caso o campo error¹ é retornado no payload de retorno

¹ para mais detalhes, verifique a Tabela de referência de retorno no campo error

Importante A promoção estar no status "ACTIVE" significa que ela está devidamente cadastrada e ativa em nosso sistema, porém não significa que ela estará necessariamente aparecendo no App do iFood para todos os usuários. Isso se deve ao fato de que, além das promoções inseridas pela integração, outras promoções podem estar ativas para o mesmo item (sejam promoções bancadas iFood, pela indústria ou até inseridas por você via Portal do Parceiro ou executivos comerciais). A fim de evitar duplo subsídio, o iFood apresenta para o usuário somente uma das promoções ativas para o item, usando uma regra de priorização. Essa priorização tem como base mostrar o melhor desconto para o usuário, porém outras regras adicionais podem ser aplicadas.

Retorno da requisição

Sucesso

HTTP status code 200

Response body

{
  "promotions": [
    {
        "promotionItemId": "005f5ea0-1ff4-4c9b-9f48-76d94bfe4694",
        "ean": "3213434343",
        "status": "PROCESSING",
        "initialDate": "2024-10-10",
        "finalDate": "2024-10-11",
        "promotionType": "LXPY",
        "promotionName": "Promoção teste do tipo LXPY",
        "progressiveDiscount": {
            "quantityToBuy": 3,
            "quantityToPay": 2
        }
    }
  ],
  "pagination": {
    "nextOffset": 99,
    "currentOffset": 0
  }
}

Erro

Quando ocorrer algum erro ao realizar o processamento, será retornado o HTTP status code 400 ou 422

{
"type": "Business Exception || Unprocessable Entity",
"title": "Business Exception || Unprocessable Entity",
"status": 400 || 422,
"detail": "Detail error",
"instance": "07228dab-644c-4bec-b8a3-073397a839a0"
}

Quando ocorrer algum erro em algum parâmetro ou no body, será retornado o HTTP status code 412 HTTP status code 412

{
"type": "Precondition Failed || Invalid Argument",
"title": "Invalid Request Body || Invalid Argument",
"status": 412,
"detail": "Detail error",
"instance": "07228dab-644c-4bec-b8a3-073397a839a0"
}

Tabela de valores retornados no campo error

Valor	Detalhamento
DATE_INVALID	Verifique se `initialDate` e `finalDate` estão no formato esperado (ex: `2024-10-23`) e que `finalDate` seja maior que `initialDate`.
PROMOTION_TYPE_INVALID	Revise os valores informados no campo `promotionType` na seção Tipos de promoções.
DISCOUNT_INVALID	Dependendo do tipo de promoção, revise: - PERCENTAGE_PER_X_UNITS: `discountValue` e `quantityToBuy` devem ser informados e maiores que zero. - PERCENTAGE: `discountValue` deve ser informado e maior que zero. - LXPY: `quantityToBuy` e `quantityToPay` devem ser informados e maiores que zero. Além dessas validações, os itens integrados serão recusados caso o desconto desejado seja superior a 70% do valor de venda original do item.
ITEM_NOT_FOUND	Verifique se o ean enviado está correto, se o produto está ativo e com estoque na loja informada.
INTERNAL_ERROR	Demais erros¹

¹ Entre em contato com suporte iFood para maiores detalhes

Retorno no módulo de Order

Caso alguma promoção enviada pelo módulo de Promotion seja aplicada a um pedido da sua loja, o benefício será apresentado no endpoint GET /orders/{id}/virtual-bag, da seguinte forma:

Os benefícios serão apresentados no campo benefit.benefits para todas as mecânicas;
Caso queira saber somente os benefícios em itens que são patrocinados pela sua loja (que é o caso das promoções enviadas pelo módulo de Promotion):
- Filtre somente os benefícios em que target seja ITEM;
- Destes, filtre somente os benefícios que possuem somente 1 elemento em sponsorships, e que este possua liability como PARTNER ou CHAIN.
Para saber o valor do item com desconto:
- Obtenha o valor de targetId do benefício e use para correlacionar com o item (elemento em bag.items que tenha uniqueId de mesmo valor).
- O valor no item é sempre sem qualquer desconto. Então, subtraia o valor de sponsorships.amount.value (do benefício) do valor do campo prices.grossValue.value (do item).

Critérios de Homologação

Verifique os critérios para realizar sua homologação.