O painel de operador do Cabgo cobre 80% do que a maioria das operações precisa acompanhar diariamente. Os 20% restantes são sempre diferentes: o mapa de cancelamentos por zona da última hora que o coordenador de turno quer em uma tela secundária, a tabela de pagamento projetado por motorista que a área administrativa precisa antes do fechamento semanal, o indicador de cobertura por zona e hora que o dono do negócio quer no celular sem abrir o painel completo. Esses 20% existem em todas as operações, sempre variam e antes sempre exigiam contratar alguém para desenvolvê-los. Um agente de IA conectado à API pública do Cabgo reduz esse tempo de semanas para horas — não porque automatize as decisões, mas porque transforma em código executável as instruções que o operador dá em linguagem natural.

Este artigo é para o operador técnico ou integrador que já conhece a API do Cabgo e quer entender como combiná-la com um agente para construir uma visão sob medida em uma tarde de trabalho real. Não pressupõe experiência prévia na construção de dashboards, mas pressupõe que o leitor já trabalhou com APIs REST e entende a diferença entre uma requisição autenticada e uma sem autenticação. O resultado concreto ao fim da tarde é uma página HTML funcional, um feed JSON ou uma planilha atualizável — o formato depende de para quem serve — que mostra os dados da operação que o painel padrão não agrega da mesma forma.

O que a API expõe e o painel não mostra da mesma forma

A API pública do Cabgo retorna os mesmos dados que o painel exibe, mas sem os agrupamentos, filtros e janelas de tempo que o painel escolhe por design. Isso tem uma implicação direta para o integrador: todos os dados estão disponíveis, mas o formato em que chegam é o escolhido por quem faz a consulta, não o imposto pelo produto. Uma consulta ao endpoint de corridas com os parâmetros corretos retorna as corridas das últimas seis horas por zona, com motorista, com status da corrida e com tempo de resposta ao passageiro — o painel não tem essa visão nesse formato. Uma consulta de disponibilidade de motoristas em intervalos de 15 minutos permite reconstruir a curva de cobertura do turno como uma tabela que não existe em nenhum relatório predefinido da plataforma.

O painel do Cabgo é otimizado para o caso de uso mais comum de cada operação; a API é otimizada para quem constrói. A distinção importa porque muitos operadores assumem que, se o painel não mostra algo, é porque a API também não tem. Na prática, o painel é uma camada de apresentação sobre a mesma API disponível publicamente: o que ele mostra é um subconjunto selecionado do que a API expõe. O integrador que entende essa distinção tem acesso a mais dados do que o produto padrão apresenta, e o agente é o parceiro que transforma esses dados na visão específica que a operação precisa.

O agente como parceiro de desenvolvimento: o que ele substitui no ciclo de construção

Em um processo de desenvolvimento tradicional, construir um dashboard interno sobre uma API externa envolve quatro blocos de trabalho sequenciais: explorar a documentação para entender quais endpoints existem e o que cada um retorna, escrever as requisições e lidar com a autenticação, transformar o JSON no formato que o frontend espera e construir a interface. Com um agente, esses quatro blocos se reduzem a uma sequência mais curta porque o agente pode executar os dois primeiros de forma direta — fazer as requisições reais à API com os dados da operação — e auxiliar nos dois seguintes com código gerado a partir do output real, não de exemplos hipotéticos.

A diferença prática é que o agente trabalha com os dados reais da operação desde o primeiro prompt, não com mocks nem com dados de exemplo do sandbox. Quando o operador descreve o que quer ver — «os dez motoristas com mais cancelamentos na última semana, com o percentual de cancelamento e o tempo médio entre a atribuição e o início da corrida» — o agente consulta o endpoint real, retorna os dados reais e tem o contexto para gerar o código que os transforma em uma tabela HTML. O ciclo de descrição, código e validação com dados reais leva entre 15 e 30 minutos por visão, frente a vários dias em um processo de desenvolvimento sem agente.

O formato primeiro: decidir o output antes de escrever a primeira consulta

Antes de fazer a primeira requisição à API convém definir em qual formato o output final vai viver. A escolha não é técnica — é de público. Três formatos cobrem 90% dos casos de uso sob medida que os operadores descrevem:

Os primeiros 90 minutos: das credenciais a uma consulta com dados reais

O primeiro bloco de trabalho é validar que a autenticação funciona e que a primeira consulta retorna dados da operação correta. Se o integrador trabalha com o agente MCP do Cabgo ativo, essa validação é imediata: o agente faz a primeira requisição autenticada com o token do operador e o resultado já corresponde ao tenant correto. Se trabalha em modo API direto sem o agente MCP, o primeiro passo é construir a requisição com o token no header de autorização e verificar que o response inclui dados do tenant correto — não o default do token quando há mais de um tenant ativo na conta.

Uma vez que a primeira requisição funciona, o segundo passo é construir a consulta que extrai os dados específicos que o dashboard precisa. Este é o ponto em que o agente é mais útil: o integrador descreve em linguagem natural o que quer ver — «me dê os dez motoristas com mais cancelamentos na última semana, com o percentual de cancelamento e o tempo médio entre a atribuição e o início da corrida» — e o agente gera o endpoint correto com os parâmetros de filtro, o código para transformar o response na estrutura necessária e detecta os casos em que o dado precisa ser cruzado entre dois endpoints distintos. A vantagem desse ciclo é que o código gerado parte de dados reais, não de uma resposta hipotética da documentação.

Os 90 minutos seguintes: do output da API a uma visão legível

O segundo bloco de trabalho é converter o JSON da API em algo que o usuário final consiga ler sem ler JSON. Para uma página HTML, o agente gera o template com os dados embutidos ou com o script fetch que os carrega dinamicamente. O estilo pode ser descrito em linguagem natural — «tabela limpa com fundo escuro, sem bordas, texto em branco, linhas alternadas em cinza escuro» — e o agente gera o CSS correspondente. O resultado não vai ser um design de produto polido, mas sim uma visão funcional que o coordenador reconhece como dados da sua operação na ordem e no formato que lhe servem para tomar uma decisão rápida.

Neste ponto convém dedicar dez minutos a testar a visão com faixas de dados extremas antes de dá-la por concluída: o que acontece se um motorista tem zero corridas no período, se uma zona não teve atividade, se a API retorna um array vazio no lugar do objeto esperado. O agente pode gerar os casos de teste e o código que os trata se o integrador os descrever explicitamente — esse passo não acontece sozinho. Os dashboards sob medida quase sempre falham em produção pelas mesmas razões: campos ausentes no response, formatos de data inconsistentes entre endpoints e paginação que o código da primeira tarde não trata porque os dados do período de teste nunca ultrapassaram o limite da primeira página.

O que falha em produção e como antecipar antes que aconteça

Três problemas aparecem com mais frequência que qualquer outro quando um dashboard sob medida chega ao uso diário. O primeiro é a autenticação: os tokens da API têm validade limitada e o dashboard que funciona no dia do lançamento deixa de funcionar semanas depois, quando o token expira. A solução é simples — um mecanismo de renovação automática do token ou um alerta que avise a equipe quando ele está próximo de expirar — e o agente a gera se o integrador a pedir antes de encerrar a sessão de construção. O segundo é o rate limiting: quando o dashboard faz requisições a cada cinco minutos e o coordenador o deixa aberto em várias telas, o número de requisições por hora pode ultrapassar o limite que a API permite por token. Adicionar cache local ao script — guardar o último response e não consultar de novo até que passem N minutos — também é gerado pelo agente em uma instrução adicional.

O terceiro são as mudanças de esquema: se a plataforma atualiza o formato de um campo na resposta da API, o código que assume o nome anterior deixa de funcionar sem um erro óbvio — às vezes produz silêncio, às vezes um undefined onde deveria aparecer um número. Esse risco é menor em APIs com versionamento explícito, mas convém documentar dentro do próprio código quais campos são usados e de qual endpoint, de modo que, quando aparecer um comportamento inesperado, o diagnóstico leve minutos em vez de horas. O agente pode gerar essa documentação inline como comentários no script se o integrador a pedir ao terminar: não adiciona tempo à tarde de construção e reduz o custo de manutenção nas semanas seguintes.

Um dashboard sob medida sobre a API do Cabgo não exige um sprint de desenvolvimento — exige uma tarde com um agente bem configurado e um formato de output definido antes de começar. A parte que o agente não substitui é a mais importante: decidir qual visão falta à equipe e quanto dano operacional produz não tê-la. Esse diagnóstico sempre vem do operador que conhece seu turno, não do integrador que conhece a API. Quando as duas peças se juntam — o operador que sabe o que precisa acompanhar e o integrador que sabe como pedir isso à API — o agente transforma essa conversa em código executável no mesmo tempo em que antes se teria redigido o brief.

O dashboard que resulta dessa tarde não vai ser perfeito: vão faltar casos extremos que o uso diário vai descobrir, algum campo vai mudar de nome na próxima atualização da API e o script vai precisar de um ajuste menor. Isso é normal e não muda a equação de fundo. O que muda é o ponto de partida: em vez de esperar semanas até que a equipe de desenvolvimento tenha disponibilidade, o operador tem uma visão funcional em produção no dia seguinte. A partir daí, cada ciclo de melhoria é mais rápido porque o agente pode iterar sobre o código existente com os dados reais que o uso diário gerou desde que o dashboard entrou em produção.