Full API

This API gives broad access to a delivery company's operation — orders, customers, couriers, vehicle types, webhooks. Use it when your system integrates with one specific delivery company that gave you an API key (e.g., an ERP or internal dashboard connected to its operation). Endpoints are named in Portuguese; payloads and responses are JSON.

Introduction

The Full integration gives access to the same set of operations the delivery company uses in its own Admin Panel: creating orders, tracking status, managing the customers who request deliveries, looking up the available vehicle types and subscribing to webhooks. Unlike OpenDelivery, which is multi-customer and uses OAuth, Full is one-to-one: a fixed API key issued by the delivery company itself, with permission over its operation.

Typical flow:

1. The delivery company gives you the API key (Bearer token).
2. You use POST /v1/orders/calcular to simulate price and distance before the consumer confirms.
3. You create the order with POST /v1/orders (or do everything in a single call with POST /v1/chamar-entregador).
4. You track it in real time via webhook, subscribing to the events you use, or by polling GET /v1/orders/{id}.

Base URL

All endpoints below are relative to this base, on the delivery company's domain:

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

🔑 Authentication

Every call requires the header Authorization: Bearer <your-api-key>. The key is static (it does not expire over time); it only changes if it is regenerated manually. Treat it like a password — do not expose it in front-end code. You can regenerate it at any time in the Credentials tab of the app in the Portal.

Always send Accept: application/json and Content-Type: application/json as well on requests with a body.

Two kinds of key

The delivery company can issue two kinds of API key, and what each one reaches is different:

The split exists because the two things are not the same: whoever reads their own balance cannot credit it, and the courier team belongs to the company, not to whoever hires the delivery.

// 403 — the credential does not reach the resource
{"mensagem": "Esta credencial não tem acesso a este recurso"}

cURL example

curl https://entregasexpressas.com.br/api/v1/tipos-veiculos \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Accept: application/json"

Calculate price

Before sending the order you can simulate its price by sending the delivery data — it returns the distance, the gross price and formatted descriptions. Nothing is created in the system.

Request body

Example

curl -X POST https://entregasexpressas.com.br/api/v1/orders/calcular \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_veiculo_id": 1,
    "categoria_id": 3,
    "cliente_id": 3,
    "endereco_coleta": {
      "endereco": "Rua teste, 123 - Teste, São Paulo - SP, 00000-000",
      "latitude": -23.570914,
      "longitude": -46.645079,
      "nome": "João",
      "telefone": "(11) 99999-9923"
    },
    "enderecos_entrega": [
      {
        "endereco": "Rua teste, 33 - Teste 2, São Paulo - SP, 00000-000",
        "latitude": -23.585292,
        "longitude": -46.655723,
        "nome": "Maria",
        "telefone": "(11) 12131-9923"
      }
    ],
    "dimensoes_pacote": { "peso": 15, "largura": 15, "altura": 15, "comprimento": 15 },
    "retorno_necessario": true,
    "prova_entrega_necessaria": false
  }'

200 response

{
  "preco": 12.50,
  "distancia": 5.42,
  "precoDescricao": "R$ 12,50",
  "distanciaDescricao": "5,42 km"
}

New order

Creates a delivery order. The pickup and delivery addresses must contain latitude/longitude, or the text address for automatic geocoding. Prerequisite: the customer exists (use cliente_id), or you send the nested cliente object.

Request body

List orders

Lists orders, paginated. You can also look up specific orders by id or external_id.

Query string

200 response

Returns Laravel's standard pagination, with data[] containing one Order object per item — full schema in Order object.

{
  "current_page": 1,
  "data": [ /* Order objects */ ],
  "first_page_url": "...",
  "from": 1,
  "last_page": 4,
  "last_page_url": "...",
  "limit": 50,
  "next_page_url": "...",
  "path": "https://entregasexpressas.com.br/api/v1/orders",
  "prev_page_url": null,
  "to": 50,
  "total": 187
}

Get order

Fetches the data of a specific order by its ID.

URL params

200 response

Returns the full Order object — see Order object.

// 404
{"mensagem": "Pedido não encontrado"}

Cancel order

Cancels an order. Available only for orders that have not been accepted yet (pending, waiting, scheduled or preparing).

Responses

// 200 OK
{"mensagem": "Pedido cancelado"}

// 400 — the current status does not allow cancellation
{"mensagem": "O pedido não pode ser cancelado"}

