API atual/Referência completa/Campo e alçadas dos representantes

Rotas de visita

Lista, cria, edita e exclui as rotas de visita dos representantes, que são listas nomeadas de clientes a visitar.

Uma rota de visita é um plano: um nome (por exemplo "Zona Sul, segunda-feira") e a lista de clientes que o representante visita nesse roteiro. O app do representante lê as rotas para montar o dia. A rota não prova a visita: isso é o check-in.

Listar todas as rotas

GET/api/v1/admin/trade-reps/routesAdmin

Lista as rotas de todos os representantes

200Rotas

json

{
  "routes": [
    {
      "id": 2,
      "rep_id": 2,
      "name": "Zona Sul - Segunda-feira",
      "customer_ids": ["0be53abf-9e80-4cdd-a512-bbcc30e651bf", "67bf291c-0846-4053-9528-8cfd5ab0ebf1"],
      "customer_count": 2,
      "created_at": "2026-07-15T01:09:24Z",
      "updated_at": "2026-07-15T01:09:24Z"
    }
  ],
  "total": 1
}

Campos da resposta

routesarray

Rotas, da mais nova para a mais antiga. Sem paginação.

routes[].idinteger

Id da rota (inteiro).

routes[].rep_idinteger

Representante dono da rota.

routes[].owner_vendor_idstring

Seller dono, no modo do seller. Ausente se vazio.

routes[].namestring

Nome da rota.

routes[].customer_idsarray

Ids (UUID) dos clientes a visitar.

routes[].customer_countinteger

Quantidade de clientes na rota.

routes[].created_atstring

Criação (RFC 3339).

routes[].updated_atstring

Última alteração.

totalinteger

Quantidade de rotas.

Rotas de um representante

GET/api/v1/admin/trade-reps/{id}/routesAdmin

Lista as rotas de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

A resposta tem o mesmo formato da lista geral, só com as rotas desse representante.

Criar uma rota

POST/api/v1/admin/trade-reps/routesAdmin

Cria uma rota de visita

Corpo da requisição

rep_idintegerobrigatório

Representante dono da rota.

namestringobrigatório

Nome da rota. Não pode ser só espaços.

owner_vendor_idstring

Seller dono, no modo do seller.

customer_idsarray

Clientes a visitar (ids UUID).

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps/routes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rep_id": 2, "name": "Centro, quarta-feira", "customer_ids": ["9766444d-9feb-4f55-a272-3973eaf4686e"]}'

201Rota criada

json

{
  "id": 5,
  "rep_id": 2,
  "name": "Centro, quarta-feira",
  "customer_ids": ["9766444d-9feb-4f55-a272-3973eaf4686e"],
  "customer_count": 1,
  "created_at": "2026-10-11T22:10:00Z",
  "updated_at": "2026-10-11T22:10:00Z"
}

Editar uma rota

Atualização parcial: só o que você mandar muda. Mandar customer_ids substitui toda a lista de clientes; omitir deixa a lista como está.

PUT/api/v1/admin/trade-reps/routes/{routeId}Admin

Edita o nome e os clientes de uma rota

Parâmetros de caminho

routeIdintegerobrigatório

Id da rota.

Corpo da requisição

namestring

Novo nome.

customer_idsarray

Lista completa de clientes. Substitui a anterior; [] esvazia a rota.

Excluir uma rota

DELETE/api/v1/admin/trade-reps/routes/{routeId}Admin

Exclui uma rota

Parâmetros de caminho

routeIdintegerobrigatório

Id da rota.

200Excluída

json

{ "status": "deleted" }

Excluir uma rota também exclui todos os check-ins registrados nela. Não há como desfazer.

Erros

Status	Quando	Corpo de exemplo
400	`routeId` ou `id` não é inteiro.	`{"error":"invalid route ID"}`
400	Criação sem `rep_id` ou sem `name`.	`{"error":"create route failed","detail":"rep_id and name are required"}`
400	Exclusão de rota que não existe.	`{"error":"delete route failed","detail":"route not found"}`
400	Corpo não é JSON.	`{"error":"invalid request body","detail":"..."}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`

