Granatum Financeiro

Anexa um arquivo (nota fiscal, boleto, comprovante) a um lançamento do cliente, em DUAS chamadas. O arquivo NUNCA vai como argumento nem volta em resposta: ele vai direto ao armazenamento, por um comando de envio que a tool entrega pronto. Requer autorização de escrita (lancamentos:write) e altera dados reais; o perfil Somente relatórios não anexa, e o perfil Lançamentos por usuário só anexa em lançamento que criou. (1) PEDIR O ENVIO: informe lancamento_id, nome_arquivo (com a extensão) e tamanho_bytes (de 1 byte a 5 MB (5242880 bytes)). Nada é anexado ainda: a tool devolve status 'envio_pendente' com envio_id, url, campos, valido_ate (o envio vale 10 minutos) e exemplo_de_comando, um curl com os campos reais. (2) ENVIAR: se você consegue executar comandos (shell com acesso à rede, como no Claude Code ou em agentes com terminal), execute o exemplo_de_comando por conta própria, trocando <caminho do arquivo> pelo caminho real do arquivo; o esperado é HTTP 204. (3) CONFIRMAR: chame de novo com lancamento_id e envio_id (sem nome_arquivo nem tamanho_bytes). A tool confere que o arquivo chegou, registra o anexo e devolve status 'anexado' com o anexo criado. O envio_id vale 1 hora e uma confirmação só. SEM SHELL OU SEM REDE (comum em apps de conversa): se você não consegue executar o comando, NÃO insista, NÃO tente outro caminho e NÃO afirme que anexou: nada foi anexado até a confirmação devolver 'anexado'. Explique ao usuário e oriente-o a anexar o arquivo pela tela do lançamento no Granatum. Se a confirmação voltar com codigo 'arquivo_nao_enviado' (o arquivo não chegou, o link venceu ou o envio já foi confirmado), peça UM envio novo (chamada sem envio_id) e envie de novo; se falhar outra vez, oriente o usuário a anexar pela interface. SÉRIE: se o lançamento é de série e escopo_serie não vem na confirmação, a tool NÃO anexa e devolve status 'escopo_necessario' com a posição e o tamanho da série; pergunte ao usuário e chame de novo (o arquivo já enviado e o envio_id continuam valendo). 'so_este' anexa só a esse lançamento; 'este_e_proximos' põe o mesmo arquivo, sem enviá-lo de novo, nesse lançamento e nos seguintes da série, e a resposta diz em quantos lançamentos o anexo entrou (lancamentos_alcancados); esta escolha grava de uma vez, sem prévia, então não a faça por conta própria. url, campos e envio_id são credenciais temporárias: não os mostre ao usuário nem os repita.