// 404
{"mensagem": "Pedido não encontrado"}

Call a courier (one-shot)

Creates an order of the call a courier type, where the delivery addresses are set by the courier at pickup time. You must provide the number of delivery locations (num_locais_entrega). It also creates the user inline if cliente_id is not sent.

Request body

201 response — example

{
  "id": 128,
  "order_status": "pending",
  "status": "Pendente",
  "total_value": 0,
  "distance": 0,
  "pickup_location_data": {
    "endereco": "Rua teste, 123 - Teste, São Paulo - SP, 00000-000",
    "latitude": -23.570914,
    "longitude": -46.645079
  },
  "delivery_locations_data": [
    {"endereco": "Endereço de Entrega #1 (Definido no momento da entrega)", "latitude": null, "longitude": null, "delivered": false},
    {"endereco": "Endereço de Entrega #2 (Definido no momento da entrega)", "latitude": null, "longitude": null, "delivered": false}
  ]
}

Full response schema in Order object.

Users (customers)

CRUD for the users (customers) who place orders through the company. Each user belongs to a central (hub) — the hub ID is implicit in the API key.

List / search users

Get user

// 404
{"mensagem": "Usuário não encontrado"}

Create user

// Request
{
  "nome": "Novo Usuário",
  "email": "[email protected]",
  "senha": "0346nlkasd",
  "telefone": "(11) 12532-1234",
  "external_id": "12516"
}

// 400 — validation
{"mensagem": "Erro de validação", "errors": {"email": ["O email informado está em uso"]}}

Update user

Updates the data of an existing user. Only the fields you send are updated.

// 404
{"mensagem": "Usuário não encontrado"}

User object (response)

Generate access token

Generates an access token for a user. If the user does not exist, it is created automatically with the data you send — which is why every field of the record is required.

// 201
{"token": "aB3dEf4gHi5jKl6mNo7pQr8sTu9vWx0yZ1aB2cD3eF4gH5iJ6kL7mN8oP9q"}

// 400 — validation
{"mensagem": "Erro de validação", "errors": {"email": ["O campo email é obrigatório"]}}

Block / unblock a customer

Blocking cuts off the intake: the customer can no longer place orders, through the portal or the API. It does not cancel or interrupt what is already in progress — an order out for delivery keeps being handled normally.

Both return the updated User object, with the bloqueado field. No body is needed.

The same state can also be sent on PUT /v1/usuarios/{id}, in the optional bloqueado field — it is the same thing, for those who sync the whole record in a single call. Omitting the field keeps the current state.

curl -X POST https://entregasexpressas.com.br/api/v1/usuarios/3/bloqueio \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Accept: application/json"

// 200
{"data": {"id": 3, "nome": "Loja Centro", "bloqueado": true, "saldo": 152.40}}

Wallet (balance, statement and entries)

The digital wallet is the prepaid balance the delivery company keeps for each customer and for each courier. These endpoints read the balance, read the statement and make manual entries — the same ones the Admin Panel makes on the "Adicionar saldo" (add balance) and "Remover saldo" (remove balance) screens.

Safe retries (external_id)

Every entry accepts an external_id — the identifier of that entry in your system. It exists for a practical reason: network timeouts are the common case in an integration, and without an idempotency key, retrying a money POST credits twice.

• First call: 201 with "duplicada": false.
• Retry with the same external_id: 200 with "duplicada": true and the same entry — nothing is created, nothing is added.

The key is unique per wallet. Use a value your system can reproduce on the retry (the ID of the transaction in your ERP, for example) — a value drawn at random on each attempt protects nothing. Without external_id, every call is a new entry.

Get balance

// 200
{"data": {"usuario_id": 3, "saldo": 152.40}}

usuario_id is the owner of the wallet. When the ID you query belongs to a sub-user, the response carries the account owner's ID: a sub-user has no wallet of its own, it spends the store's.

Statement

// 200
{
  "data": [
    {
      "id": 8813,
      "uuid": "1f0a…",
      "operacao": "credito",
      "tipo": "adicao_saldo",
      "valor": 200.00,
      "descricao": "Recarga via Pix — comprovante 8812",
      "status": "concluido",
      "external_id": "erp-recarga-4410",
      "forma_pagamento": "pix",
      "referencia_id": null,
      "data_criacao": "2026-09-09T14:02:11.000000Z"
    }
  ],
  "meta": {"pagina": 1, "por_pagina": 50, "total": 137, "saldo": 448.90}
}

