Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Item

Módulo exclusivo Este módulo es de uso exclusivo de socios que operan con canales de mercado y no está disponible para todos los desarrolladores. Si está interesado en utilizar funciones de esta API, contacte al equipo de atención.

Visión general

Use la API de Item para enviar y gestionar productos. iFood procesa los datos con base en reglas de disponibilidad antes de mostrarlos en la aplicación.

Estrategia de integración (POST vs PATCH)

ATENCIÓN: Use POST únicamente para crear ítems. El uso incorrecto para actualizaciones degrada el rendimiento de la integración.

Para optimizar el rendimiento, utilice los métodos HTTP según se describe a continuación:Método POST (Creación):

Use ÚNICAMENTE para registrar nuevos ítems o reactivar ítems inactivos
No reenvíe el catálogo completo si no hay nuevos productos

Método PATCH (Actualización):

Use para actualizar ítems existentes (precio, inventario, detalles)
Envíe únicamente los campos que sufrieron cambios

Límites de procesamiento y volumetría

Para asegurar la ingesta rápida de datos y evitar colas de procesamiento, siga rigurosamente la regla a continuación:Regla de oro: Planifique la orquestación de los envíos para no exceder el 25% del total de ítems del catálogo en una ventana de 35 minutos.Impacto: El cumplimiento de esta métrica es esencial para garantizar la estabilidad del rendimiento y la agilidad en la actualización de los datos.Ejemplo: Si el catálogo posee 10.000 ítems, envíe como máximo 2.500 ítems cada 35 minutos.Bloqueo: La API retorna el estado 429 Too Many Requests si se excede el límite. Si recibe este error, espere al inicio de la siguiente ventana de tiempo.

Métodos de envío

1. Envío completo (POST)

Use estrictamente para nuevos productos.POST ingestion/{merchantId}?reset=falseCampos obligatorios:

barcode: EAN (Código de Barras Europeo) o código interno de báscula
name: Nombre del producto

Comportamiento:

Valores null sobrescriben datos existentes
El parámetro reset=true desactiva productos ausentes en el payload (acción destructiva)
Los campos no enviados recibirán valores predeterminados (null, cadena vacía, 0, etc.)

1.1. Parámetro reset

Cuando envía reset=true, iFood desactiva automáticamente todos los productos ausentes en el payload.

ATENCIÓN: Esta acción es destructiva.

Cuándo usar:

Limpiar productos de prueba de la base
Eliminar ítems integrados indebidamente

Comportamiento: Si ningún producto es identificado para desactivación, el proceso no será ejecutado.Ejemplo de Payload:

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

Importante: Para productos vendidos por peso, el campo inventory.stock debe informarse en kilogramos (KG). Ejemplo: 1 = 1 KG, 1.5 = 1,5 KG.

2. Envío parcial (PATCH)

Recomendado para actualización de catálogo (precio, inventario).PATCH ingestion/{merchantId}Cómo funciona:

Envíe únicamente los campos modificados

Ejemplo de Payload:El payload es el mismo del POST, la diferencia es que enviará solamente los campos que desea alterar.

[
    {
        "barcode": "123",
        "name": "Cambiando nombre del producto de ejemplo"
    }
]

2.1. Consideraciones importantes

No utilice PATCH para activar un producto.Para reactivar productos, utilice la ruta POST. El sistema requiere el payload completo para validar la información.

Detalles de Endpoints de la API

POST Item Integration

Descripción: Envía nuevas integraciones de productos, actualiza todos los datos del producto o los reactiva.Ejemplo cURL:

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

Códigos de respuesta:

202 Success: Solicitud procesada exitosamente
400 Bad Request: Error en la solicitud (validación de datos)
429 Too Many Requests: Límite de solicitudes excedido
500 Server Error: Error del servidor

Campos de la solicitud:

Campo	Tipo	Obligatorio	Descripción
barcode	string	Sí	EAN o código interno de báscula
name	string	Sí	Nombre del producto
plu	string	No	Código PLU interno
active	boolean	No	Define si el ítem está activo para la venta
details	object	No	Detalles del producto (categorización, marca, volumen, unidad, imagen, descripción)
prices	object	No	Objeto que contiene `price` y `promotionPrice`
scalePrices	array	No	Array con reglas de precios escalonados por cantidad
inventory	object	No	Objeto que contiene `stock` (cantidad en inventario)
multiple	object	No	Objeto para configurar múltiplos (exclusivo iFood Shop) con `originalEan` y `quantity`
channels	array	No	Canales de venta: `ifood-app`, `ifood-shop`

PATCH Item Integration

Descripción: Actualización parcial recomendada si el producto ya fue enviado anteriormente y no todos los campos requieren cambios. Permite enviar solo los campos que desea actualizar.Ejemplo cURL:

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

Códigos de respuesta:

202 Success: Solicitud procesada exitosamente
400 Bad Request: Error en la solicitud (validación de datos)
429 Too Many Requests: Límite de solicitudes excedido
500 Server Error: Error del servidor

Campos de la solicitud:

Campo	Tipo	Obligatorio	Descripción
barcode	string	Sí	EAN o código interno de báscula (identificador)
name	string	No	Nombre del producto
plu	string	No	Código PLU interno
active	boolean	No	Define si el ítem está activo para la venta
details	object	No	Detalles del producto (categorización, marca, volumen, unidad, imagen, descripción)
prices	object	No	Objeto que contiene `price` y `promotionPrice`
scalePrices	array	No	Array con reglas de precios escalonados por cantidad
inventory	object	No	Objeto que contiene `stock` (cantidad en inventario)
multiple	object	No	Objeto para configurar múltiplos con `originalEan` y `quantity`
channels	array	No	Canales de venta: `ifood-app`, `ifood-shop`

Expurgo de ítems

El sistema elimina definitivamente del catálogo ítems sin actualización hace 15 días y que cumplan con una de las siguientes condiciones:

Estado inactivo (active: false)
Precio cero o negativo (prices.price ≤ 0)

ATENCIÓN: Los ítems expurgados requieren registro completo vía método POST.

Cómo evitar el expurgo de ítems

Envíe una actualización antes del plazo de 15 días para:

Cambiar el estado a activo (active: true)
Actualizar el precio a un valor válido (mayor que cero)
Modificar cualquier otro campo del ítem

Acompañe ítems inactivos o con precio cero en el Portal del Socio para prevenir eliminaciones no planificadas.

Campos principales

La tabla a continuación lista los campos principales para la integración de ítems:

Campo	Descripción
barcode	EAN o código interno de báscula
name	Nombre del producto
plu	Código interno PLU
active	Estado de venta (`true`/`false`)
inventory.stock	Cantidad en inventario
prices.price	Precio base
prices.promotionPrice	Precio promocional
scalePrices	Reglas de mayoreo
channels	Canales de venta (`ifood-app`, `ifood-shop`)

Ejemplo de payload mínimo:

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

Promociones

Reglas de promoción

Aplicación inmediata: Las promociones en este módulo no utilizan programación (fechas de inicio/fin). El descuento entra en vigor inmediatamente después del envío.Actualización: Para cambiar un valor promocional, reenvíe el ítem vía PATCH con el nuevo precio.Eliminación: Para finalizar una promoción, envíe los campos de valor promocional como null.

Validación e impacto

Verificación: Confirme la aplicación del descuento en la sección de Catálogo del Portal del Socio.Módulo Order: Los pedidos recibidos contendrán automáticamente el precio final con descuento aplicado (precio "por" o mayoreo).

Mecánica 'DE-POR'

Configure precios promocionales enviando el valor original y el valor con descuento.Cómo configurar:

prices.price: Valor original (precio "DE")
prices.promotionPrice: Valor promocional (precio "POR")

Reglas:

El descuento debe ser superior al 5%
Para eliminar la promoción, envíe prices.promotionPrice: null

Ejemplo:

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

Descuento por cantidad

Esta funcionalidad permite aplicar descuentos en el valor unitario del producto a partir de la compra de una cantidad mínima.Cómo configurar:

scalePrices[0].quantity: Cantidad mínima para activar el descuento
scalePrices[0].price: Valor unitario con descuento aplicado

Ejemplo:

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

En este ejemplo, el cliente paga $10.00 por unidad en compras de hasta 5 ítems, y $9.00 por unidad a partir de 6 ítems.

Múltiplos (iFood Shop)

Utilice esta mecánica para vender empaques con múltiples unidades (ej.: paquetes) en el canal iFood Shop.

Estos campos son exclusivos para iFood Shop.

Campos obligatorios:

multiple.originalEan: EAN del producto unitario contenido en el paquete
multiple.quantity: Cantidad de unidades en el paquete (valores ≤ 1 invalidan la integración)
barcode: EAN del paquete o código interno de la tienda
plu: Utilice el formato código_cantidad para control interno
- Ejemplo: Para un paquete de 12 unidades, use 7896045506217_12 o 1234_12.

Ejemplo de payload:

[
  {
    "barcode": "7891234567890",
    "plu": "7891234567890_12",
    "name": "Leche Entera 1L - Paquete con 12 unidades",
    "multiple": {
      "originalEan": "7891234567891",
      "quantity": 12
    }
  }
]

Canales de venta

Use el campo channels para restringir la integración del ítem a canales específicos contratados.Valores aceptados:

ifood-app
ifood-shop

Si el campo channels es omitido o enviado como null, los cambios serán aplicados automáticamente a todos los canales configurados para el socio.

Ejemplo - Restringir ítem a iFood Shop:

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

Ejemplo - Disponibilizar en múltiples canales:

[
  {
    "barcode": "7891234567890",
    "name": "Producto multicanal",
    "channels": ["ifood-app", "ifood-shop"]
  }
]

Migración de la integración legada

SiteMercado Service API

Para socios que ya integran sus ítems por la SiteMercado Service API, la migración a la Merchant API trae muchas similitudes que facilitan el cambio de integración.

Mapeo de campos

Campo Service API	Campo Merchant API
idLoja	`En 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	`ELIMINADO`
caracteristicas	`ELIMINADO`
quantidadeEstoqueMinimo	`ELIMINADO`

Criterios de homologación

Verifique los criterios para realizar su homologación.

¿Esta página fue útil?

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