Atualiza um lançamento (avulso, ocorrência de uma série ou dividido) ou uma transferência existente nos livros do cliente. Requer autorização de escrita (lancamentos:write). Chama a API do Granatum em nome do usuário autenticado e altera dados reais. Antes de chamar, confirme com o usuário o lançamento e os campos que serão alterados. lancamento_ids leva de 1 a 100 ids: com um id altera aquele lançamento; com vários, aplica a MESMA alteração em cada um (só valem descricao, valor, categoria_id, centro_custo_lucro_id, pessoa_id, forma_pagamento_id, conta_id, data_vencimento, data_competencia, observacao, documento, tags_adicionar e tags_remover; itens e escopo_serie não valem com vários ids; identificador_externo também não: é de um lançamento só). CONFIRMAÇÃO: toda chamada que alcança mais de um lançamento (vários ids, escopo_serie 'este_e_proximos' ou total_repeticoes) NÃO grava na primeira vez: devolve status 'confirmacao_necessaria' com a quantidade que seria alterado (quantidade_a_alterar), quantos desses JÁ ESTÃO PAGOS (ja_pagos) e os pulados (o que ficaria como está, com o motivo). Essa quantidade conta por PARCELA: um lançamento por parcela, e uma TRANSFERÊNCIA por parcela, que são dois lançamentos (as duas pontas); numa série de transferência a prévia traz também quantidade_de_transferencias_a_alterar e quantidade_de_lancamentos_a_alterar, e a dica diz "2 transferência(s) (4 lançamentos)", para o usuário não confundir. Apresente isso ao usuário e pergunte explicitamente se deve prosseguir; só reenvie, com os mesmos argumentos mais confirmado: true, APÓS resposta humana explícita — nunca autoconfirme. A segunda chamada grava e devolve o resultado real, que pode diferir da prévia se algo mudou no intervalo. Com um id e sem série não há confirmação. Se a prévia traz `impedidos`, NÃO há o que confirmar: nada será alterado enquanto eles estiverem no pedido. VÁRIOS IDS: todo id pedido é alvo. Se algum é impedido pelo estado (conciliados, quando a alteração mexe em valor ou conta; pagos até a data de bloqueio de caixa; com competência até a data de bloqueio de competência (valor, competência e classificação não mudam, e vale para qualquer campo, menos o vencimento, que é livre; nos pagos no caixa fechado o vencimento também não muda); transferências; saldo inicial; cobrança ou NFS-e agendada com campo fora da lista; fatura de cartão), NADA é alterado: a prévia traz `impedidos` (cada id com codigo, descricao e os campos recusados em `campos`) e diz que nada será alterado enquanto eles estiverem no pedido; confirmar com eles no pedido devolve erro com a mesma lista e não altera nada. Para alterar o restante, refaça a chamada SEM esses ids. Lançamento DIVIDIDO de 2 ou mais itens com valor, descricao ou tipo_lancamento no pedido não é estado, é pedido que não se aplica a ele (valor, descrição e tipo são de cada item): erro com codigo 'pedido_nao_se_aplica_aos_alvos', `impedidos` e NADA alterado; tire o dividido do pedido ou altere os itens dele com itens_alterar (o tipo do item é itens_alterar[].tipo). Só o que o pedido ALCANÇA sem nomear (escopo_serie 'este_e_proximos' com um id) pode ficar como está, com o motivo em pulados. Um id inexistente ou de outra empresa recusa o pedido todo, sem gravar. SÉRIE: se o lançamento é de série (parcelas, repetição) e escopo_serie não vem, a tool NÃO grava: devolve status 'escopo_necessario' com o tamanho da série (tamanho_da_serie, as parcelas VIVAS, e total_gravado quando o total gravado é outro, porque excluir parcela não o desce; ou serie_sem_fim) e a posição do lançamento. Pergunte ao usuário e chame de novo. escopo_serie 'so_este' altera só aquela ocorrência (as outras ficam exatamente como estão); 'este_e_proximos' altera esta e as seguintes (só o que mudou em relação a esta propaga, e as já pagas também mudam), com a confirmação abaixo. DIVIDIDO: itens_adicionar, itens_alterar e itens_remover mexem nos itens; os ids de item vêm de obter_lancamentos com lancamento_ids (cada item é um lançamento). Num dividido, valor, categoria, descrição, pessoa, centro, forma e tags são DE CADA ITEM (use itens_alterar); data de vencimento, competência, conta, documento e observação valem para o lançamento todo, no nível de cima. A resposta traz os itens como ficaram e o valor total. Para excluir o lançamento dividido inteiro use excluir_lancamento. Com escopo_serie 'este_e_proximos' valem itens_adicionar, itens_alterar e itens_remover: o item novo entra nesta parcela e nas seguintes, o alterado muda nesta e nas seguintes (o item correspondente de cada mês, pelo grupo dele) e o removido sai delas, com a prévia e o confirmado; os meses que o estado impede (pago, conciliado, bloqueado, com cobrança) ficam como estão e aparecem em pulados com o motivo. CADA ITEM DIZ O QUE É: itens_adicionar[].tipo ('despesa' ou 'receita') é obrigatório, e o valor é a grandeza (sempre positivo); o tipo dá o sinal. Um dividido pode misturar despesa e receita: o total é a soma dos itens com sinal (despesa negativa, receita positiva), e o item de desconto ou retenção é só o item de tipo contrário ao dos outros. Nada se deduz do primeiro item nem do total. Em itens_alterar, tipo (opcional) TROCA o tipo daquele item e o sinal do valor (a grandeza fica): a pessoa do item precisa ter o papel do tipo novo (cliente em receita, fornecedor em despesa; senão a chamada é recusada em itens_alterar[N].pessoa_id e você envia a pessoa certa ou 0) e os tipos de custo vão a 0 ao virar receita. tipo_lancamento no nível de cima NÃO vale num dividido: o tipo é de cada item (itens_alterar[].tipo). A resposta traz cada item com o próprio tipo. ITEM NOVO, O QUE ELE GRAVA: só o que você enviar. O que não for enviado (centro de custo, pessoa, forma de pagamento, tipos de custo e tags) fica vazio: a API não copia de outro item. Se o usuário quer a pessoa, o centro, a forma ou as tags de outro item, leia-os (obter_lancamentos com lancamento_ids) e envie-os no item novo. Os tipos de custo não têm campo nesta ferramenta: o item novo fica sem tipo de custo. TOTAL DA SÉRIE: total_repeticoes (com periodicidade, no avulso que vira série) aumenta ou diminui o número de parcelas de uma série limitada, de lançamento, dividido ou transferência, pelo mesmo motor do PUT do REST; sempre devolve a prévia (confirmacao_necessaria, com quantidade_de_parcelas_a_criar e quantidade_de_parcelas_a_excluir) e só grava com confirmado: true; igual ao gravado não grava; vale a série inteira, sem perguntar escopo_serie quando é o único campo do pedido. TAGS: tags_adicionar e tags_remover (não substituem o conjunto: as outras tags ficam). COBRANÇA: o lançamento com cobrança (não cancelada, ou cancelada em transferência) ou com NFS-e agendada só aceita alterar observacao, documento, tipo_documento_id, categoria_id, centro_custo_lucro_id, identificador_externo, tipo_custo_nivel_producao_id, tipo_custo_apropriacao_produto_id, tags_adicionar, tags_remover; qualquer outra alteração (valor, vencimento, conta, pessoa, forma de pagamento, tipo, descrição, competência) é recusada com o código cobranca_ou_nfse_agendada e nada é gravado: nesse caso diga ao usuário que isso se altera pelo sistema atual do Granatum. PAGAMENTO: em lançamento, data_pagamento NÃO é aceito aqui (é recusado): para dar baixa, trocar a data do pagamento ou estornar use a tool registrar_pagamento. Transferência: lancamento_ids pode ter o id de qualquer uma das duas pontas, e a alteração vale para a transferência inteira (as duas pontas, sem inverter o sentido); só o que você informa muda, e o resto fica como está gravado. Valem descricao, valor, data_vencimento, conta_id (conta de origem), conta_destino_id, centro_custo_lucro_id, documento, observacao, tags_adicionar, tags_remover, data_competencia, data_pagamento, pagamento_automatico, identificador_externo_origem, identificador_externo_destino e escopo_serie, e os demais campos são recusados. data_vencimento muda só o vencimento: NÃO baixa nem reabre a transferência (a API Rails fazia isso, esta ferramenta não). Para dar baixa informe data_pagamento (hoje ou passada; o vencimento não muda, como no lançamento), e data_pagamento "" a reabre. Uma ponta conciliada não muda de valor, de conta nem de data de pagamento; transferência paga até a data de bloqueio de caixa não se altera; transferência com competência até a data de bloqueio de competência também não (valor, contas, descrição e competência não mudam; o vencimento passa), e a competência nova até essa data é recusada. Numa parcela de série de transferência, escopo_serie 'so_este' (o padrão) muda só a parcela pedida, que segue na série, e 'este_e_proximos' leva o que mudou também às parcelas seguintes (os dois lançamentos de cada parcela), como no lançamento: só o que difere da pedida propaga, o vencimento anda a partir do pedido, um período por parcela, a conta de origem e a de destino vão cada uma para a sua ponta, a baixa (data_pagamento) e os identificadores externos ficam só na parcela pedida, e a parcela seguinte já paga também muda (salvo a protegida por bloqueio, que fica como está e aparece em pulados). Com 'este_e_proximos' a tool NÃO grava na primeira vez: devolve a prévia (confirmacao_necessaria) e só grava com confirmado: true depois da confirmação explícita do usuário.

Busca clientes e fornecedores da empresa autenticada por nome, nome fantasia. Cliente e fornecedor são atributos da mesma pessoa — uma pessoa pode ser ambos. Use para descobrir o pessoa_id ao criar um lançamento. O valor 0 representa 'sem pessoa vinculada'.

Concilia (em lote, de 1 a 100 pares) movimentos do extrato bancário com lançamentos: cada par {movimento_id, lancamento_id} liga o movimento ao lançamento e, quando preciso, baixa o lançamento. Requer autorização de escrita (lancamentos:write). Altera dados reais do cliente e só vale para os perfis Administrador e Lançamentos. Um par vale quando o movimento está pendente (sem vínculo e não ignorado) e o lançamento está sem vínculo, em aberto ou já pago, com o mesmo sinal e o valor exato ao centavo, de qualquer conta; não precisa ter sido sugerido por obter_conciliacoes_pendentes. O que cada par faz no lançamento: se já está pago no mesmo dia e na mesma conta do movimento, só liga (o lançamento não muda); se está em aberto, dá baixa com a data do movimento e a conta do extrato; se já está pago em outra data ou conta, a data do pagamento e a conta passam a ser as do movimento. O movimento importado por CSV não se concilia pelo MCP (fica para a tela do Granatum): o par é recusado. Quando o lançamento muda, vale o caixa fechado: com a data antiga ou a nova até a data de bloqueio de caixa da empresa o par é recusado. CONFIRMAÇÃO: sem confirmado: true a chamada NÃO grava: devolve status 'confirmacao_necessaria' com a quantidade e o que cada par faria (acao: vincular, baixar, mudar_data_do_pagamento, mudar_conta, mudar_data_do_pagamento_e_conta). Na ação baixar de um lançamento de outra conta (conta_antes_id diferente de conta_depois_id), diga ao usuário que a baixa leva o lançamento para a conta do extrato. Fluxo: leia com obter_conciliacoes_pendentes, conte as confiáveis ao usuário (isso só informa); o pedido dele para conciliar autoriza só a prévia (conciliar sem confirmado); mostre a prévia, termine a resposta ali perguntando "concilio estes N?" e só confirme depois do sim dele à prévia; nunca concilie um movimento revisar ou bloqueado sem antes mostrar o movimento, o motivo e o(s) candidato(s) e o usuário escolher o lançamento; só depois da escolha chame a prévia. Nunca mande parâmetro opcional vazio ou zero: omita. Mostre isso ao usuário e só reenvie, com os mesmos pares mais confirmado: true, numa resposta seguinte a uma mensagem nova do usuário que veio DEPOIS da prévia e a aceita; um "pode", "sim" ou "confirma" dito antes da prévia não vale; nunca chame conciliar duas vezes na mesma resposta; nunca autoconfirme. A confirmação confere cada par de novo na hora de gravar. LOTE: todo par do pedido é alvo. Se algum estiver impedido (caixa fechado, movimento ou lançamento já conciliado, par que deixou de valer, id de outra empresa ou inexistente), o pedido INTEIRO é recusado, nada é gravado, e a resposta lista cada par impedido com o motivo (status erro, codigo alvos_impedidos, impedidos). Isso acontece quando algo mudou entre a leitura e o sim. Diga ao usuário "N mudaram desde a consulta: motivos; concilio as outras M?" e, se ele aceitar, refaça sem os impedidos, mostrando a prévia nova antes de confirmar. Não faz (fica na tela do Granatum): valor diferente, vários lançamentos para um movimento, criar lançamento a partir do movimento, ignorar movimento e voltar a data de bloqueio. Perfis sem acesso à conciliação (só Administrador e Lançamentos a usam) recebem a recusa "Seu perfil nesta empresa não dá acesso à conciliação": não insista.

