Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Homologation criteria

Before requesting homologation for the Shipping module, ensure your integration meets all functional and non-functional criteria described on this page.

Pre-homologation

Critical points:

Your application must be fully developed and tested before submission
Evaluation covers your entire application, not just API calls
Only Professional accounts (CNPJ) are accepted
Personal or Student accounts (CPF) will be automatically rejected

Who should use this documentation

Shipping module only integrators:Use this document to validate your implementation before requesting homologation.Multi-module integrators:If your integration also uses the Orders module, refer to Orders homologation criteria in addition to the criteria below.Already certified integrators:While optional, we recommend validating your integration against these criteria to:

Ensure ongoing compliance
Identify improvement opportunities
Anticipate production issues

Functional requirements

Your integration must implement the following features to be considered compliant.

Event management

Implement a robust system for consuming iFood events:

Requirement	Details
Event polling	Query the /polling endpoint every 30 seconds. Shorter intervals may result in rate limiting; longer intervals may cause event loss.
Acknowledgment	Send /acknowledgment immediately after processing each event. Failing to acknowledge events can cause reprocessing.
Deduplication	Implement logic to identify and discard duplicate events received during polling. Use `eventId` as the unique identifier.

Why this is critical: The event system is the primary communication channel between platforms. Failures in this integration result in inconsistent orders.

On Demand order management

Your integration must process immediate On Demand orders with the following parameters:

orderType=DELIVERY
orderTiming=IMMEDIATE
salesChannel=POS

Order confirmation

Receive confirmation requests for immediate delivery orders
Confirm within the integrator's system
Validate delivery data before confirming

Order cancellation

You must implement the following steps:

Consume cancellation reasons via /cancellationReasons
Display dynamic list of reasons in POS system
Allow user selection before processing cancellation
Send selected reason in the cancellation request

Important: You cannot hardcode cancellation reasons. API-returned codes must be consumed dynamically.

Status synchronization

Your integration must react to the following status change events:

Orders cancelled by customer (iFood app user)
Orders cancelled by iFood (operational restrictions)
Orders confirmed/cancelled by third parties (e.g., Order Manager, iFood Dashboard)

Update the integrator's status to maintain consistency with the platform.

Address management

Implement the ability to:

Accept address change requests (when feasible)
Reject requests (when unable to fulfill)
Respect timeframes set by iFood for response

Address changes are critical to delivery operations. Respond promptly.

Collection code

Implement collection code validation in two stages:

Verify presence of pickupCode in the order
Validate confirmation by driver before marking as picked up

The collection code is essential for delivery operation security.

Non-functional requirements

These requirements ensure your integration is reliable, secure, and operational in production.

Authentication and security

Token renewal:

Renew tokens before expiration (recommended: 5 minutes before expiry)
Implement automatic refresh without manual intervention
Avoid unnecessary renewals (causes latency increase)

Rate limiting:

Respect request limits documented for each endpoint
Implement request queue for traffic spikes
Monitor 429 Too Many Requests status code and apply backoff

Reliability

Error handling:

Implement retry with exponential backoff for transient failures (5xx, timeout)
Use 2x multiplier with random jitter (e.g., 1s, 2s, 4s, 8s)
Maximum 3-5 attempts per request
Log all attempts

Idempotency:

Use idempotency-key in state-altering operations (cancellations, confirmations)
Implement client-side deduplication

Observability and monitoring

Logging:

Log all critical operations (confirmation, cancellation, synchronization)
Include orderId, eventId, timestamp, and operation status
Retain logs for minimum 30 days

Alerts:

Implement alerts for:
- Consecutive polling failures (e.g., 5 consecutive failures)
- Abnormal endpoint response delay (> 30s)
- Error rate above threshold (e.g., > 5%)
- Missing token renewal

Monitoring:

Track success rate of critical operations
Monitor end-to-end latency (request to processing)
Measure polling response time

Recommended requirements

While not mandatory for approval, implementing these features significantly improves user experience:

Receipt printing

Print all order information following the model in receipt layout:

Order identifier (order ID)
Delivery data (address, contact)
Order items and quantities
Delivery time
Special notes

Benefit: Reduces operational errors and improves communication with drivers.

Delivery observations

Display and process the delivery.observations field at two points:

System screen: Show prominently when receiving the order
Printed receipt: Include as a separate section

Typical observations: Access instructions, time restrictions, emergency contact.Benefit: Ensures critical instructions reach the driver without information loss.

Homologation process

Stage 1: Preparation

Before submitting, validate:

Application fully developed (no "TODO" or in-progress features)
Integrator's account is Professional (CNPJ)
Test environment configured with valid credentials
Codebase in version control

Stage 2: Internal validation

Run the complete test suite:

Events: Polling works every 30s; acknowledgment sent correctly
Orders: Confirmation, cancellation, and synchronization work
Addresses: Acceptance/rejection of changes processed
Collection codes: Validation with driver confirmation
Errors: Retry with exponential backoff; complete logging
Edge cases: Duplicate events, timeouts, rate limiting

Tip: Use automated test scripts to validate each scenario.

Stage 3: Submission

Prepare documentation for submission:

Describe your solution and how it meets each criterion
Provide log examples showing critical operations
Share reliability metrics (success rate, latency)
Note any deviations from requirements with justification

Stage 4: Review and feedback

The iFood homologation team will:

Review code and architecture (when applicable)
Execute integration tests in a controlled environment
Provide feedback within 5 business days
Request corrections or improvements, if needed

Stage 5: Approval

After approval, you will receive:

Formal homologation confirmation
Production credentials
Go-live documentation

Next steps

Ready to get started?

Review the complete technical documentation
Consult integration examples
Explore the API reference

Questions?

Contact us: support-integrators@ifood.com.br
Visit the Developer Portal

After approval:

Migrate test credentials to production
Configure continuous monitoring in production
Establish internal technical support SLA
Test roll-out with small volume before scaling

Was this page helpful?

Rate your experience in the new Developer portal: