Item

Visão Geral

Estratégia de integração (POST vs PATCH)

• Use APENAS para cadastrar novos itens ou reativar itens inativos.
• Não reenvie o catálogo completo se não houver novos produtos.

• Use para qualquer atualização de itens existentes (preço, estoque, detalhes).
• Envie apenas os dados que sofreram alteração.

Limites de processamento e volumetria

Métodos de Envio

1. Envio Completo (POST)

• barcode: EAN (Código de Barras Europeu) ou código interno de balança
• name: Nome do produto

• Valores null sobrescrevem dados existentes.
• O parâmetro reset=true desativa produtos ausentes no payload (ação destrutiva).
• Campos não enviados receberão valores padrão (null, string vazia, 0, etc.).

1.1. Parâmetro reset

• Limpar produtos de teste da base
• Remover itens integrados indevidamente

[
    {
        "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
    }
]

2. Envio Parcial (PATCH)

• Envie apenas os campos modificados

[
    {
        "barcode": "123",
        "name": "Alterando nome do produto de exemplo"
    }
]

2.1. Considerações importantes

Detalhamento dos Endpoints

POST Item Integration

curl -X POST "https://merchant-api.ifood.com.br/item/v1.0/ingestion/{merchantId}?reset=false" \
  -H "Authorization: Bearer SEU_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "barcode": "7891234567890",
      "name": "Leite Integral 1L",
      "active": true,
      "inventory": {
        "stock": 100
      },
      "prices": {
        "price": 5.99
      }
    }
  ]'

• 202 Success: Requisição processada com sucesso
• 400 Bad Request: Erro na requisição (validação de dados)
• 429 Too Many Requests: Limite de requisições excedido
• 500 Server Error: Erro no servidor

PATCH Item Integration

curl -X PATCH "https://merchant-api.ifood.com.br/item/v1.0/ingestion/{merchantId}" \
  -H "Authorization: Bearer SEU_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "barcode": "7891234567890",
      "prices": {
        "price": 6.50
      }
    }
  ]'

• 202 Success: Requisição processada com sucesso
• 400 Bad Request: Erro na requisição (validação de dados)
• 429 Too Many Requests: Limite de requisições excedido
• 500 Server Error: Erro no servidor

Expurgo de Itens

• Status inativo (active: false)
• Preço zerado ou negativo (prices.price ≤ 0)

Como evitar o expurgo de itens

• Alterar o status para ativo (active: true)
• Atualizar o preço para um valor válido (maior que zero)
• Modificar qualquer outro campo do item

Principais Campos

[
  {
    "barcode": "7891234567890",
    "name": "Leite Integral 1L",
    "active": true,
    "inventory": {
      "stock": 100
    },
    "prices": {
      "price": 5.99
    }
  }
]

Promoções

Regras de promoção

Validação e impacto

Mecânica 'DE-POR'

• prices.price: Valor original (preço "DE")
• prices.promotionPrice: Valor promocional (preço "POR")

• O desconto deve ser superior a 5%
• Para remover a promoção, envie prices.promotionPrice: null

[
  {
    "barcode": "7891234567890",
    "prices": {
      "price": 10.00,
      "promotionPrice": 8.50
    }
  }
]

Desconto por quantidade

• scalePrices[0].quantity: Quantidade mínima para ativar o desconto
• scalePrices[0].price: Valor unitário com desconto aplicado

[
  {
    "barcode": "7891234567890",
    "prices": {
      "price": 10.00
    },
    "scalePrices": [
      {
        "quantity": 6,
        "price": 9.00
      }
    ]
  }
]

Múltiplos (iFood Shop)

• multiple.originalEan: EAN do produto unitário contido no pacote
• multiple.quantity: Quantidade de unidades no pacote (valores ≤ 1 invalidam a integração)
• barcode: EAN do pacote ou código interno da loja
• plu: Utilize o formato código_quantidade para controle interno
  • Exemplo: Para um pacote de 12 unidades, use 7896045506217_12 ou 1234_12.

[
  {
    "barcode": "7891234567890",
    "plu": "7891234567890_12",
    "name": "Leite Integral 1L - Fardo com 12 unidades",
    "multiple": {
      "originalEan": "7891234567891",
      "quantity": 12
    }
  }
]

Canais de Venda

• ifood-app
• ifood-shop

[
  {
    "barcode": "7891234567890",
    "name": "Produto exclusivo Shop",
    "channels": ["ifood-shop"]
  }
]

[
  {
    "barcode": "7891234567890",
    "name": "Produto multi-canal",
    "channels": ["ifood-app", "ifood-shop"]
  }
]

Migração da integração legada

SiteMercado Service API

De-Para Payloads

Critérios de Homologação