Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Events

Visión general

Polling es un método simple para recibir actualizaciones de una API. Tu sistema envía solicitudes regulares, cada 30 segundos, al endpoint GET /events:polling y verifica si hay nuevos eventos. La API retorna la información nueva desde la última solicitud.Cuando hay eventos, la API retorna el código 200 con la lista. Si no hay eventos, retorna 204.El polling es fácil de implementar, pero puede aumentar el tráfico y causar retrasos en comparación con webhooks.

Retención de eventos

La API mantiene pedidos y eventos por hasta 8 horas después de la entrega. Después de ese plazo, la API no retorna los eventos. La API solo retorna eventos sin ACK. Envía el ACK solo después de garantizar que almacenaste el evento.

Ordenación de eventos

La API puede entregar eventos fuera de orden. Para garantizar la secuencia correcta, ordena los eventos por el campo createdAt después de recibirlos.

Filtros

Puedes filtrar los pedidos recibidos en el polling.

Filtro por categoría

Usa el parámetro categories en la query para filtrar pedidos por categoría. Por defecto, la API retorna eventos para las categorías FOOD y GROCERY. Consulta las categorías de pedido para más detalles.

/events:polling?categories=FOOD,GROCERY,ANOTAI,FOOD_SELF_SERVICE 
/events:polling?categories=ALL (Serán retornadas todas las categorías, inclusive nuevas categorías que serán creadas con el tiempo)

Pedidos de la categoría ANOTAI solo aparecen si el restaurante usa el pago Pagamento Online iFood en Anota AI. En caso contrario, esos pedidos no se muestran.

Filtro por tipo de evento

Usa los parámetros types y groups para filtrar eventos por tipo o grupo.Ejemplos:

/events:polling?groups=STATUS,DELIVERY,TAKEOUT
/events:polling?types=COL,CFM,CAN,AAO
/events:polling?groups=ORDER_STATUS&types=AAO,AAD

Eventos no filtrados reciben acknowledgment automático (auto-acknowlegment). Si cambias el filtro, eventos ya confirmados no serán retornados. Consume todos los eventos en un único flujo y repasa conforme a tu lógica.Los groups ya incluyen los types. Evita filtros duplicados, como ?groups=ORDER_STATUS&types=PLC,CFM....No es posible filtrar eventos del grupo OTROS. Para recibir todos los eventos, no uses filtros.

Filtro por merchants

El endpoint retorna eventos de hasta 500 tiendas que tu token accede. Usa el header x-polling-merchants para especificar tiendas.Ejemplo:

--header 'x-polling-merchants: 0a0000aa-0aa0-00aa-aa00-0000aa000001,0a0000aa-0aa0-00aa-aa00-0000aa000002,0a0000aa-0aa0-00aa-aa00-0000aa000003'

Filtro x-polling-merchants y aplicaciones centralizadas y distribuidas

Si tu aplicación (centralizada o distribuida) utiliza un token con permiso para varios merchants, agrega el filtro x-polling-merchants en las requests de polling. Así, recibes eventos solo del merchant especificado. Sin ese filtro, el sistema envía eventos de todos los merchants vinculados al token.En aplicaciones centralizadas con tokens que acceden a muchos merchants, siempre usa el header x-polling-merchants para filtrar eventos por merchant. En caso contrario, puede ocurrir el error "Bad request. Too many polling merchants". En el header, envía una lista de IDs de los merchants deseados. El límite es 100 IDs por header.Si tu aplicación accede hasta 500 merchants y no usas el header, recibirá eventos de todos los merchants. Para accesos arriba de 500 merchants, es obligatorio usar el header y dividir las requests en lotes de hasta 100 merchants cada uno.

Para aplicaciones centralizadas con más de 500 merchants, recomendamos el uso de webhooks. Los webhooks entregan eventos en tiempo real y reducen problemas con el uso del filtro x-polling-merchants.

403 - Forbidden

