Existe uma segunda realidade que nasce somente quando o veículo entra em movimento: quanto ele efetivamente percorreu, quando começou a se deslocar, quanto tempo levou, qual odômetro foi observado, onde iniciou e onde terminou determinado percurso.

Estamos estudando a integração da solução de telemetria da frota, contratada por meio da Localiza/Mobi7, ao sistema próprio do Pet Táxi.

O objetivo não é simplesmente colocar um ponto em um mapa. É construir uma ligação entre o que foi planejado comercial e operacionalmente e as evidências produzidas pela execução física.

Telemetria produz fatos sobre o veículo. O sistema do Pet Táxi é que pode transformar esses fatos em contexto operacional.

O sistema conhece a intenção. A telemetria registra o que aconteceu com o veículo.

Quando um orçamento é elaborado, trabalhamos com uma expectativa. Existe uma distância prevista, uma janela de horário, determinado veículo e um destino conhecido. Quando o veículo efetivamente circula, outra camada de informação passa a existir.

Essas duas colunas não competem entre si. Elas descrevem dimensões diferentes da mesma operação.

Um orçamento pode dizer que determinado atendimento deverá consumir 24 quilômetros. A telemetria pode posteriormente registrar um percurso de 26 quilômetros. Nenhuma dessas informações, isoladamente, explica tudo.

A primeira representa planejamento. A segunda representa evidência física. A parte realmente interessante começa quando conseguimos relacioná-las.

Integrar não significa simplesmente importar campos

É tentador imaginar uma integração como uma sequência simples: API → banco de dados → tela.

Na prática, esse costuma ser apenas o começo. Uma fonte externa possui seus próprios identificadores para veículos, motoristas e eventos. Nosso sistema possui sua própria representação da frota e da operação.

A primeira preocupação, portanto, não é copiar informação. É saber a que informação interna determinado dado externo pertence.

Um veículo é um bom exemplo. Nosso cadastro já conhece placa, identificação documental, características técnicas, situação operacional e outras propriedades. A fonte de telemetria possui sua própria identidade para aquele mesmo veículo.

Não faria sentido substituir uma pela outra. O melhor cenário é preservar as duas.

$veiculoInterno = $veiculos->localizarPorPlaca($dadosExternos->placa);

if ($veiculoInterno === null) {
    throw new VeiculoNaoIdentificado();
}

$vinculoTelemetria = new VinculoTelemetria(
    veiculoId: $veiculoInterno->id(),
    origem: 'mobi7',
    identificadorExterno: $dadosExternos->id
);

$vinculos->salvar($vinculoTelemetria);

O trecho é conceitual, não uma implementação atualmente em produção. Mas ele demonstra uma decisão arquitetural importante: o sistema interno continua responsável por saber o que é um veículo para o Pet Táxi.

O identificador externo funciona como ligação com outra fonte de informação. Essa separação evita transformar a arquitetura interna em uma cópia do fornecedor utilizado naquele momento.

Uma camada própria entre o sistema e a telemetria

Esse cuidado pode ir além. Em vez de permitir que diferentes partes do sistema conheçam diretamente a forma específica como determinada API entrega seus dados, podemos criar uma representação interna.

Assim, o restante da aplicação não precisa perguntar “como a Mobi7 chama essa informação?”. Precisa perguntar “o que um percurso significa para nós?”.

interface FonteTelemetria
{
    public function percursos(
        Veiculo $veiculo,
        DateTimeImmutable $inicio,
        DateTimeImmutable $fim
    ): iterable;

    public function ultimaLeitura(Veiculo $veiculo): ?LeituraTelemetria;
}

final class Mobi7Telemetria implements FonteTelemetria
{
    public function percursos(
        Veiculo $veiculo,
        DateTimeImmutable $inicio,
        DateTimeImmutable $fim
    ): iterable {
        // Consulta a fonte externa e traduz
        // o resultado para conceitos internos.
    }
}

Não há endpoint, chave, credencial ou estrutura privada da API expostos nesse exemplo. O objetivo é mostrar o princípio de projeto: o sistema continua falando a linguagem da operação, mesmo quando se comunica com sistemas que falam outra linguagem.

