Fluxo+

View saved version →

---
name: fluxoplus
description: Use para consultar vendas, estoque, pagamentos, contas e operação das unidades pelo Fluxo+, ou realizar edições ACS suportadas quando houver pedido explícito, permissão e capacidade da conexão.
---

Fluxo+ consulta sistemas das unidades. Só ACS edita produtos, clientes, estoque_produtos e compras, conforme acesso/capacidade.

- action='read' é padrão. 'edit' exige intenção explícita e edit sem filtros: network_id/unit_id exatos, request_id UUID e códigos consultados. Nunca amplie edição para outras unidades/redes.
- compras: 'lançadas hoje' usa data_referencia='lancamento'; 'emitidas', 'emissao'. O padrão é 'recebimento'. Cadastro ausente não é emissão.
- compras edit.kind='fuel': nota, litros/tanque, LMC e parcelas com competência; preserva medições, saldos, custos e preços. estoque_combustivel confere o dia, não cada descarga.
- pending não grava. Use contexto e referências; não invente códigos, custos, parcelas ou efeitos. Omissão preserva campos opcionais; null limpa só onde permitido. Siga o contrato; não contorne recusas nem descarte dados para forçar edição.
- Conflito exige nova consulta. Em indeterminate, confira o ERP antes de outra escrita. request_id não garante execução única. Só completed confirma os efeitos retornados, sem comprovar propagação ao aplicativo, caixa ou bomba.
- Peça o período inteiro, sem dividir dias/meses ou duplicar chamadas. Use agrupar_por/comparar_com e projeções calculadas. Preserve agrupamento; totais incluem linhas truncadas.
- Consultas aceitam nomes; sem unidades/redes, todas as autorizadas. Localização/CNPJ: consulte unidades e use seu id. Nome ambíguo/inexistente exige esclarecimento; nunca troque ou retire filtros por suposição. Identifique cada rede, sem misturar números.
- quantidade tem produto/unidade_medida: não some litros com unidades. itens conta linhas. Operador da venda pode diferir do frentista.
- Siga nota, unidades_fora, redes_fora, periodo.parcial e dados_ate. cobertura.completa=false indica faltas; null, início desconhecido. Falhas e dados ausentes nunca são zero nem provam ausência no ERP.
- Respeite permissões. clientes pagina por cursor: não some totais de páginas. transacoes busca vendas individuais/por condição; para somar, use agregações.

Edições ACS
- Consultar é o padrão. Somente conexões ACS com a operação disponível e pessoas com permissão de edição podem alterar dados. Os demais sistemas, inclusive a demonstração, permanecem somente para consulta. Um pedido de análise, relatório ou previsão não autoriza alterar registros.
- produtos altera preço-base de mercadoria elegível; não altera combustível, bomba nem o cadastro fiscal completo. clientes cria, atualiza ou vincula cadastros, sem alterar crédito, limites ou condições comerciais. estoque_produtos define mínimo/ideal e registra contagem por local. compras cria ou edita compras de mercadorias e registra entradas documentais de combustível por campos manuais ou XML suportado; não emite nota fiscal, paga contas, cancela compras nem cria produtos ou fornecedores.
- Na entrada de combustível, use edit.kind='fuel', quantidade em litros, data de LMC (lmc_on) e alocações por tanque. Cruze os dados da nota e do boleto com o cadastro: fornecedor por CNPJ, produto e tanque existente. Um tanque ativo único do produto pode ser resolvido automaticamente; vários tanques exigem alocação explícita. Dados extraídos de PDF entram no contrato manual; isso não substitui campos ausentes nem validação fiscal. Dados fiscais sem representação nativa suportada, inclusive retenção monofásica, impedem a importação; não os descarte nem converta em ICMS-ST para forçar o lançamento. Não invente CFOP, tributos, custos ou datas.
- O lançamento de combustível grava documento, recebido no LMC e parcelas, preservando medição física, saldo atual de tanque, custos correntes e preços. Atualização exige versão atual e registro nativo suportado. Toda parcela nova exige competence em mês/ano (ex.: 11/2026); ao alterar, omissão preserva competência preenchida e parcela antiga vazia exige valor. Após completed, confira compras e contas_pagar; a consulta atual dos tanques não precisa aumentar, porque essa modalidade não altera seu saldo. Ler ou registrar uma linha digitável não paga o boleto.
- Quando útil ao analisar ou lançar combustível, pode conferir a coerência diária com estoque_combustivel, agrupado por dia e produto, na mesma rede/unidade e data de LMC da entrada. Compare abertura + recebido − vendido com o fechamento medido e mostre a diferença em litros, com o dia e produto. Não some novamente os litros da nota já incluídos no recebido; uma simulação de nota ainda não lançada deve ser identificada como hipótese. Sem fechamento ou cobertura suficiente, diga que a comparação está pendente. É uma referência opcional para apontar números que merecem conferência, não uma etapa obrigatória do lançamento nem prova de falta em uma descarga; não ajuste registros para fazer os números baterem nem invente uma tolerância de aceitação.
- Antes de editar, determine a rede, a unidade e os registros exatos a partir das consultas e referências retornadas. Em cadastro de cliente compartilhado, respeite a autorização de todas as unidades alcançadas. Não amplie o alvo de uma edição para resolver falta de acesso.
- Use action='edit' com o objeto edit da própria tool. pending pede informações ou referências e não confirma gravação no ERP. Não invente códigos, embalagens, custos, parcelas ou efeito no estoque; siga o contrato e o contexto retornados. Em uma atualização, omissão preserva campos opcionais e null só limpa os campos que o contrato permitir.
- request_id identifica a chamada, sem garantir execução única. Diante de conflito, consulte novamente e revise; em indeterminate, confira o ERP antes de decidir outra escrita. Não repita automaticamente. Só completed confirma os efeitos descritos na resposta. Uma contagem salva como rascunho não altera saldo; concluir o pedido no banco não comprova propagação ao aplicativo ACS, caixa ou bomba.

Relatórios, planilhas e dashboards
- Use os recursos disponíveis da plataforma de IA para gerar arquivos e dashboards. O Fluxo+ fornece os dados; não fornece um agendador próprio. Só confirme uma recorrência depois de o recurso de agendamento da plataforma confirmar dia, horário e fuso. Se esse recurso não estiver disponível, entregue a análise possível e explique o limite.
- No PDF mensal, compare o total vendido no mês anterior à projeção total do mês atual devolvida por vendas. Mostre o detalhamento por produto separadamente: a projeção total não é uma previsão por produto. Projeção ausente não autoriza inventar uma estimativa.
- Na planilha de ontem, consulte vendas por produto e pagamentos por finalizadora para abas separadas. Não distribua pagamentos por produto cruzando dois agregados independentes. No dashboard, distinga vendas do mês de estoque atual e associe produtos dentro de cada rede/unidade; preserve avisos de cobertura e produtos não atendidos.

Onde está cada coisa
- Nas consultas, as mesmas tools valem para os sistemas que oferecem os dados pedidos; cada unidade responde pelo seu. unidades lista as unidades da rede com o tipo de cada uma (posto ou loja). As tools que só existem num tipo de unidade (tanques, abastecimentos e estoque_combustivel, do posto) só aparecem para a rede que tem unidade daquele tipo. agrupar_por ['tipo'] compara postos e lojas.
- Números de vendas, faturamento, margem, itens, ticket e finalizadoras vêm de vendas e pagamentos; nos postos, litros, abastecimentos e estoque vêm de vendas, abastecimentos e estoque_combustivel. Na previsão do mês, os dias depois de ontem viram projeção.
- O padrão da semana e do dia sai numa chamada só: agrupar_por ['dia_da_semana'], ['hora'] ou os dois juntos, no período inteiro. Cada linha traz dias, quantos dias ela soma, para a média por dia.
- Quem participa de mais de uma rede (um gestor que cuida das redes de donos diferentes) recebe cada resposta em redes, uma parte por rede, e cada unidade de unidades traz a sua rede. Uma unidade pedida pelo nome é respondida pela rede que a tem. redes_fora diz a rede que ficou de fora e por quê (a assinatura, o perfil da pessoa naquela rede, um dado que a rede não tem). Duas redes de mesmo nome vêm com um número depois do nome da segunda. Um número em unidades é o id que a tool unidades devolve. Para comparar redes, mostre lado a lado.
- produtos, estoque_produtos, compras, contas_pagar, contas_receber, transacoes, clientes, ocorrencias, caixa e despesas consultam o sistema da unidade na hora; uma unidade cujo sistema ainda não informa aquilo vem em unidades_fora, com o motivo.
- Uma venda específica, ou contar vendas por uma condição (valor exato, cliente, placa, NSU, número da nota, canceladas, abastecimentos sem baixa): transacoes. O total dela conta tudo sem precisar listar; para ver mais linhas, pagina 2, 3… (paginas diz quantas há).
- Compras: item a item, ou somadas por produto, fornecedor, mês ou unidade (agrupar_por). Nota emitida contra o CNPJ da unidade sem compra lançada: notas_nao_lancadas.
- Cadastro fiscal (NCM, CEST, CFOP, CST ou CSOSN, ICMS, PIS e COFINS): produtos com fiscal true. Auditoria do cadastro: NCM vazio, ncm_cest_confere false (o NCM e o CEST não batem), preço abaixo do custo.
- Clientes cadastrados, quem comprou no período e quanto, quem parou de comprar: clientes. Quem está devendo: contas_receber.
- A pergunta escolhe o agrupamento: total anual não exige evolução; evolução anual costuma usar meses, mensal usa dias. Para o melhor dia do ano, peça vendas com o ano inteiro, agrupar_por ['dia'], ordenar_por 'faturamento', ordem 'desc' e limite 1. O ranking considera todos os dias; não procure apenas no melhor mês.
- Em clientes, redução de abastecimento usa data_inicial/data_final e comparacao_inicial/comparacao_final, metrica 'litros', variacao 'reducao' e ordenar_por 'reducao': inclui quem caiu a zero. Os totais são completos antes do limite. proximo_cursor traz mais linhas mantendo rede, filtros e limite; não some totais de páginas nem faça uma chamada por dia. Para evolução por cliente use agrupar_por 'dia' ou 'mes', sem comparação. Cada período cobre até 366 dias; registros individuais ficam em transacoes.
- Quem cancelou venda, mexeu na medição do tanque (na loja, acertou o estoque à mão), trocou preço ou excluiu nota ou cartão: ocorrencias.
- Caixa de cada operador (sobra, falta, sangrias, vales): caixa. Sobra e falta só existem onde o sistema confere o caixa; sem conferência, sobra_falta vem vazio, que não é caixa batido nem com problema. Despesas e o resultado do mês: despesas com a margem de vendas.

Como ler as respostas
- Operador é quem vendeu: no posto, o frentista; na loja, o vendedor ou o operador de caixa, conforme o sistema. Por produto (agrupar_por ['produto', 'operador']), só onde o sistema diz quem vendeu cada item.
- Em vendas, itens é quantas vezes o produto foi vendido (linhas de venda) e soma por produto, grupo e dia; vendas é o número de vendas inteiras e não se divide por produto: uma venda com dois produtos é uma venda e dois itens. itens_por_venda é o tamanho da cesta. grupo e subgrupo são os do cadastro de produtos do sistema (em alguns sistemas, o subgrupo é a marca); categoria separa só combustível, lubrificante, Arla e o resto: numa loja, as categorias estão em grupo e subgrupo.
- faturamento é a venda menos as devoluções do período, que entram no dia em que foram feitas; onde o sistema registra devolução e desconto, faturamento_bruto, devolucoes e desconto vêm ao lado. Numa ótica, quase toda devolução é troca: a venda nova entra como venda, e o vale de troca aparece em pagamentos como finalizadora própria, que não é dinheiro novo.
- Margem é faturamento menos custo, pelo último custo de compra gravado em cada venda, já sem o que voltou nas devoluções; produto sem custo fica fora da margem. Margem por litro só existe nos combustíveis.
- Meta: onde o sistema tem meta cadastrada, vendas de meses inteiros traz meta e meta_pct (sobre o faturamento) no total e por unidade, mês e vendedor, e a projeção do mês diz se a meta será batida. Meta vazia é loja ou vendedor sem meta cadastrada, nunca meta zero; a nota diz quais e como foram as outras.
- Numa loja cujo sistema manda as vendas em lotes, unidades traz vendas_ate: hoje vai até a última venda recebida, e a comparação de hoje para nessa hora.
- Uma informação que as tools não expõem pode existir no sistema da unidade. Explique o limite da integração sem afirmar ausência na fonte ou aproximar com outro número.
- Períodos de vários anos podem ser consultados de uma vez: vendas retorna total e evolução anual por padrão; preserve mês, dia ou outro recorte solicitado. Confira cobertura e unidades_fora antes de chamar um total de completo; falta de histórico não é zero.
- quantidade separa produto e unidade_medida automaticamente. Um nome desconhecido traz alternativas; confirme a intenção antes de substituir o filtro, especialmente em formas de pagamento (Premmia não equivale automaticamente a QR code).
- Em estoque_produtos, o saldo é o do sistema da unidade, relido na hora. Saldo negativo quer dizer estoque errado no sistema (venda sem entrada lançada, compra lançada em outra embalagem), não prateleira negativa; quando o aviso diz que muitos estão negativos, diga isso e trate a cobertura e o parado como indicação. parado tem saldo e não vendeu na janela; zerado que vende bem é o que pode estar faltando.
- Em pagamentos, uma venda paga de duas formas conta nas duas: não some vendas entre finalizadoras.
- Em clientes, o consumo são as vendas no nome do cliente; vendas_convenio, valor_convenio e litros_convenio são a parte paga no convênio.
- Em contas_pagar e contas_receber, abertas são as parcelas sem baixa e vencidas as de vencimento anterior a hoje; parcelas vencidas há muito tempo podem ser baixas que faltam no sistema; valor é o nominal, sem juros, multa ou desconto.
- Em compras, valor é o total do item com impostos e as notas canceladas ficam fora. A data padrão é a do recebimento; na ACS, data_referencia='emissao' seleciona emissão e 'lancamento' seleciona cadastro. Para "lançadas hoje", use 'lancamento'; cadastro ausente não recebe uma data presumida.
- Em despesas, a data é a do lançamento e as transferências entre caixa e bancos ficam fora.
- Em ocorrencias, por_operacao conta tudo o que casa e as linhas vêm das mais recentes.
- Finalizadora é a forma de pagamento que fecha a venda: dinheiro, crédito, débito, PIX, convênio, ticket, frota.
- O "número da transação" do comprovante do cartão é o NSU; a autorização é outro número do mesmo comprovante. A nota do consumidor é a NFC-e: número, série e chave de 44 dígitos. O ID do PIX que o cliente mostra não fica no sistema: ache o PIX por valor e hora.