Si no usas el filtro x-polling-merchants al hacer una solicitud de polling, la API retornará eventos de todos los merchants que el token accede.Cuando usas el filtro x-polling-merchants, la API verifica si el token tiene permiso para todos los merchants informados. Si el token no tiene permiso para algún merchant, la API retorna error 403. El cuerpo de la respuesta, en el campo unauthorizedMerchants, lista los merchants sin permiso.Cómo resolverRemueve los merchants sin permiso del filtro x-polling-merchants y envía una nueva solicitud de polling para recibir eventos de los merchants autorizados.Cómo identificar la causaVerifica si el merchant revocó el acceso de tu aplicación. Si es necesario, pide una nueva autorización al responsable del merchant.Si el merchant aprobó el acceso recientemente, el token puede haber sido generado antes de la aprobación. Genera un nuevo token para acceder al merchant aprobado.

Múltiples devices o aplicaciones

Más de una aplicación puede consumir eventos de la misma tienda. La API genera un identificador único para cada aplicación basado en las credenciales, llamado "device". El control de acknowledgment usa este identificador.Otra aplicación puede recibir y confirmar un evento del tipo PLACED antes que el tuyo. En esa situación, recibirás el evento de confirmación generado por otro device. Registra y actualiza el estado del pedido basado en todos los eventos recibidos, aun que vengan de otros devices.Este mecanismo permite que la tienda use diferentes aplicaciones, como tu app y el Gestor de Pedidos, al mismo tiempo.

Rate Limit Cada cliente puede hacer una request cada 30 segundos por token. Si excede ese límite, la API puede bloquear al cliente temporalmente y retornar el código 429.

Eventos de pedidos

Conoce más aquí sobre todos los detalles y ejemplos de eventos enviados por iFood.

Eventos duplicados y fecha del pedido

La API puede retornar el mismo evento más de una vez, incluyendo eventos antiguos de PLACED. Siempre verifica el ID del evento y descarta duplicados. No proceses el mismo evento más de una vez.Realiza el acknowledgment para todos los eventos recibidos, aun que ya hayas procesado anteriormente.Si recibes un evento de PLACED repetido, descártalo y no crees un nuevo pedido.

Acknowledgment de eventos

Siempre envía /acknowledgment al recibir nuevos eventos para evitar recibirlos nuevamente. En el cuerpo de la request, envía un array con los IDs de los eventos o el contenido completo recibido en el polling. La API usa solo el ID para procesar el acknowledgment. Cada request acepta hasta 2000 IDs.Orientaciones:

Envía acknowledgment para cada polling con eventos.
Envía acknowledgment de todos los eventos, aun los no utilizados por tu sistema.
Envía acknowledgment solo una vez por evento.

Presencia en el polling

El merchant permanece online mientras tu integración realiza polling de eventos cada 30 segundos. Si el polling para, el merchant pierde el estado de online.

Conoce más aquí sobre el concepto de presencia en iFood.

Criterios de homologación

Consulta abajo los requisitos y criterios de homologación:

Para realizar la homologación de aplicación es necesario que la misma ya esté lista. Las pruebas se hacen en la APP como un todo y no solo en las llamadas de nuestras APIs.

Pedidos de homologación con registros de cuenta Personal/Estudiante (CPF) no serán aceptados. Solo pedidos con registro de cuenta Profesional (CNPJ).

Enviar requests en el endpoint GET /events:polling cada 30 segundos para no perder pedidos.
Usar el header x-polling-merchants para filtrar eventos por merchant.
Filtrar eventos también por tipo y grupo, si es necesario.
EnviarPOST /events/acknowledgment para todos los eventos recibidos (código 200) inmediatamente después de la request de polling.
Para aplicaciones de Integradora Logística, es obligatorio enviar el parámetro excludeHeartbeat=true al realizar una solicitud en el endpoint GET /events:polling. Esto es necesario para evitar que la tienda sea abierta, causando cancelación de pedidos y posteriormente evitando que el merchant sea penalizado en la plataforma, por mal uso del módulo. Conoce más en Status de Conexão dos Parceiros no iFood.

¿Esta página fue útil?

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

En esta página