Order module homologation

Verify your Order API integration meets production requirements. When stores fail to receive or confirm orders, customers experience cancellations.All applications must meet these functional and non-functional criteria before going live.

Prerequisites

Professional account registration (CNPJ) — personal/student accounts cannot complete homologation
Application ready for testing (entire app, not just API calls)
Test store data (store ID, store name)
Stable internet connection

Homologation criteria

Your application must meet these functional and non-functional requirements to integrate the Order module.

Functional requirements

All applications must support:

Event consumption via polling or webhook
- For polling: Request the /polling endpoint every 30 seconds to stay available on the platform
  - Use the x-polling-merchants header to filter events by merchant
  - Filter events by type and group as needed
- For webhook: Successfully respond to webhook requests (verified by internal audit)
- Send /acknowledgment for all received events with 200 status code
Order confirmation and dispatch
- Receive and confirm immediate delivery orders (orderType = DELIVERY, orderTiming = IMMEDIATE)
- Receive and confirm scheduled delivery orders (orderType = DELIVERY, orderTiming = SCHEDULED)
  - Display scheduled date and time
- Receive and confirm pickup orders (orderType = TAKEOUT)
Order cancellation
- Query /cancellationReasons endpoint to retrieve available codes/reasons for the order moment
- Display available cancellation reasons in POS system
- Accept customer or iFood cancellations
Payment handling
- Receive and display card payment details (card brand)
- Receive and display cash payment with change amount on screen and/or receipt
Promotional handling
- Receive discount coupons and display amount and subsidy responsibility (iFood/Store)
Order information display
- Display item observations on screen and/or receipt (example: "Remove onion")
- Display CPF/CNPJ on screen if required or auto-fill in fiscal document
- Display pickup code on screen and/or receipt
Duplicate prevention
- Discard duplicate events if received more than once during polling
Order synchronization
- Update order status when changed by other applications (e.g., Order Manager)
Order negotiation
- Receive and process events from Order Negotiation Platform

Category-specific requirements

Food & Restaurants

In addition to functional requirements above:

Display delivery observations on receipt (from delivery.observations field)
Follow the suggested receipt format model in documentation

Groceries, Pharmacies & Other Categories

In addition to functional requirements above:

Import orders via virtual-bag endpoint in SPE status
Limit acknowledgment requests to 2000 event IDs per request (split into multiple requests if necessary)
Send acknowledgment after processing events (not immediately), to avoid data loss

Non-functional requirements

All applications must:

Renew tokens only when about to expire or immediately after expiration
Respect API rate limit policies for each endpoint

Desirable requirements

Recommended but not mandatory:

Follow suggested receipt format model
Display delivery observations on receipts

Testing and validation

Use the Web Order Manager to:

Confirm and cancel test orders
Validate that your application updates order status when changed by another system
Test synchronization between applications