Veja também

API atual/Referência completa/Campo e alçadas dos representantes

Rotas de visita

Lista, cria, edita e exclui as rotas de visita dos representantes, que são listas nomeadas de clientes a visitar.

Listar todas as rotas

GET/api/v1/admin/trade-reps/routesAdmin

Lista as rotas de todos os representantes

200Rotas

json

{
  "routes": [
    {
      "id": 2,
      "rep_id": 2,
      "name": "Zona Sul - Segunda-feira",
      "customer_ids": ["0be53abf-9e80-4cdd-a512-bbcc30e651bf", "67bf291c-0846-4053-9528-8cfd5ab0ebf1"],
      "customer_count": 2,
      "created_at": "2026-07-15T01:09:24Z",
      "updated_at": "2026-07-15T01:09:24Z"
    }
  ],
  "total": 1
}

Campos da resposta

routesarray

Rotas, da mais nova para a mais antiga. Sem paginação.

routes[].idinteger

Id da rota (inteiro).

routes[].rep_idinteger

Representante dono da rota.

routes[].owner_vendor_idstring

Seller dono, no modo do seller. Ausente se vazio.

routes[].namestring

Nome da rota.

routes[].customer_idsarray

Ids (UUID) dos clientes a visitar.

routes[].customer_countinteger

Quantidade de clientes na rota.

routes[].created_atstring

Criação (RFC 3339).

routes[].updated_atstring

Última alteração.

totalinteger

Quantidade de rotas.

Rotas de um representante

GET/api/v1/admin/trade-reps/{id}/routesAdmin

Lista as rotas de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

A resposta tem o mesmo formato da lista geral, só com as rotas desse representante.

Criar uma rota

POST/api/v1/admin/trade-reps/routesAdmin

Cria uma rota de visita

Corpo da requisição

rep_idintegerobrigatório

Representante dono da rota.

namestringobrigatório

Nome da rota. Não pode ser só espaços.

owner_vendor_idstring

Seller dono, no modo do seller.

customer_idsarray

Clientes a visitar (ids UUID).

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps/routes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rep_id": 2, "name": "Centro, quarta-feira", "customer_ids": ["9766444d-9feb-4f55-a272-3973eaf4686e"]}'

201Rota criada

json

{
  "id": 5,
  "rep_id": 2,
  "name": "Centro, quarta-feira",
  "customer_ids": ["9766444d-9feb-4f55-a272-3973eaf4686e"],
  "customer_count": 1,
  "created_at": "2026-10-11T22:10:00Z",
  "updated_at": "2026-10-11T22:10:00Z"
}

Editar uma rota

Atualização parcial: só o que você mandar muda. Mandar customer_ids substitui toda a lista de clientes; omitir deixa a lista como está.

PUT/api/v1/admin/trade-reps/routes/{routeId}Admin

Edita o nome e os clientes de uma rota

Parâmetros de caminho

routeIdintegerobrigatório

Id da rota.

Corpo da requisição

namestring

Novo nome.

customer_idsarray

Lista completa de clientes. Substitui a anterior; [] esvazia a rota.

Excluir uma rota

DELETE/api/v1/admin/trade-reps/routes/{routeId}Admin

Exclui uma rota

Parâmetros de caminho

routeIdintegerobrigatório

Id da rota.

200Excluída

json

{ "status": "deleted" }

Excluir uma rota também exclui todos os check-ins registrados nela. Não há como desfazer.

Erros

Status	Quando	Corpo de exemplo
400	`routeId` ou `id` não é inteiro.	`{"error":"invalid route ID"}`
400	Criação sem `rep_id` ou sem `name`.	`{"error":"create route failed","detail":"rep_id and name are required"}`
400	Exclusão de rota que não existe.	`{"error":"delete route failed","detail":"route not found"}`
400	Corpo não é JSON.	`{"error":"invalid request body","detail":"..."}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`