Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Como funciona

Entenda o processamento assíncrono, o parâmetro reset e as estratégias de integração da API de Promotion.

Processamento assíncrono

Todas as requisições retornam 202 Accepted, mas o processamento ocorre de forma assíncrona:

Você envia requisição POST → API retorna 202 imediatamente
Sistema enfileira sua requisição para validação
Validações ocorrem nos próximos segundos
Consulte com GET usando aggregationId para verificar status real

Implicações

Não aguarde na requisição (pode timeout)
Não assuma sucesso apenas pelo status 202
Consulte o endpoint GET para verificar ACTIVE, ERROR ou outro status

Fluxo de status

POST (requisição enviada)
  ↓
202 Accepted (recebido na fila)
  ↓
PROCESSING (validando)
  ↓
SCHEDULED ou ACTIVE (validação passou)
  ↓
ERROR (validação falhou)

Parâmetro `reset`

reset=false (padrão)

POST /merchants/{merchantId}/promotions

Novas requisições adicionam-se às promoções existentes
Promoções anteriores continuam ativas
Recomendado: Use em praticamente todos os casos

reset=true (destrutivo)

POST /merchants/{merchantId}/promotions?reset=true

Substitui completamente todas as promoções da loja
Desativa itens não presentes no novo payload
Ação permanente e não reversível

Ação	Item	Resultado
Criar	No payload, não existe	Novo item promocional criado
Manter	No payload, já existe	Item continua com novos parâmetros
Desativar	Não no payload	Item marcado `FINISHING` e removido

Cuidado: reset=true desativa todos os itens não enviados. Use apenas quando tiver certeza absoluta de que deseja sincronizar o catálogo completo.

Quando usar `reset=true`

Use apenas quando:

Sincronizar completamente o estado com um sistema externo
Remover todas as promoções ativas de uma loja
Garantir que apenas o conjunto especificado esteja ativo

Quando NÃO usar `reset=true`

Evite reset=true quando:

Apenas quer adicionar novas promoções (use POST sem o parâmetro)
Durante horários de pico de vendas na loja
A loja tem mais de 10.000 itens promocionais
Sem ter validado o payload completo internamente

Boas práticas para reset

Aspecto	Recomendação
Frequência	Máximo uma vez por dia
Horário	Fora do pico de vendas (ex: 2h-6h)
Limite	Máximo 10.000 itens por requisição
Validação	Validar localmente antes de enviar
Rastreamento	Usar `aggregationTag` com timestamp

Estratégia de integração

Cenário 1: Primeira integração

Dia 1: Enviar promoções iniciais via POST

curl -X POST "https://merchant-api.ifood.com.br/promotion/v1.0/merchants/{merchantId}/promotions" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregationTag": "inicial-001",
    "promotions": [ ... ]
  }'

Resposta: 202 Accepted com aggregationIdDia 2+: Adicionar ou atualizar promoções

curl -X POST "https://merchant-api.ifood.com.br/promotion/v1.0/merchants/{merchantId}/promotions" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregationTag": "atualizacao-001",
    "promotions": [ ... ]
  }'

Cenário 2: Substituir catálogo completo

Use reset=true quando precisar sincronizar completamente:

curl -X POST "https://merchant-api.ifood.com.br/promotion/v1.0/merchants/{merchantId}/promotions?reset=true" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregationTag": "sincronizacao-noturna-001",
    "promotions": [ ... ]
  }'

Recomendação: Agendar para 3h da madrugada

Cenário 3: Adicionar nova promoção a catálogo existente

Use POST sem reset (padrão):

curl -X POST "https://merchant-api.ifood.com.br/promotion/v1.0/merchants/{merchantId}/promotions" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -d '{
    "aggregationTag": "novo-item-001",
    "promotions": [
      {
        "promotionName": "Nova promoção",
        "channels": ["IFOOD-APP"],
        "items": [ ... ]
      }
    ]
  }'

Apenas este novo item é criado. Promoções existentes permanecem ativas.

Workflow prático: Ciclo de vida da promoção

Hora	Ação	Método	Esperado
08:00	Criar promoção	`POST`	`202 Accepted` com `aggregationId`
08:05	Consultar status	`GET`	Status `PROCESSING`
08:10	Consultar status	`GET`	Status `ACTIVE`
09:00	Cliente faz pedido	Manual	Desconto aparece no pedido
18:00	Atualizar desconto	`PATCH`	`202 Accepted` (ou `POST` + `reset`)
23:59	Promoção expira	Automático	Status muda para `FINISHED`

Monitoramento de status

Logo após criar (0-5 segundos)

Aguarde antes de consultar:

sleep 2

curl -X GET "https://merchant-api.ifood.com.br/promotion/v1.0/merchants/{merchantId}/promotions/{aggregationId}/items" \
  -H "Authorization: Bearer {JWT_TOKEN}"

Estratégia de polling

Primeira tentativa (0-5s): Pode estar em PROCESSING
Tentativas seguintes (5-30s): Ainda pode estar PROCESSING
Após 30s: Se ainda PROCESSING, investigar ou esperar mais
Status ERROR: Consulte campo error para código específico

Referência de campos

aggregationTag

Identificador customizado para rastreamento. Use para auditar requisições:

{
  "aggregationTag": "verão-2026-001",
  "promotions": [ ... ]
}

Requisitos:

Deve ser único por requisição
Use timestamp ou UUID para garantir unicidade
Máximo 255 caracteres

aggregationId (resposta)

ID retornado na resposta 202. Use para consultar status:

curl -X GET "https://merchant-api.ifood.com.br/promotion/v1.0/merchants/{merchantId}/promotions/{aggregationId}/items" \
  -H "Authorization: Bearer {JWT_TOKEN}"

Próximos passos

Erros e troubleshooting — Diagnóstico de problemas
Endpoints — Referência técnica
Homologação — Prepare para produção

¿Esta página fue útil?

Evalúa tu experiencia en el nuevo portal de desarrolladores: