Alvore Finance

Cria ou edita um profissional da equipe, com grade semanal e ausências. Sem `id`: cria (`clientRequestId` obrigatório). Com `id` + `version` (de ler_equipe ou do `atual` de um 409): edita; `version` diferente da gravada responde 409 com o profissional `atual` e nada é gravado. `grade` e `ausencias` enviadas substituem as listas inteiras.

salvar_profissional

Cria ou edita um serviço do catálogo. Sem `id`: cria (`clientRequestId` obrigatório). Com `id` + `version` (de ler_servicos ou do `atual` de um 409): edita; `version` diferente da gravada responde 409 com o serviço `atual` e nada é gravado. `entrega` diz como o serviço é consumido: SESSAO, ETAPAS ou HORAS. `roteiro` enviado grava uma versão nova do roteiro (etapas com horas previstas e insumos do estoque); a anterior fica no histórico. `codigoServico`, `aliquotaIss` e `issRetido` são os dados fiscais do serviço; null herda o valor do perfil fiscal da empresa.

salvar_servico

Cria um projeto da consultoria na empresa e devolve o projectId. Cada chamada cria um projeto novo, exceto o replay do mesmo clientRequestId. Não há checagem de projeto com tema parecido; os projetos existentes estão em listar_projetos.

criar_projeto

Cria, edita ou muda a situação de um contrato de serviço ou de venda; não gera cobrança. Sem `id`: cria em RASCUNHO (`clienteId`, `forma`, `itens`, `inicio` e `clientRequestId` obrigatórios; PROJETO exige `fim`). A forma VENDA aceita item de produto do catálogo (`produtoId`), de serviço ou livre (`descricao`), com `precoUnitario` opcional; sem `valor`, o valor é a soma dos itens com preço. As formas de serviço exigem o módulo Presta serviços e aceitam só itens de serviço; sem ele, só VENDA. Com `id` + `version` (de ler_contratos_servico ou do `atual` de um 409): edita um contrato em RASCUNHO ou ATIVO; cliente e forma não mudam; `itens` substitui a lista inteira e não recalcula o `valor`, que só muda quando vem junto na edição; com aditivo válido, `valor`, `inicio`, `fim` e `itens` respondem 409 (mudam só por aditivo); `version` diferente da gravada responde 409 com o contrato `atual`. Com `id` + `acao` + `clientRequestId`: ativar, pausar, retomar, concluir ou cancelar; transição fora do caminho responde 409. Vendedor restrito grava só em contratos de clientes e negócios que ele enxerga.

salvar_contrato_servico

Desfaz um lote de classificação manual (`loteId` devolvido por classificar_transacao ou por ler_historico_classificacao): reverte cada transação para o estado anterior e, se o lote tinha aprendido/tocado uma regra, desfaz essa ação também ("CREATED" desativa; "UPDATED"/"DISABLED" restaura o estado anterior). Transação alterada depois deste lote, ou que não existe mais, é listada em `conflitos` (com `motivo`) e não é revertida; com `conflitos` não vazio a reversão é parcial, e o lote fica marcado como desfeito mesmo assim (as transações em conflito não voltam mais por este lote). O campo `regra` vem "desativada", "restaurada", "conflito" (a regra mudou depois do lote e ficou como está) ou null (o lote não tocou regra). `simular: true` só conta revertidas/conflitos/regra, sem gravar nada. Lote já desfeito responde 409, então a mesma chamada repetida não desfaz duas vezes. Também respondem 409 o lote do par com a caixinha (origem CAIXA) e o desfazer dele, que só a tela Caixa do app reverte, o lote da categoria do título ERP conciliado (origem ERP) e o desfazer dele, que só a própria conciliação reverte, e o lote que tocou a transação de banco de um par ativo com a caixinha, enquanto o par estiver ativo.

desfazer_classificacao

Fecha um run aberto por `iniciar_run` com status 'done' ou 'failed' e um resumo de uma frase do que foi feito, exibido no cockpit. A contagem de tokens do modelo e o custo são opcionais e informados por quem chama; o servidor não os mede. Um run já encerrado devolve o estado gravado, sem sobrescrever. Um run aberto com um token OAuth renovado depois pode ser encerrado com o token renovado da mesma conexão (mesmo dono, mesmo aplicativo e mesmo alvo) quando o agente e a empresa informados são os do run.

encerrar_run

Estorna um movimento do livro de estoque nativo: grava um movimento do tipo ESTORNO com a quantidade oposta, datado de hoje (BRT), no mesmo local e apontando para o original, que não é alterado nem apagado. O livro não tem edição nem exclusão; a correção de um lançamento é o estorno seguido de um novo lançamento. Cada movimento aceita um único estorno (um segundo responde 409). Um movimento do tipo ESTORNO não pode ser estornado, e movimentos de ordem de produção (CONSUMO_OP, PRODUCAO_OP) são recusados (422). O estorno é aceito também em movimento de produto arquivado.

estornar_movimento_estoque

Exclui do plano de contas PJ um grupo (`nivel: "grupo"`, `grupoId`), uma categoria (`nivel: "categoria"`, `categoriaId`) ou uma subcategoria (`nivel: "subcategoria"`, `subcategoriaId`), ids de ler_plano_contas. A exclusão é em cascata: o grupo leva as categorias dele e a categoria leva as subcategorias dela. As transações classificadas no que sai voltam a não classificadas (pendentes, fora da DRE até serem classificadas de novo); as regras de categorização e o de-para ERP que apontavam para essas subcategorias são removidos (os títulos do ERP voltam a "a Identificar"). Não há desfazer. Subcategoria com lançamento na caixinha de dinheiro físico é recusada (409): o livro da caixinha só se corrige por estorno. A resposta traz quantos grupos, categorias, subcategorias, transações, regras e de-para ERP foram afetados; `simular: true` devolve as mesmas contagens sem excluir nada.

excluir_plano_contas

Lista o histórico de classificação manual da empresa: lotes (tela, lote, MCP, caixa, ERP ou desfazer), mais recentes primeiro, com origem, escopo, autor (`actorUserId`), subcategoria nova (`subcategoryIdNova`), regra aprendida e a ação nela (`ruleId`, `ruleAction`, se houve) e se já foi desfeito. Com `transacaoId`, lista só as mudanças daquela transação, uma por lote que a tocou. `loteId` é o identificador aceito por desfazer_classificacao. `desfazivel` é false para lote já desfeito, para lote do par com a caixinha (origem CAIXA) e o desfazer dele, que só a tela Caixa do app desfaz, e para lote da categoria do título ERP conciliado (origem ERP) e o desfazer dele, que só a própria conciliação desfaz; lote com `desfazivel: true` que tocou a transação de banco de um par ativo com a caixinha ainda responde 409 em desfazer_classificacao.

ler_historico_classificacao

Deixa o plano de contas PJ da empresa igual a um plano gerencial (ex.: o do ERP do cliente), em lote: cria, renomeia, reordena e reativa grupos, categorias e subcategorias, e grava o `codigoExterno` (código da classe no ERP, único por empresa) em cada subcategoria. A subcategoria é identificada pelo `codigoExterno` (sem código, adota a de mesmo nome na categoria); categoria e grupo, pelo nome ou por `categoriaId`/`grupoId` para renomear. A ordem das linhas é a ordem da árvore. Entrada: `csv` (texto com separador `;`, colunas grupo, papel, categoria, codigo, subcategoria, sinal, budgetRole, atividade — o cabeçalho casa por prefixo) OU `linhas`. `dePara` move as transações de uma subcategoria antiga (`subcategoriaId` de ler_plano_contas) para a nova (`codigoExterno`), com histórico desfazível em desfazer_classificacao (o desfazer devolve as transações; regras TENANT e de-para ERP levados junto ficam na conta nova), e leva junto regras TENANT e de-para ERP; transação cujo sinal o destino não aceita, ou casada com a caixinha, fica onde está e é contada. Subcategoria antiga que esvazia é INATIVADA, nunca apagada, e as regras TENANT dela são desligadas; `inativarAusentes: true` inativa também as ausentes do arquivo sem histórico (com histórico seguem ativas, listadas em `mantidasComHistorico`). Arquivo com qualquer erro é recusado inteiro, com a lista de erros. Receita financeira (budgetRole *_INCOME) em grupo DESPESA_FINANC é coerente: o "(±) Resultado Financeiro" da DRE soma com sinal. Toda chamada devolve criados, renomeados, inativados e o efeito na DRE dos últimos 12 meses (por mês e por papel), calculado sobre o estado anterior; `simular: true` devolve o mesmo resultado sem gravar.

importar_plano_contas

Abre um run (execução) de um agente sobre uma empresa e devolve o runId. Indicada para marcar o início de um trabalho do agente. Enquanto houver run aberto (até `encerrar_run`), as leituras auditadas, as propostas, os projetos e as versões de artefato feitos com o mesmo token ficam ligados, no cockpit, ao run aberto mais recente desse token. Abrir um run encerra como 'failed' o run ainda aberto do mesmo token e do mesmo agente. Repetir o mesmo `clientRequestId` devolve o run já criado (`replay: true`), e o campo `status` indica se ele ainda está aberto; um run encerrado não é reaberto, e um `clientRequestId` diferente abre outro run.

iniciar_run

Lança um movimento (ENTRADA, SAIDA, AJUSTE ou SALDO_INICIAL) no livro de estoque nativo de um produto ativo (`produtoId` ou `codigo`, exatamente um); produto arquivado é recusado (422). ENTRADA, SAIDA e SALDO_INICIAL recebem `quantidade` positiva e o tipo define o sinal. AJUSTE recebe a diferença contada, com sinal e diferente de zero. SALDO_INICIAL só é aceito quando o produto não tem nenhum movimento naquele local. `data` em YYYY-MM-DD, não posterior a hoje (BRT). O livro é só de acréscimo: esta tool não edita nem apaga movimentos, e a correção de um lançamento é o estorno dele seguido de um novo lançamento. Saldo negativo é aceito e sinalizado em `alertas`. `extras` guarda campos livres do lançamento (fornecedor, destino, motivo) e o estorno não os copia.

lancar_movimento_estoque

Devolve o HTML de um artefato (a versão corrente, ou a versão indicada em `version` — inclusive o rascunhoPendente de listar_artefatos). Funciona para rascunho e publicado.

ler_artefato

Configuração do módulo Presta serviços da empresa (catálogo, equipe e contratos de serviço dentro de Vendas): ponto de partida (`base`: SESSAO, PACOTE, PROJETO ou HORAS), `formas` de contrato oferecidas no formulário do CRM, `regraFaltaPadrao` dos contratos novos (CONTA ou NAO_CONTA), `duracaoPadraoMin` de atendimento sem duração definida, `avisoPacoteRestante` (pacote acabando quando restar até esse número), `diasParado` e `diasVencendo` dos filtros de contrato. `version` é a versão da configuração; 0 indica empresa sem configuração salva (vale o padrão). `propostaPendente` traz a sugestão de configuração ainda não conferida na tela, ou null. O catálogo e a equipe estão em ler_servicos e ler_equipe.

ler_configuracao_servicos

Lista as regras determinísticas de categorização ativas e aprovadas desta empresa: o dicionário curado pela consultoria (`origin: "GLOBAL"`) e as regras aprendidas da própria empresa (`origin: "TENANT"`). Regras desativadas não aparecem nesta lista. Regra por documento (CPF/CNPJ) não expõe o documento: o rótulo é o nome da contraparte ou um texto genérico. Nas demais regras, o rótulo é a descrição limpa de uma transação representativa ou, na falta dela, o próprio padrão de texto.

ler_regras

Caixinhas (metas) do cliente pessoa física: reserva de emergência, projetos de vida e PGBL, com meta, valor atual (investido, em conta ou manual), percentual atingido, prazo e aporte mensal necessário para chegar à meta no prazo. Os valores são os da tela de Caixinhas.

ler_caixinhas_pf

Minutos livres e ocupados por profissional em cada dia do período, a partir da grade, das ausências, dos negócios marcados no CRM e das entregas agendadas. Negócios sem profissional aparecem em semVinculo. Período de até 366 dias.

ler_capacidade

Taxonomia de categorias do cliente pessoa física: grupos e subcategorias (as da base e as criadas para ele), com o papel no orçamento de cada uma, e as regras de classificação próprias do cliente. Regra por contraparte aparece pelo nome da contraparte; o documento não é devolvido.

ler_categorias_pf

Catálogo de serviços da empresa, por código, paginado por `cursor`; `busca` casa parte do código ou do nome. Com `servicoId`, devolve um serviço com o roteiro vigente (etapas e insumos), as horas previstas e, para quem vê custo, custo das horas, custo dos insumos e margem.

ler_servicos

O que o cliente pessoa física tem a pagar e a receber nos próximos 30 dias, dia a dia: faturas de cartão, contas fixas, assinaturas, dívidas, lançamentos pontuais e entradas de renda previstas, com o total de saídas, a entrada prevista e a sobra. É a mesma fila de 'Próximos 30 dias' da Visão Geral e do Fluxo de Caixa.

ler_compromissos_pf

Conexões bancárias (Open Finance) ativas do cliente pessoa física: instituição, situação, se precisa reconectar, se o banco limitou a consulta, quando a conexão foi atualizada e a data da transação mais recente. Conexão desconectada de propósito não aparece. É a mesma lista da tela de Contas conectadas do app.

ler_conexoes_pf

Consulta em tempo real, no ERP da empresa, as contas correntes (e, no Lote Mobile, as formas de pagamento) cadastradas, com os ids numéricos usados no payload de baixa. Só leitura: não altera o ERP nem movimenta dinheiro. Aceita provider 'lote_mobile' (devolve `contasCorrentes` e `formasPagamento`, ids de `contaCorrenteId`/`formaPagamentoId`; `integracaoBancaria: true` indica a conta que o ERP usa para remessa bancária) e 'omie' (devolve só `contasCorrentes`, cujo `id` é o `contaCorrenteId` de omie:baixar_conta_pagar e omie:incluir_conta_pagar; `inativa: true` é recusada na execução).

ler_opcoes_baixa_erp

Devolve o contexto cadastral e de classificação de uma empresa: identidade (CNPJ, razão social, nome fantasia, CNAE, descrição do CNAE e segmento estimado a partir do CNAE), até 30 grupos do plano de contas PJ (id textual do grupo, nome e papel na DRE; não são ids de subcategoria) e até 15 descrições de saída mais recorrentes nas transações. Para consultor e agente, inclui também `regrasHumanas`: até 20 regras de categorização do tenant (padrão → nome da subcategoria), sem filtro de aprovação nem de ativação, o que inclui propostas do agente ainda não revisadas e regras desativadas; para o titular da empresa esse campo não é devolvido. Indicada quando a análise precisa da identidade, do plano de contas, dos fornecedores recorrentes ou das regras de categorização da empresa.

ler_contexto_empresa

Contratos da empresa: de serviço (avulso, pacote, recorrente, projeto), com o saldo de cada serviço (contratado, consumido e restante), e de venda (VENDA), com os itens vendidos (serviço, produto do catálogo ou descrição livre), quantidade e preço, sem saldo. Filtros: parados e acabando (só serviço), vencendo e forma. Com `contratoId`, devolve um contrato com itens, saldo e as 20 entregas mais recentes; sem ele, uma página por `cursor`, do mais recente ao mais antigo. No RECORRENTE o saldo é o do mês corrente (dia de Brasília). Com `contratoId`, escopo de leitura financeira e Presta serviços ligado, inclui os títulos a receber ligados ao contrato e, para quem administra a empresa, títulos do mesmo cliente que podem ser a cobrança dele (sugestões, nada gravado). Vendedor restrito recebe só contratos de clientes e negócios que ele enxerga.

ler_contratos_servico

Painel de dívidas do cliente pessoa física, o mesmo da aba Dívidas: quanto compromete por mês e a fração da renda, contratos aprovados com saldo, parcela, CET e custo acima da referência de mercado, ordem de ataque sugerida, contratos do Open Finance aguardando aprovação e posição líquida investimentos × dívidas. Com token de consultor, as dívidas manuais incluem as que a consultoria cadastrou.

ler_dividas_pf

Profissionais da empresa com especialidades, grade semanal (dia da semana 0 = domingo, início e fim HH:MM) e ausências. `custoHora` só aparece para quem vê custo.

ler_equipe

Devolve o blob de estado que o time da empresa gravou no artefato (ex.: itens marcados num checklist). Só leitura: o estado é dado do cliente e não pode ser escrito por aqui.

ler_estado

Eventos de buffet da cópia sincronizada do ERP da empresa (hoje, BuffetMax), no lote ativo de títulos de cada conexão. `cliente` só com dígitos filtra pelo id do cliente no ERP (igualdade exata); outro texto busca no nome do cliente (sem diferenciar maiúsculas nem acentos). `periodoDe`/`periodoAte` filtram a data do evento (YYYY-MM-DD, inclusive). `status` filtra por lista. `truncado: true` quando há mais eventos do que `limite`.

ler_eventos

Faturas dos cartões de crédito do cliente pessoa física, por cartão: a fechada a pagar (vencimento, total, mínimo, situação), a aberta em curso (total e composição) e as parcelas já conhecidas das próximas faturas, agregadas por vencimento. São os mesmos números do card de faturas da Visão Geral. Os valores são de caixa (data de vencimento).

ler_faturas_cartao_pf

Componentes da ficha técnica de um produto pai, do lote de estoque ativo. `encontrado: false` quando o código não tem nenhuma linha de estrutura no lote — não é o mesmo que "produto sem componentes".

ler_estrutura

Ficha técnica vigente de um produto nativo (componentes, quantidades, perda, rendimento), identificado por `produtoId` ou `codigo` (exatamente um). `ficha: null` indica produto sem ficha. Com `explodir: true`, inclui a necessidade de insumos folha para `quantidade` (default 1) unidades do produto, até `niveis` (default 10); `explosao: null` quando o produto não tem ficha. Cada insumo da explosão traz `custoUnitario`, `custo` e `origemCusto` (`padrao` = custo padrão do produto; `ultima_entrada` = última entrada de estoque não estornada; null = sem custo), e a explosão traz `custoTotal`, `custoPorUnidade` e `insumosSemCusto`.

ler_ficha_tecnica_alvore

Devolve a referência de formato do HTML de um artefato Alvore: identidade visual (cores, tipografia, CSS base), restrições da sandbox do iframe, o script da ponte que salva o que o usuário marca e um esqueleto HTML por tipo. Quando a empresa tem o módulo Produtos ligado, inclui também a API de dados (alvoreDados) e os modelos estoque, ficha_tecnica, ordem_producao e ordem_compra, que são também as telas dos lugares do menu Produtos (parâmetro `lugar` de criar_artefato); com o CRM ligado, os dados do CRM e o modelo contrato (e, com o documento do contrato liberado, o caminho até o modelo nativo de documento, propor_modelo_contrato); com o módulo Presta serviços ligado, os dados de Serviços e os modelos contratos_servico, catalogo_servicos e equipe_servicos, que são também as telas dos lugares Contratos, Catálogo de serviços e Equipe, dentro de Vendas. Serve para montar o HTML enviado a criar_artefato, nova_versao ou aplicar_patch. Sem `tipo`, devolve a referência geral e a lista de modelos. Não devolve o conteúdo de artefatos existentes (esse é o papel de ler_artefato).

ler_guia_artefato

Resultado mês a mês do cliente pessoa física num período de 2 a 12 meses (de/ate "YYYY-MM"): quanto entrou, gastou, guardou e sobrou, e a composição dos gastos (contas fixas, dia a dia, parcelas, assinaturas). Os números são os mesmos da tela de Orçamento por período. O mês corrente vem marcado como parcial.

ler_historico_pf

Projeção de liberdade financeira do cliente pessoa física a partir das premissas salvas no planejamento: idade atual e alvo, renda desejada, aporte, patrimônio investível e taxas; resultado com anos até a meta, patrimônio necessário, até que idade dura e saldo ano a ano. Sem premissas suficientes, a resposta diz o que falta.

ler_liberdade_financeira_pf

Modelos de documento do contrato da empresa: os ativos, com finalidade (CONTRATO ou ADITIVO, derivada do texto) e versão; para quem administra a empresa, também as sugestões pendentes de propor_modelo_contrato. `formato` traz a sintaxe do texto, os limites e a lista fixa de variáveis aceitas. Com `modeloId` ou `propostaId`, inclui o texto daquele item. Modelo arquivado não aparece.

ler_modelos_contrato

Movimentos do extrato bancário da empresa (conta corrente, status lançado) que ainda não têm título no Conta Azul, do mais recente para o mais antigo. Cada item traz `id` (o `transactionId` de conta_azul:criar_lancamento), data, valor, sentido, tipo ('pagar' ou 'receber'), descrição, contraparte, conta bancária, `possivelBaixa` (há título em aberto parecido no Conta Azul) e `sugestoes` de categoria, contato e conta financeira, com `sugerido` quando a sugestão é única. `opcoes` lista os ids aceitos na proposta: categorias por tipo, contatos e contas financeiras do Conta Azul. Sai da cópia sincronizada, sem chamar o Conta Azul. `desde` define o primeiro dia da janela (padrão 90 dias, máximo 365); `truncado: true` indica transações além do teto de leitura, e `semLoteAtivo: true` indica que o Conta Azul ainda não sincronizou (sem sugestões nem opções).

ler_extrato_sem_lancamento_erp

Livro de movimentos de estoque nativo, do mais recente ao mais antigo, paginado por `cursor`. Aceita filtro por produto (`produtoId` ou `codigo`) e por período (`de`/`ate`, YYYY-MM-DD). `estornado: true` indica que já existe um estorno apontando para o movimento.

ler_movimentos_estoque

Ordens de produção nativas da empresa. Sem `id`: lista paginada por `cursor`, da mais recente à mais antiga, com filtro por `status` e `produtoId`. Com `id`: o detalhe de uma ordem, com `movimentos` (as linhas do livro de estoque ligadas a ela) e, quando PLANEJADA, `consumoPrevisto`: as matérias-primas que iniciar vai baixar (a ficha gravada na ordem, descendo pelas fichas vigentes dos semiacabados, sem os itens que não controlam estoque), cada uma com `quantidade`, `saldo` atual somado de todos os locais e `falta` (o que passa do saldo). Fora de PLANEJADA, `consumoPrevisto` vem vazio e o consumo real está em `movimentos`.

ler_ordens_producao

Orçamento do cliente pessoa física num mês: os 4 KPIs (renda, fixas, variáveis, sobra — planejado × realizado), o teto de gastos variáveis do mês (teto, gasto, disponível, status, projeção de fim de mês) e a árvore da DRE familiar podada (grupo → categoria → subcategoria, cada nó com meta, realizado e saldo). `mes`: "YYYY-MM"; ausente = mês corrente.

ler_orcamento_pf

Compras parceladas e compromissos do cliente pessoa física, com o mesmo cálculo do painel de Dívidas: valor mensal, progresso, mês de término de cada parcela, quais aguardam aprovação e a linha do tempo dos próximos 12 meses com os meses em que o compromisso mensal cai. Devolve até 100 compras; a resposta informa o total e se houve corte.

ler_parcelas_pf