API Completa (Full)

Esta API é o acesso amplo à operação da empresa de entregas — pedidos, clientes, entregadores, tipos de veículo, webhooks. Use quando seu sistema integra com uma empresa de entregas específica que te forneceu uma API key (ex.: ERP/painel interno conectado à operação dela). Endpoints em português, payload e respostas em JSON.

Introdução

A integração Full dá acesso ao mesmo conjunto de operações que a empresa de entregas usa no próprio painel admin: criação de pedidos, acompanhamento de status, gestão dos clientes que pedem entrega, consulta de tipos de veículo disponíveis e subscrição a webhooks. Diferente da OpenDelivery, que é multi-cliente e usa OAuth, a Full é 1-pra-1: uma API key emitida pela própria empresa de entregas, fixa, com permissão sobre a operação dela.

Fluxo típico:

1. A empresa de entregas te entrega a API key (Bearer token).
2. Você usa POST /v1/orders/calcular para simular preço/distância antes do consumidor confirmar.
3. Cria o pedido com POST /v1/orders (ou tudo em um único call com POST /v1/chamar-entregador).
4. Acompanha em tempo real via webhook, assinando os eventos que usa, ou polling do GET /v1/orders/{id}.

URL base

Todos os endpoints abaixo são relativos a esta base, no domínio da empresa de entregas:

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

🔑 Autenticação

Todas as chamadas exigem o header Authorization: Bearer <sua-api-key>. A key é estática (não expira por tempo); só muda se for regerada manualmente. Trate como senha — não exponha em código de front-end. Regerar pode ser feito a qualquer momento na aba Credenciais do app no portal.

Sempre envie também Accept: application/json e Content-Type: application/json nos requests com body.

Dois tipos de chave

A empresa de entregas pode emitir dois tipos de API key, e o que cada uma alcança é diferente:

A separação existe porque as duas coisas não são a mesma: quem lê o próprio saldo não pode creditá-lo, e a equipe de entregadores é da empresa, não de quem contrata a entrega.

// 403 — a credencial não alcança o recurso
{"mensagem": "Esta credencial não tem acesso a este recurso"}

Exemplo cURL

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

Calcular valor

Antes de enviar o pedido você pode simular o valor enviando os dados da entrega — devolve distância, preço bruto e descrições formatadas. Não cria nada no sistema.

Corpo do request

Exemplo

curl -X POST https://entregasexpressas.com.br/api/v1/orders/calcular \
  -H "Authorization: Bearer <sua-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
  }'

Resposta 200

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

Novo pedido

Cria um pedido de entrega. Os endereços de coleta e entrega devem conter latitude/longitude, ou o endereço textual para geocodificação automática. Pré-requisito: o cliente existe (use cliente_id) ou envie o objeto cliente aninhado.

Corpo do request

Listar pedidos

Lista os pedidos paginados. Também é possível buscar pedidos específicos por id ou external_id.

Query string

Resposta 200

Retorna a paginação padrão do Laravel com data[] contendo um objeto Pedido por item — schema completo em Objeto Pedido.

{
  "current_page": 1,
  "data": [ /* objetos Pedido */ ],
  "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
}

Obter pedido

Busca os dados de um pedido específico pelo seu ID.

URL params

Resposta 200

Retorna o objeto Pedido completo — ver Objeto Pedido.

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

Cancelar pedido

Cancela um pedido. Disponível apenas para pedidos que ainda não foram aceitos (pending, waiting, scheduled ou preparing).

Respostas

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

// 400 — status atual não permite cancelamento
{"mensagem": "O pedido não pode ser cancelado"}

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

Chamar entregador (one-shot)

Cria um pedido do tipo chamar entregador, onde os endereços de entrega serão definidos pelo entregador no momento da coleta. É necessário informar a quantidade de locais de entrega (num_locais_entrega). Também cria o usuário inline se cliente_id não for enviado.

Corpo do request

Resposta 201 — exemplo

{
  "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}
  ]
}

Schema completo da resposta em Objeto Pedido.

Usuários (clientes)

CRUD dos usuários (clientes) que disparam pedidos pela empresa. Cada usuário pertence a uma central (praça) — o ID da central vem implícito no API key.

Listar / buscar usuários

Obter usuário

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

Cadastrar usuário

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

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

Editar usuário

Atualiza os dados de um usuário existente. Apenas os campos enviados são atualizados.

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

Objeto Usuário (resposta)

Gerar token de acesso

Gera um token de acesso para um usuário. Se o usuário não existir, ele é criado automaticamente com os dados enviados — por isso todos os campos do cadastro são obrigatórios.

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

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

Bloquear / desbloquear contratante