Percurso não é atendimento

Talvez essa seja uma das distinções mais importantes de todo o projeto.

A telemetria pode registrar que determinado veículo saiu de um ponto, percorreu determinada distância e chegou a outro ponto. Mas isso não significa que ela saiba por que isso aconteceu.

Ela não conhece necessariamente o animal transportado, o cliente, o orçamento, a finalidade do serviço, as particularidades daquele destino ou a decisão comercial por trás daquele deslocamento.

O veículo pode sair para abastecer. Pode ir para manutenção. Pode deslocar-se até o primeiro cliente antes de começar um atendimento. Pode fazer um retorno operacional. Pode existir mais de um animal ou mais de um destino dentro de uma mesma operação.

O GPS vê deslocamento. O domínio do Pet Táxi precisa determinar significado.

A integração também revela o que ainda precisamos modelar

Esse estudo já produziu um resultado interessante antes mesmo da integração estar pronta.

Ao analisar o sistema existente, percebemos que existe uma estrutura rica para orçamento, veículos, abastecimentos, custos e manutenção, mas ainda não uma entidade operacional completa que represente explicitamente um deslocamento realizado ou um atendimento executado.

Isso é importante. Uma integração externa não serve apenas para trazer novos dados. Às vezes ela revela conceitos que ainda não precisaram existir formalmente dentro do sistema.

Essa diferença é típica de sistemas que amadurecem com a operação. Não criamos entidades porque parecem tecnicamente elegantes. Criamos quando uma distinção começa a mudar decisões.

Distância prevista versus distância realizada

Aqui aparece uma das possibilidades mais evidentes. Nosso sistema já trabalha com distância prevista durante a elaboração comercial. A telemetria acrescenta a possibilidade de conhecermos a distância observada no deslocamento.

Imagine um exemplo fictício:

Exemplo meramente ilustrativo. Os valores não representam uma operação real do Pet Táxi.

Uma diferença de 1,5 quilômetro isoladamente não diz muita coisa. Mas cem operações semelhantes podem dizer.

Talvez determinada região apresente sistematicamente diferença entre a distância utilizada na estimativa e a distância efetivamente percorrida. Talvez determinado destino possua particularidades de acesso. Talvez determinado horário produza outro comportamento.

É nesse momento que a telemetria deixa de responder apenas “quanto o carro andou?” e começa a ajudar a responder “nossas premissas continuam representando a realidade?”.

$comparacao = [
    'distancia_prevista'  => $orcamento->distanciaPrevistaKm(),
    'distancia_observada' => $percurso->distanciaKm(),
];

$comparacao['diferenca_km'] =
    $comparacao['distancia_observada']
    - $comparacao['distancia_prevista'];

$comparacao['variacao_percentual'] =
    $comparacao['distancia_prevista'] > 0
        ? ($comparacao['diferenca_km']
            / $comparacao['distancia_prevista']) * 100
        : null;

A intenção aqui não seria alterar retroativamente aquilo que foi contratado pelo cliente. Dado operacional não precisa virar cobrança automática.

Ele pode servir primeiro para análise. Se determinado padrão de diferença se repetir, a regra de formação de preço pode ser revista para os próximos orçamentos.

Isso é muito diferente de transformar telemetria em taxímetro.

Preço, custo previsto e custo observado são coisas diferentes

Essa distinção merece atenção especial. O preço cobrado de um cliente é resultado de uma decisão comercial. O custo representa outra coisa.

Se uma operação prevista para 20 quilômetros terminou consumindo 23 quilômetros, isso não significa necessariamente que o cliente deva pagar três quilômetros adicionais. Mas os três quilômetros aconteceram. Economicamente, eles existem.

Essa separação protege a lógica comercial e, ao mesmo tempo, melhora a capacidade gerencial. Um sistema mais maduro não precisa escolher entre orçamento e realidade. Ele pode preservar os dois.

Tempo previsto também pode ser confrontado com tempo observado

Distância é apenas uma dimensão. Tempo é outra.

Uma operação planejada pode possuir início e término estimados. A telemetria acrescenta marcas temporais ligadas ao movimento real do veículo.