Add balance

Manual credit — the same entry the Admin Panel makes in "Adicionar saldo" (add balance).

curl -X POST https://entregasexpressas.com.br/api/v1/usuarios/3/carteira/creditos \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"valor": 100.50, "descricao": "Bônus de campanha", "external_id": "erp-credito-9931"}'

// 201
{
  "data": {"id": 8812, "operacao": "credito", "tipo": "adicao_saldo", "valor": 100.50, "status": "concluido", "external_id": "erp-credito-9931"},
  "saldo": 252.90,
  "duplicada": false
}

Remove balance

// 400 — only when permitir_saldo_negativo = false
{"mensagem": "Saldo insuficiente para o débito"}

Record a top-up

Records a top-up the customer has already paid. It is the same credit as carteira/creditos, with two differences:

• the payment method is required and is stored on the statement;
• the top-up fee configured by the delivery company is applied by default — the same one that applies when the payment arrives through the gateway. It becomes a debit of its own, linked to the top-up, and shows on the statement as "Taxa de recarga" (top-up fee).

The fee only exists for pix, boleto and credit_card, and only when the delivery company has configured it — for the other methods, and where it is not configured, the full amount is credited and the taxa block does not appear in the response.

// 201
{
  "data": {"id": 8813, "operacao": "credito", "tipo": "adicao_saldo", "valor": 200.00, "forma_pagamento": "pix"},
  "taxa": {"valor": 4.00, "transacao_id": 8814},
  "saldo": 448.90,
  "duplicada": false
}

Courier wallet

The same four endpoints exist for the courier, replacing usuarios with entregadores and the customer's ID with the courier's ID (the id returned by /v1/entregadores).

• The courier's balance goes negative in normal use of the operation — that is how the app's commission is charged to them. That is why the debit does not check the balance by default.
• On the courier's carteira/recargas there is no fee: the top-up fee is configured for the customer and does not describe a courier's deposit. forma_pagamento is still required, so the statement says where the money came from.

Couriers

Look up the company's courier team, their real-time status, block access and block withdrawals only. Their wallet is covered in the Wallet section.

List couriers

Entregador object (response)

// 200
{
  "data": [
    {
      "id": 12,
      "nome": "João Souza",
      "email": "[email protected]",
      "telefone": "(11) 99999-8888",
      "cpf": "000.000.000-00",
      "ativo": true,
      "aprovado": true,
      "bloqueado": false,
      "bloqueado_ate": null,
      "veiculo": {"modelo": "Honda CG 160", "cor": "Vermelho", "placa": "ABC1D23"},
      "tipos_servico": [{"id": 1, "nome": "Moto"}],
      "saldo": -18.70,
      "saque_bloqueado": false,
      "data_criacao": "2026-03-02T11:20:00.000000Z"
    }
  ],
  "meta": {"pagina": 1, "por_pagina": 50, "total": 34}
}

Online couriers

Only the couriers who are online now, from the one who sent a position most recently to the oldest, with the same pagination as the listing. Each item is a full Courier object; the webhook's courier events carry a subset of it.

Get courier

Block / unblock a courier

Blocking takes the courier out of operation: they stop receiving order offers and cannot accept what was already on their screen. It does not interrupt an order in progress — blocking in the middle of a shift cannot leave a delivery orphaned on the street; they finish what they are carrying.

curl -X POST https://entregasexpressas.com.br/api/v1/entregadores/12/bloqueio \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"bloqueado_ate": "2026-09-20T18:00:00-03:00"}'

// 200
{"data": {"id": 12, "nome": "João Souza", "ativo": false, "bloqueado": true, "bloqueado_ate": "2026-09-20T21:00:00.000000Z"}}

Block / unblock withdrawals

Blocks only the withdrawals and advances from the wallet. The courier stays online, receiving, accepting and delivering orders normally. The response is the Entregador object, with saque_bloqueado updated.

curl -X POST https://entregasexpressas.com.br/api/v1/entregadores/12/bloqueio-saque \
  -H "Authorization: Bearer <your-api-key>"

// 200
{"data": {"id": 12, "nome": "João Souza", "ativo": true, "saque_bloqueado": true, ...}}

Vehicle types & categories

