Open Delivery Integration

Complete technical documentation for our Open Delivery API. The integration follows the ABRASEL specification — if you have already implemented the standard on another logistics platform, you reuse the same code and change only the base URL, client_id and client_secret.

Introduction

The Entregas Expressas Open Delivery API lets software built on the Open Delivery specification integrate with our platform without new development. The typical flow:

1. The merchant (end customer) generates a client_id + client_secret in its panel and sends them to you.
2. You exchange those credentials for an access token via OAuth2 (client credentials).
3. You create deliveries, simulate prices, mark orders ready for pickup, cancel — all with the token in the header.
4. You receive webhooks on every status change (accepted, picked up, delivered, etc.).

Exchanging information with the merchant

🔁 You send to the merchant

• Merchant ID — the merchant's identifier in your system (UUID recommended, up to 100 chars).
• Webhook URL — the URL where you will receive update events.

🔐 The merchant sends to you

• Client ID — generated in the Entregas Expressas panel.
• Client Secret — treat it like a password; never expose it in the front end.

Each merchant generates its own pair of credentials — do NOT share credentials between different merchants. The customer fills everything in under Integrações > Open Delivery (Integrations > Open Delivery) and checks “ativar integração” (enable integration).

Base URL & APP-ID

Default base URL:

https://entregasexpressas.com.br/api/opendelivery

Our APP-ID:

d3e3eaf2-e585-4177-962a-7be998efab8e

🔑 Authentication

Standard OAuth 2.0 client_credentials. It issues a JWT access token valid for 24h (expires_in: 86400). Send the token in the Authorization: Bearer <token> header of every subsequent call.

Request body

{
  "grant_type": "client_credentials",
  "client_id": "<merchant_client_id>",
  "client_secret": "<merchant_client_secret>"
}

Response 200

{
  "access_token": "eyJhbGciOiJIUzI1NiI...",
  "token_type": "bearer",
  "expires_in": 86400
}

cURL example

curl -X POST https://entregasexpressas.com.br/api/opendelivery/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "...",
    "client_secret": "..."
  }'

📊 Simulate a delivery (availability and price)

Before creating a delivery, simulate the price, ETAs and vehicle availability. Useful for showing the delivery fee in the merchant's checkout before the consumer completes the purchase.

Request body — main fields

Request body — example

{
  "merchant": {
    "id": "22815773000169-dbc7e35a-c936-4665-9e13-eb55eb8b6824",
    "name": "Pizza Plaza"
  },
  "pickupAddress": {
    "country": "BR", "state": "BR-SP", "city": "São Paulo",
    "district": "Moema", "street": "Av. Plaza", "number": "100",
    "postalCode": "20111-000", "complement": "",
    "latitude": -23.54809, "longitude": -46.63638
  },
  "deliveryAddress": {
    "country": "BR", "state": "BR-SP", "city": "São Paulo",
    "district": "Vila Mariana", "street": "R. Domingos de Morais", "number": "1267",
    "postalCode": "04009-002", "complement": "Apto 31",
    "latitude": -23.59045, "longitude": -46.63876
  },
  "vehicle": {
    "type": ["MOTORBIKE_BAG"],
    "container": "THERMIC",
    "containerSize": "MEDIUM"
  },
  "limitTimes": {
    "pickupLimit": 20,
    "deliveryLimit": 45,
    "orderCreatedAt": "2026-05-17T14:32:00Z"
  },
  "totalOrderPrice": { "value": 89.90, "currency": "BRL" },
  "totalWeight": 1200,
  "returnToMerchant": false,
  "canCombine": true,
  "onlinePayment": true
}

Response 200 — returned fields

{
  "deliveryPrice": { "value": 12.50, "currency": "BRL" },
  "vehicles": {
    "availableVehicles": 4,
    "nextAvailableVehicle": 0
  },
  "ETAs": {
    "updateMethod": "ONLINE",
    "pickupEtaInMinutes": 8,
    "pickupEtaDatetime": "2026-05-17T14:40:00Z",
    "deliveryEtaInMinutes": 32,
    "deliveryEtaDatetime": "2026-05-17T15:04:00Z",
    "maxDeliveryTime": "2026-05-17T15:17:00Z"
  }
}

📦 Create a new delivery

Registers a new delivery request. Returns 202 Accepted — the final acceptance arrives via webhook (ACCEPTED or REJECTED).

Request body — required fields

All the fields of /availability, plus:

The payments object

Response 202 — request accepted for processing

{
  "deliveryId": "8f3e9c20-aa14-4f5d-92b2-9bca6e0a3e10",
  "orderId": "52122852-6626-11ed-9022-0242ac120002",
  "status": "PENDING",
  "createdAt": "2026-05-17T14:32:05Z"
}

🍔 iFood orders (and orders from other marketplaces)

When the order originated in a marketplace and your system hands the delivery over to us, send the source and its codes in the metadata object of POST /v1/logistics/delivery. They are what the courier uses to complete the delivery on iFood, and what the merchant uses to find the order in its panel.

