Overview

This guide presents recommended practices for integrating with iFood APIs. Follow these recommendations to create robust, efficient, and secure integrations.

General practices

Connection and fault tolerance

Timeout: Test connectivity automatically when timeout occurs. Notify the user about connection problems.
5XX Errors: Implement automatic retry for server errors (500, 502, 503, 504). If the problem persists for more than 5 minutes, contact support.
Monitoring: Configure alerts to identify recurring problems.

Processing

Parallelization: Process each merchant independently to prevent failures or high volume from affecting other users.
Unknown fields: Configure your application to accept new enums without breaking. Discard events with unknown enums instead of interrupting processing.

Rate Limit

All endpoints have request limits per period. Respect these limits to avoid temporary blocks.

Authentication

Token management

Reuse tokens: Request new token only when the current one is about to expire.
Error 401: Check if the token has expired. If so, request a new token.
Error 403: Confirm if you have authorized access to the merchant and if there are no pending requests.

Orders

Pooling

Frequency: Execute pooling every 30 seconds to keep the merchant active on the platform.
Filters: Use the x-polling-merchants header to filter events by merchant, type, or group.
Merchant limits: For applications with more than 500 merchants, mandatory use of the x-polling-merchants header. Implement the header when reaching 100 merchants.

Event processing

Frequency: Persist events before sending acknowledgment. If persistence fails, you will receive the event again in the next polling.
Duplication: Use the unique ID to ensure orders and events are not processed more than once.
Unknown events: Send acknowledgment and discard unknown events. Continue processing subsequent events.

Order operations

Mandatory query: Query order details before confirming or canceling.
Asynchronous confirmation: Confirmation returns status 202 (asynchronous). The order is only effectively confirmed when the confirmation event appears in pooling.
Single query only: Query order details only once. Details are immutable.
Old orders: Do not query or update orders after 8 hours from delivery time. The API is not a data backup.

Webhook

To ensure reliable reception of events and real-time notifications, use webhooks following security, validation, and resilience recommendations. Check the complete guide of best practices for webhooks at this link.

Was this page helpful?

Rate your experience in the new Developer portal:

On this page