Cria um lançamento (receita ou despesa) nos livros do cliente: avulso, com repetição (parcelas ou recorrente, parâmetro repeticao) ou dividido em vários itens (parâmetro itens). Também cria uma transferência entre duas contas (tipo_lancamento 'transferencia'). Requer autorização de escrita (lancamentos:write). Chama a API do Granatum em nome do usuário autenticado — é uma escrita real, não simulação. Período fechado: a criação é recusada se a competência estiver até a data de bloqueio de competência ou, quando pago, se a data de pagamento estiver até a data de bloqueio de caixa; a resposta traz a frase da trava, como 'Competência fechada até DD/MM/AAAA: nenhum lançamento entra nesse período.' ou 'Caixa fechado até DD/MM/AAAA: nenhum lançamento pago entra nesse período.'. Antes de chamar, confirme com o usuário os dados do lançamento; com repeticao, confirme também a quantidade, porque cada ocorrência é um lançamento real. Com repeticao, a resposta traz repeticao.grupo_id e repeticao.quantidade_criada; consulte as ocorrências com obter_lancamentos (grupo_id). Com itens, cada item diz o próprio tipo (despesa ou receita), e a resposta traz o valor total (a soma dos itens) e o id e o tipo de cada item. Transferência: informe conta_id (conta de origem, de onde o dinheiro sai), conta_destino_id (para onde entra), valor, data_vencimento e descricao; são opcionais centro_custo_lucro_id, documento, observacao, tag_ids, data_competencia, data_pagamento, pagamento_automatico, identificador_externo_origem, identificador_externo_destino e repeticao. SEM data_pagamento a transferência nasce EM ABERTO, qualquer que seja data_vencimento (hoje, passada ou futura): para registrar uma transferência que já aconteceu informe data_pagamento (hoje ou passada; o vencimento fica o data_vencimento informado, como no lançamento). SEM pagamento_automatico: true a transferência em aberto NÃO se efetiva sozinha na data. Categoria, pessoa, forma de pagamento, itens e identificador_externo (o identificador é um por ponta) NÃO se aplicam a transferência e são recusados. A transferência pode se repetir com repeticao, igual ao lançamento (periodicidade com total_repeticoes ou infinito): cada ocorrência é um par de pontas, todas no mesmo grupo_id, com as mesmas tags e centro; só a 1ª nasce paga (com data_pagamento) e os identificadores externos ficam só na 1ª; confirme a quantidade, porque cada ocorrência são dois lançamentos reais. A resposta traz as duas pontas vinculadas da 1ª ocorrência (origem e destino, cada uma com o seu id). Os identificadores externos da transferência (origem e destino) têm a mesma checagem de duplicata do lançamento; se a resposta se perder confira com obter_lancamentos antes de repetir. Se a resposta trouxer status 'confirmacao_necessaria', apresente os lancamentos_existentes ao usuário e pergunte explicitamente se deve criar mesmo assim; só reenvie com confirmar_duplicata: true após resposta humana explícita — nunca autoconfirme.