metadata fields

What we do with each code

• Locator code: when the delivery is completed, the courier app shows the 8-digit code with a shortcut to iFood's delivery confirmation page. If the text does not contain the locator code in this format, the delivery proceeds normally, just without that shortcut.
• Order number, phone number and pickup code: they appear in the delivery notes, in the panel and in the courier app.
• The root-level orderId and orderDisplayId remain the IDs of your system. Do not replace them with the iFood IDs: the orderId is how we prevent duplicate deliveries and how you query, cancel and mark an order ready for pickup.

Example

{
  "orderId": "52122852-6626-11ed-9022-0242ac120002",
  "orderDisplayId": "4821",
  "merchant": { "id": "loja-123", "name": "Hamburgueria Central" },
  ...
  "metadata": {
    "pickUpCode": "7391",
    "partnerData": {
      "orderPartnerName": "iFood",
      "orderDisplayId": "6512",
      "phoneNumber": "0800 200 5011, localizador: 93898428"
    }
  }
}

🛎️ Report ready for pickup

Use it when the order is ready ahead of the estimated time and you want to call the courier earlier. Only required if you set notifyReadyForPickup: true when creating the delivery.

No body. The orderId in the URL is the same UUID sent in POST /v1/logistics/delivery.

❌ Cancel a delivery

Can be called at any time. If the courier has already accepted, the logistics operator may charge an additional fee according to its policy. If the order is part of a combined delivery, it is detached (the other orders proceed normally).

Request body

Response 202

{
  "additionalCharges": false
}

additionalCharges indicates whether the cancellation incurs an additional charge.

🔍 Delivery details

Retrieves the full state of a delivery — the last attempt processed (in case of retries).

Returns an object with all the fields of the DeliveryOrder (the one you sent), plus the event history, courier data (deliveryMan) and location (geoLocalization) when available.

📬 Status webhook

On every change in the delivery state, we send a POST to the Webhook URL configured by the merchant. Respond with HTTP 204 within 10s — anything else triggers a retry with backoff.