Com isso, ao longo do tempo, podemos estudar perguntas como:

• determinadas regiões exigem mais tempo do que estimamos?
• determinado horário produz atrasos recorrentes?
• determinado destino costuma gerar permanência maior?
• quanto tempo de uma operação é deslocamento e quanto é espera?
• nossas janelas continuam adequadas?

Novamente, a diferença entre uma ocorrência e um padrão é fundamental. Um congestionamento excepcional ensina pouco. Cinquenta atendimentos semelhantes apresentando o mesmo comportamento ensinam bastante.

É assim que dados históricos deixam de ser arquivo morto e passam a funcionar como mecanismo de aprendizado.

O odômetro ganha uma segunda testemunha

Existe outro encontro particularmente interessante entre os sistemas.

Hoje, quilometragem já possui significado em diferentes partes da operação. Ela pode estar presente no cadastro do veículo, em registros de abastecimento, em locações, em cálculos de custo e em outras análises.

A telemetria acrescenta uma nova fonte. Isso não significa que a nova fonte precise substituir imediatamente todas as demais. Significa que elas podem ser confrontadas.

Essa arquitetura é mais interessante do que simplesmente decretar: “a API é a verdade”.

Sistemas reais precisam conviver com diferenças. Equipamentos podem possuir critérios diferentes de medição. Informações manuais podem conter erro. Um evento pode chegar atrasado. Uma leitura pode não estar disponível.

Em vez de escolher silenciosamente um vencedor, o sistema pode registrar a origem das informações e detectar divergências.

$odometroInformado = $abastecimento->odometroKm();
$odometroObservado = $telemetria->odometroKm();

$diferenca = abs($odometroInformado - $odometroObservado);

if ($diferenca > $toleranciaKm) {
    $pendencias->registrar(
        tipo: 'DIVERGENCIA_ODOMETRO',
        veiculo: $veiculo,
        informado: $odometroInformado,
        observado: $odometroObservado
    );
}

O sistema não corrige automaticamente o abastecimento. Ele detecta algo que merece atenção.

Automação madura não é aquela que decide tudo sozinha. É aquela que sabe quando possui informação suficiente para decidir e quando deve apenas chamar atenção para uma divergência.

Abastecimento passa a conversar com deslocamento

Essa possibilidade também pode aprofundar uma estrutura que já existe. Quando um abastecimento possui data, hora, veículo e odômetro, ele deixa uma fotografia daquele momento. A telemetria fornece outra sequência de fotografias do uso físico do veículo.

Combinadas, essas fontes podem apoiar análises de:

• distância percorrida entre abastecimentos;
• compatibilidade entre odômetro informado e observado;
• consumo por período;
• custo operacional por quilômetro;
• comportamento fora do padrão;
• autonomia observada.

Mais uma vez, não se trata de abolir o registro de abastecimento. O abastecimento possui natureza financeira e documental que a telemetria não substitui.

A integração enriquece o dado existente.

Manutenção pode deixar de depender apenas de atualização manual

O sistema do Pet Táxi já possui uma estrutura técnica para manutenção que pode representar componentes, procedimentos e intervalos.

Algumas manutenções dependem de tempo. Outras dependem de quilometragem. Algumas podem depender de uso.

A telemetria acrescenta uma fonte periódica para parte dessas grandezas.

$odometroAtual = $telemetria->odometroKm();

$proximaRevisao =
    $ultimaRevisao->odometroKm()
    + $plano->intervaloKm();

$restante = $proximaRevisao - $odometroAtual;

if ($restante <= $margemDeAvisoKm) {
    $alertas->criar(
        veiculo: $veiculo,
        tipo: 'MANUTENCAO_PREVENTIVA',
        restanteKm: max(0, $restante)
    );
}

Também aqui existe uma distinção importante. A telemetria não decide qual manutenção o veículo precisa.

Nossa estrutura técnica continua responsável pela regra. A fonte externa ajuda a responder quanto o veículo foi utilizado. O conhecimento de manutenção continua pertencendo ao domínio da operação.

Motorista: quando um dado externo revela um conceito interno ausente

A integração também levantou uma questão interessante sobre motoristas.

A fonte de telemetria pode, em determinadas situações, possuir informação relacionada à pessoa identificada na condução. Nosso sistema, entretanto, ainda não possui uma modelagem operacional completa relacionando motorista, veículo, atendimento e período de condução.

Isso impede uma associação ingênua.

Motorista associado ao veículo
≠
Motorista responsável por qualquer operação daquele veículo

Veículos podem ser compartilhados. Pessoas podem alternar condução. Uma identificação pode estar indisponível. Uma viagem pode atravessar diferentes contextos.

Por isso, se esse conceito passar a fazer diferença para a operação, provavelmente precisará ganhar estrutura própria.

Esse é um ótimo exemplo de como integração também funciona como ferramenta de descoberta do domínio.

O dado chega antes da modelagem e nos obriga a perguntar o que ele realmente significa.

Coordenada não é destino

Talvez a mesma prudência seja ainda mais importante com localização.

No artigo anterior desta série, mostramos por que, para o Pet Táxi, um destino não deve ser tratado simplesmente como endereço. Um destino pode possuir características de acesso, funcionamento, referência, particularidades operacionais e conhecimento acumulado.

Telemetria acrescenta coordenadas. Mas coordenada e destino não são sinônimos.

Uma posição geográfica pode mostrar que o veículo esteve próximo de uma clínica. Ela não explica em qual entrada o atendimento ocorreu, se houve estacionamento, se existiu espera, se o animal foi entregue, se houve alteração de procedimento ou qual conhecimento operacional foi produzido naquela visita.

É justamente aí que os dois artigos começam a se encontrar. A localização externa não substitui o destino operacional. Ela acrescenta evidência àquilo que já sabemos sobre ele.

Uma chegada pode ser inferida. Mas inferência precisa continuar sendo inferência.

Imagine que o sistema conheça as coordenadas aproximadas de determinado destino e receba posições do veículo. Tecnicamente, seria possível desenvolver uma regra para identificar aproximação.

$distancia = distanciaEmMetros(
    $posicao->latitude(),
    $posicao->longitude(),
    $destino->latitude(),
    $destino->longitude()
);

if ($distancia <= $destino->raioOperacionalMetros()) {
    $eventos->registrarCandidato(
        tipo: 'POSSIVEL_CHEGADA',
        destino: $destino,
        ocorridoEm: $posicao->data()
    );
}

Observe a escolha das palavras: possível chegada.

Não: atendimento concluído.

Uma boa integração precisa preservar o grau de certeza de cada conclusão. Isso se torna ainda mais importante quando automações passam a influenciar indicadores, custos ou decisões operacionais.

Nem tudo que pode ser automatizado deve ser automatizado

Quanto mais dados um sistema recebe, maior a tentação de transformar todos eles em regras automáticas. Esse é um risco.

Algumas decisões são ótimas candidatas a automação. Outras deveriam inicialmente produzir apenas informação.

A pergunta correta não é “podemos automatizar?”.

Qual decisão esta informação realmente sustenta?

Governança também é arquitetura

Localização, deslocamento, identificação de motorista e comportamento de condução não são dados que deveriam circular pelo sistema sem propósito definido.

Uma integração desse tipo precisa responder antecipadamente:

• por que cada informação será armazenada;
• por quanto tempo ela terá utilidade;
• quem poderá consultá-la;
• que informações precisam ser agregadas em vez de exibidas individualmente;
• o que realmente precisa ser preservado;
• o que pode ser descartado depois de gerar um indicador;
• quando uma informação operacional também se relaciona a uma pessoa.

Isso é engenharia tanto quanto escrever o código da integração.

Receber todos os dados disponíveis simplesmente porque a API os fornece seria a decisão mais fácil. Não necessariamente a melhor.

O sistema não precisa guardar a rua inteira para aprender com ela

Talvez determinada análise precise saber que um percurso consumiu 18,4 quilômetros, 47 minutos, determinado veículo e determinada janela de horário.

Ela pode não precisar guardar indefinidamente cada coordenada intermediária percorrida pelo veículo.

