Search in documentation

Modules

Logistics

Authentication

Merchant

Catalog

Order

Events

Shipping

Review

Financial

Solutions

Logistics

The Logistics API provides features to manage all stages of a delivery operation: from order receipt to delivery confirmation. Use it to integrate your logistics system with the iFood platform.

Use cases

Logistics integrations: Third-party platforms that manage deliveries for multiple merchants
Delivery operations: Systems that need to control order status in real-time
Delivery driver management: Allocation and tracking of drivers and deliveries
Delivery verification: Validation of delivery code to confirm receipt

Integration flow

The lifecycle of an order follows this sequence:

Receive orders - Via polling or webhook
Get details - Complete order information
Assign driver - Designate driver for pickup and delivery
Notify movement - Report displacement (pickup and delivery)
Confirm arrival - Validate arrival at origin and destination addresses
Verify code - Request and validate customer delivery code

┌─────────────┐
│New Order    │
└──────┬──────┘
       │ Polling/Webhook
       ▼
┌─────────────────────────┐
│Get Order Details        │
└──────┬──────────────────┘
       │ GET /orders/{id}
       ▼
┌──────────────────────┐
│Assign Driver         │
└──────┬───────────────┘
       │ POST /assignDriver
       ▼
┌──────────────────────┐
│Order Pickup          │
├──────┬───────────────┤
│ POST │ /goingToOrigin
│ POST │ /arrivedAtOrigin
└──────┬───────────────┘
       │
       ▼
┌──────────────────────┐
│Order Delivery        │
├──────┬───────────────┤
│ POST │ /dispatch
│ POST │ /arrivedAtDestination
└──────┬───────────────┘
       │
       ▼
┌──────────────────────┐
│Verify Code           │
└──────┬───────────────┘
       │ POST /verifyDeliveryCode
       ▼
┌─────────────┐
│Delivered ✓  │
└─────────────┘

Minimum requirements

To use the Logistics API you need:

Professional account (CNPJ) - Personal accounts (CPF) are not accepted
API credentials - Client ID and Secret for authentication
Test environment - Test store to validate integration
Stable connection - Reliable internet for polling or webhooks

Required for pollingIf you use polling to receive events, always include the excludeHeartbeat=true parameter to prevent the store from remaining open unintentionally.

Fundamental concepts

Before you start, familiarize yourself with these concepts that apply to all iFood APIs:

Authentication

The Logistics API uses OAuth 2.0 with Bearer tokens.How it works:

Obtain an access token using your credentials (Client ID and Secret)
Include the token in the Authorization: Bearer YOUR_TOKEN header
Automatically renew the token before expiration (default: 3 hours)

For more details: Consult the Authentication documentation to learn about authentication flows, token renewal, and best practices.Important: If you receive a 401 Unauthorized error, your token has expired. Request a new one immediately.

Rate Limit

The Logistics API has request limits to ensure reliability:

100 requests per minute for most endpoints
When you exceed the limit, you'll receive status 429 Too Many Requests
The Retry-After header indicates how many seconds to wait before retrying

How to avoid:

Poll every 30-60 seconds (no more frequently)
Process events in batches, not one at a time
Implement exponential backoff for retries

For specific limits and retry strategies: Consult the Rate Limit documentation.

Error handling

The API returns standard HTTP status codes plus Logistics-specific errors:

Code	Meaning	What to do
`200`	OK	Request successful
`202`	Accepted	Async operation accepted (result will come via event)
`400`	Bad Request	Invalid payload or missing field - check your request
`401`	Unauthorized	Token expired or invalid - renew the token
`403`	Forbidden	No permission for this merchant - check permissions
`404`	Not Found	Order not found or not eligible
`409`	Conflict	Operation invalid for current order state
`412`	Precondition Failed	Order must be in valid state before this action
`422`	Unprocessable Entity	Data rejected by business logic (e.g., wrong code)
`429`	Too Many Requests	Rate limit exceeded - wait before retrying
`500`	Server Error	Server error - retry after 30 seconds

For a complete analysis of each error, see Error Handling below.

Error handling - Logistics specific

Beyond standard HTTP errors, the Logistics API returns these specific codes:

202 Accepted (Async operation)

Endpoints like /assignDriver, /goingToOrigin, etc. return 202 because operations are processed asynchronously.What it means: Your request was accepted, but the result will come via an event (polling or webhook).Example:

curl -X POST https://api.ifood.com.br/logistics/v1.0/orders/{id}/assignDriver \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"workerName":"John","workerPhone":"1199999999","workerVehicleType":"MOTORCYCLE"}'

# Response: 202 Accepted (empty body)
# Result: You'll receive an event confirming the assignment

409 Conflict (Invalid state)

Returned when you attempt an operation invalid for the current order state.Common causes:

Try to assign driver twice to the same order
Call /arrivedAtDestination before /dispatch
Call an endpoint outside the correct sequence

Solution: Follow the sequence: assignDriver → goingToOrigin → arrivedAtOrigin → dispatch → arrivedAtDestination → verifyDeliveryCode

412 Precondition Failed (Invalid Handshake)

Returned when calling /verifyDeliveryCode and the order is not eligible.Common causes:

Order didn't receive the DELIVERY_DROP_CODE_REQUESTED event
You didn't complete arrivedAtDestination before verifying code
Order is in cancelled state

Solution: Check if you received the DELIVERY_DROP_CODE_REQUESTED event via polling/webhook. If not, the order doesn't require code validation.

422 Unprocessable Entity (Data Rejected)

Returned when data is valid syntactically but rejected by business logic.Common causes in Logistics:

Delivery code incorrect or doesn't match expected
Code was already verified previously
Order in invalid state

Solution: Read the error message in the response to understand the exact reason for rejection.

Next steps

Choose how you want to proceed:

Order structure

Understand the complete structure of order data, including fields, types, and real examples.

Order details

Understand the complete structure of order data, including fields, types, and real examples.

Best practices

Learn the recommendations for token management, rate limiting, error handling, and security.

Troubleshooting

Find solutions to common integration problems and understand error codes.

Homologation

See the validation criteria and how to schedule the homologation process for your application.

Quick endpoint reference

Operation	Endpoint	Method
Assign driver	`/assignDriver`	POST
Notify pickup	`/goingToOrigin`	POST
Confirm pickup	`/arrivedAtOrigin`	POST
Notify delivery	`/dispatch`	POST
Confirm delivery	`/arrivedAtDestination`	POST
Verify code	`/verifyDeliveryCode`	POST
Get order	`/orders/{id}`	GET