Cadastra um cliente ou um fornecedor nos livros do cliente, para usar o id dele em criar_lancamento (pessoa_id). Requer autorização de escrita (lancamentos:write). Chama a API do Granatum em nome do usuário autenticado e altera dados reais. ANTES de chamar, use SEMPRE buscar_pessoas (por nome): se a pessoa já existe, use o id dela e NÃO cadastre de novo. O Granatum ACEITA o mesmo nome repetido e duplicaria o cadastro. papel diz o que a pessoa é neste cadastro: 'fornecedor' (você paga a ela; vale em despesa) ou 'cliente' (ela paga você; vale em receita). tambem_outro_papel: true quando ela também é o outro (cliente que também é fornecedor, ou o inverso); false (padrão) quando é só um. Só nome é obrigatório; contato e endereço são opcionais, mas informe só o que o usuário disse. A resposta traz a pessoa no formato de buscar_pessoas, com o id. Dados inválidos (e-mail, CEP) voltam como erro_validacao com o nome do campo, sem cadastrar nada. Editar e excluir pessoa não existem aqui.

Desfaz a conciliação (em lote, de 1 a 100, por movimento_ids OU por lancamento_ids, nunca os dois) de movimentos do extrato bancário; quando o usuário falar do lançamento ("desfaz a conciliação daquele pagamento"), use lancamento_ids: cada lançamento resolve para o movimento do seu vínculo ativo, e o que não está conciliado é recusado com o motivo "o lançamento não está conciliado": remove o vínculo de cada movimento e, se o lançamento não tiver outro vínculo ativo, restaura pelo estado de antes da conciliação a data de pagamento (a que era em aberto volta a em aberto), o vencimento e o valor. Requer autorização de escrita (lancamentos:write). Altera dados reais do cliente e só vale para os perfis Administrador e Lançamentos. A conta do lançamento NÃO volta: a resposta diz em que conta ele ficou. Vínculo antigo, sem o estado de antes, só tem o vínculo removido: o lançamento continua pago, e reabrir é o estorno (registrar_pagamento com pago: false). A restauração segue o caixa fechado: se ela mudar uma data até a data de bloqueio de caixa da empresa, o movimento é recusado. Lançamento conciliado no mesmo dia volta igual. CONFIRMAÇÃO: sem confirmado: true a chamada NÃO grava: devolve status 'confirmacao_necessaria' com o que cada vínculo desfeito faria. Mostre ao usuário e só reenvie com confirmado: true numa resposta seguinte a uma mensagem nova do usuário que veio DEPOIS da prévia e a aceita; um "pode" ou "sim" dito antes da prévia não vale; nunca chame desconciliar duas vezes na mesma resposta; nunca autoconfirme. LOTE: todo movimento do pedido é alvo. Um movimento impedido (não conciliado, de outra empresa, inexistente, caixa fechado) recusa o pedido INTEIRO, nada é gravado, e a resposta lista cada impedido com o motivo; refaça sem eles, com prévia nova. Com o estado de antes da conciliação (snapshot), a restauração volta a data de pagamento (nula volta a em aberto), o vencimento e o valor. Sem ele (vínculo antigo), só o vínculo sai: diga ao usuário que o lançamento continua pago e que reabrir é o estorno.