Important: we send the POST to the Webhook URL exactly as registered, without appending any route suffix. If your endpoint expects to receive the events at /v1/newLogisticEvent, register that path already included in the Webhook URL itself (e.g., https://your-domain/v1/opendelivery/webhook/v1/newLogisticEvent).

Required headers

Payload — main fields

The event type, timestamp and message are nested inside the event object (not at the top level). The fields below are always sent; the operational fields (vehicle, deliveryPrice, eta, deliveryPerson) only appear in progress events — not in PENDING, REJECTED or CANCELLED.

The structure follows the official OpenDelivery newLogisticEvent schema. The operational fields (vehicle, deliveryPrice, eta, deliveryPerson) are conditional: they accompany progress events, but not PENDING, REJECTED or CANCELLED.

Example — acceptance event

{
  "deliveryId": "32a20413-d5da-4b5d-a7f1-7a36e7f3495f",
  "orderId": "2003",
  "orderDisplayId": "12",
  "merchant": { "id": "2001", "name": "Loja Exemplo" },
  "event": {
    "type": "ACCEPTED",
    "datetime": "2026-05-17T14:32:18.000000Z",
    "message": "Pedido aceito pelo serviço de entrega"
  },
  "problem": [],
  "customerName": "João da Silva",
  "vehicle": {
    "type": "MOTORBIKE_BAG",
    "container": "THERMIC",
    "containerSize": "MEDIUM",
    "instruction": "N/A"
  },
  "deliveryPrice": {
    "price": { "value": 12.5, "currency": "BRL" },
    "pricingList": "NORMAL",
    "additionalPricePercentual": 0
  },
  "eta": {
    "updateMethod": "OFFLINE",
    "pickupEtaInMinutes": 15,
    "pickupEtaDatetime": "2026-05-17T14:47:18.000000Z",
    "deliveryEtaInMinutes": 30,
    "deliveryEtaDatetime": "2026-05-17T15:02:18.000000Z",
    "maxDeliveryTime": "2026-05-17T16:02:18.000000Z"
  },
  "deliveryPerson": {
    "id": "1138",
    "name": "Carlos Silva",
    "phone": "5511999990000",
    "pictureURL": "https://cdn.exemplo.com/couriers/1138.jpg"
  },
  "externalTrackingURL": "https://seu-dominio/tracking/32a20413-d5da-4b5d-a7f1-7a36e7f3495f",
  "combinedOrdersIds": []
}

Example — rejection event

{
  "deliveryId": "32a20413-d5da-4b5d-a7f1-7a36e7f3495f",
  "orderId": "2003",
  "orderDisplayId": "12",
  "merchant": { "id": "2001", "name": "Loja Exemplo" },
  "event": {
    "type": "REJECTED",
    "datetime": "2026-05-17T14:33:02.000000Z",
    "message": "Pedido fora do raio de entrega",
    "rejectionInfo": { "reason": "REGION_NOT_SERVED" }
  },
  "problem": [],
  "customerName": "João da Silva",
  "externalTrackingURL": "https://seu-dominio/tracking/32a20413-d5da-4b5d-a7f1-7a36e7f3495f",
  "combinedOrdersIds": []
}

Validating the signature (Node.js)

const crypto = require('crypto');
function validateSignature(rawBody, headerSignature, clientSecret) {
  const expected = crypto
    .createHmac('sha256', clientSecret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(headerSignature, 'hex')
  );
}

Auxiliary schemas

AddressLogistics

Vehicle

Price

Error codes

Using the developer dashboard

The whole development cycle happens inside the portal: you create the app, receive sandbox credentials, configure the webhook, inspect requests and simulate orders without having to coordinate with a real courier. The steps below follow the natural order of the work.

1. Create an OpenDelivery app

In the dashboard, click Apps > New app and choose the OpenDelivery type. As soon as the app is created, we automatically provision a sandbox merchant in a dedicated hub, with the integration already enabled. There is no manual “connect to a customer” step — the sandbox exists so you can develop without depending on a real customer.

2. Where to get the test client_id and client_secret

1. Open the app in the dashboard.
2. Go to the Credentials tab.
3. Copy the client_id and client_secret fields — there is a copy button next to each one.
4. Use exactly those values in the payload of POST /oauth/token from the authentication section.

Need to regenerate the client_secret? Use the Regenerate credentials button in the Credentials tab itself. The old pair stops working immediately — update your application before regenerating.

3. Configure the webhook URL

1. Open the app's Webhook tab.
2. In the Webhook URL field, paste the HTTPS URL where your application receives events (format detailed in Status webhook).
3. Check “Allow the merchant to override this URL” if you want to give that option to the end customer — in production, some merchants have their own webhook (POS system, ERP). If you leave it unchecked, the URL is fixed for everyone.
4. Click Save. The change takes effect immediately — no deploy is needed on our side.

4. Inspect received requests

The Inspection tab shows every request our platform made to your API (and, in some cases, what your API responded). For each one:

• Method, full path, status code and latency.
• Headers sent and the full payload (request body).
• Filters by endpoint and by status — useful for viewing only 4xx errors or only webhooks.

Use it to debug OAuth, validate payloads, and find the cause of a 4xx your application returned without having to dig through your own logs.

5. Simulate orders and trigger webhooks

Test orders tab: lists the orders created via API in the sandbox merchant. For each one, you can advance the status manually (accept, assign a courier, mark as picked up, delivered, or trigger a rejection). Each change sends the real webhook to your URL — you test the handlers on your side without coordinating a real courier or waiting minutes.

6. Invite other developers on your team

1. Members tab > Invite.
2. Enter your colleague's email.
3. If they already have a portal account, they receive a link to accept. If not, they receive a link to sign up already linked to your app.
4. Members see everything: credentials, webhook, inspection, simulation.

7. Adjust the app's name, description, logo and website

Settings tab: app name, a clear description of what it does, public website, and logo (PNG/SVG). This data appears in the public showcase and on the screen where the merchant enables your integration — a clear description and a sharp logo have a direct effect on conversion. The three fields (description, app website, logo) are required to submit the app for approval.

Submit for approval

Once your implementation is working in sandbox, you submit the app for approval by the Plataforma Entregas Expressas team. When approved, the app becomes visible to the 30,000+ merchants that use the platform — they find your app in the public showcase and connect from their own panel, generating real credentials.

Prerequisites before submitting

• Final app name (this is the name the merchant will see).
• A clear description — what your integration does, what the merchant gains.
• App website — a public page where the merchant can understand your product.
• Logo — it will appear in the showcase and on the activation screen.
• Working OAuth: you can exchange client_id + client_secret for a token at POST /oauth/token.
• Delivery creation tested at POST /delivery.
• Webhook being received, with the HMAC signature validated on your side.

How to submit

1. Open the app in the dashboard.
2. In the Overview tab, click Submit for review.
3. If any of the required fields is empty, the portal shows exactly what is missing before enabling the button — fill it in under Settings and come back.
4. The app moves to the “Awaiting review” status. You receive an email as soon as the team evaluates it.

What changes after approval

• The app starts appearing in the public showcase and on the Integrações > Open Delivery screen each merchant sees in its panel.
• Each merchant that enables your integration generates its own pair of client_id + client_secret in its panel — your application needs to accept multiple pairs and route them by your merchantId.
• Official partner apps may receive a dedicated base URL (dedicated host). Ask the team if that is relevant for you.

If it is rejected

The reason appears in the dashboard (Overview tab) and by email. The most common fixes are: a vague description, a low-quality logo, a webhook that does not validate the signature, or a partial implementation of the required endpoints. Fix it and click Submit for review again — there is no limit on attempts.

Create / access my apps   View the Full API