Isso cria uma distinção entre dados brutos e conhecimento derivado.

Uma arquitetura consciente pode consumir detalhe quando necessário e preservar apenas aquilo que continua possuindo valor para a operação.

O verdadeiro potencial aparece depois de muitas operações

Um percurso isolado é registro.

Dezenas deles começam a produzir comparação.

Centenas podem começar a produzir conhecimento.

Considere algumas perguntas que uma base histórica poderia ajudar a responder:

Esse talvez seja o ponto mais importante do projeto.

O valor não está em saber onde o veículo está neste minuto. Muitos sistemas já fazem isso.

O valor está em permitir que aquilo que aconteceu hoje melhore uma decisão que será tomada amanhã.

Telemetria não substitui experiência operacional

Seria fácil concluir que, depois dessa integração, o sistema passaria a conhecer a operação sozinho. Não é isso.

O dado pode mostrar: “o veículo permaneceu 22 minutos naquela região”.

A experiência humana pode explicar: “naquela clínica existe um procedimento de entrada que normalmente exige espera”.

Essas duas informações possuem naturezas diferentes. Uma é observação. A outra é interpretação operacional.

Quando as duas conseguem conviver, o sistema fica mais valioso. Não porque eliminou a experiência das pessoas, mas porque conseguiu dar estrutura para que diferentes formas de conhecimento se encontrem.

O fornecedor fornece dados. O significado continua sendo nosso.

Esse talvez seja o princípio arquitetural mais importante desta integração.

A plataforma de telemetria conhece muito bem aquilo que acontece com o veículo. Nosso sistema conhece aquilo que acontece com a operação.

Os dois lados possuem conhecimento diferente.

Se misturarmos essas responsabilidades, criaremos dependência e ambiguidade. Se mantivermos a separação, poderemos utilizar os dados externos sem abrir mão da nossa própria modelagem.

Essa segunda frase é onde mora a inteligência específica do negócio.

Estamos estudando, não anunciando algo pronto

A integração ainda está em estudo. E é importante dizer isso.

Ter acesso contratado a uma API não significa que a decisão correta seja começar imediatamente a gravar todos os dados que ela disponibiliza.

Antes é necessário compreender:

• quais conceitos já existem;
• quais ainda precisam ser modelados;
• quais relações são confiáveis;
• quais dados realmente criam valor;
• quais automações são desejáveis;
• quais devem permanecer assistidas;
• como preservar histórico e origem das informações;
• como impedir que um dado externo altere silenciosamente uma verdade interna.

Essa etapa não é atraso de implementação. É parte da implementação.

Quando o sistema começa a conferir a própria representação da realidade

No artigo anterior, mostramos como um sistema próprio pode aprender a linguagem da operação.

O orçamento não precisa ser apenas uma linha de tabela. O animal não precisa ser apenas um cadastro. O destino não precisa ser apenas endereço. O custo não precisa ser apenas valor.

Agora surge uma nova etapa.

O sistema que aprendeu a representar a operação pode começar a confrontar essa representação com aquilo que aconteceu fisicamente.

Planejamos 18,6 quilômetros. Percorremos 20,1.

Esperávamos 42 minutos. Observamos 49.

O abastecimento registrou determinado odômetro. A telemetria observou outro valor próximo.

Uma manutenção depende de quilômetros. O veículo continua acumulando uso.

Cada uma dessas diferenças isoladamente pode parecer pequena. O conjunto delas, acumulado ao longo do tempo, forma outra coisa:

feedback operacional.

E talvez essa seja a evolução mais interessante de um sistema próprio.

Primeiro ele registra.

Depois representa.

Em seguida relaciona.

E, quando consegue comparar aquilo que imaginávamos com aquilo que realmente aconteceu, começa a ajudar a empresa a aprender com a própria execução.

Não porque a máquina passou a conhecer o negócio sozinha.

Mas porque finalmente conseguimos colocar planejamento, experiência humana e evidências da operação para conversar dentro da mesma estrutura.

É quando o sistema deixa de enxergar apenas o que deveria acontecer e começa a aprender também com o que aconteceu na rua.