Each company configures which vehicle types it operates (motorcycle, car, etc.) and, optionally, categories within each type (e.g., "Moto com bag" vs "Moto sem bag"). Use these endpoints to build the pickers in your system and to find out weight/dimension limits before sending the order.

List vehicle types

Response fields

Get vehicle type

// 200
{"id": 1, "nome": "Moto"}

// 404
{"mensagem": "Tipo de veículo não encontrado"}

List a vehicle type's categories

Response fields

// 404
{"message": "Tipo de veículo não encontrado"}

Webhooks

Instead of polling /orders/{id}, register a webhook URL with the list of events it should receive. On each event, the Platform sends a JSON POST to that URL, with the event name in event. The URL is configured through the endpoints below or in the delivery company's Admin Panel.

Events

Subscribe only to what your integration uses. Each URL receives exactly the events in its eventos list, which can be changed at any time through PATCH /v1/webhooks/{id}.

Headers sent on delivery

Order status (order_status)

List webhooks

Get webhook

Register webhook

// Request
{
  "url": "https://entregas-expressas.teste",
  "codigo_seguranca": "Aas#asdg@fngasd",
  "eventos": ["ORDER_ACCEPTED", "ORDER_COLLECTED", "ORDER_COMPLETED", "ORDER_CANCELLED", "COURIER_LOCATION_UPDATED"]
}

// 400 — validation
{"mensagem": "Erro de validação", "errors": {"url": ["Uma URL de webhook com este endereço já existe"]}}

// 403 — courier event not included in the plan
{"mensagem": "Eventos de entregador estão disponíveis nos planos Premium e Platina"}

Update webhook

Changes the events or the security code of a URL that is already registered. Only the fields you send change. It is also the way to migrate a URL from the legacy format: just send the eventos list.

// Request
{"eventos": ["ORDER_CREATED", "ORDER_CANCELLED", "COURIER_ONLINE", "COURIER_OFFLINE"]}

Remove webhook

// 200
{"mensagem": "Webhook removido com sucesso"}

// 404
{"mensagem": "Webhook não encontrado"}

Webhook object (response)

Payload delivered to your URL

For order events, the delivery is a POST with event + the full Order object (see Order object). Use order_status and the order's date fields as the source of truth: the arrival order between two events is not guaranteed.