Exclui um anexo de lançamento (exclusão lógica; o arquivo só sai do armazenamento quando nenhum lançamento o usa mais). Requer autorização de escrita (lancamentos:write) e apaga dados reais; antes de chamar, confirme com o usuário qual anexo será excluído. O anexo_id vem de obter_lancamentos com campos_adicionais: ["anexos"]. O perfil Somente relatórios não exclui; o perfil Lançamentos por usuário só exclui anexo de lançamento que criou. ANEXO DE SÉRIE: um anexo que foi posto em vários lançamentos da série (este_e_proximos ao anexar) exige escopo_serie; sem ele a tool NÃO exclui e devolve status 'escopo_necessario'. 'so_este' exclui o anexo só do lançamento pedido e os outros continuam com ele; 'este_e_proximos' exclui o anexo desse lançamento e dos seguintes da série. CONFIRMAÇÃO: escopo_serie 'este_e_proximos' alcança mais de um lançamento e NÃO exclui na primeira vez: devolve status 'confirmacao_necessaria' com a quantidade de anexos a excluir, os lançamentos afetados (lancamentos_afetados) e se o arquivo sairia do armazenamento (arquivo_sera_apagado). Apresente isso ao usuário e pergunte explicitamente se deve prosseguir; só reenvie, com os mesmos argumentos mais confirmado: true, APÓS resposta humana explícita — nunca autoconfirme. A segunda chamada exclui e devolve o resultado real, que pode diferir da prévia se algo mudou no intervalo. Com 'so_este' ou com anexo de um lançamento só não há confirmação. Em anexo de lançamento fora de série, ou que não foi posto em vários lançamentos, não informe escopo_serie: ele é recusado.