Postos
- tanques mostra o nível de cada tanque agora e para quantos dias dá. dias_de_cobertura é o volume do combustível no posto dividido pela média de litros vendidos por dia nos 7 dias completos até ontem (media_diaria_7d); o volume é o saldo do sistema, relido na hora da pergunta.
- LMC é o Livro de Movimentação de Combustíveis: escritural = abertura + recebido − vendido; o fechamento é a medição de abertura do dia seguinte, então hoje fica fora das perdas; perdas_ganhos = fechamento − escritural, negativo indica diferença a menor. Use dias_acima_tolerancia conforme retornado e preserve os avisos de cobertura. Diferenças diárias ou acumuladas indicam o que conferir, sem comprovar a causa ou o volume de uma descarga isolada.
- vendido_encerrante é o que os encerrantes das bombas marcaram, sem aferição; diferenca_encerrante compara esse volume ao vendido registrado. Use essa diferença e ocorrencias de medicao como apoio à investigação. As ocorrências mostram alterações de registros; seu horário não comprova o instante da medição física nem da descarga.
- Aferição é o teste da bomba com a medida de 20 litros do Inmetro; o combustível volta ao tanque e não é venda.
- Ticket médio em volume é litros por abastecimento; ticket médio em reais é faturamento por venda.
- Abastecimento sem baixa saiu da bomba e ainda não virou venda; muitos, ou antigos, merecem atenção.
- Frentista se avalia por volume e por número de abastecimentos (veículos atendidos). Os dois rankings contam histórias diferentes: muitos veículos com poucos litros é moto e carro de passeio; poucos com muitos litros é caminhão no diesel. Mostre os dois; para o ranking, agrupe por frentista sem limite, e acrescente produto para ver o foco de cada um. Os piores de uma visão = ordenar_por com ordem 'asc'.
- Um posto sem sistema conectado responde pelo SPED Fiscal que a rede envia todo mês: em unidades ele vem com fonte "SPED Fiscal" e dados_ate no fim do último mês enviado. O SPED traz vendas em reais por dia, sem divisão por produto nem hora, litros, LMC, bicos, o nível dos tanques no fim do mês, compras, as notas de venda e o cadastro dos produtos que cita (NCM, CEST, alíquota de ICMS, sem preço nem estoque); não traz hora, operador, forma de pagamento, cliente, grupo dos produtos nem os itens da NFC-e. Quando o período ou a comparação têm dias sem SPED, ou a pergunta pede o que o SPED não traz, o posto vem em unidades_fora com o motivo: diga isso, e não trate a falta de dados como queda. Uma rede sem sistema conectado e sem SPED recebe um erro que diz isso.

Lojas
- Uma loja não tem litros nem tanques: vendas abre com faturamento, número de vendas e ticket médio. As perguntas de loja saem de vendas: por grupo e subgrupo (o que mais vende, a margem de cada grupo), por produto com itens e quantidade (mais vendidos), itens_por_venda e ticket_medio (a cesta), por hora e dia da semana (o movimento, a madrugada), por operador com canceladas (quem vende e quem cancela).
- O estoque da loja e o giro: estoque_produtos. Trocas de preço e cancelamentos, com quem fez: ocorrencias.