API legada/Referência completa/Frete e rotas

GETRotas: consulta

Lista as rotas de entrega de um gerente, da mais nova para a mais antiga.

Devolve as rotas de entrega que pertencem a um gerente: cada uma com nome, lista de clientes e status. Use quando um app de campo ou um ERP precisa saber o que o gerente deve atender. Não há paginação: todas as rotas do gerente vêm de uma vez.

O mesmo comportamento está disponível em três grafias (routes, ec_routes, ecroutes) e em duas bases (/api/v1.0 e /api). A primeira entrada é a principal; as demais são aliases listados logo abaixo.

GET/api/v1.0/routes/{manager_id}Admin

Listar as rotas de um gerente

Parâmetros de caminho

manager_iduuidobrigatório

Id do usuário gerente. Um número inteiro que não seja id de usuário é tratado como id de representante da força de vendas e devolve o outro formato descrito abaixo. O valor 0 é recusado com 400.

Cabeçalhos

Authorizationstringobrigatório

Basic base64(e-mail:chave_de_api) ou Bearer $TOKEN de um administrador.

GET/api/v1.0/ec_routes/{manager_id}Admin

Alias de GET /api/v1.0/routes/{manager_id}

Mesmo corpo, mesma resposta e mesmo comportamento de GET /api/v1.0/routes/{manager_id}.

GET/api/v1.0/ecroutes/{manager_id}Admin

Alias de GET /api/v1.0/routes/{manager_id}

Mesmo corpo, mesma resposta e mesmo comportamento de GET /api/v1.0/routes/{manager_id}.

GET/api/routes/{manager_id}Admin

Alias de GET /api/v1.0/routes/{manager_id}