Exclui um lançamento (avulso, ocorrência de uma série ou dividido) ou uma transferência existente dos livros do cliente. Requer autorização de escrita (lancamentos:write). Chama a API do Granatum em nome do usuário autenticado e apaga dados reais. Antes de chamar, confirme explicitamente com o usuário. lancamento_ids leva de 1 a 100 ids: com um id exclui aquele lançamento; com vários, exclui cada um deles (também os já pagos que você nomear). CONFIRMAÇÃO: NÃO exclui na primeira vez a chamada que alcança mais de um lançamento (vários ids, ou escopo_serie 'este_e_proximos') nem a que leva um lançamento DIVIDIDO (o id de um item, sozinho ou entre vários ids, com qualquer escopo_serie): devolve status 'confirmacao_necessaria' com a quantidade que seria excluída (quantidade_a_excluir, que conta por PARCELA: um lançamento por parcela e uma transferência por parcela, que são dois lançamentos, as duas pontas; numa série de transferência a prévia traz também quantidade_de_transferencias_a_excluir e quantidade_de_lancamentos_a_excluir, e a dica diz "2 transferência(s) (4 lançamentos)"), quantos desses JÁ ESTÃO PAGOS (ja_pagos), os pulados (o que ficaria como está, com o motivo) e, para cada dividido, a quantidade de itens, o valor total e a lista dos itens (lancamentos_divididos). Apresente isso ao usuário (no dividido: que o lançamento sai INTEIRO, com os N itens listados) e pergunte explicitamente se deve prosseguir; só reenvie, com os mesmos argumentos mais confirmado: true, APÓS resposta humana explícita — nunca autoconfirme. A segunda chamada exclui e devolve o resultado real, que pode diferir da prévia se algo mudou no intervalo. Só o lançamento que não é dividido, com um id e sem 'este_e_proximos', exclui sem confirmação. SÉRIE: se o lançamento é de série e escopo_serie não vem, a tool NÃO exclui: devolve status 'escopo_necessario' com o tamanho da série (tamanho_da_serie, as parcelas VIVAS, e total_gravado quando o total gravado é outro) e a posição do lançamento; pergunte ao usuário e chame de novo. escopo_serie 'so_este' exclui só aquela ocorrência (as outras ficam como estão); 'este_e_proximos' exclui esta e as seguintes, com a confirmação acima; os próximos já pagos só saem com excluir_pagos: true, senão aparecem em pulados. VÁRIOS IDS: todo id pedido é alvo. Se algum é impedido pelo estado (conciliados, pagos até a data de bloqueio de caixa ou com competência até a data de bloqueio de competência, transferência com ponta impedida, saldo inicial, cobrança ou NFS-e agendada, fatura de cartão), NADA é excluído: a prévia traz `impedidos` (cada id com codigo e descricao) e diz que nada será excluído enquanto eles estiverem no pedido; confirmar com eles no pedido devolve erro com a mesma lista. Para excluir o restante, refaça a chamada SEM esses ids. Só a parcela que o pedido ALCANÇA sem nomear (escopo_serie 'este_e_proximos') pode ficar como está, com o motivo em pulados. Um id inexistente ou de outra empresa recusa o pedido todo, sem gravar. DIVIDIDO: o id de qualquer item exclui o lançamento dividido INTEIRO (todos os itens), nunca só o item, e isso SEMPRE passa pela confirmação acima, que mostra a quantidade de itens e a lista deles. Com escopo_serie 'este_e_proximos' num dividido, cada mês seguinte que a série alcança também sai inteiro (todos os itens do dividido daquele mês, não só os do grupo do item). Para tirar só um item NÃO use esta ferramenta: use itens_remover em atualizar_lancamento. Se o lançamento não puder ser excluído (conciliado, pago até a data de bloqueio de caixa, competência até a data de bloqueio de competência, saldo inicial), a resposta tem status 'nao_excluido' com o motivo e NADA foi excluído. Transferência: lancamento_ids pode ter o id de qualquer uma das duas pontas, e excluir uma exclui as duas; a resposta traz os dois ids excluídos (lancamentos_excluidos). Numa parcela de série de transferência, escopo_serie aceita 'so_este' (só o par da parcela pedida) e 'este_e_proximos' (a parcela pedida e as seguintes, com a prévia e o confirmado), e excluir_pagos vale como no lançamento: cada parcela sai sempre com as duas pontas, e a parcela que o estado impede em qualquer das pontas fica como está e aparece em pulados. Numa série sem fim, as parcelas que sobram deixam de repetir nas duas pontas.

Lista as categorias do plano de contas da empresa autenticada, com a hierarquia em caminho. Use para entender a estrutura contábil disponível, para descobrir IDs de categoria a usar em filtros de obter_dre, obter_fluxo_caixa ou obter_lancamentos, ou quando o usuário quiser ver/explicar a hierarquia de categorias. Para criar_lancamento, só use categoria-folha: itens com aceita_lancamento=true. Categoria-pai tem aceita_lancamento=false e a API do Granatum recusa lançamento nela.