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

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.

Envio dos dados

Exemplo para promoções do tipo: FIXED PERCENTAGE e FIXED_PRICE

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

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: ATACAREJO

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

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	FIXED, PERCENTAGE, FIXED_PRICE, LXPY, ATACAREJO 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, ATACAREJO 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.
- FIXED: determina o valor do desconto em R$.
- PERCENTAGE: determina o valor do desconto do item em porcentagem.
- FIXED_PRICE: determina o valor final do item.
- LXPY: determina o valor de desconto dado um combo de itens.
- ATACAREJO: aplica o valor do desconto a partir de uma quantidade X 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: FIXED , PERCENTAGE, FIXED_PRICE 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 ATACAREJO deve ser enviado o promotionType, o progressiveDiscount e o discountValue EX:

    {
        "promotionType": "ATACAREJO", 
        "discountValue": "valor final do item",
        "progressiveDiscount":{
            "quantityToBuy": 3, 
        }
    }

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": "FIXED", "discountValue": 2}	R$ 8,00
{"promotionType": "PERCENTAGE", "discountValue": 10}	R$ 9,00
{"promotionType": "FIXED_PRICE", "discountValue": 6}	R$ 6,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": "ATACAREJO", "discountValue": 6, "progressiveDiscount": {"quantityToBuy": 3}}	Os 3 itens sairão por R$ 18,00, cada um por R$ 6,00
{"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.

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"
}

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
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: - ATACAREJO e PERCENTAGE_PER_X_UNITS: `discountValue` e `quantityToBuy` devem ser informados e maiores que zero. - FIXED, PERCENTAGE e FIXED_PRICE: `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

Critérios de Homologação

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