Módulo Viagens

O módulo de viagens vincula um condutor a um veículo em um intervalo de datas. Ao criar uma viagem, todas as multas e notificações do veículo dentro do período informado são automaticamente associadas ao condutor.

Como funciona

Quando você cria uma viagem:

1. O sistema busca todas as multas e notificações do veículo no intervalo startDate → endDate
2. As que ainda não têm condutor indicado são vinculadas ao condutor da viagem
3. Se endDate não for definido, o vínculo permanece ativo para eventos futuros

Regras importantes

• O veículo principal (vehicleId) não pode ter o campo type (tipo de veículo) igual a REBOQUE ou SEMIRREBOQUE
• Veículos adicionais com type REBOQUE ou SEMIRREBOQUE só são permitidos se o veículo principal for CAMINHÃO ou TRATOR
• É possível vincular até 3 veículos adicionais por viagem
• Se houver duas viagens para o mesmo dia e a multa não tiver hora definida, será vinculada à primeira viagem criada

Criar viagem

POST /key/trips

curl -X POST \
  https://apidev.v1.frota162.com.br/key/trips \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "vehicleId": "123456",
    "driverId": "15",
    "startDate": "2024-08-01T13:20:07.046Z",
    "endDate": "2024-08-02T13:20:07.046Z"
  }'

Campos

Campo	Tipo	Obrigatório	Descrição
vehicleId	string	Sim	ID do veículo principal
driverId	string	Sim	ID do condutor
startDate	string (ISO 8601)	Sim	Data/hora de início
endDate	string (ISO 8601)	Não	Data/hora de fim (omitir para viagem sem fim)
kmStart	string	Não	Quilometragem inicial
kmEnd	string	Não	Quilometragem final
notes	string	Não	Observações da viagem
description	string	Não	Descrição geral
metadata	array	Não	Campos customizados [{ key, value }]
additionalVehicleIds	array	Não	IDs de até 3 veículos adicionais

Exemplo com todos os campos

{
  "vehicleId": "123456",
  "driverId": "654321",
  "startDate": "2024-08-01T13:20:07.046Z",
  "endDate": "2024-08-02T13:20:07.046Z",
  "kmStart": "1055",
  "kmEnd": "2600",
  "notes": "Pneu furou no km 200",
  "description": "Entrega São Paulo → Campinas",
  "metadata": [
    { "key": "internalTripId", "value": "TRIP-2024-001" }
  ],
  "additionalVehicleIds": ["789012", "345678"]
}

Resposta

{
  "message": { "id": "7434" },
  "error": false,
  "code": "fbk_200"
}

Viagem sem data de fim

Omita endDate para criar uma viagem aberta. O condutor continuará sendo vinculado a novas multas e notificações do veículo até que endDate seja definido via atualização.

{
  "vehicleId": "123456",
  "driverId": "15",
  "startDate": "2024-08-01T00:00:00.000Z"
}

Listar viagens

GET /key/trips

curl -X GET \
  'https://apidev.v1.frota162.com.br/key/trips?pagination[page]=1&pagination[perpage]=10' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC' \
  -H 'cache-control: no-cache'

Resposta

{
  "message": {
    "pagination": {
      "currentPage": 1,
      "pageSize": 10,
      "totalItems": 2,
      "totalPages": 1
    },
    "data": [
      {
        "id": "7434",
        "accountId": "24",
        "driverId": "15",
        "vehicleId": "123456",
        "startDate": "2024-08-01T13:20:07.000Z",
        "endDate": "2024-08-02T13:20:07.000Z",
        "kmStart": "1055",
        "kmEnd": "2600",
        "notes": "Observações",
        "description": "Descrição",
        "metadata": [{ "key": "internalTripId", "value": "TRIP-2024-001" }],
        "additionalVehicleIds": ["789012"],
        "createdAt": "2024-08-02T09:29:08.000Z"
      }
    ]
  },
  "error": false,
  "code": "fbk_200"
}

Buscar viagem por ID

GET /key/trips/{id}

curl -X GET \
  https://apidev.v1.frota162.com.br/key/trips/7434 \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC' \
  -H 'cache-control: no-cache'

Resposta

{
  "message": {
    "id": "7434",
    "accountId": "24",
    "driverId": "15",
    "vehicleId": "123456",
    "startDate": "2024-08-01T13:20:07.000Z",
    "endDate": "2024-08-02T13:20:07.000Z",
    "kmStart": "1055",
    "kmEnd": "2600",
    "notes": "Observações",
    "description": "Descrição",
    "metadata": [{ "key": "internalTripId", "value": "TRIP-2024-001" }],
    "additionalVehicleIds": ["789012"],
    "createdAt": "2024-08-02T09:29:08.000Z"
  },
  "error": false,
  "code": "fbk_200"
}

Atualizar viagem

PUT /key/trips/{id}

Use para fechar uma viagem aberta (adicionar endDate), ajustar quilometragem ou atualizar o veículo.

cuidado

Não é possível alterar o condutor via atualização. Para isso, exclua a viagem e crie uma nova no mesmo intervalo.

curl -X PUT \
  https://apidev.v1.frota162.com.br/key/trips/7434 \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "endDate": "2024-08-03T18:00:00.000Z",
    "kmEnd": "2600"
  }'

Para definir endDate como null (viagem sem fim):

{ "endDate": null }

Excluir viagem

DELETE /key/trips/{id}

Ao excluir uma viagem, todas as multas e notificações dentro do intervalo são desvinculadas do condutor.

curl -X DELETE \
  https://apidev.v1.frota162.com.br/key/trips/7434 \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC' \
  -H 'cache-control: no-cache'

Resposta

{
  "message": { "id": "7434" },
  "error": false,
  "code": "fbk_200"
}

Casos de uso comuns

Registrar uma entrega

{
  "vehicleId": "123",
  "driverId": "15",
  "startDate": "2024-08-01T07:00:00.000Z",
  "endDate": "2024-08-01T18:00:00.000Z",
  "description": "Rota de entrega — zona leste",
  "metadata": [
    { "key": "routeId", "value": "ROTA-042" },
    { "key": "orderId", "value": "PED-00123" }
  ]
}

Escala contínua (motorista fixo)

{
  "vehicleId": "456",
  "driverId": "20",
  "startDate": "2024-01-01T00:00:00.000Z",
  "description": "Motorista fixo — sem data de fim"
}

Para encerrar a escala futuramente, atualize adicionando endDate.

Próximos passos

Quero...	Ir para...
Boas práticas para fechar viagens e evitar vínculos incorretos	Boas Práticas
Receber eventos de multas e notificações em tempo real	Webhooks