{
  "event": "ORDER_ACCEPTED",
  "order": {
    "id": 1234,
    "public_id": "A7K2",
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": null,
    "user_id": 10,
    "started_at": "2025-01-15 10:30:00",
    "pickup_location": "Rua Exemplo, 100 - Centro",
    "pickup_location_data": {
      "latitude": -23.5505,
      "longitude": -46.6333,
      "endereco": "Rua Exemplo, 100 - Centro"
    },
    "delivery_locations_data": [
      {
        "id": "abc123",
        "latitude": -23.5605,
        "longitude": -46.6433,
        "endereco": "Rua Destino, 200 - Bairro",
        "rua": "Rua Destino",
        "numero": "200",
        "bairro": "Bairro",
        "cidade": "Sao Paulo",
        "estado": "SP",
        "complemento": "Apto 101",
        "cep": "01001-000",
        "nome": "Joao Silva",
        "telefone": "(11) 99999-9999",
        "external_id": "123",
        "order_display_id": "PED-001",
        "delivered": false,
        "delivered_date": null,
        "delivery_failed": false,
        "evidence": {
          "photo": "https://exemplo.com/foto.jpg",
          "photos": ["https://exemplo.com/foto.jpg"],
          "signature": null,
          "document": "123.456.789-00",
          "name": "Joao Silva",
          "observation": null
        }
      }
    ],
    "need_return_to_pickup_location": false,
    "need_delivery_proof": false,
    "distance": 5.2,
    "return_distance": 0,
    "total_value": 15.50,
    "customer_observation": "Pedido via integração",
    "valor_pedidos": 89.90,
    "offline_payment_method_id": null,
    "pagamento_faturado": false,
    "payment_gateway": "carteira_digital",
    "gateway_method": null,
    "payment_code": null,
    "payment_base64": null,
    "payment_expiration_date": null,
    "payment_url": null,
    "payment_status": "paid",
    "order_status": "accepted",
    "type": "delivery",
    "status_observation": null,
    "category_id": 1,
    "vehicle_type_id": 1,
    "height": null,
    "length": null,
    "width": null,
    "weight": null,
    "created_at": "2025-01-15T10:30:00.000000Z",
    "updated_at": "2025-01-15T10:35:00.000000Z",
    "accepted_at": "2025-01-15T10:35:00.000000Z",
    "arrived_pickup_location_at": null,
    "arrived_limit_date": null,
    "picked_up_at": null,
    "finished_at": null,
    "collect_limit_date": null,
    "pickup_code": "1234",
    "status": "Aceito",
    "courier": "Carlos Entregador",
    "courier_data": {
      "id": 5,
      "name": "Carlos Entregador",
      "location": {
        "latitude": -23.5510,
        "longitude": -46.6340
      }
    },
    "category": {"id": 1, "name": "Alimentação"},
    "vehicle_type": {"id": 1, "name": "Moto"},
    "user": {
      "id": 10,
      "email": "[email protected]",
      "name": "Restaurante Exemplo",
      "external_id": null
    },
    "tracking_url": "https://entregasexpressas.com.br/tracking/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Payload of courier events

event + a subset of the Courier object in courier, the same in all three events, with the status and position at the time of sending: id, name, online, status, last_seen_at, location and active_orders. Vehicle, phone and service types are available at /v1/entregadores/online.

{
  "event": "COURIER_LOCATION_UPDATED",
  "courier": {
    "id": 12,
    "name": "João Souza",
    "online": true,
    "status": "busy",
    "last_seen_at": "2026-09-28T14:02:11.000000Z",
    "location": {"latitude": -23.5505, "longitude": -46.6333},
    "active_orders": [{"id": 48213, "external_id": "PED-001", "order_status": "collected"}]
  }
}

Legacy format

URLs registered without eventos ("eventos": null in the response) keep working as before, for compatibility: they receive ORDER_CREATED, ORDER_UPDATED (any change of status or of order data) and ORDER_DELETED for all orders, with the same Order object. They do not receive courier events.

Order object (full schema)

Schema of the response of the endpoints POST /v1/orders, GET /v1/orders (in data[]), GET /v1/orders/{id}, POST /v1/chamar-entregador and of the webhook payload (in order).

Main fields

Addresses

Package and vehicle

Payment

Lifecycle timestamps

Courier

Order customer (user)

Courier object

Each item of /v1/entregadores/online carries the full object; the webhook's courier events carry a subset of it in courier (see which fields). The names follow the Order object: id, name and location are the same as in courier_data, and each order in active_orders uses order_status.

{
  "id": 12,
  "name": "João Souza",
  "phone": "(11) 99999-8888",
  "online": true,
  "status": "busy",
  "last_seen_at": "2026-09-28T14:02:11.000000Z",
  "location": {"latitude": -23.5505, "longitude": -46.6333},
  "vehicle": {"model": "Honda CG 160", "color": "Vermelho", "plate": "ABC1D23"},
  "vehicle_types": [{"id": 1, "name": "Moto"}],
  "active_orders": [{"id": 48213, "external_id": "PED-001", "order_status": "collected"}],
  "updated_at": "2026-09-28T14:02:11.000000Z"
}

Error codes

Error responses follow the Platform's standard — the message is in mensagem (not message):

{
  "mensagem": "Erro de validação",
  "errors": {
    "tipo_veiculo_id": ["O campo tipo_veiculo_id é obrigatório"]
  }
}

On lookup routes, not-found comes as {"mensagem": "Pedido não encontrado"} (likewise for user, webhook, vehicle type). The categories endpoint, however, uses message ({"message": "Tipo de veículo não encontrado"}) — a small inherited inconsistency.

Using the developer Dashboard

The full test cycle happens in the Portal. Each Full app automatically gets:

• A sandbox hub (Central) isolated from the real operation.
• An admin user for that hub, which you can access through the Access the app's sandbox platform button (at the top of the app page or in the Credentials tab) — useful to see how things look through the administrator's eyes.
• An admin test token, valid only inside that hub.
• An Inspection tab with every request you make (body, response, headers, status).

Step by step

1. Create a Full app in the Dashboard.
2. Credentials tab: copy the Bearer Token and use it in the Authorization header.
3. Webhook tab: paste your HTTPS URL to receive events during testing.
4. Make calls from your system/cURL/Postman. Each request shows up in Inspection within seconds.
5. Use the Access the app's sandbox platform button to see the created order from the company's side (map, assignment, finance) — useful for debugging behavior that depends on rules configured by the company.

Create / access my apps   See the OpenDelivery guide