Bloquear corta a entrada: o contratante deixa de lançar pedido, pelo portal e pela API. Não cancela nem interrompe o que já está em andamento — pedido na rua continua sendo operado normalmente.

Os dois devolvem o objeto Usuário atualizado, com o campo bloqueado. Nenhum corpo é necessário.

O mesmo estado também pode ser enviado no PUT /v1/usuarios/{id}, no campo opcional bloqueado — é a mesma coisa, para quem sincroniza o cadastro inteiro numa chamada só. Omitir o campo mantém o estado atual.

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

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

Carteira (saldo, extrato e lançamentos)

A carteira digital é o saldo pré-pago que a empresa de entregas mantém para cada contratante e para cada entregador. Estes endpoints leem o saldo, leem o extrato e fazem os lançamentos manuais — os mesmos que o painel faz nas telas "Adicionar saldo" e "Remover saldo".

Reenvio seguro (external_id)

Todo lançamento aceita um external_id — o identificador daquele lançamento no seu sistema. Ele existe por um motivo prático: timeout de rede é o caso comum de uma integração, e sem uma chave de idempotência a retentativa de um POST de dinheiro credita duas vezes.

• Primeira chamada: 201 com "duplicada": false.
• Reenvio com o mesmo external_id: 200 com "duplicada": true e o mesmo lançamento — nada é criado, nada é somado.

A chave é única por carteira. Use um valor que o seu sistema saiba reproduzir na retentativa (o id do movimento no seu ERP, por exemplo) — um valor sorteado a cada tentativa não protege de nada. Sem external_id, cada chamada é um lançamento novo.

Consultar saldo

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

usuario_id é o dono da carteira. Quando o id consultado é de um subusuário, a resposta traz o do titular: subusuário não tem carteira própria, ele gasta a da loja.

Extrato

// 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}
}

Acrescentar saldo

Crédito manual — o mesmo lançamento que o painel faz em "Adicionar saldo".

curl -X POST https://entregasexpressas.com.br/api/v1/usuarios/3/carteira/creditos \
  -H "Authorization: Bearer <sua-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
}

Retirar saldo

// 400 — só quando permitir_saldo_negativo = false
{"mensagem": "Saldo insuficiente para o débito"}

Registrar recarga

Registra uma recarga que o contratante já pagou. É o mesmo crédito de carteira/creditos, com duas diferenças:

• a forma de pagamento é obrigatória e fica gravada no extrato;
• a taxa de recarga configurada pela empresa de entregas é aplicada por padrão — a mesma que incide quando o pagamento chega pelo gateway. Ela vira um débito próprio, ligado à recarga, e aparece no extrato como "Taxa de recarga".

A taxa só existe para pix, boleto e credit_card, e só quando a empresa de entregas a configurou — nas demais formas, e onde ela não está configurada, o valor entra cheio e o bloco taxa não aparece na resposta.

// 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
}

Carteira do entregador

Os mesmos quatro endpoints existem para o entregador, trocando usuarios por entregadores e o id do contratante pelo id do entregador (o id devolvido por /v1/entregadores).

• O saldo do entregador fica negativo no uso normal da operação — é assim que a comissão do app é cobrada dele. Por isso o débito não confere saldo por padrão.
• Em carteira/recargas do entregador não há taxa: a taxa de recarga é configurada para o contratante e não descreve o depósito de um entregador. forma_pagamento continua obrigatória, para o extrato dizer de onde veio o dinheiro.

Entregadores

Consulta da equipe de entregadores da empresa, situação em tempo real, bloqueio de acesso e bloqueio só de saque. A carteira deles está na seção Carteira.

Listar entregadores

Objeto Entregador (resposta)

// 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}
}

Entregadores online

Só os entregadores online agora, do que mandou posição mais recentemente para o mais antigo, com a mesma paginação da listagem. Cada item é um objeto Courier completo; os eventos de entregador do webhook trazem um recorte dele.

Obter entregador

Bloquear / desbloquear entregador

Bloquear tira o entregador de operação: ele deixa de receber oferta de pedido e não consegue aceitar o que já estava na tela dele. Não interrompe pedido em andamento — bloquear no meio do expediente não pode deixar entrega órfã na rua; ele conclui o que está com ele.

curl -X POST https://entregasexpressas.com.br/api/v1/entregadores/12/bloqueio \
  -H "Authorization: Bearer <sua-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"}}

Bloquear / desbloquear saque

Bloqueia só os saques e as antecipações da carteira. O entregador continua online, recebendo, aceitando e entregando pedidos normalmente. A resposta é o objeto Entregador, com saque_bloqueado atualizado.

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

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

Tipos de veículo & categorias

