Visión general

Esta guía presenta prácticas recomendadas para integrar con las APIs de iFood. Sigue estas recomendaciones para crear integraciones robustas, eficientes y seguras.

Prácticas generales

Conexión y tolerancia a fallos

Timeout: Prueba la conectividad automáticamente cuando ocurra timeout. Notifica al usuario sobre problemas de conexión.
Errores 5XX: Implementa retry automático para errores de servidor (500, 502, 503, 504). Si el problema persiste por más de 5 minutos, contacta el soporte.
Monitoreo: Configura alertas para identificar problemas recurrentes.

Procesamiento

Paralelización: Procesa cada merchant de forma aislada para evitar que fallos o alto volumen afecten otros usuarios.
Campos desconocidos: Configura tu aplicación para aceptar nuevos enums sin quebrar. Descarta eventos con enums desconocidos en lugar de interrumpir el procesamiento.

Rate Limit

Todos los endpoints tienen límites de solicitudes por período. Respeta estos límites para evitar bloqueos temporales.

Autenticación

Gestión de token

Reutiliza tokens: Solicita nuevo token solo cuando el actual esté próximo a expirar.
Error 401: Verifica si el token expiró. Si es así, solicita un nuevo token.
Error 403: Confirma si tienes acceso autorizado al merchant y si no hay solicitudes pendientes.

Pedidos

Polling

Frecuencia: Ejecuta polling cada 30 segundos para mantener el merchant activo en la plataforma.
Filtros: Usa el header x-polling-merchants para filtrar eventos por merchant, tipo o grupo.
Límites de merchants: Para aplicaciones con más de 500 merchants, usa obligatoriamente el header x-polling-merchants. Implementa el header cuando alcances 100 merchants.

Procesamiento de eventos

Frecuencia: Persiste eventos antes de enviar acknowledgment. Si la persistencia falla, recibirás el evento nuevamente en el próximo polling.
Duplicación: Usa el ID único para garantizar que pedidos y eventos no sean procesados más de una vez.
Eventos desconocidos: Envía acknowledgment y descarta eventos desconocidos. Continúa procesando eventos subsecuentes.

Operaciones con pedidos

Consulta obligatoria: Consulta los detalles del pedido antes de confirmar o cancelar.
Confirmación asíncrona: La confirmación retorna status 202 (asíncrono). El pedido solo se confirma efectivamente cuando el evento de confirmación aparece en el polling.
Una consulta apenas: Consulta los detalles del pedido solo una vez. Los detalles son inmutables.
Pedidos antiguos: No consultes ni actualices pedidos después de 8 horas del horario de entrega. La API no es un backup de datos.

Webhook

Para garantizar la recepción confiable de eventos y notificaciones en tiempo real, utiliza webhooks siguiendo las recomendaciones de seguridad, validación y resistencia. Consulta la guía completa de mejores prácticas para webhooks en este enlace.

¿Esta página fue útil?

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

En esta página