Mesmo corpo, mesma resposta e mesmo comportamento de GET /api/v1.0/routes/{manager_id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

GET/api/ec_routes/{manager_id}Admin

Alias de GET /api/v1.0/routes/{manager_id}

Mesmo corpo, mesma resposta e mesmo comportamento de GET /api/v1.0/routes/{manager_id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

GET/api/ecroutes/{manager_id}Admin

Alias de GET /api/v1.0/routes/{manager_id}

Mesmo corpo, mesma resposta e mesmo comportamento de GET /api/v1.0/routes/{manager_id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/routes/12da2430-2092-40da-b361-c0ed2c1cd0d4"

Resposta

200Rotas do gerente (formato de rota de entrega)

json

{
  "success": true,
  "routes": [
    {
      "id": "b094b7c2-2e1f-4174-9551-b05fa2fe482e",
      "manager_id": "12da2430-2092-40da-b361-c0ed2c1cd0d4",
      "name": "Zona Sul",
      "customers": ["0d6b8d2e-3f0a-4f0c-9d3c-6b1f2a9a7c11"],
      "status": "A",
      "created_at": "2026-10-11T21:21:52.599702Z"
    }
  ]
}

Campos da resposta

successboolean

Sempre true quando a consulta funciona.

routesarray

Rotas do gerente, da criação mais recente para a mais antiga. Lista vazia ([]) se não houver nenhuma.

routes[].iduuid

Id da rota. Use este valor em PUT e DELETE.

routes[].manager_iduuid

Gerente dono da rota.

routes[].namestring

Nome da rota (no corpo de criação o campo se chama route).

routes[].customersarray|null

Ids de clientes, como foram gravados. Pode ser null se a rota foi atualizada sem enviar customers.

routes[].statusstring

AD

A ativa, D desativada.

routes[].created_atstring

Criação, em RFC 3339 (UTC).

200Rotas da força de vendas (manager_id inteiro)

json

{
  "success": true,
  "routes": [
    {
      "route_id": "17",
      "manager_id": "42",
      "route": "Centro",
      "customers": ["301", "302"],
      "created_at": 1791753601
    }
  ]
}

Neste formato, created_at é um timestamp Unix em segundos e o nome da rota vem em route. Ele só aparece quando manager_id é um inteiro (id de representante comercial do módulo de força de vendas), nunca com UUID.

Erros

Status	Quando	Corpo
400	`manager_id` igual a `0`	`{"error": "invalid id parameter"}`
401	Sem credencial ou credencial inválida	`{"message": "Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.", "status": 401}`
403	Usuário autenticado que não é administrador	`{"message": "Forbidden: admin scope required", "status": 403}`
500	`manager_id` que não é UUID nem inteiro (por exemplo `abc`)	`{"message": "Query failed", "status": 500}`

Veja também

GETRotas: consulta

Lista as rotas de entrega de um gerente, da mais nova para a mais antiga.

GET/api/v1.0/routes/{manager_id}Admin

Listar as rotas de um gerente

Parâmetros de caminho

manager_iduuidobrigatório

Cabeçalhos

Authorizationstringobrigatório

Basic base64(e-mail:chave_de_api) ou Bearer $TOKEN de um administrador.

GET/api/v1.0/ec_routes/{manager_id}Admin

Alias de GET /api/v1.0/routes/{manager_id}

Mesmo corpo, mesma resposta e mesmo comportamento de GET /api/v1.0/routes/{manager_id}.

GET/api/v1.0/ecroutes/{manager_id}Admin

Alias de GET /api/v1.0/routes/{manager_id}

Mesmo corpo, mesma resposta e mesmo comportamento de GET /api/v1.0/routes/{manager_id}.

GET/api/routes/{manager_id}Admin

Alias de GET /api/v1.0/routes/{manager_id}

Mesmo corpo, mesma resposta e mesmo comportamento de GET /api/v1.0/routes/{manager_id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

GET/api/ec_routes/{manager_id}Admin

Alias de GET /api/v1.0/routes/{manager_id}

Mesmo corpo, mesma resposta e mesmo comportamento de GET /api/v1.0/routes/{manager_id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

GET/api/ecroutes/{manager_id}Admin

Alias de GET /api/v1.0/routes/{manager_id}

Mesmo corpo, mesma resposta e mesmo comportamento de GET /api/v1.0/routes/{manager_id}. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/routes/12da2430-2092-40da-b361-c0ed2c1cd0d4"

Resposta

200Rotas do gerente (formato de rota de entrega)

json

{
  "success": true,
  "routes": [
    {
      "id": "b094b7c2-2e1f-4174-9551-b05fa2fe482e",
      "manager_id": "12da2430-2092-40da-b361-c0ed2c1cd0d4",
      "name": "Zona Sul",
      "customers": ["0d6b8d2e-3f0a-4f0c-9d3c-6b1f2a9a7c11"],
      "status": "A",
      "created_at": "2026-10-11T21:21:52.599702Z"
    }
  ]
}

Campos da resposta

successboolean

Sempre true quando a consulta funciona.

routesarray

Rotas do gerente, da criação mais recente para a mais antiga. Lista vazia ([]) se não houver nenhuma.

routes[].iduuid

Id da rota. Use este valor em PUT e DELETE.

routes[].manager_iduuid

Gerente dono da rota.

routes[].namestring

Nome da rota (no corpo de criação o campo se chama route).

routes[].customersarray|null

Ids de clientes, como foram gravados. Pode ser null se a rota foi atualizada sem enviar customers.

routes[].statusstring

AD

A ativa, D desativada.

routes[].created_atstring

Criação, em RFC 3339 (UTC).

200Rotas da força de vendas (manager_id inteiro)

json

{
  "success": true,
  "routes": [
    {
      "route_id": "17",
      "manager_id": "42",
      "route": "Centro",
      "customers": ["301", "302"],
      "created_at": 1791753601
    }
  ]
}

Erros

Status	Quando	Corpo
400	`manager_id` igual a `0`	`{"error": "invalid id parameter"}`
401	Sem credencial ou credencial inválida	`{"message": "Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.", "status": 401}`
403	Usuário autenticado que não é administrador	`{"message": "Forbidden: admin scope required", "status": 403}`
500	`manager_id` que não é UUID nem inteiro (por exemplo `abc`)	`{"message": "Query failed", "status": 500}`