Cada empresa configura quais tipos de veículo opera (moto, carro etc.) e, opcionalmente, categorias dentro de cada tipo (ex.: "Moto com bag" vs "Moto sem bag"). Use estes endpoints pra montar os pickers do seu sistema e pra descobrir limites de peso/dimensão antes de enviar o pedido.

Listar tipos de veículo

Campos da resposta

Obter tipo de veículo

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

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

Listar categorias do tipo de veículo

Campos da resposta

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

Webhooks

Em vez de fazer polling de /orders/{id}, cadastre uma URL de webhook com a lista de eventos que ela deve receber. A cada evento, a Plataforma envia um POST JSON para essa URL, com o nome do evento em event. A URL é configurada pelos endpoints abaixo ou no painel da empresa de entregas.

Eventos

Assine só o que sua integração usa. Cada URL recebe exatamente os eventos da lista eventos, que pode ser alterada a qualquer momento pelo PATCH /v1/webhooks/{id}.

Cabeçalhos enviados na entrega

Status do pedido (order_status)

Listar webhooks

Obter webhook

Cadastrar 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 — validação
{"mensagem": "Erro de validação", "errors": {"url": ["Uma URL de webhook com este endereço já existe"]}}

// 403 — evento de entregador fora do plano
{"mensagem": "Eventos de entregador estão disponíveis nos planos Premium e Platina"}

Alterar webhook

Troca os eventos ou o código de segurança de uma URL já cadastrada. Só os campos enviados mudam. É também o caminho para migrar uma URL do formato legado: basta enviar a lista de eventos.

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

Remover webhook

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

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

Objeto Webhook (resposta)

Payload entregue na sua URL

Nos eventos de pedido, o envio é um POST com event + objeto Pedido completo (ver Objeto Pedido). Use o order_status e os campos de data do pedido como fonte da verdade: a ordem de chegada entre dois eventos não é garantida.

{
  "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 dos eventos de entregador

event + um recorte do objeto Courier em courier, igual nos três eventos, com a situação e a posição do momento do envio: id, name, online, status, last_seen_at, location e active_orders. Veículo, telefone e tipos de serviço ficam em /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"}]
  }
}

Formato legado

URLs cadastradas sem eventos ("eventos": null na resposta) seguem funcionando como antes, por compatibilidade: recebem ORDER_CREATED, ORDER_UPDATED (qualquer mudança de status ou de dados do pedido) e ORDER_DELETED de todos os pedidos, com o mesmo objeto Pedido. Não recebem eventos de entregador.

Objeto Pedido (schema completo)

Schema da resposta dos endpoints POST /v1/orders, GET /v1/orders (em data[]), GET /v1/orders/{id}, POST /v1/chamar-entregador e do payload do webhook (em order).

Campos principais

Endereços

Pacote e veículo

Pagamento

Timestamps de ciclo

Entregador

Cliente do pedido (user)

Objeto Courier (entregador)

Cada item de /v1/entregadores/online traz o objeto completo; os eventos de entregador do webhook trazem um recorte dele em courier (ver quais campos). Os nomes seguem o objeto Pedido: id, name e location são os mesmos do courier_data, e cada pedido em active_orders usa 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"
}

Códigos de erro

Respostas de erro seguem o padrão da Plataforma — mensagem em mensagem (não message):

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

Em rotas de busca o not-found vem como {"mensagem": "Pedido não encontrado"} (idem para usuário, webhook, tipo de veículo). Já o endpoint de categorias usa message ({"message": "Tipo de veículo não encontrado"}) — pequena inconsistência herdada.

Usar o painel do desenvolvedor

O ciclo completo de teste acontece no portal. Cada app Full recebe automaticamente:

• Uma praça sandbox (Central) isolada da operação real.
• Um usuário admin dessa praça que você pode acessar via botão Acessar plataforma sandbox do app (no topo da página do app ou na aba Credenciais) — útil pra ver pelos olhos do administrador como as coisas estão.
• Um token de teste de admin, válido apenas dentro dessa praça.
• Aba Inspeção com cada request que você fizer (body, response, headers, status).

Passo a passo

1. Crie um app Full no painel.
2. Aba Credenciais: copie o Bearer Token e use-o no header Authorization.
3. Aba Webhook: cole sua URL HTTPS pra receber eventos durante os testes.
4. Faça chamadas pelo seu sistema/cURL/Postman. Cada request aparece em Inspeção em segundos.
5. Use o botão Acessar plataforma sandbox do app pra ver o pedido criado pelo lado da empresa (mapa, atribuição, financeiro) — útil pra debugar comportamentos que dependem de regras configuradas pela empresa.

Criar / acessar meus apps   Ver guia OpenDelivery