# Financeiro Inteligente — Documentação > Documentação do Financeiro Inteligente: contas a pagar, contas a receber, transações, conciliações e API. ## pt Bem-vindo! O Financeiro Inteligente é a plataforma de back-office financeiro multi-empresa para o mercado brasileiro: contas a pagar e a receber, lançamentos, conciliação, importações e envio de pagamentos ao banco — várias empresas, em um só lugar. - [Financeiro Inteligente — Documentação](https://docs.finance.kobana.com.br/pt/index.md): Bem-vindo! O Financeiro Inteligente é a plataforma de back-office financeiro multi-empresa para o mercado brasileiro: contas a pagar e a receber, lançamentos, conciliação, importações e envio de pagamentos ao banco — várias empresas, em um só lugar. ### search - [Buscar na documentação](https://docs.finance.kobana.com.br/pt/search.md) ### anexos A biblioteca de arquivos do espaço de trabalho — vínculo muitos-para-muitos com títulos e lançamentos. - [Anexos](https://docs.finance.kobana.com.br/pt/anexos.md): A biblioteca de arquivos do espaço de trabalho — vínculo muitos-para-muitos com títulos e lançamentos. ### api - [Referência da API](https://docs.finance.kobana.com.br/pt/api.md) #### overview - [Visão geral](https://docs.finance.kobana.com.br/pt/api/overview.md) - [Autenticação](https://docs.finance.kobana.com.br/pt/api/overview/authentication.md): A API do Financeiro Inteligente usa um access token da Conta Kobana para autenticar todas as requisições. - [Retenção de dados](https://docs.finance.kobana.com.br/pt/api/overview/data-retention.md): Esta página descreve por quanto tempo cada tipo de dado é mantido no Financeiro Inteligente. - [Endpoints](https://docs.finance.kobana.com.br/pt/api/overview/endpoints.md): | Ambiente | Plataforma (acesso web) | API (v1) | - [Erros](https://docs.finance.kobana.com.br/pt/api/overview/errors.md): Toda resposta de erro usa um envelope JSON estável. - [Seleção de campos](https://docs.finance.kobana.com.br/pt/api/overview/fields.md): As leituras de registro — as listagens e os GET de um item — aceitam ?fields= para devolver só as colunas que você vai usar: - [Filtros e ordenação](https://docs.finance.kobana.com.br/pt/api/overview/filtering.md): Os endpoints GET de coleção aceitam filtros e ordenação por query string, além da paginação por cursor. Quais campos são filtráveis e ordenáveis varia por recurso — consulte a especificação OpenAPI de cada endpoint. Aqui está a gramática comum. - [Idempotência](https://docs.finance.kobana.com.br/pt/api/overview/idempotency.md): A API suporta idempotência para repetir solicitações com segurança, sem executar a mesma operação duas vezes. Útil quando uma chamada é interrompida em trânsito e você não recebe resposta — por exemplo, uma requisição para criar uma conta a pagar que cai por erro de rede pode ser repetida com a mesma chave, garantindo que apenas um registro seja criado. - [Introdução](https://docs.finance.kobana.com.br/pt/api/overview/introduction.md): Você que é dev, divirta-se! ✨ - [OpenAPI](https://docs.finance.kobana.com.br/pt/api/overview/openapi.md): A especificação da API do Financeiro Inteligente está disponível em formato OpenAPI 3.1 para importar na ferramenta de sua preferência. - [Listagem e paginação](https://docs.finance.kobana.com.br/pt/api/overview/pagination.md): Todos os endpoints GET que retornam coleções usam paginação por cursor. - [Postman](https://docs.finance.kobana.com.br/pt/api/overview/postman.md): Baixe a coleção no idioma de sua preferência e importe no Postman, ou abra a versão online direto do workspace público da Kobana. - [Limite de requisições](https://docs.finance.kobana.com.br/pt/api/overview/rate-limit.md): Os limites são por janela deslizante de 1 hora — cada requisição conta contra o limite pelos 60 minutos seguintes, não há um "zerar" em horário fixo — e separados em três faixas: leitura (GET), escrita (POST, PUT, PATCH, DELETE) e as ações que movimentam dinheiro, que têm um balde próprio, mais restrito. - [User-Agent](https://docs.finance.kobana.com.br/pt/api/overview/user-agent.md): O cabeçalho User-Agent identifica sua integração. Inclua seu nome e um endereço de e-mail válido para que a equipe da Kobana possa entrar em contato caso: ### aprovar-pagamentos O portão que exige o ok de uma pessoa antes de um título entrar na lista oficial de contas a pagar. - [Aprovar pagamentos](https://docs.finance.kobana.com.br/pt/aprovar-pagamentos.md): O portão que exige o ok de uma pessoa antes de um título entrar na lista oficial de contas a pagar. ### cartoes Cartões de crédito, pré-pagos e de benefício — faturas, limite, parcelas, compras internacionais, assinaturas e o pagamento da fatura. - [Cartões](https://docs.finance.kobana.com.br/pt/cartoes.md): Cartões de crédito, pré-pagos e de benefício — faturas, limite, parcelas, compras internacionais, assinaturas e o pagamento da fatura. #### cadastrar-e-converter Cadastrar um cartão com conta nova, converter uma conta de crédito que já existe, e a prévia das faturas que o formulário calcula enquanto você digita. - [Cadastrar e converter](https://docs.finance.kobana.com.br/pt/cartoes/cadastrar-e-converter.md): Cadastrar um cartão com conta nova, converter uma conta de crédito que já existe, e a prévia das faturas que o formulário calcula enquanto você digita. #### fatura-e-corte A tela do cartão — faturas por mês, o cabeçalho da fatura, os lançamentos, a data de fechamento prevista e a confirmada, e o histórico. - [Fatura e fechamento](https://docs.finance.kobana.com.br/pt/cartoes/fatura-e-corte.md): A tela do cartão — faturas por mês, o cabeçalho da fatura, os lançamentos, a data de fechamento prevista e a confirmada, e o histórico. #### fechar-conferir-pagar O fechamento automático e a conta a pagar da fatura, a conferência com o total do banco, o pagamento integral ou parcial, desfazer, reabrir, a recarga do pré-pago e o cartão no fluxo de caixa. - [Fechar, conferir e pagar](https://docs.finance.kobana.com.br/pt/cartoes/fechar-conferir-pagar.md): O fechamento automático e a conta a pagar da fatura, a conferência com o total do banco, o pagamento integral ou parcial, desfazer, reabrir, a recarga do pré-pago e o cartão no fluxo de caixa. #### lancamentos-e-iof Lançar compras à vista, parceladas e internacionais, estornos, juros e tarifas — em qual fatura cada um cai, o IOF e a cotação, editar uma série, mover e antecipar. - [Lançamentos e IOF](https://docs.finance.kobana.com.br/pt/cartoes/lancamentos-e-iof.md): Lançar compras à vista, parceladas e internacionais, estornos, juros e tarifas — em qual fatura cada um cai, o IOF e a cotação, editar uma série, mover e antecipar. #### recorrencias Assinaturas cobradas no cartão — as cobranças previstas em cada fatura, confirmar com o valor real, não cobrado, a sugestão de atualizar o valor, editar e encerrar. - [Recorrências](https://docs.finance.kobana.com.br/pt/cartoes/recorrencias.md): Assinaturas cobradas no cartão — as cobranças previstas em cada fatura, confirmar com o valor real, não cobrado, a sugestão de atualizar o valor, editar e encerrar. #### relatorios IOF pago nas compras internacionais, por mês, cartão, categoria ou fornecedor, e o previsto × realizado das recorrências — com exportação em CSV e XLSX. - [Relatórios](https://docs.finance.kobana.com.br/pt/cartoes/relatorios.md): IOF pago nas compras internacionais, por mês, cartão, categoria ou fornecedor, e o previsto × realizado das recorrências — com exportação em CSV e XLSX. ### categorias Classificação hierárquica em até três níveis, por receita e despesa. - [Categorias](https://docs.finance.kobana.com.br/pt/categorias.md): Classificação hierárquica em até três níveis, por receita e despesa. ### centros-de-classificacao Alocar custos e receitas a departamentos e projetos — com rateio entre centros. - [Centros de classificação](https://docs.finance.kobana.com.br/pt/centros-de-classificacao.md): Alocar custos e receitas a departamentos e projetos — com rateio entre centros. ### classificadores-personalizados Dimensões de classificação que você cria — como "Região" ou "Produto" — com seus próprios valores. - [Classificadores personalizados](https://docs.finance.kobana.com.br/pt/classificadores-personalizados.md): Dimensões de classificação que você cria — como "Região" ou "Produto" — com seus próprios valores. ### cli #### overview - [Autenticação](https://docs.finance.kobana.com.br/pt/cli/overview/authentication.md): KOBANA_TOKEN guarda a credencial de um produto por vez. Um token do Financeiro Inteligente não autentica em nenhum outro produto Kobana, e vice-versa. - [Variáveis de ambiente](https://docs.finance.kobana.com.br/pt/cli/overview/environment-variables.md): Todas as variáveis também podem ser definidas em um arquivo .env (carregado via dotenvy). - [Códigos de saída](https://docs.finance.kobana.com.br/pt/cli/overview/exit-codes.md): Toda execução do kobana termina com um destes códigos, para que um script decida o que fazer sem precisar interpretar o corpo JSON do erro. - [Instalação](https://docs.finance.kobana.com.br/pt/cli/overview/installation.md): Homebrew (macOS e Linux) - [Introdução](https://docs.finance.kobana.com.br/pt/cli/overview/introduction.md): kobana é uma ferramenta de linha de comando única para as APIs de todos os produtos Kobana — o Financeiro Inteligente incluído. Ela é construída e mantida em repositório próprio (kobana-cli), não por este produto, e não tem endpoint algum escrito à mão: na inicialização ela lê as specs OpenAPI 3.1 embutidas no binário e monta a árvore de comandos a partir delas. Atualizar a superfície da API é questão de atualizar a spec embutida e publicar um build novo — nenhum código por endpoint. #### resources - [Agentes de IA](https://docs.finance.kobana.com.br/pt/cli/resources/ai-agents.md): Instruções que o assistente executa sozinho, com as permissões da pessoa dona do token — por exemplo, um resumo diário das contas a pagar que venceram. A listagem traz só os agentes da pessoa do token no workspace, nunca os de outro membro. Cada execução gasta crédito de IA e vira uma nova conversa do assistente (lastrun.conversationid); uma ação destrutiva espera a confirmação da pessoa no assistente. - [Habilidades de IA](https://docs.finance.kobana.com.br/pt/cli/resources/ai-skills.md): Conjuntos de instruções, no formato Agent Skills, que o assistente carrega quando uma tarefa casa com a description da habilidade — é tudo o que ele lê para decidir. A listagem traz as habilidades que a pessoa do token enxerga no workspace: as dela e as que outros membros compartilharam com ela (is_owner diferencia; mine=true filtra só as próprias). - [Anexos](https://docs.finance.kobana.com.br/pt/cli/resources/attachments.md): Arquivos — nota, contrato, comprovante — enviados ao acervo e ligados a um ou mais títulos. links cria esse vínculo e unlink o desfaz. - [Regras automáticas](https://docs.finance.kobana.com.br/pt/cli/resources/automatic-rules.md): As regras que classificam lançamentos sozinhas, avaliadas na ordem em que estão. reorder é o que muda essa ordem. - [Bancos](https://docs.finance.kobana.com.br/pt/cli/resources/banks.md): A tabela de bancos suportados, para preencher os dados bancários de uma conta ou pessoa. Somente leitura. - [Fluxo de caixa](https://docs.finance.kobana.com.br/pt/cli/resources/cash-flow.md): A projeção consolidada: entradas e saídas realizadas e previstas por período, saldo acumulado e o marco de hoje. Somente leitura — é o resultado de tudo o mais, não uma coleção editável. - [Categorias](https://docs.finance.kobana.com.br/pt/cli/resources/categories.md): O plano de contas: a árvore de receitas e despesas pela qual todo lançamento é classificado. - [Centros de classificação](https://docs.finance.kobana.com.br/pt/cli/resources/classification-centers.md): A segunda dimensão de classificação — centro de custo, projeto, filial —, usada para ratear um mesmo título entre áreas. - [Empresas](https://docs.finance.kobana.com.br/pt/cli/resources/companies.md): As empresas do grupo. Toda conta, título e lançamento pertence a uma delas, e quase todo filtro aceita company_id. - [Classificadores personalizados](https://docs.finance.kobana.com.br/pt/cli/resources/custom-classifiers.md): Dimensões de classificação que a própria empresa define — projeto, contrato, filial — ao lado de categoria e centro de classificação. Cada classificador pertence a uma empresa (filtre com company_id) e traz os seus values[] embutidos; os valores são o que se atribui a contas a pagar, a receber e lançamentos. - [Contas financeiras](https://docs.finance.kobana.com.br/pt/cli/resources/financial-accounts.md): As contas em que o dinheiro entra e sai — conta corrente, caixa, cartão. Todo lançamento, pagamento e recebimento aponta para uma conta financeira, e é o saldo dela que o fluxo de caixa projeta. - [Lançamentos](https://docs.finance.kobana.com.br/pt/cli/resources/financial-transactions.md): O extrato de fato: cada crédito e débito ocorrido em uma conta financeira, classificado por categoria e centro de classificação. O endpoint aggregates devolve totais em vez da lista inteira. - [Notas fiscais](https://docs.finance.kobana.com.br/pt/cli/resources/fiscal-documents.md): As notas fiscais (NF-e e NFS-e) recebidas contra as empresas do workspace — por NFE.io, upload de XML ou SEFAZ. São somente leitura: o produto não emite notas, então não há create nem cancelamento. A listagem vem ordenada pela emissão mais recente. - [Identidade do token](https://docs.finance.kobana.com.br/pt/cli/resources/me.md): Quem está por trás do token: a pessoa (user, nulo num token de integração), a organização e os detalhes do próprio token. Serve para testar se o token configurado vale — é o primeiro comando a rodar depois de definir KOBANA_TOKEN. O token em si nunca volta na resposta. - [Organização](https://docs.finance.kobana.com.br/pt/cli/resources/organization.md): O perfil da organização do token, no topo da hierarquia: vale para todos os workspaces. O recurso é singular — não há list nem id, porque um token sempre alcança uma organização só, a dele. - [Recursos](https://docs.finance.kobana.com.br/pt/cli/resources/overview.md): Todo recurso de finance abaixo é gerado a partir da mesma spec OpenAPI documentada na Referência da API — o CLI chama exatamente os mesmos endpoints, então filtros, validação e comportamento de exclusão são idênticos. Recorra à introspecção de schema sempre que os parâmetros exatos de um comando não estiverem óbvios nos exemplos destas páginas. - [Contas a pagar](https://docs.finance.kobana.com.br/pt/cli/resources/payables.md): As obrigações a vencer e já pagas, com aprovação de pagamento, envio ao banco e rateio por centro de classificação. Contas pendentes de aprovação só aparecem na listagem se você filtrar por paymentapproval=pendingapproval. - [Pessoas](https://docs.finance.kobana.com.br/pt/cli/resources/people.md): Clientes e fornecedores — a contraparte de qualquer título. ids devolve só os identificadores, útil para não encher a janela de contexto de um agente. - [Comprovantes](https://docs.finance.kobana.com.br/pt/cli/resources/receipts.md): Os comprovantes de pagamento gerados pela plataforma. Somente leitura. - [Contas a receber](https://docs.finance.kobana.com.br/pt/cli/resources/receivables.md): O que você tem a receber, com emissão e cancelamento de cobrança pelo Gateway Bancário a partir do próprio título. Para movimentar o dinheiro, o comando é charge — o registro em si fica aqui. - [Conciliações](https://docs.finance.kobana.com.br/pt/cli/resources/reconciliations.md): O vínculo entre um lançamento do extrato e o título que ele liquida. Criar a conciliação baixa o título; excluí-la desfaz a baixa. - [Impostos](https://docs.finance.kobana.com.br/pt/cli/resources/taxes.md): Os tributos retidos ou a recolher vinculados a um título. - [Transferências](https://docs.finance.kobana.com.br/pt/cli/resources/transfers.md): Movimentações entre duas contas financeiras suas. Gera os dois lançamentos — saída e entrada — em uma chamada. #### usage - [Flags globais](https://docs.finance.kobana.com.br/pt/cli/usage/global-flags.md): | Flag | Descrição | - [Helpers](https://docs.finance.kobana.com.br/pt/cli/usage/helpers.md): Helpers são comandos prefixados com + que entregam fluxos de vários passos que os comandos dinâmicos sozinhos não dão: interfaces simplificadas, operações em lote ou chamadas compostas por vários endpoints. Eles não embrulham uma única chamada de API já disponível pelos comandos dinâmicos — cada flag de helper controla lógica de orquestração, não uma versão remodelada de --params/--json. - [Uso](https://docs.finance.kobana.com.br/pt/cli/usage/overview.md): Sintaxe - [Introspecção de schema](https://docs.finance.kobana.com.br/pt/cli/usage/schema.md): Devolve parâmetros, campos obrigatórios, tipos e respostas — tudo derivado da spec OpenAPI embutida, então está sempre em sincronia com o que o comando de fato aceita. O caminho segue a mesma forma do comando: ... ### comprovantes Onde ficam os comprovantes de pagamento — os capturados sozinhos e os que você envia à mão. - [Comprovantes](https://docs.finance.kobana.com.br/pt/comprovantes.md): Onde ficam os comprovantes de pagamento — os capturados sozinhos e os que você envia à mão. ### conciliacao Fechar cada linha do extrato com o título que ela paga, ou lançar o que falta — uma a uma (Manual) ou várias de uma vez (Em lote). - [Conciliação](https://docs.finance.kobana.com.br/pt/conciliacao.md): Fechar cada linha do extrato com o título que ela paga, ou lançar o que falta — uma a uma (Manual) ou várias de uma vez (Em lote). ### contas-a-pagar Compromissos de saída da organização — parcelas, recorrência, tributos e envio ao banco. - [Contas a pagar](https://docs.finance.kobana.com.br/pt/contas-a-pagar.md): Compromissos de saída da organização — parcelas, recorrência, tributos e envio ao banco. #### ciclo-de-vida Estados, transições e o portão de aprovação — Rascunho → Pendente → Pago. - [Ciclo de vida das contas a pagar](https://docs.finance.kobana.com.br/pt/contas-a-pagar/ciclo-de-vida.md): Estados, transições e o portão de aprovação — Rascunho → Pendente → Pago. #### disparo-kobana Enviar contas a pagar aprovadas ao banco pelo Gateway Bancário — pré-requisitos, status e liquidação automática. - [Envio de pagamentos ao banco](https://docs.finance.kobana.com.br/pt/contas-a-pagar/disparo-kobana.md): Enviar contas a pagar aprovadas ao banco pelo Gateway Bancário — pré-requisitos, status e liquidação automática. #### importacao-csv Importar lotes de contas a pagar via planilha — colunas aceitas, formato tolerante e o portão de aprovação. - [Importação CSV — Contas a pagar](https://docs.finance.kobana.com.br/pt/contas-a-pagar/importacao-csv.md): Importar lotes de contas a pagar via planilha — colunas aceitas, formato tolerante e o portão de aprovação. #### operacao-e-pagamento Tipo de operação, documento (boleto, conta de consumo, tributo, PIX), transferência (TED, PIX) ou débito automático, e as coordenadas de pagamento. - [Operação e pagamento](https://docs.finance.kobana.com.br/pt/contas-a-pagar/operacao-e-pagamento.md): Tipo de operação, documento (boleto, conta de consumo, tributo, PIX), transferência (TED, PIX) ou débito automático, e as coordenadas de pagamento. #### parcelas-e-recorrencia Dividir em parcelas ou repetir periodicamente — os três tipos de conta e o comportamento das séries. - [Parcelas e recorrência](https://docs.finance.kobana.com.br/pt/contas-a-pagar/parcelas-e-recorrencia.md): Dividir em parcelas ou repetir periodicamente — os três tipos de conta e o comportamento das séries. #### tributos DARF, DARE, GRU, GPS, FGTS, ICMS, ISS, IPTU e ITBI — como informar a guia e o que vai ao banco. - [Tributos](https://docs.finance.kobana.com.br/pt/contas-a-pagar/tributos.md): DARF, DARE, GRU, GPS, FGTS, ICMS, ISS, IPTU e ITBI — como informar a guia e o que vai ao banco. ### contas-a-receber Compromissos de entrada da organização — parcelas, recorrência e recebimento. - [Contas a receber](https://docs.finance.kobana.com.br/pt/contas-a-receber.md): Compromissos de entrada da organização — parcelas, recorrência e recebimento. #### ciclo-de-vida Estados, transições e recebimento — Rascunho → Pendente → Recebido. - [Ciclo de vida das contas a receber](https://docs.finance.kobana.com.br/pt/contas-a-receber/ciclo-de-vida.md): Estados, transições e recebimento — Rascunho → Pendente → Recebido. #### cobranca-kobana Gerar boleto ou Pix de uma conta a receber pelo Gateway Bancário — pré-requisitos, estados e cancelamento. - [Cobrança por boleto e Pix](https://docs.finance.kobana.com.br/pt/contas-a-receber/cobranca-kobana.md): Gerar boleto ou Pix de uma conta a receber pelo Gateway Bancário — pré-requisitos, estados e cancelamento. #### importacao-csv Importar lotes de contas a receber via planilha — colunas aceitas e formato tolerante. - [Importação CSV — Contas a receber](https://docs.finance.kobana.com.br/pt/contas-a-receber/importacao-csv.md): Importar lotes de contas a receber via planilha — colunas aceitas e formato tolerante. #### parcelas-e-recorrencia Dividir em parcelas ou repetir periodicamente — mesmo comportamento das contas a pagar. - [Parcelas e recorrência — Contas a receber](https://docs.finance.kobana.com.br/pt/contas-a-receber/parcelas-e-recorrencia.md): Dividir em parcelas ou repetir periodicamente — mesmo comportamento das contas a pagar. ### contas-financeiras Contas bancárias e de caixa das empresas — saldo calculado pelos lançamentos. - [Contas financeiras](https://docs.finance.kobana.com.br/pt/contas-financeiras.md): Contas bancárias e de caixa das empresas — saldo calculado pelos lançamentos. ### dashboard A tela inicial — indicadores de desempenho e a projeção do fluxo de caixa. - [Visão geral](https://docs.finance.kobana.com.br/pt/dashboard.md): A tela inicial — indicadores de desempenho e a projeção do fluxo de caixa. ### docs-mcp Esta documentação tem um servidor MCP próprio. Com ele, um assistente de IA - [MCP da Documentação](https://docs.finance.kobana.com.br/pt/docs-mcp.md): Esta documentação tem um servidor MCP próprio. Com ele, um assistente de IA ### empresas As entidades jurídicas (CNPJ) do espaço de trabalho — consulta à Receita, matriz e filial. - [Empresas](https://docs.finance.kobana.com.br/pt/empresas.md): As entidades jurídicas (CNPJ) do espaço de trabalho — consulta à Receita, matriz e filial. ### extratos-bancarios Importar OFX e QIF na conta financeira — deduplicação, histórico e desfazer. - [Extratos bancários](https://docs.finance.kobana.com.br/pt/extratos-bancarios.md): Importar OFX e QIF na conta financeira — deduplicação, histórico e desfazer. ### impostos O catálogo de taxas e tributos vinculáveis a contas a pagar e a receber. - [Impostos](https://docs.finance.kobana.com.br/pt/impostos.md): O catálogo de taxas e tributos vinculáveis a contas a pagar e a receber. ### integracoes Conexões com serviços externos — Gateway Bancário, Open Finance, Fintera e WhatsApp. - [Integrações](https://docs.finance.kobana.com.br/pt/integracoes.md): Conexões com serviços externos — Gateway Bancário, Open Finance, Fintera e WhatsApp. #### fintera Importação de dados financeiros da Fintera — onze recursos, vínculo de empresas e agendamentos. - [Integração Fintera](https://docs.finance.kobana.com.br/pt/integracoes/fintera.md): Importação de dados financeiros da Fintera — onze recursos, vínculo de empresas e agendamentos. #### kobana Envio de pagamentos ao banco e sincronização de contas, extratos e pessoas via Kobana. - [Integração Gateway Bancário (Kobana)](https://docs.finance.kobana.com.br/pt/integracoes/kobana.md): Envio de pagamentos ao banco e sincronização de contas, extratos e pessoas via Kobana. #### open-finance Conecte as contas bancárias da empresa pelo Open Finance e receba saldos e extratos automaticamente. - [Open Finance](https://docs.finance.kobana.com.br/pt/integracoes/open-finance.md): Conecte as contas bancárias da empresa pelo Open Finance e receba saldos e extratos automaticamente. #### whatsapp Fotos de perfil de clientes e fornecedores via Evolution API — configuração por empresa. - [Integração WhatsApp (Evolution API)](https://docs.finance.kobana.com.br/pt/integracoes/whatsapp.md): Fotos de perfil de clientes e fornecedores via Evolution API — configuração por empresa. ### lancamentos As movimentações das contas financeiras — entradas e saídas; a base da conciliação. - [Lançamentos](https://docs.finance.kobana.com.br/pt/lancamentos.md): As movimentações das contas financeiras — entradas e saídas; a base da conciliação. #### importacao-csv Importar lançamentos em lote via planilha — dentro da conta financeira, com cabeçalho em português. - [Importação CSV — Lançamentos](https://docs.finance.kobana.com.br/pt/lancamentos/importacao-csv.md): Importar lançamentos em lote via planilha — dentro da conta financeira, com cabeçalho em português. ### manutencao Ferramentas de higiene dos dados — pessoas (telefones, nomes, duplicados, vazios e fotos) e lançamentos duplicados. - [Manutenção](https://docs.finance.kobana.com.br/pt/manutencao.md): Ferramentas de higiene dos dados — pessoas (telefones, nomes, duplicados, vazios e fotos) e lançamentos duplicados. ### mcp #### overview - [Autenticação](https://docs.finance.kobana.com.br/pt/mcp/overview/authentication.md): O servidor MCP aceita um Bearer token no cabeçalho Authorization, e nada além disso — sem cookie, sem certificado de cliente, sem token na URL. Uma requisição com ?accesstoken= (ou ?token=, ?apikey= e afins) é recusada com 401 e error="invalid_request", mesmo acompanhada de um cabeçalho válido: na URL o token vaza para logs, histórico do navegador e intermediários. - [Clientes](https://docs.finance.kobana.com.br/pt/mcp/overview/clients.md): Qualquer cliente que fale Streamable HTTP MCP e saiba fazer o fluxo OAuth 2.1 do MCP consegue conectar. Você só informa a URL e o cliente descobre sozinho onde autenticar, abre o login da Kobana no navegador e guarda o token. Veja Autenticação. - [Endpoints](https://docs.finance.kobana.com.br/pt/mcp/overview/endpoints.md): Servidor MCP - [Erros](https://docs.finance.kobana.com.br/pt/mcp/overview/errors.md): As falhas chegam por dois canais diferentes, e a distinção importa: um é requisição quebrada, o outro é algo que o modelo deve ler e reagir. - [Idempotência](https://docs.finance.kobana.com.br/pt/mcp/overview/idempotency.md): As tools de criação e alteração aceitam um argumento idempotency_key. Ele é enviado ao endpoint como o cabeçalho X-Idempotency-Key que a API REST já honra — veja Idempotência na API. - [Introdução](https://docs.finance.kobana.com.br/pt/mcp/overview/introduction.md): O servidor MCP do Financeiro Inteligente é um servidor Model Context Protocol remoto que expõe as operações da API pública — contas a pagar e a receber, lançamentos, conciliações, contas financeiras, fluxo de caixa e cadastros — como tools que um cliente de IA pode chamar. Você o conecta por URL; não há nada para instalar. - [Listagem, Filtros e Campos](https://docs.finance.kobana.com.br/pt/mcp/overview/pagination.md): As tools _list usam a mesma paginação da API REST: por cursor*. - [Limite de Requisições](https://docs.finance.kobana.com.br/pt/mcp/overview/rate-limit.md): O servidor MCP gasta os mesmos limites da API REST, contados por pessoa na organização — não por token —, mais um limite próprio para o protocolo. Gerar um token novo, ou reautorizar o cliente, não zera o orçamento. - [Resources e prompts](https://docs.finance.kobana.com.br/pt/mcp/overview/resources-and-prompts.md): Além das tools, o servidor oferece três coisas que o cliente usa por conta própria: resources (documentos que você anexa à conversa), prompts (roteiros prontos que você escolhe) e completions (autocomplete dos argumentos dos dois). Na era 2026-07-28, ele também pede confirmação antes de rodar uma tool destrutiva — inclusive as que movem dinheiro. - [Transporte](https://docs.finance.kobana.com.br/pt/mcp/overview/transport.md): Streamable HTTP, stateless. Uma mensagem JSON-RPC 2.0 por POST, uma resposta JSON. Não há Mcp-Session-Id, não há resumabilidade e não há stream servidor→cliente: a aplicação roda várias réplicas, e nenhuma operação precisa empurrar mensagens para o cliente. #### tools - [Contas financeiras e fluxo de caixa](https://docs.finance.kobana.com.br/pt/mcp/tools/accounts.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Contas a pagar e a receber](https://docs.finance.kobana.com.br/pt/mcp/tools/billings.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Anexos, notas fiscais, schemas e espaços](https://docs.finance.kobana.com.br/pt/mcp/tools/documents.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Tools](https://docs.finance.kobana.com.br/pt/mcp/tools/overview.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Cadastros](https://docs.finance.kobana.com.br/pt/mcp/tools/registers.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Lançamentos e conciliação](https://docs.finance.kobana.com.br/pt/mcp/tools/transactions.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} ### meus-dados Suas informações de conta e como o login sem senha funciona. - [Meu perfil](https://docs.finance.kobana.com.br/pt/meus-dados.md): Suas informações de conta e como o login sem senha funciona. ### notas-fiscais As notas fiscais (NF-e e NFS-e) recebidas contra as empresas do espaço — de onde vêm, como se ligam a uma empresa e como viram contas a pagar. - [Notas fiscais](https://docs.finance.kobana.com.br/pt/notas-fiscais.md): As notas fiscais (NF-e e NFS-e) recebidas contra as empresas do espaço — de onde vêm, como se ligam a uma empresa e como viram contas a pagar. ### pessoas Clientes, fornecedores e contatos — papéis acumuláveis, fotos e exclusão. - [Pessoas](https://docs.finance.kobana.com.br/pt/pessoas.md): Clientes, fornecedores e contatos — papéis acumuláveis, fotos e exclusão. ### regras-automaticas Classificação automática de lançamentos e títulos por critérios que você define. - [Regras automáticas](https://docs.finance.kobana.com.br/pt/regras-automaticas.md): Classificação automática de lançamentos e títulos por critérios que você define. ### sdk Os SDKs são as bibliotecas oficiais para chamar a API REST do Financeiro Inteligente em Node.js / TypeScript, Python, Ruby e PHP, sem montar requisições HTTP, autenticação, paginação e tratamento de erros à mão. - [SDKs do Financeiro Inteligente](https://docs.finance.kobana.com.br/pt/sdk.md): Os SDKs são as bibliotecas oficiais para chamar a API REST do Financeiro Inteligente em Node.js / TypeScript, Python, Ruby e PHP, sem montar requisições HTTP, autenticação, paginação e tratamento de erros à mão. ### seguranca Regras anti-fraude para pagamentos e transferências — limites, contas, favorecidos, tipos de operação e canais, com toda alteração aprovada pela Kobana. - [Segurança](https://docs.finance.kobana.com.br/pt/seguranca.md): Regras anti-fraude para pagamentos e transferências — limites, contas, favorecidos, tipos de operação e canais, com toda alteração aprovada pela Kobana. ### transferencias Mover dinheiro entre contas do espaço de trabalho — dois lançamentos espelhados. - [Transferências](https://docs.finance.kobana.com.br/pt/transferencias.md): Mover dinheiro entre contas do espaço de trabalho — dois lançamentos espelhados. ### workspaces A caixa que isola os dados de cada organização — criação, troca e exclusão. - [Espaços de trabalho](https://docs.finance.kobana.com.br/pt/workspaces.md): A caixa que isola os dados de cada organização — criação, troca e exclusão. --- # Full Documentation Content [Pular para o conteúdo principal](#__docusaurus_skipToContent_fallback) [![Kobana](/pt/img/kobana-logo-hor-positivo.png)![Kobana](/pt/img/kobana-logo-hor-negativo.png)](https://docs.finance.kobana.com.br/pt/pt/.md) [**Financeiro Inteligente**](https://docs.finance.kobana.com.br/pt/pt/.md) Documentação [Documentação](https://docs.finance.kobana.com.br/pt/pt/.md)[API](https://docs.finance.kobana.com.br/pt/pt/api/overview.md)[MCP](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/introduction.md)[CLI](https://docs.finance.kobana.com.br/pt/pt/cli/overview/introduction.md)[SDK](https://docs.finance.kobana.com.br/pt/pt/sdk.md) Perguntar à IA [](#) * [🇧🇷 Português](https://docs.finance.kobana.com.br/pt/pt/search.md) * [🇺🇸 English](https://docs.finance.kobana.com.br/pt/en/search) * [🇪🇸 Español](https://docs.finance.kobana.com.br/pt/es/search) Buscar # Buscar na documentação ![Empresa Neutra em Carbono](/pt/img/badge-neutra-carbono.webp)![Empresa Parceira da Natureza](/pt/img/badge-parceira-natureza.webp) Comercial[3003-0386](tel:+551130030386) [](https://wa.me/551130030386)[](mailto:comercial@kobana.com.br) ![Kobana](/pt/img/kobana-logo-site.webp)![](/pt/img/kobana-cegonha.webp) © 2008/2026 Kobana Tecnologia Ltda. | CNPJ: 05.813.794/0001-26 | Calçada das Margaridas, 163, Sala 02 — Centro Comercial Alphaville — Barueri, SP — 06453-038 --- # Anexos A **Biblioteca de anexos** (`/attachments`) guarda todos os arquivos do espaço de trabalho — vinculados ou não a contas a pagar, contas a receber e lançamentos. ![Biblioteca de anexos](/pt/assets/images/15-attachments-d80312c60eba6df4335e8f4c5f22dd5a.png) ## Duas portas para o mesmo acervo[​](#duas-portas-para-o-mesmo-acervo "Link direto para Duas portas para o mesmo acervo") Anexos aparecem em dois lugares, e a diferença é a direção: * **A biblioteca** (`/attachments`) parte **do arquivo**: você sobe um documento e escolhe a quais registros ele pertence. * **A seção Anexos** — dentro de uma conta a pagar, a receber ou de um lançamento — parte **do registro**: você está num título e escolhe quais arquivos ligar a ele. observação **É o mesmo acervo.** Todo arquivo enviado cai na biblioteca, inclusive os que você sobe de dentro de um formulário. Não existe anexo privado de um registro. O vínculo é **muitos para muitos**: um arquivo pode servir a vários registros, e um registro pode ter vários arquivos. ## Escopo[​](#escopo "Link direto para Escopo") A biblioteca é **do espaço de trabalho inteiro**, não de uma empresa. Ela funciona com o seletor do cabeçalho em "todas as empresas", e um arquivo vinculado a um título de uma empresa continua visível para todo o espaço de trabalho. ## Enviar[​](#enviar "Link direto para Enviar") Clique em **Anexar arquivos** e escolha um arquivo — arraste para a área ou clique nela. | | | | ------------ | ---------------------------------------- | | **Formatos** | pdf, png, jpg, jpeg, xml, ofx, csv, xlsx | | **Tamanho** | até 10 MB | Arquivo acima do limite é recusado ali mesmo: *"Arquivo excede o limite de 10 MB"*. **É um arquivo por vez**, apesar do botão no plural. O sistema também confere se o **conteúdo bate com a extensão** — um arquivo renomeado é recusado. ## A listagem[​](#a-listagem "Link direto para A listagem") Colunas: **Nome** (o título, quando houver, com o nome do arquivo abaixo), **Uso**, **Tamanho**, **Enviado em** e **Enviado por**. Um arquivo já ligado a algum registro mostra a marca **Já anexado** na coluna Uso. * **Busca** por **nome do arquivo ou título** — procura nos dois, então o arquivo é encontrado tanto pelo nome original quanto pelo nome que você deu a ele. * **Abas**: **Todos** e **Já anexado**. Não há filtro inverso (só os não vinculados), nem por tipo, data ou autor. * A listagem vem sempre **do envio mais recente para o mais antigo**, 25 por página. > **Clicar no cabeçalho de uma coluna reordena apenas a página que está na tela**, não a biblioteca inteira. O ícone à direita de cada linha abre uma ficha com **os registros vinculados àquele arquivo**, cada um com link para abrir. Não é uma prévia do arquivo. ## Ações da linha[​](#ações-da-linha "Link direto para Ações da linha") | Ação | O que faz | | -------------- | ---------------------------------------------------------------------------------------------- | | **Visualizar** | Abre o arquivo em nova aba. PDF e imagens abrem no navegador; xml, ofx, csv e xlsx **baixam**. | | **Editar** | Muda o **Título** — o único campo editável | | **Vincular** | Liga (e desliga) o arquivo de registros | | **Excluir** | Remove o arquivo da biblioteca | ### Título[​](#título "Link direto para Título") O único campo que você edita. Se preenchido, aparece no lugar do nome do arquivo nas listagens; em branco, o nome do arquivo volta a valer. Não há descrição, categoria, pastas ou versões, e **não dá para trocar o arquivo** — só o título. ## Vincular[​](#vincular "Link direto para Vincular") **Vincular** abre um diálogo com três abas — **Conta a pagar**, **Conta a receber** e **Lançamento**. Busque pela descrição, marque os registros e confirme. Coisas que valem saber antes: * **A seleção não atravessa abas.** Trocar de aba zera as marcações, então ligar o mesmo arquivo a um título e a um lançamento são duas operações. * **O diálogo mostra os 25 primeiros** de cada aba, sem paginação. Para além disso, use a busca. * Registros **já vinculados** sobem para o topo, já marcados e travados. **Desvincular também mora aqui**: cada linha já vinculada tem um botão para desfazer. Não há confirmação nesse caminho — a ação é imediata. ## Excluir[​](#excluir "Link direto para Excluir") observação **Um arquivo vinculado não pode ser excluído.** O sistema recusa e diz a quantos registros ele está ligado: *"Anexo vinculado a 2 contas a pagar, 1 conta a receber e 0 lançamentos."* Desvincule de todos antes. **Um comprovante de pagamento também segura o arquivo dele.** Aí não existe desvincular: o dono do arquivo é o comprovante, e a mensagem é outra — *"Anexo é o documento de um comprovante — exclua o comprovante para remover o arquivo"*. Ver [Comprovantes](https://docs.finance.kobana.com.br/pt/pt/comprovantes/.md). Não há cascata: excluir nunca apaga os registros, e nunca desfaz vínculos por conta própria. O diálogo avisa: *"O arquivo será removido permanentemente. Se estiver vinculado a algum registro, desvincule antes."* A ação aparece em qualquer linha, inclusive nas que estão vinculadas — nesses casos você só descobre o bloqueio depois de confirmar. ## Anexar de dentro de um registro[​](#anexar-de-dentro-de-um-registro "Link direto para Anexar de dentro de um registro") Na seção **Anexos** de uma conta ou lançamento, o botão **Anexar Arquivo** abre um diálogo com dois caminhos lado a lado: * **Escolher no computador** — envia agora. Aqui o envio dispara **assim que você escolhe o arquivo**, sem botão de confirmar. * **Escolher na biblioteca** — pega um arquivo que já existe. Mostra 5 por página, sem busca; os já anexados aparecem marcados. O rodapé traz **Ir para biblioteca de anexos**, que leva a `/attachments`. Nessa seção, **Desvincular** pede confirmação e explica: *"O arquivo continua na biblioteca e em outros registros vinculados."* observação **Numa conta ainda não salva, depende de como o arquivo entrou.** Se você **enviou o arquivo ali mesmo** e mudou de ideia, Desvincular o apaga da biblioteca também — o envio inteiro é desfeito, que é o que se espera de uma criação abandonada. Se você **pegou da biblioteca**, Desvincular só o solta do rascunho: o arquivo era da biblioteca antes de você começar e continua lá. --- # Referência da API --- # Visão geral --- # Autenticação A API do Financeiro Inteligente usa um **access token da Conta Kobana** para autenticar todas as requisições. ## O token[​](#o-token "Link direto para O token") O token é um JWT `RS256` emitido pelo **Authorization Server da Kobana** (`account.kobana.com.br`). Esta API apenas o **verifica**, contra a chave pública que aquele servidor publica — ela não guarda chave de assinatura e não consegue emitir token nenhum. Requisitos conferidos a cada requisição: | Claim | Exigência | | ----- | ------------------------------------------------------------------------------------------------------------------------ | | `iss` | O identificador do Authorization Server, como URL: `https://account[.{env}].kobana.com.br` | | `aud` | A URL desta API: `https://api.finance[.{env}].kobana.com.br`. Pode ser uma **lista** — a regra é *contém*, não igualdade | | `exp` | **Obrigatória.** Token sem expiração é recusado | | `org` | **A conta Kobana** em cujo nome o token age. É ela que resolve a organização aqui, e é **obrigatória** | | `sub` | **A pessoa** (`users.public_id`). Vai para auditoria e atribuição; não escopa nada | | `jti` | Id único do token — base da revogação e da auditoria | O **workspace** vem do header `X-Workspace-Id`: o `org` diz a organização, e uma organização pode ter vários workspaces. Ele é **seletor, não concessão** — um workspace de outra organização não é alcançável adivinhando o id. Sem o header, quando há mais de um workspace, a resposta é `400 WORKSPACE_REQUIRED`. As exceções são `GET /v1/me` e `GET`/`PATCH /v1/organization`: são de **nível de organização** — respondem pela organização do token, valem para todos os workspaces — e não levam o header. :::caution Mudança em relação ao token gerado no dashboard Antes a credencial era um token gerado na plataforma, com secret exibido uma única vez. O mesmo valor assinava e verificava, então um vazamento em qualquer um dos dois lados era vazamento da **emissão**. Agora quem emite é o Authorization Server, e esta API só verifica. ::: Se o Authorization Server estiver inalcançável, a resposta é **`5xx`, nunca `401`** — um `401` aí mandaria você depurar uma credencial boa durante uma indisponibilidade nossa. ## Como enviar o token[​](#como-enviar-o-token "Link direto para Como enviar o token") Inclua o cabeçalho `Authorization: Bearer ` em cada requisição. ``` export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx curl -i \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'Content-Type: application/json' \ -H 'User-Agent: Meu Sistema (contato@minhaempresa.com.br)' \ -X GET 'https://api.finance.kobana.com.br/v1/financial-accounts' ``` ## Escopos[​](#escopos "Link direto para Escopos") Os escopos têm **dois eixos**: o **recurso**, sempre prefixado pelo app (`finance/payables`), e o **nível de acesso**, um escopo global sem prefixo — `read`, `write`, `delete`, `import` ou `export`. Toda requisição exige **um** nível, dado pelo método HTTP, sobre **o recurso** que o endpoint nomeia; cada operação da referência declara o par na frase "Requires scope `finance/` with access level ``". | Método | Nível exigido | | ---------------------- | --------------------------------------------------------------- | | `GET` | nenhum — o escopo do recurso sozinho lê | | `POST`, `PUT`, `PATCH` | `write` — enviar pagamento ao banco e emitir cobrança inclusive | | `DELETE` | `delete` — **`write` não exclui** | Um nível não substitui o outro: `write` não exclui, e `delete` não lê nem escreve. Um nível também pode valer só num recurso, na forma `finance/:` (`finance/payables:delete`); só os escopos com o prefixo `finance/` contam. `import` e `export` são para endpoints de importação e exportação em lote — esta API não tem nenhum hoje. Toda exclusão é um `DELETE`, e todo `DELETE` é uma exclusão. | Recurso | Escopo | O que a leitura cobre | | ------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Contas financeiras | `finance/accounts` | contas e saldos | | Catálogo de bancos | `finance/banks` | só leitura, não há escrita | | Contas a pagar | `finance/payables` | títulos a pagar | | Contas a receber | `finance/receivables` | títulos a receber | | Envio ao banco | `finance/payable_dispatches` | os envios de pagamento e seu estado | | Emissão de cobrança | `finance/receivable_charges` | as cobranças (boleto/Pix) emitidas | | Comprovantes de pagamento | `finance/receipts` | só leitura | | Notas fiscais recebidas | `finance/fiscal_documents` | só leitura | | Transações | `finance/transactions` | lançamentos e transferências | | Conciliações | `finance/reconciliations` | conciliações (a escrita cobre criar e dissolver) | | Fluxo de caixa projetado | `finance/cash_flow` | só leitura | | Empresas | `finance/companies` | | | Pessoas | `finance/people` | | | Categorias | `finance/categories` | | | Centros de classificação | `finance/cost_centers` | o escopo nomeia o grant, por isso `cost_centers` e não `classification-centers` como na URL | | Regras automáticas | `finance/automatic_rules` | a escrita inclui reordenar | | Impostos | `finance/taxes` | | | Anexos | `finance/attachments` | a escrita cobre upload e gerenciamento | | Organização | `finance/settings` | o perfil da organização do token (`/organization`); a escrita exige o dono da organização ou acesso a todos os espaços | | **Coringa do recurso** | `finance/all` | lê **todos** os recursos acima — e **não concede verbo nenhum** | Dois exemplos: `finance/payables read` lê títulos a pagar e não escreve; `finance/payables read write delete` também cria, altera e apaga, e continua sem alcançar contas a receber. A forma granular `finance/payables:write` é **exceção** da gramática, não o formato padrão: ela satisfaz os dois eixos para aquele recurso só, e existe para "lê um recurso, escreve outro". `finance/*` é curinga de **cadastro** e nunca é emitido num token — a comparação aqui é sempre literal. Na gramática por recurso, leitura é o recurso sem verbo; o `read` que existe é o **nível de acesso** da Conta Kobana, abaixo. Regras de resolução: * `finance/all` alcança **todos** os recursos, mas não concede nível nenhum. `finance/all read` lê tudo; para escrever é preciso o nível: `finance/all write`. * `finance/receipts` lista os comprovantes, mas **não baixa o documento**: o `download_url` aponta para o recurso de anexos, então buscar os bytes exige também `finance/attachments`. * `finance/fiscal_documents` lista as notas recebidas, mas **não baixa o XML**: o `xml_download_url` aponta para o recurso de anexos, então buscar os bytes exige também `finance/attachments`. aviso **Mover dinheiro é recurso próprio, não nível próprio.** Enviar um pagamento ao banco (e cancelar o envio) e emitir uma cobrança (e cancelá-la) são `write` em recursos separados: `finance/payable_dispatches` e `finance/receivable_charges`. Um token com `finance/payables write` grava título e **não** dispara pagamento. `finance/all write` (ou `all write`) alcança os dois, porque o coringa cobre todo recurso. Um token só com o nível `write`, sem escopo por recurso, não alcança nada. ### Nível de acesso[​](#nível-de-acesso "Link direto para Nível de acesso") O escopo **é cobrado em toda rota** (só `GET /me` dispensa, para você testar um token). Os escopos por recurso acima estão cadastrados na Conta Kobana, e o token pessoal os carrega conforme os recursos que você marcou. Todo token traz também o **nível de acesso** que você concedeu ao autorizar, e ele só vale dentro do alcance dos escopos de recurso (`finance/…` ou `all`). **Um token sem escopo de recurso deste app — só com níveis (`read write`) ou só com recursos de outro app (`billing/invoices write`) — não alcança nada**; só o `GET /me` o atende. Dentro do alcance: | Nível | O que alcança | | ------------------- | ------------------------------------------------------------------------------------------------------------- | | `read` | leitura (`GET`) — o escopo do recurso sozinho já lê | | `write` | toda escrita (`POST`, `PUT`, `PATCH`), inclusive enviar pagamento ao banco e emitir cobrança — **não exclui** | | `delete` | `DELETE`, e só ele | | `import` / `export` | importação / exportação em lote (nenhum endpoint hoje) | **`all` não é nível de acesso.** É o coringa de recurso, igual a `finance/all`: alcança todo recurso e não concede verbo nenhum. `all` sozinho lê tudo; `all write` lê e escreve tudo; excluir, importar e exportar exigem o verbo explícito (`all delete`). **Quando o token traz escopos por recurso** — o token pessoal que você cria na Conta Kobana, por exemplo —, **são eles que definem o alcance**, e os níveis só valem dentro desses recursos: `finance/payables read write` lê e escreve contas a pagar e nada mais; `finance/all read` (ou só `all`) lê tudo e não escreve nada. Faltando qualquer um dos dois eixos, a resposta é `403 INSUFFICIENT_SCOPE`, com `required` (o conjunto mínimo de escopos a acrescentar — o recurso primeiro, depois o verbo: `["finance/payables", "delete"]`), `access` (o verbo da requisição) e `granted` em `details`. Um token sem nenhum escopo de recurso que esta API reconheça não alcança nada. :::caution Mudanças que quebram compatibilidade * Os escopos antigos `finance.`, `finance..write`, `finance.all`, `finance.all.write` e os sufixos `.dispatch` / `.charge` **não são mais aceitos**: use `finance/` e os níveis de acesso. * Um `DELETE` exige `delete`: `write` não exclui mais. * Um token só com níveis de acesso, sem escopo `finance/…` nem `all`, não alcança mais nada (antes alcançava todo recurso). Peça os recursos junto, ou `all`. * `all` não concede mais verbo nenhum: é o coringa de recurso, como `finance/all`. Um token só com `all` passa a só ler; para escrever, excluir, importar ou exportar, peça o verbo junto (`all write delete`). * Enviar ao banco e emitir cobrança exigem `write` (no recurso de dinheiro, quando o token traz escopos por recurso); `all` não é mais exigido. * Desvincular um anexo passou de `DELETE /v1/attachments/{id}/links` para `POST /v1/attachments/{id}/unlink`, com o mesmo corpo `{ type, id }`. * O `details` do `403 INSUFFICIENT_SCOPE` traz `required` como lista: o conjunto mínimo de escopos que falta (ex. `["finance/payables", "delete"]`), nunca vazio; `accepted_levels` saiu. ::: ## Boas práticas[​](#boas-práticas "Link direto para Boas práticas") * **Nunca** versione tokens em git. Use variáveis de ambiente ou cofres (AWS Secrets Manager, Vault, etc.). * Use tokens distintos por integração — facilita rotacionar/revogar sem derrubar tudo. * Peça os escopos mínimos necessários (princípio do menor privilégio) — `read` quando a integração só lê, `delete` só para quem apaga, e o recurso de dinheiro (`finance/payable_dispatches`, `finance/receivable_charges`) só para quem envia ao banco ou cobra. * Revogue imediatamente qualquer token vazado. * Aponte sempre para `https://` — chamadas na porta 80 são redirecionadas para 443, mas clientes não reenviam o corpo num redirect. --- # Retenção de dados Esta página descreve por quanto tempo cada tipo de dado é mantido no Financeiro Inteligente. ## Workspaces ativos[​](#workspaces-ativos "Link direto para Workspaces ativos") | Tipo de dado | Retenção | | ------------------------------------- | --------------- | | Logs de Requisições da API | 30 dias | | Transações | Indefinidamente | | Contas a Pagar | Indefinidamente | | Contas a Receber | Indefinidamente | | Contas Financeiras | Indefinidamente | | Empresas e Pessoas | Indefinidamente | | Categorias e Centros de Classificação | Indefinidamente | | Anexos | Indefinidamente | | Qualquer dado não listado | Indefinidamente | ## Workspaces inativos[​](#workspaces-inativos "Link direto para Workspaces inativos") Workspaces sem acesso por período prolongado podem ter dados arquivados. Entre em contato com o suporte para restauração. Os tempos acima podem ser alterados a qualquer momento. --- # Endpoints | Ambiente | Plataforma (acesso web) | API (v1) | | ------------ | ------------------------------------------------------------------------------ | ---------------------------------------------- | | **Produção** | [app.finance.kobana.com.br](https://app.finance.kobana.com.br) | `https://api.finance.kobana.com.br/v1` | | **Sandbox** | [app.finance.sandbox.kobana.com.br](https://app.finance.sandbox.kobana.com.br) | `https://api.finance.sandbox.kobana.com.br/v1` | Esta documentação está publicada em [docs.finance.kobana.com.br](https://docs.finance.kobana.com.br). dica Desenvolva contra o **sandbox** e troque para produção apenas mudando a base URL — os contratos são os mesmos. --- # Erros Toda resposta de erro usa um envelope JSON estável. aviso **Ramifique sua lógica pelo `code`, nunca pelo texto de `message`** — a mensagem é legível por humanos e pode mudar; o `code` é contrato. ## Envelope[​](#envelope "Link direto para Envelope") ``` { "error": { "code": "VALIDATION_ERROR", "message": "Request body validation failed.", "details": { "issues": [ { "path": "amount", "code": "invalid_type", "message": "Expected number, received string" } ] } } } ``` | Campo | Descrição | | --------------- | ------------------------------------------------------------------------------------------------------------------ | | `error.code` | Código estável (tabela abaixo). Ramifique por ele. | | `error.message` | Texto legível, em inglês. **Não parseie.** | | `error.details` | Presente em alguns erros — dados estruturados úteis (campo ofensor, motivo, escopo faltante). Ver exemplos abaixo. | ## Códigos[​](#códigos "Link direto para Códigos") | `code` | HTTP | Quando | | ------------------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `BAD_REQUEST` | 400 | Query/body malformado — JSON inválido, filtro/operador desconhecido, cursor inválido, valor de filtro vazio, `limit` inválido. | | `INVALID_TOKEN` | 401 | Token ausente, malformado, assinatura inválida ou expirado. | | `INVALID_AUDIENCE` | 401 | A `aud` do token não é aceita. | | `TOKEN_REVOKED` | 401 | Token revogado. | | `INSUFFICIENT_SCOPE` | 403 | Token válido, mas sem o escopo exigido. `details.required` é o conjunto mínimo de escopos a acrescentar ao token para a requisição passar — o escopo do recurso primeiro (`finance/`, ou `finance/all` fora do catálogo), depois o verbo; nunca vazio, nunca `all`. `details` traz também `access` e `granted`. | | `UNKNOWN_ORGANIZATION` | 403 | O `sub` do token não corresponde a nenhum workspace. | | `NOT_FOUND` | 404 | Recurso inexistente **ou fora do seu workspace** — por isolamento, um recurso de outro tenant lê como `404`. | | `CONFLICT` | 409 | Conflito de estado: requisição idêntica ainda em andamento, ou corrida em uma constraint única. | | `IDEMPOTENCY_KEY_REUSED` | 409 | `X-Idempotency-Key` reusada com um corpo diferente. Reenvie os parâmetros originais ou gere uma chave nova. | | `VALIDATION_ERROR` | 422 | O corpo não satisfaz o schema — campo ausente, tipo errado, chave desconhecida. `details.issues` diz onde. Reenviar o mesmo corpo não adianta. | | `UNPROCESSABLE_ENTITY` | 422 | Corpo bem-formado que o domínio recusou — FK fora do tenant, transição de estado inválida. Pode passar quando o estado mudar. | | `RATE_LIMITED` | 429 | Limite de requisições atingido. Ver [Limite de Requisições](https://docs.finance.kobana.com.br/pt/pt/api/overview/rate-limit.md). | | `INTERNAL_ERROR` | 500 | Falha inesperada no servidor. **Nunca** carrega `details`. Reenvie com backoff. | ## Exemplos de `details`[​](#exemplos-de-details "Link direto para exemplos-de-details") **Validação de schema (422):** ``` { "error": { "code": "VALIDATION_ERROR", "message": "Request body validation failed.", "details": { "issues": [ { "path": "amount", "code": "invalid_type", "message": "Expected number, received string" } ] } } } ``` **Escopo insuficiente (403):** ``` { "error": { "code": "INSUFFICIENT_SCOPE", "message": "Token is missing required scope: `finance/payable_dispatches`, to change payable_dispatches.", "details": { "required": ["finance/payable_dispatches"], "access": "write", "granted": ["finance/payables", "read", "write"] } } } ``` **Idempotency-Key reusada com corpo diferente (409):** ``` { "error": { "code": "IDEMPOTENCY_KEY_REUSED", "message": "X-Idempotency-Key was already used with different request parameters. Reuse the original parameters or generate a new key." } } ``` --- # Seleção de campos As leituras de registro — as listagens e os `GET` de um item — aceitam `?fields=` para devolver só as colunas que você vai usar: ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: Meu Sistema (contato@example.com)' \ -H "X-Workspace-Id: $WORKSPACE_ID" \ 'https://api.finance.kobana.com.br/v1/payables?status=pending&fields=description,amount,due_date' ``` ``` { "data": [ { "id": "8c8b4c4f-…", "description": "Aluguel", "amount": 1500.5, "due_date": "2026-11-10T00:00:00.000Z" } ], "meta": { "next_cursor": null } } ``` Regras: * Nomes separados por vírgula, em snake\_case — os mesmos que a resposta completa traz. * Sem o parâmetro (ou com ele vazio), voltam **todos** os campos. * O **`id` sempre volta**, mesmo que não seja pedido. * Só o **primeiro nível**: pedir um campo que é objeto (`reconciliation`, `classification_centers`) devolve o objeto inteiro. Não há sintaxe `objeto.campo`. * Um nome que o recurso não tem → `400 BAD_REQUEST`, com `details.unknown` (o que não foi reconhecido) e `details.available` (o que existe). Um nome errado nunca é ignorado em silêncio. * O `meta` da listagem não é afetado — o `next_cursor` continua lá. * Combina com [filtros, ordenação](https://docs.finance.kobana.com.br/pt/pt/api/overview/filtering.md) e [paginação](https://docs.finance.kobana.com.br/pt/pt/api/overview/pagination.md). Não se aplica a escritas (que devolvem o registro inteiro), aos totais (`/aggregates`, `/cash-flow`), à varredura de ids (`/ids`) nem ao download de anexo — nesses o parâmetro é recusado com `400`. --- # Filtros e ordenação Os endpoints `GET` de coleção aceitam filtros e ordenação por query string, além da [paginação por cursor](https://docs.finance.kobana.com.br/pt/pt/api/overview/pagination.md). **Quais campos são filtráveis e ordenáveis varia por recurso** — consulte a [especificação OpenAPI](https://docs.finance.kobana.com.br/pt/pt/api/overview/openapi.md) de cada endpoint. Aqui está a **gramática** comum. ## Filtros[​](#filtros "Link direto para Filtros") Sintaxe: `?campo=valor` (igualdade) ou `?campo[operador]=valor`. | Operador | Sintaxe | Significado | | ---------------- | ------------------------------------ | ------------------------------------ | | `eq` (implícito) | `?status=paid` ou `?status[eq]=paid` | Igual a | | `in` | `?status[in]=pending,paid` | Está em (lista separada por vírgula) | | `gte` | `?due_date[gte]=2026-01-01` | Maior ou igual | | `lte` | `?due_date[lte]=2026-01-31` | Menor ou igual | | `gt` | `?amount[gt]=100.00` | Maior que | | `lt` | `?amount[lt]=100.00` | Menor que | | `not` | `?status[not]=cancelled` | Diferente de | Regras: * Cada recurso permite um **subconjunto** de campos e operadores; um campo ou operador fora da allowlist → `400 bad_request`. * `eq` é sempre permitido quando o campo é filtrável. * Valor vazio (`?campo=` ou `?campo[in]=`) → `400`. Omita o parâmetro para não filtrar. * Vários filtros combinam com **E** lógico. ## Ordenação[​](#ordenação "Link direto para Ordenação") `?sort_by=campo` escolhe o campo e `?sort_order=asc|desc` a direção (padrão `asc`). Um único campo por vez; um campo fora da allowlist → `400`, e `sort_order` sem `sort_by` também. ## Exemplo[​](#exemplo "Link direto para Exemplo") ``` # Contas a pagar de uma empresa, vencendo em janeiro, mais recentes primeiro curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: Meu Sistema (contato@example.com)' \ 'https://api.finance.kobana.com.br/v1/payables?company_id=00000000-0000-0000-0000-000000000001&due_date[gte]=2026-01-01&due_date[lte]=2026-01-31&sort_by=due_date&sort_order=desc&limit=100' ``` ## Combinando com paginação[​](#combinando-com-paginação "Link direto para Combinando com paginação") Filtros e ordenação valem entre páginas — passe o `cursor` da resposta anterior junto dos **mesmos** filtros. Ver [Listagem e Paginação](https://docs.finance.kobana.com.br/pt/pt/api/overview/pagination.md). --- # Idempotência A API suporta idempotência para repetir solicitações com segurança, sem executar a mesma operação duas vezes. Útil quando uma chamada é interrompida em trânsito e você não recebe resposta — por exemplo, uma requisição para criar uma conta a pagar que cai por erro de rede pode ser repetida com a mesma chave, garantindo que apenas um registro seja criado. ## Como usar[​](#como-usar "Link direto para Como usar") Envie o cabeçalho `X-Idempotency-Key: ` em qualquer requisição `POST`, `PUT` ou `PATCH`. A chave é livre, gerada pelo seu lado. Recomendamos `UUID v4` ou outra string aleatória com entropia suficiente para evitar colisões. Nas **ações de dinheiro** o cabeçalho é **obrigatório**: enviar ao banco, cancelar envio, emitir cobrança e cancelar cobrança respondem `400 bad_request` (`details.reason = "idempotency_key_required"`) sem ele. ``` curl -i \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: 8c0f5d6e-3f8b-4cb5-9a47-d8f5b15e9b21' \ -H 'User-Agent: Meu Sistema (contato@example.com)' \ -d '{ "account_id": "00000000-0000-0000-0000-000000000001", "description": "Aluguel Janeiro/2026", "amount": 3500.0, "due_date": "2026-01-10" }' \ -X POST 'https://api.finance.kobana.com.br/v1/payables' ``` ## Como funciona[​](#como-funciona "Link direto para Como funciona") Quando o servidor recebe uma requisição com `X-Idempotency-Key`: 1. **Reserva a chave** atomicamente, escopada ao **workspace**. Dois workspaces diferentes podem usar a mesma chave sem conflito. 2. **Calcula a impressão digital da requisição** — SHA-256 de `método + caminho + corpo bruto`. Esse hash é guardado junto com a chave. 3. **Executa o handler**. Se ele retornar uma resposta, o servidor grava `status_code`, corpo e cabeçalhos relevantes vinculados à chave. 4. **Marca a chave como completa**. Qualquer nova requisição com a mesma chave dentro de **24 horas** recebe a resposta original verbatim — mesmo `status_code`, mesmo corpo, mesmos cabeçalhos — acrescida do cabeçalho `X-Idempotent-Replay: true` para indicar que se trata de uma reexecução. aviso A camada salva o resultado **independentemente de ter sido sucesso ou falha**. Retries com a mesma chave retornam o mesmo resultado, **incluindo erros `5xx`** — para tentar de novo de verdade depois de um erro do servidor, gere uma chave nova. ### Limites[​](#limites "Link direto para Limites") * Tamanho máximo da chave: **255 caracteres**. * Retenção: chaves expiram automaticamente **24 horas** após a criação. * Escopo: por workspace. Uma chave usada em um workspace não interfere em outro. * Caracteres aceitos: qualquer string UTF-8 imprimível. ## Conflitos[​](#conflitos "Link direto para Conflitos") Se a mesma chave for reutilizada com uma requisição diferente (qualquer mudança em método, caminho ou corpo), a API responde `409` com o código `IDEMPOTENCY_KEY_REUSED`. ``` { "error": { "code": "IDEMPOTENCY_KEY_REUSED", "message": "X-Idempotency-Key was already used with different request parameters. Reuse the original parameters or generate a new key." } } ``` ## Métodos aceitos[​](#métodos-aceitos "Link direto para Métodos aceitos") | Método | Aceita `X-Idempotency-Key`? | | -------- | --------------------------------------- | | `POST` | ✅ Sim | | `PUT` | ✅ Sim | | `PATCH` | ✅ Sim | | `GET` | ❌ Não (já é idempotente por definição) | | `DELETE` | ❌ Não (já é idempotente por definição) | ## Boas práticas[​](#boas-práticas "Link direto para Boas práticas") * **Uma chave por operação lógica**. Não reutilize a mesma chave para criar dois recursos diferentes — você receberá `409 IDEMPOTENCY_KEY_REUSED`. * **Persista a chave junto com o estado da operação** no seu lado, para que o retry depois de crash ou reinício use a mesma chave. * **Combine com backoff exponencial** ao receber `5xx` ou timeout. * **Limpe a chave depois de 24 horas**. Não há ganho em mantê-la no seu lado após esse prazo. --- # Introdução Você que é dev, divirta-se! ✨ A API do Financeiro Inteligente é **REST sobre HTTPS, com JSON e autenticação Bearer**. Tudo o que as telas fazem com contas a pagar, contas a receber, lançamentos, cadastros e conciliações está disponível para os seus sistemas — no mesmo isolamento por espaço de trabalho do produto. ## Primeiros passos[​](#primeiros-passos "Link direto para Primeiros passos") 1. **Gere um token** na plataforma, em **Integrações → Token de API** — ver [Autenticação](https://docs.finance.kobana.com.br/pt/pt/api/overview/authentication.md). 2. **Faça a primeira chamada**: ``` export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: Meu Sistema (contato@minhaempresa.com.br)' \ 'https://api.finance.kobana.com.br/v1/financial-accounts' ``` 3. **Explore os recursos** — a categoria **Recursos**, na barra lateral, documenta cada endpoint com exemplos. Ou importe a [especificação OpenAPI](https://docs.finance.kobana.com.br/pt/pt/api/overview/openapi.md) / a [coleção do Postman](https://docs.finance.kobana.com.br/pt/pt/api/overview/postman.md). dica Prefira o **sandbox** (`https://api.finance.sandbox.kobana.com.br/v1`) para desenvolver — ver [Endpoints](https://docs.finance.kobana.com.br/pt/pt/api/overview/endpoints.md). ## Formato[​](#formato "Link direto para Formato") A API aceita apenas o formato `JSON`. Todas as requisições devem usar `Content-Type: application/json`. Todas as respostas usam `snake_case`. | Tipo de campo | Formato | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **DateTime** | Formato [ISO8601](https://pt.wikipedia.org/wiki/ISO_8601). Exemplos — Data: `2026-01-24`. Data e Hora: `2026-01-24T10:07Z` | | **Money** | **String decimal** com 2 casas e ponto como separador, em BRL. Ex.: `"100.00"`. Sempre enviado/recebido como string (nunca número), para preservar a precisão dos centavos; até 13 dígitos inteiros. Lançamentos e títulos são sempre positivos — a direção (débito/crédito, custo/receita) vai em `type`/polaridade, nunca no sinal. Saldos de conta podem ser negativos | | **UUID** | Identificadores de recursos no formato UUID v4 | ## Convenções[​](#convenções "Link direto para Convenções") Convenções usadas nesta documentação: | Convenção | Descrição | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`:variable`** | Nome de variável que precisa ser substituída em uma URL. | | **`#{variable}`** | Nome de variável que precisa ser substituída por valores da sua conta. | | **`...`** | Conteúdo da resposta truncado para facilitar a leitura. | | **`$KOBANA_TOKEN`** | Token de acesso. Para testes em linha de comando, exporte-o: `export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx` e cole os comandos da documentação no terminal. | ## Códigos de retorno[​](#códigos-de-retorno "Link direto para Códigos de retorno") A API retorna códigos HTTP padrão: | | Código | Descrição | | -- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | ✅ | **200 OK** | Requisição bem-sucedida. Toda resposta de sucesso traz corpo, inclusive `DELETE`: `{ "data": { "id": "…", "deleted": true } }`. | | ✅ | **201 Created** | Recurso criado com sucesso. | | ❌ | **400 Bad Request** | Requisição inválida, em geral conteúdo mal formado. | | ❌ | **401 Unauthorized** | Token de acesso ausente ou inválido. | | ❌ | **403 Forbidden** | Acesso à API bloqueado ou usuário sem permissão. | | ❌ | **404 Not Found** | Endereço acessado não existe. | | ❌ | **409 Conflict** | Conflito com o estado atual do recurso — p.ex. reuso de `X-Idempotency-Key` com outro corpo. | | ❌ | **422 Unprocessable Entity** | Requisição válida, mas os dados enviados não são. | | ❌ | **429 Too Many Requests** | Limite de requisições atingido. | | ❌ | **500 Internal Server Error** | Erro interno no processamento. Consulte o [status dos servidores](https://status.kobana.com.br). | O envelope e o vocabulário estável de códigos de erro estão em [Erros](https://docs.finance.kobana.com.br/pt/pt/api/overview/errors.md). ## ID das requisições (Request-Id)[​](#id-das-requisições-request-id "Link direto para ID das requisições (Request-Id)") Cada requisição possui um identificador associado, disponível no cabeçalho `Request-Id` da resposta. Esse valor ajuda na depuração e auditoria — as requisições e seus IDs podem ser consultadas no painel do sistema. O log de requisições fica disponível por **30 dias**. Ao abrir um chamado de suporte sobre uma requisição específica, informe o `Request-Id` para acelerar a investigação. ## Segurança[​](#segurança "Link direto para Segurança") A API do Financeiro Inteligente usa certificados **SSL 2048 bits**. Toda requisição deve ser feita via **HTTPS** — chamadas na porta 80 são redirecionadas para 443. Os clientes devem suportar `TLSv1.2` ou `TLSv1.3` com uma das cifras: `TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES128-SHA256`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-RSA-CHACHA20-POLY1305`, `ECDHE-RSA-AES256-SHA384`. `TLSv1` e `TLSv1.1` não são suportados. ## Cache HTTP[​](#cache-http "Link direto para Cache HTTP") Use os cabeçalhos HTTP de cache para reduzir carga e ganhar velocidade. A maioria das respostas inclui `ETag` e/ou `Last-Modified` — armazene esses valores e reenvie nas próximas requisições via `If-None-Match` e `If-Modified-Since`. Se o recurso não mudou, a resposta será `304 Not Modified`, sem corpo e sem reprocessamento. Mais informações: [HTTP Cache Docs](http://www.mnot.net/cache_docs/). ## Tratamento de erros[​](#tratamento-de-erros "Link direto para Tratamento de erros") Erros 5xx indicam falhas no servidor: **500 Internal Server Error** (aplicação indisponível), **502 Bad Gateway**, **503 Service Unavailable** e **504 Gateway Timeout** (falhas pontuais de infraestrutura). Sua aplicação deve identificar esses códigos e reagendar a requisição após alguns minutos com backoff. Status dos servidores: . ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Especificações](https://docs.finance.kobana.com.br/pt/pt/api/overview/openapi.md) — OpenAPI 3.1 em YAML para download. * [Endpoints](https://docs.finance.kobana.com.br/pt/pt/api/overview/endpoints.md) — URLs de produção e sandbox. * [User-Agent](https://docs.finance.kobana.com.br/pt/pt/api/overview/user-agent.md) — cabeçalho para identificar sua aplicação. * [Limite de requisições](https://docs.finance.kobana.com.br/pt/pt/api/overview/rate-limit.md) — throttling e headers de resposta. * [Listagem e paginação](https://docs.finance.kobana.com.br/pt/pt/api/overview/pagination.md) — cursor e envelope das coleções. * [Filtros e ordenação](https://docs.finance.kobana.com.br/pt/pt/api/overview/filtering.md) — gramática de `?campo[operador]=`, `?sort_by=` e `?sort_order=`. * [Seleção de campos](https://docs.finance.kobana.com.br/pt/pt/api/overview/fields.md) — `?fields=` para devolver só as colunas que você usa. * [Idempotência](https://docs.finance.kobana.com.br/pt/pt/api/overview/idempotency.md) — `X-Idempotency-Key` para retries seguros. * [Erros](https://docs.finance.kobana.com.br/pt/pt/api/overview/errors.md) — envelope e vocabulário de códigos de erro. * [Retenção de dados](https://docs.finance.kobana.com.br/pt/pt/api/overview/data-retention.md) — política de guarda por tipo de recurso. --- # OpenAPI A especificação da API do Financeiro Inteligente está disponível em formato OpenAPI 3.1 para importar na ferramenta de sua preferência. ## OpenAPI 3.1[​](#openapi-31 "Link direto para OpenAPI 3.1") | Versão | Idioma | Arquivo | | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | v1 | Português | [openapi-v1-pt.yaml](https://docs.finance.kobana.com.br/pt/pt/assets/files/openapi-v1-pt-9a63c71c25a9b0816c435bf01a39950f.yaml) | | v1 | English | [openapi-v1-en.yaml](https://docs.finance.kobana.com.br/pt/pt/assets/files/openapi-v1-en-152fe871601f9ff86730d43fa9d0f068.yaml) | | v1 | Español | [openapi-v1-es.yaml](https://docs.finance.kobana.com.br/pt/pt/assets/files/openapi-v1-es-e15db594e818543214dbd31b2ba92c0b.yaml) | Também disponível via a própria API em tempo real, no host de produção ou de sandbox (inclui a URL do servidor atual): | Formato | Endpoint | | ------- | ---------------------- | | YAML | `GET /v1/openapi.yaml` | | JSON | `GET /v1/openapi.json` | ## Coleção do Postman[​](#coleção-do-postman "Link direto para Coleção do Postman") Disponível também como coleção pronta para importar no Postman. Detalhes e arquivos em [Postman](https://docs.finance.kobana.com.br/pt/pt/api/overview/postman.md). --- # Listagem e paginação Todos os endpoints `GET` que retornam coleções usam paginação por **cursor**. ## Parâmetros[​](#parâmetros "Link direto para Parâmetros") Enviados via query string: | Parâmetro | Tipo | Default | Descrição | | --------- | ------------- | ------- | ---------------------------------------------------------------- | | `limit` | inteiro 1–100 | `25` | Quantidade de itens por página. Máximo **100**. | | `cursor` | string | — | Cursor opaco retornado em `meta.next_cursor` da página anterior. | ## Resposta[​](#resposta "Link direto para Resposta") Toda resposta de sucesso da API vem em `{ data }`. Numa listagem, `data` é o array da página e `meta` traz o cursor: ``` { "data": [ { "id": "00000000-0000-0000-0000-000000000001", "name": "Conta Corrente" } ], "meta": { "next_cursor": "eyJpZCI6Mn0" } } ``` | Campo | Descrição | | ------------------ | -------------------------------------------------------------------------------------------------------------------------- | | `data` | Array com os itens da página atual. Num recurso único (`GET /{id}`, `POST`, `PATCH`, `DELETE`) é o objeto em vez do array. | | `meta.next_cursor` | Cursor para a próxima página. `null` quando não há mais itens. | ## Exemplos[​](#exemplos "Link direto para Exemplos") ### Primeira página[​](#primeira-página "Link direto para Primeira página") ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: Meu Sistema (contato@example.com)' \ 'https://api.finance.kobana.com.br/v1/financial-accounts?limit=25' ``` ### Próxima página[​](#próxima-página "Link direto para Próxima página") ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: Meu Sistema (contato@example.com)' \ 'https://api.finance.kobana.com.br/v1/financial-accounts?limit=25&cursor=eyJpZCI6Mn0' ``` ## Iterando todas as páginas[​](#iterando-todas-as-páginas "Link direto para Iterando todas as páginas") Padrão recomendado em pseudo-código: ``` async function fetchAll(url, token) { const out = []; let cursor = null; while (true) { const params = cursor ? `?limit=100&cursor=${cursor}` : '?limit=100'; const res = await fetch(`${url}${params}`, { headers: { Authorization: `Bearer ${token}` }, }); const { data, meta } = await res.json(); out.push(...data); if (!meta.next_cursor) break; cursor = meta.next_cursor; } return out; } ``` ## Boas práticas[​](#boas-práticas "Link direto para Boas práticas") * `limit=100` minimiza o número de requisições e consome menos do [limite de requisições](https://docs.finance.kobana.com.br/pt/pt/api/overview/rate-limit.md). * Aplique [filtros](https://docs.finance.kobana.com.br/pt/pt/api/overview/filtering.md) (ex.: `?company_id=`, `?occurred_at[gte]=2026-01-01`) para reduzir o volume antes de paginar. aviso **O cursor é opaco** — não tente decodificá-lo nem construí-lo manualmente. Guarde-o exatamente como veio em `meta.next_cursor` e devolva-o em `?cursor=`. --- # Postman Baixe a coleção no idioma de sua preferência e importe no Postman, ou abra a versão online direto do workspace público da Kobana. ## Workspace público[​](#workspace-público "Link direto para Workspace público") As coleções v1 da API do Financeiro Inteligente estão publicadas no workspace [**universokobana/kobana-finance-api**](https://www.postman.com/universokobana/kobana-finance-api/overview), com uma coleção por idioma. ## Coleção online[​](#coleção-online "Link direto para Coleção online") Abra diretamente no Postman (web ou app): [**API do Financeiro Inteligente (v1.0.0) — Português**](https://www.postman.com/universokobana/kobana-finance-api/collection/46791755-98450bf6-afcd-4de0-8072-7632cad6445b) ## Coleções para download[​](#coleções-para-download "Link direto para Coleções para download") Importe o arquivo `.json` diretamente no Postman (**File → Import**): | Versão | Idioma | Arquivo | | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | v1 | Português | [postman-v1-pt.json](https://docs.finance.kobana.com.br/pt/pt/assets/files/postman-v1-pt-2805a6b38f13dd4bdf8c3b8ab53636a5.json) | | v1 | English | [postman-v1-en.json](https://docs.finance.kobana.com.br/pt/pt/assets/files/postman-v1-en-9bce9f42b878da0bc64550a5d2670a02.json) | | v1 | Español | [postman-v1-es.json](https://docs.finance.kobana.com.br/pt/pt/assets/files/postman-v1-es-5df4535af8486782d042bb3326191e79.json) | ## Usando[​](#usando "Link direto para Usando") 1. Baixe e importe o arquivo `.json` no Postman (**File → Import**) — ou abra a [coleção online](#cole%C3%A7%C3%A3o-online) diretamente. 2. Abra a aba **Variables** da coleção e preencha: * `baseUrl` — produção (`https://api.finance.kobana.com.br/v1`) ou sandbox (`https://api.finance.sandbox.kobana.com.br/v1`). * `bearerToken` — seu JWT, gerado nas configurações da plataforma em **Integrações → Token de API**. 3. A autenticação `Bearer` já vem configurada no nível da coleção apontando pra `{{bearerToken}}`. 4. Abra qualquer request, ajuste parâmetros se necessário e clique em **Send**. --- # Limite de requisições Os limites são por **janela deslizante de 1 hora** — cada requisição conta contra o limite pelos 60 minutos seguintes, não há um "zerar" em horário fixo — e separados em três faixas: **leitura** (`GET`), **escrita** (`POST`, `PUT`, `PATCH`, `DELETE`) e as **ações que movimentam dinheiro**, que têm um balde próprio, mais restrito. | Tipo | Limite | | --------------------------------------------------------------------------------------- | ------------------------- | | Leitura (`GET`) | **60 requisições/hora** | | Escrita (`POST`, `PUT`, `PATCH`, `DELETE`) | **1000 requisições/hora** | | Movimentação de dinheiro (emitir/cancelar cobrança, enviar/cancelar pagamento ao banco) | **60 requisições/hora** | As ações de movimentação de dinheiro contam apenas contra a faixa própria (`throttle_v1_money`), não contra a de escrita. Caso sua operação precise de um número maior, fale com o suporte ou comercial. ## Headers de resposta[​](#headers-de-resposta "Link direto para Headers de resposta") A cada requisição, o servidor anexa aos cabeçalhos da resposta os limites utilizados e quando a contagem libera: | Header | Exemplo | Descrição | | ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `X-RateLimit-Limit` | `60` | Limite de requisições para o cliente. | | `X-RateLimit-Name` | `throttle_v1_write` | Nome do throttle utilizado. | | `X-RateLimit-Remaining` | `0` | Número de requisições disponíveis. | | `X-RateLimit-Reset` | `1782648000000` | [Unix time](https://en.wikipedia.org/wiki/Unix_time) em **milissegundos** — quando a contagem reinicia. | | `Retry-After` | `30` | Segundos até a contagem reiniciar. Ver [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). | ### Exemplo de resposta em sucesso[​](#exemplo-de-resposta-em-sucesso "Link direto para Exemplo de resposta em sucesso") ``` Date: Fri, 17 Jul 2026 12:00:00 GMT Content-Type: application/json; charset=utf-8 X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 486 ``` ### Exemplo de resposta em bloqueio[​](#exemplo-de-resposta-em-bloqueio "Link direto para Exemplo de resposta em bloqueio") Quando o limite é atingido, o servidor retorna `HTTP 429 Too Many Requests`. Aguarde o número de segundos do header `Retry-After` antes da próxima requisição. ``` HTTP/1.1 429 Too Many Requests Date: Fri, 17 Jul 2026 12:00:00 GMT Content-Type: application/json; charset=utf-8 X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1784293200000 X-RateLimit-Name: throttle_v1_write Retry-After: 3600 { "error": { "code": "RATE_LIMITED", "message": "Write request rate limit exceeded for this token." } } ``` dica Use `limit=100` nas [listagens](https://docs.finance.kobana.com.br/pt/pt/api/overview/pagination.md) e os [filtros](https://docs.finance.kobana.com.br/pt/pt/api/overview/filtering.md) para reduzir o número de requisições — e trate `429` com backoff pelo `Retry-After`, nunca com retry imediato. Referência: [RateLimit header fields for HTTP](https://ietf-wg-httpapi.github.io/ratelimit-headers/draft-ietf-httpapi-ratelimit-headers.html) --- # User-Agent O cabeçalho `User-Agent` identifica sua integração. Inclua seu nome e um endereço de e-mail válido para que a equipe da Kobana possa entrar em contato caso: 1. Você esteja fazendo algo errado, e possamos avisá-lo antes de bloquear; 2. Esteja fazendo algo muito legal, e possamos dar os parabéns 🙂 Exemplo: ``` User-Agent: Meu Nome (meunome@example.com) ``` Exemplo de como passar esse cabeçalho usando cURL: ``` curl -i \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'Content-Type: application/json' \ -H 'User-Agent: Meu Nome (meunome@example.com)' \ -X GET 'https://api.finance.kobana.com.br/v1/financial-accounts' ``` aviso Envie esse cabeçalho em **todas** as requisições — ele fica registrado no log de acessos da API e é o que identifica sua integração num contato de suporte. --- # Aprovar pagamentos **Aprovar pagamentos** (`/payables/approvals`) é o portão de entrada das contas a pagar: um título novo — criado por formulário, CSV ou API — **não entra na lista oficial** até que alguém aprove. É a trava contra lançamento indevido — nada que uma pessoa (ou a API) crie como obrigação nova vira dinheiro a sair sem um segundo par de olhos. Vem **ligada por padrão** e pode ser desligada por espaço de trabalho (ver [Ligar ou desligar](#ligar-ou-desligar)). ## Onde fica[​](#onde-fica "Link direto para Onde fica") Menu **Financeiro** → **Aprovar pagamentos**, logo abaixo de Contas a pagar. O item mostra um **badge com o número de títulos que ainda precisam de aprovação** — os aguardando e os aprovados parcialmente, não os já aprovados ou recusados. O número respeita a empresa selecionada no cabeçalho. ## Ligar ou desligar[​](#ligar-ou-desligar "Link direto para Ligar ou desligar") A aprovação é uma **configuração do espaço de trabalho**, e vem **ligada por padrão**. O controle fica na tela **Configurações de Aprovação**, aberta pelo **ícone de engrenagem, no canto superior direito desta tela** — o interruptor **"Exigir aprovação"**, com a explicação dos dois estados logo abaixo. | Estado | O que acontece ao criar um título | | ------------------- | ------------------------------------------------------------------------------------------------ | | **Ligada** (padrão) | Entra na fila e só vira oficial depois que alguém aprova — vale tudo o que esta página descreve. | | **Desligada** | Entra **direto na lista oficial** de contas a pagar, sem passar por aqui. | observação O interruptor governa **só títulos novos**. Desligar não libera o que já está aguardando, e ligar não puxa para a fila o que já é oficial; títulos recusados continuam bloqueados. ### As alterações passam pela Kobana[​](#as-alterações-passam-pela-kobana "Link direto para As alterações passam pela Kobana") ![Configurações de aprovação](/pt/assets/images/31-payment-approval-settings-3c0d45d98640d55ba7b9cdf6d820122c.png) **Nada nesta tela muda na hora.** Ligar ou desligar a aprovação, mudar o número de aprovações, permitir que quem criou aprove, enviar ao banco depois de aprovar e aprovar lotes no gateway automaticamente — tudo isso vira uma **solicitação** que a Kobana aprova ou nega, como as regras de [Segurança](https://docs.finance.kobana.com.br/pt/pt/seguranca/.md#nada-vale-na-hora). * Ao confirmar a mudança, o botão é **Enviar para aprovação**, e o aviso diz: *"A alteração passa a valer quando a Kobana aprovar."* * A tela mostra sempre os valores **em vigor**. Com um pedido em análise, aparece o aviso *"Há 1 solicitação pendente de alteração destas configurações"*, com o link **Ver solicitações**, que abre a lista de [Solicitações](https://docs.finance.kobana.com.br/pt/pt/seguranca/.md#solicita%C3%A7%C3%B5es) — onde dá para acompanhar ou cancelar o pedido. * Pedir essas mudanças exige a permissão **Configurações de aprovação**, que por padrão só o Proprietário tem. ## Quantas aprovações[​](#quantas-aprovações "Link direto para Quantas aprovações") Na mesma tela, **Aprovações necessárias** define quantas **pessoas diferentes** precisam aprovar cada título — de 1 (padrão) a 10. O número não pode passar de quantas pessoas **com acesso ao espaço e permissão de aprovar pagamentos** existem: a tela mostra essa contagem e bloqueia os valores acima dela. Se alguém perder a permissão depois, a tela avisa em vermelho que os títulos novos vão ficar parados na fila. Com mais de uma, cada aprovação é registrada e o título fica como **Aprovado parcialmente** até a última: continua **fora da lista oficial** e aparece na aba de mesmo nome, com o progresso (*"1 de 2 aprovações"*). Quando a última pessoa aprova, ele entra na lista. Se alguém **editar o pagamento** de um título que ainda espera aprovação — valor, datas, fornecedor, código de barras, Pix ou dados bancários —, as aprovações já dadas são descartadas e ele volta para **Aguardando**: cada pessoa aprova de novo o que mudou. Editar categoria, centro de classificação ou observações não mexe nas aprovações. observação O número é **congelado quando o título entra na fila**: aumentar a configuração vale só para os títulos novos. **Diminuir** vale também para os que já estão esperando — é a saída quando alguém perde a permissão e a fila fica exigindo mais pessoas do que restam. Quando a Kobana aprova a redução, um título que já tem as aprovações do número novo entra na lista na hora. ## O que o portão bloqueia[​](#o-que-o-portão-bloqueia "Link direto para O que o portão bloqueia") Enquanto aguarda aprovação, o título **existe** mas fica fora de tudo: * **Não aparece** na lista de Contas a pagar * **Não conta** em totais, em vencidos, no fluxo de caixa, nos relatórios nem na Visão geral * **Não pode** ser enviado ao banco * **Não aceita** baixa manual — "Marcar como pago" não aparece Ou seja: para o resto do sistema, ele ainda não é uma obrigação. ## Quem passa pelo portão[​](#quem-passa-pelo-portão "Link direto para Quem passa pelo portão") | Origem | Passa? | | ----------------------------------------------- | ----------------------------------------------------------- | | Formulário (`/payables/new`) | **Sim** | | Importação de CSV | **Sim** | | API | **Sim** | | Publicar um rascunho | **Sim** — salvar como rascunho não é um atalho para escapar | | Parcelas de recorrência geradas automaticamente | Só se a série ainda aguarda aprovação | | Títulos importados do Fintera | Não | | Títulos anteriores à criação do portão | Não | A regra em uma frase: **tudo que alguém cria como obrigação nova passa; tudo que é derivado, sincronizado ou legado já nasce oficial.** ## A tela[​](#a-tela "Link direto para A tela") ![Tela de aprovação de pagamentos](/pt/assets/images/30-payment-approvals-c78373fccb9fd0ac15068f77891bc978.png) Quatro abas, cada uma com seu contador: | Aba | Lista | | -------------------------- | -------------------------------------------------------------------- | | **Aguardando** | A fila que precisa do seu ok, ordenada por vencimento | | **Aprovados parcialmente** | Títulos que já receberam aprovação, mas ainda esperam outras pessoas | | **Aprovados** | Histórico, do mais recente | | **Recusados** | Histórico, do mais recente, com o motivo | Colunas: **Descrição** (com o fornecedor abaixo, e o motivo da recusa na aba Recusados), **Origem**, **Vencimento**, **Status** e **Valor**. Em "todas as empresas" entra também a coluna **Empresa**. A busca cobre **descrição e nome do fornecedor**. ### Origem[​](#origem "Link direto para Origem") Diz de onde o título veio, e é o campo que sustenta a decisão: * **Manual** — criado no formulário ou pela API * **Importação CSV** — veio de um arquivo ## Aprovar[​](#aprovar "Link direto para Aprovar") Nas abas **Aguardando** e **Aprovados parcialmente**, por três caminhos: * **Botão Aprovar** na própria linha * **Menu de ações** da linha * **Em lote** — marque as linhas e use **Aprovar selecionados** (até 25 por vez) O diálogo **Aprovar pagamento?** confirma: *"1 pagamento será aprovado e entra na lista de contas a pagar."* Quando ainda faltarem aprovações, ele avisa que a sua será registrada e que o título só entra na lista quando todas forem dadas. Depois de aprovar um título que ainda espera outras pessoas, a linha mostra **"Você já aprovou"** no lugar do botão. observação **Aprovar não envia ao banco.** O título passa a ser oficial e entra na lista — o envio é um passo separado, feito em Contas a pagar. Ver [Envio ao banco](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md). Numa aprovação em lote, uma falha isolada não derruba as demais. ## Recusar[​](#recusar "Link direto para Recusar") Pelo **menu de ações** da linha — não há recusa inline nem em lote. Um título aprovado parcialmente também pode ser recusado: basta uma pessoa recusar. O diálogo **Recusar pagamento?** avisa: *"O título fica bloqueado para sempre e nunca entra na lista de contas a pagar. Registre o motivo (opcional)."* O **motivo é opcional** (até 500 caracteres), mas é o que a aba Recusados vai exibir depois — sem ele, o histórico não explica a decisão. perigo **Recusar não tem volta pela interface.** Um título recusado não pode ser aprovado depois e não pode ir ao banco. Ele fica na aba Recusados como registro, e nada mais. As abas **Aprovados** e **Recusados** não têm ações — são auditoria. Clicar na descrição abre o título. ## Quem pode aprovar[​](#quem-pode-aprovar "Link direto para Quem pode aprovar") **Qualquer pessoa com acesso ao espaço de trabalho e permissão de aprovar**, com duas travas: * **Quem criou o título não pode aprová-lo** — a não ser que seja o **único membro** do espaço de trabalho. Sozinho, não há a quem pedir a aprovação, então a tela avisa *"Você é o único membro deste espaço, então pode aprovar os pagamentos que você mesmo criou. Quando outra pessoa entrar no espaço, a aprovação volta a exigir alguém além de quem criou o pagamento."* e libera a aprovação. A trava volta sozinha quando outra pessoa ganha acesso ao espaço. Quem está suspenso ou com o acesso pausado continua contando como membro; só a remoção do membro libera a aprovação. * **Cada pessoa conta uma vez.** Quando o espaço exige mais de uma aprovação, elas precisam vir de pessoas diferentes. Aprovar também **não é exposto na API** — é ação exclusiva da tela. ### Aprovação noturna e por canal[​](#aprovação-noturna-e-por-canal "Link direto para Aprovação noturna e por canal") A [Segurança](https://docs.finance.kobana.com.br/pt/pt/seguranca/.md) do espaço de trabalho pode restringir **quando** e **por onde** se aprova: * **Período noturno** — com **Permitir aprovações no período noturno** desligado, a tela mostra *"Aprovações bloqueadas no período noturno. Elas voltam a ser permitidas às 06:00."* (com o horário do seu espaço) e desabilita os botões de aprovar, na linha e em lote. * **Canal** — com **Aprovar** desligado para o canal em uso, aparece *"A Segurança deste espaço não permite aprovar pagamentos por este canal."* **Recusar nunca é bloqueado** — nem à noite, nem por canal. A regra noturna vale só para a aprovação feita por pessoas: recorrências, importações de ERP e a aprovação do lote no gateway não são aprovações deste portão. ### Envio bloqueado pela Segurança[​](#envio-bloqueado-pela-segurança "Link direto para Envio bloqueado pela Segurança") Quando um título, do jeito que está, **não vai poder ir ao banco** — tipo de operação desligado, conta bloqueada, favorecido não liberado, valor acima do limite por operação —, a linha mostra o selo **"Envio bloqueado pela Segurança"**: *"Do jeito que está, este título não vai poder ser enviado ao banco. Peça a liberação em Segurança."* Aprovar continua possível; o selo só avisa que o envio vai ser barrado. ## Editar um título aprovado[​](#editar-um-título-aprovado "Link direto para Editar um título aprovado") A aprovação vale para o pagamento **como ele foi visto**. Com a aprovação ligada, se alguém mudar num título **aprovado e ainda não enviado** ao banco qualquer um destes campos, ele **volta para a fila** (**Aguardando**), com as aprovações zeradas, e sai da lista de Contas a pagar até ser aprovado de novo: * valor; * fornecedor; * favorecido — nome, CPF/CNPJ, chave Pix, tipo da chave e dados bancários; * código de barras ou linha digitável; * conta de origem ("Pagar via"); * tipo de operação e forma de pagamento; * dados do tributo. Vale também para edições feitas pela API. Datas, juros, descontos, categoria, centro de classificação e observações não devolvem o título para a fila. Depois que o título é **enviado ao banco**, esses campos ficam **travados** — ver [Editar depois do envio](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md#editar-depois-do-envio). ## Como o estado aparece em Contas a pagar[​](#como-o-estado-aparece-em-contas-a-pagar "Link direto para Como o estado aparece em Contas a pagar") Na listagem de Contas a pagar, um título aprovado exibe um **selo redondo com um escudo**; passe o mouse para ler **"Criação aprovada"**, seguido de quem aprovou e quando — é ali que a auditoria fica à mão, sem abrir o título. Os demais estados não aparecem ali — pela própria regra do portão, eles não chegam à lista. Depois que o título é enviado ao banco, o selo dá lugar ao status do gateway. --- # Cartões Cartões (`/credit-cards`, menu **Movimentações › Cartões**) acompanha os cartões das empresas do espaço de trabalho: em qual fatura cai cada compra, quanto do limite já foi usado, as parcelas e as assinaturas que ainda vão chegar, o IOF das compras internacionais, a conferência com a fatura do banco e o pagamento. ![Lista de cartões com a fatura de cada um, o limite usado e a fatura fechada a pagar](/pt/assets/images/36-credit-cards-ecef703a11159a37ab8994ae081bf2e9.png) ## Nesta seção[​](#nesta-seção "Link direto para Nesta seção") ## [📄️Cadastrar e converter](https://docs.finance.kobana.com.br/pt/pt/cartoes/cadastrar-e-converter.md) [Cadastrar um cartão com conta nova, converter uma conta de crédito que já existe, e a prévia das faturas que o formulário calcula enquanto você digita.](https://docs.finance.kobana.com.br/pt/pt/cartoes/cadastrar-e-converter.md) ## [📄️Fatura e fechamento](https://docs.finance.kobana.com.br/pt/pt/cartoes/fatura-e-corte.md) [A tela do cartão — faturas por mês, o cabeçalho da fatura, os lançamentos, a data de fechamento prevista e a confirmada, e o histórico.](https://docs.finance.kobana.com.br/pt/pt/cartoes/fatura-e-corte.md) ## [📄️Lançamentos e IOF](https://docs.finance.kobana.com.br/pt/pt/cartoes/lancamentos-e-iof.md) [Lançar compras à vista, parceladas e internacionais, estornos, juros e tarifas — em qual fatura cada um cai, o IOF e a cotação, editar uma série, mover e antecipar.](https://docs.finance.kobana.com.br/pt/pt/cartoes/lancamentos-e-iof.md) ## [📄️Recorrências](https://docs.finance.kobana.com.br/pt/pt/cartoes/recorrencias.md) [Assinaturas cobradas no cartão — as cobranças previstas em cada fatura, confirmar com o valor real, não cobrado, a sugestão de atualizar o valor, editar e encerrar.](https://docs.finance.kobana.com.br/pt/pt/cartoes/recorrencias.md) ## [📄️Fechar, conferir e pagar](https://docs.finance.kobana.com.br/pt/pt/cartoes/fechar-conferir-pagar.md) [O fechamento automático e a conta a pagar da fatura, a conferência com o total do banco, o pagamento integral ou parcial, desfazer, reabrir, a recarga do pré-pago e o cartão no fluxo de caixa.](https://docs.finance.kobana.com.br/pt/pt/cartoes/fechar-conferir-pagar.md) ## [📄️Relatórios](https://docs.finance.kobana.com.br/pt/pt/cartoes/relatorios.md) [IOF pago nas compras internacionais, por mês, cartão, categoria ou fornecedor, e o previsto × realizado das recorrências — com exportação em CSV e XLSX.](https://docs.finance.kobana.com.br/pt/pt/cartoes/relatorios.md) ## Os três tipos[​](#os-três-tipos "Link direto para Os três tipos") | Tipo | Como funciona | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Crédito** | Uma fatura por mês. Ao fechar, a fatura vira uma [conta a pagar](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/.md) e o pagamento sai da conta que paga a fatura. Tem limite. | | **Pré-pago** | Recebe recargas de uma conta bancária e as compras saem do saldo. O limite é o próprio saldo. A fatura fecha sem conta a pagar. | | **Benefício** | Funciona como o pré-pago (vale-refeição, vale-alimentação). | ## O cartão e as suas contas[​](#o-cartão-e-as-suas-contas "Link direto para O cartão e as suas contas") Cada cartão tem uma conta do tipo **Crédito** em [Minhas contas](https://docs.finance.kobana.com.br/pt/pt/contas-financeiras/.md): criada junto com o cartão, ou uma conta de crédito que já existia e foi convertida (ver [Cadastrar e converter](https://docs.finance.kobana.com.br/pt/pt/cartoes/cadastrar-e-converter.md)). Cada compra lançada no cartão aparece **uma vez** no restante do sistema: | Onde | O que aparece | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Lançamentos** | A compra, na data dela e na categoria dela, com o selo **Cartão**. O pagamento da fatura é uma transferência, com o selo **Pagamento de fatura**; a recarga do pré-pago, com o selo **Recarga**. | | **Minhas contas** | O saldo da conta do cartão é a dívida: as compras abatem, o pagamento devolve. | | **Visão geral** | As compras entram como despesa na data da compra; o pagamento da fatura, por ser transferência, não conta de novo. | | **Fluxo de caixa** | O cartão não é caixa. A saída é o pagamento da fatura, no vencimento, pela conta que paga a fatura. Ver [Fechar, conferir e pagar](https://docs.finance.kobana.com.br/pt/pt/cartoes/fechar-conferir-pagar.md#no-fluxo-de-caixa). | | **Contas a pagar** | A fatura fechada vira uma conta a pagar, com o selo de origem **Fatura de cartão**. | observação **O que veio do cartão se altera pelo cartão.** Na tela de [Lançamentos](https://docs.finance.kobana.com.br/pt/pt/lancamentos/.md), a compra aparece com as ações de editar, classificar, conciliar e excluir desabilitadas, e o motivo no rodapé do menu: *"Lançamento do cartão: altere-o pelo cartão."* **"Abrir no cartão"** leva direto à fatura dela. O mesmo vale para as duas pontas do pagamento (*"Pagamento de fatura: desfaça pela fatura do cartão."*) e da recarga (*"Recarga do cartão: exclua-a pelo cartão."*). ## A lista[​](#a-lista "Link direto para A lista") Cada cartão é um card, na ordem do próximo vencimento: * **Apelido**, bandeira e, no pré-pago e no benefício, o tipo. Embaixo, o banco emissor, o produto e o final (`···· 4821`). * **A fatura fechada que falta pagar**, em destaque: o valor, o vencimento (*"vence 09/11 · em 4 dias"*) e o botão **Pagar**, que abre o pagamento na própria fatura. * **A fatura atual** — *"Fatura de Dez/26"*, o status, o total previsto e *"fecha 02/12 · vence 09/12"*. * **A barra do limite** — *"Usado R$ 22.007,75 de R$ 60.000,00"* e a porcentagem. A barra fica amarela a partir do **Alerta de limite** definido no cadastro e vermelha quando passa de 100%. * No pré-pago e no benefício, no lugar da fatura e do limite: **Saldo**, quanto foi usado e o botão **Recarregar**. * No rodapé, de onde sai o dinheiro: *"Paga por Itaú — Conta Corrente · Débito automático"*, ou *"Recarga por …"*. O menu **⋯** de cada card tem **Editar cartão** e **Ver a conta em Minhas contas**. No topo ficam a busca (*"Buscar por apelido ou últimos dígitos"*), as abas **Ativos**, **Bloqueados**, **Cancelados** e **Todos**, com a contagem de cada uma, a pílula **Relatório** (ver [Relatórios](https://docs.finance.kobana.com.br/pt/pt/cartoes/relatorios.md)) e **Novo cartão**. Se o espaço tem contas do tipo Crédito que ainda não são cartão, um aviso no alto da lista oferece **Converter em cartão**. ## Status do cartão[​](#status-do-cartão "Link direto para Status do cartão") **Ativo**, **Bloqueado** ou **Cancelado**, no próprio cadastro. O ícone (i) do campo explica: *"Um cartão cancelado deixa de gerar faturas novas. Cartões não são excluídos, porque as faturas ficam como histórico."* ## Permissões[​](#permissões "Link direto para Permissões") No editor de papéis, o módulo tem três grupos: **Cartões de crédito**, **Lançamentos do cartão** e **Faturas do cartão**. | Para | Precisa de | | ----------------------------------------------------------------- | ------------------------------------------------------------ | | Ver a lista | Cartões de crédito › **Listar** | | Abrir um cartão, as faturas, o histórico e os relatórios | Cartões de crédito › **Ver detalhes** | | Cadastrar, converter e editar um cartão | Cartões de crédito › **Criar** / **Editar** | | Lançar, editar, mover, antecipar e excluir compras e recorrências | Lançamentos do cartão › **Criar** / **Editar** / **Excluir** | | Alterar a data de fechamento e conferir a fatura | Faturas do cartão › **Editar** | | Fechar e reabrir a fatura | Faturas do cartão › **Fechar e reabrir** | | Pagar, desfazer o pagamento e recarregar | Faturas do cartão › **Pagar** | Como no resto do sistema, a tela não esconde o botão de quem não tem a permissão: o sistema recusa a ação ao salvar. ## Pela API e pelo MCP[​](#pela-api-e-pelo-mcp "Link direto para Pela API e pelo MCP") Tudo o que esta seção descreve também está na API v1 — [cartões](https://docs.finance.kobana.com.br/pt/pt/api/v1/list-credit-cards), [faturas](https://docs.finance.kobana.com.br/pt/pt/api/v1/get-card-statement), [lançamentos](https://docs.finance.kobana.com.br/pt/pt/api/v1/list-card-transactions), [recorrências](https://docs.finance.kobana.com.br/pt/pt/api/v1/list-card-recurrences) e [alíquotas de IOF](https://docs.finance.kobana.com.br/pt/pt/api/v1/list-iof-rates) — e nas [ferramentas do servidor MCP](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/accounts.md#credit_cards). O número completo do cartão nunca entra no sistema por nenhuma delas: só os 4 últimos dígitos. --- # Cadastrar e converter **Novo cartão** (`/credit-cards/new`) abre o cadastro em página. À direita, o painel **Prévia das faturas** mostra, enquanto você digita, o melhor dia de compra e as próximas faturas com fechamento e vencimento. ![Cadastro do cartão com a prévia das faturas ao lado](/pt/assets/images/38-credit-card-form-4d8a5acd523c1dcbb40d629352975b3a.png) **O ícone (i) ao lado do nome de um campo explica o campo.** Passe o mouse sobre ele, ou chegue nele com Tab, para ler a explicação. Nas tabelas abaixo, os textos marcados com (i) são esses. ## Conta nova ou conversão[​](#conta-nova-ou-conversão "Link direto para Conta nova ou conversão") O primeiro bloco, **Conta do cartão**, decide qual conta de Minhas contas fica com os lançamentos do cartão: | Opção | O que faz | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Criar uma conta nova** | *"Criamos em Minhas contas uma conta do tipo crédito para este cartão, com o apelido e o banco dele."* Cartão não tem agência nem número, então a conta nasce sem eles. | | **Converter uma conta de crédito** | *"Uma conta do tipo crédito que você já tem passa a ter faturas e continua em Minhas contas. A empresa é a da conta, e o banco emissor já vem preenchido com o dela."* Só aparecem contas do tipo Crédito que ainda não são cartão. | O aviso da lista de cartões, *"… é uma conta de crédito que ainda não é cartão"*, leva direto para a conversão, com a conta já escolhida. Uma conta convertida não pode ser convertida de novo em outro cartão. aviso **Uma compra lançada nos dois lugares conta duas vezes.** *"Os lançamentos que já estão em … continuam lá. Para não contar uma compra duas vezes, escolha uma data de início depois do último lançamento feito nessa conta."* A conversão não move nem apaga o histórico da conta: ele continua na conta como estava, e as faturas começam pela que inclui a **Data de início**. ## Identificação[​](#identificação "Link direto para Identificação") | Campo | Observações | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tipo** | **Crédito**, **Pré-pago** ou **Benefício**. Não muda depois do cadastro. | | **Apelido** | Obrigatório, até 60 caracteres. É o nome do cartão em todo o sistema. | | **Banco emissor** | Obrigatório, da lista de bancos. | | **Bandeira** | Obrigatória: Visa, Mastercard, Elo, American Express, Hipercard ou Outra. | | **Nome do produto** | Opcional (*"Ex.: Black, Infinite"*). | | **Últimos 4 dígitos** | Obrigatório. (i) *"Por segurança, guardamos só os 4 últimos dígitos. O número completo do cartão nunca é salvo."* | | **Status** | Ativo, Bloqueado ou Cancelado. (i) *"Um cartão cancelado deixa de gerar faturas novas. Cartões não são excluídos, porque as faturas ficam como histórico."* | perigo **O número completo do cartão é recusado em qualquer campo de texto.** Apelido, produto, descrição e observações rejeitam uma sequência que tenha cara de número de cartão — assim um número colado por engano não é gravado. CVV e validade não existem no cadastro. ## Datas da fatura[​](#datas-da-fatura "Link direto para Datas da fatura") | Campo | Observações | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Dia de fechamento** | De 1 a 31. Em mês mais curto, vale o último dia. (i) *"Dia em que o banco fecha a fatura. Compras feitas até esse dia entram na fatura do mês; as do dia seguinte em diante, na próxima."* | | **Fechamento antecipado (dias)** | De 0 a 15. (i) *"Alguns bancos fecham a fatura alguns dias antes do dia de fechamento. Se o seu faz isso, informe quantos dias. Ex.: fechamento no dia 10 e 2 dias antes: compras até o dia 8 entram nesta fatura. Na dúvida, deixe 0."* | | **Dia de vencimento** | De 1 a 31. (i) *"Dia em que a fatura vence. Se cair em fim de semana ou feriado, vale a regra de Vencimento em dia não útil."* | | **Vencimento em dia não útil** | Próximo dia útil, dia útil anterior ou manter a data. | | **Data de início** | (i) *"As faturas começam pela que inclui esta data. Compras anteriores não entram no cartão."* Uma data passada cria as faturas desde ela. | **Como as datas saem.** A fatura leva o nome do **mês do vencimento**. O fechamento cai no mesmo mês quando o dia de fechamento é antes do vencimento (fecha dia 2, vence dia 9: as duas datas em dezembro); quando é depois, cai no mês anterior (fecha dia 25, vence dia 5: fechamento em novembro, vencimento em dezembro). O fechamento é **inclusivo**: a compra feita no próprio dia do fechamento ainda entra na fatura. Com **Fechamento antecipado (dias)**, a data de fechamento de cada fatura é o dia de fechamento menos esses dias. **Dias úteis** são os do calendário bancário: sábados, domingos, os feriados nacionais e os móveis da Páscoa — segunda e terça de Carnaval, Sexta-feira Santa e Corpus Christi. No painel, um vencimento ajustado aparece com o aviso *"09/01 não é dia útil"*. ### O painel Prévia das faturas[​](#o-painel-prévia-das-faturas "Link direto para O painel Prévia das faturas") * **Melhor dia de compra** — o dia seguinte ao fechamento: *"Compras a partir de 03/12 entram na fatura de Jan/27, que vence em 11/01: o prazo mais longo para pagar."* * **As próximas três faturas**, com fechamento e vencimento e o dia da semana de cada um. * No cadastro, *"Primeira fatura no sistema: … (compras de … a …)."* e, no rodapé, *"Ao cadastrar, criamos a fatura atual e as 12 próximas."* O painel usa as mesmas regras do servidor: as datas que ele mostra são as que as faturas vão ter. ### Mudar as datas depois[​](#mudar-as-datas-depois "Link direto para Mudar as datas depois") *"Ao mudar o fechamento ou o vencimento, as próximas faturas que ainda não têm a data de fechamento confirmada são recalculadas, e os lançamentos vão para a fatura certa."* Faturas abertas, fechadas e pagas não mudam, e nem as futuras cuja data de fechamento alguém já confirmou. Para acertar a data de fechamento de uma fatura só, use **Alterar data de fechamento** nela — ver [Fatura e fechamento](https://docs.finance.kobana.com.br/pt/pt/cartoes/fatura-e-corte.md#alterar-a-data-de-fechamento). ## Limite e pagamento[​](#limite-e-pagamento "Link direto para Limite e pagamento") | Campo | Observações | | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Limite** | Só no crédito. Sem limite, o card não mostra a barra. | | **Alerta de limite** | (i) *"A barra de limite fica amarela quando o uso passa deste percentual. Ex.: 80%."* | | **Conta que paga a fatura** | (i) *"A conta bancária, da mesma empresa, de onde sai o pagamento da fatura. A conta a pagar de cada fatura já vem com ela."* No pré-pago o campo se chama **Conta que faz as recargas**. | | **Forma de pagamento** | Débito automático, Boleto ou Pix. (i) *"Como a fatura costuma ser paga. Vai para a conta a pagar de cada fatura."* | | **Fornecedor da fatura** | (i) *"Quem aparece como fornecedor na conta a pagar de cada fatura. Em branco, usamos o banco emissor."* | | **Categoria padrão** · **Centro de classificação padrão** | (i) *"Já vem preenchida em cada lançamento novo do cartão. Dá para trocar no lançamento."* | No pré-pago e no benefício, o limite não é digitado: *"No pré-pago e no benefício, o limite é o saldo carregado: ele aumenta a cada recarga."* ## Compras internacionais[​](#compras-internacionais "Link direto para Compras internacionais") | Campo | Observações | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Alíquota de IOF** | (i) *"Em branco, cada compra usa a alíquota oficial vigente na data dela. Preencha só se o seu banco cobra uma alíquota diferente."* | | **Spread do banco** | Em pontos percentuais (4 = 4%). (i) *"Percentual que o banco soma à cotação oficial da moeda (PTAX do Banco Central) nas compras internacionais. Usamos para estimar a cotação até a fatura chegar."* | Ver [Lançamentos e IOF](https://docs.finance.kobana.com.br/pt/pt/cartoes/lancamentos-e-iof.md#compra-internacional). ## Depois de salvar[​](#depois-de-salvar "Link direto para Depois de salvar") **Cadastrar cartão** (ou **Converter em cartão**) cria a fatura aberta e as 12 seguintes e leva à tela do cartão. A partir daí, todo dia, de madrugada, o sistema fecha a fatura cuja data de fechamento passou e abre a seguinte — ver [Fechar, conferir e pagar](https://docs.finance.kobana.com.br/pt/pt/cartoes/fechar-conferir-pagar.md). Para editar, use o lápis ao lado do nome do cartão ou **Editar cartão** no menu do card da lista. Na edição, **Tipo** e empresa não mudam, e a **Data de início** só volta para trás. ### Lançar uma fatura anterior[​](#lançar-uma-fatura-anterior "Link direto para Lançar uma fatura anterior") Para lançar as compras de uma fatura de antes do cadastro (o PDF de uma fatura que já venceu, por exemplo), edite o cartão e antecipe a **Data de início** para o início do período dessa fatura — no máximo 24 meses para trás. (i) *"Antecipe a data para lançar compras de faturas anteriores: as faturas desde ela são criadas, e as que já passaram do fechamento fecham na rotina diária."* A mais antiga fica aberta, para receber os lançamentos; na madrugada seguinte, o sistema fecha as que já passaram do fechamento, cada uma com a sua conta a pagar no vencimento dela, e volta a abrir a fatura atual. Sem isso, um lançamento com data anterior à primeira fatura é recusado: *"A data é anterior à primeira fatura do cartão no sistema. Para lançá-la, antecipe a data de início do cartão."* --- # Fatura e fechamento Clicar num cartão abre a tela dele (`/credit-cards/`), com duas abas no topo: **Faturas** e **Recorrências** (ver [Recorrências](https://docs.finance.kobana.com.br/pt/pt/cartoes/recorrencias.md)). A pílula **Relatório**, à direita das abas, abre os [relatórios](https://docs.finance.kobana.com.br/pt/pt/cartoes/relatorios.md) já filtrados por este cartão. ![Fatura aberta com parcelas, compra internacional com IOF e cobranças recorrentes previstas](/pt/assets/images/37-credit-card-statement-845cb40e8a4673cb046323c569534e91.png) ## O cabeçalho do cartão[​](#o-cabeçalho-do-cartão "Link direto para O cabeçalho do cartão") O apelido, a bandeira e o lápis de editar; embaixo, o tipo, o banco emissor, o produto, o final e a conta que paga a fatura. À direita, o **Limite disponível** com a barra *"Usado … de …"* — no pré-pago e no benefício, o **Saldo** e o botão **Recarregar**. E o botão **Novo lançamento** (ver [Lançamentos e IOF](https://docs.finance.kobana.com.br/pt/pt/cartoes/lancamentos-e-iof.md)). ## As faturas, mês a mês[​](#as-faturas-mês-a-mês "Link direto para As faturas, mês a mês") Uma faixa de abas mostra seis faturas de cada vez, cada uma com o mês e um ponto colorido do status; as setas trazem as anteriores e as próximas. A tela abre na fatura **Aberta**, e a escolhida fica no endereço (`?statement=2026-12`), para mandar o link de uma fatura específica. | Status | O que significa | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | **Futura** | Ainda não começou. Já recebe as parcelas e as cobranças recorrentes previstas, e a data de fechamento dela já pode ser confirmada. | | **Aberta** | O ciclo atual: recebe as compras. Há uma só por cartão. | | **Fechada** | A data de fechamento passou. No cartão de crédito, já tem conta a pagar. | | **Conferida** | O total bateu com o da fatura do banco. | | **Paga** | O pagamento cobriu o total. Os lançamentos ficam **Conciliados**. | | **Paga em parte** | Pagou-se menos que o total; o resto foi para a fatura seguinte. | ## O cabeçalho da fatura[​](#o-cabeçalho-da-fatura "Link direto para O cabeçalho da fatura") *"Fatura de dezembro de 2026"* e o status, com uma linha de números. Os campos com o ícone (i) explicam o número ao passar o mouse: | Campo | O que traz | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Período** | Do dia seguinte ao fechamento anterior até a data de fechamento desta fatura. (i) *"As compras feitas neste período entram nesta fatura."* | | **Fechamento** | A data, com o selo **Previsto** ou **Confirmado** e, na fatura aberta ou futura, o lápis de alterar. (i) *"Último dia de compras desta fatura. Fica como previsto até você confirmar a data que aparece no app do banco."* | | **Vencimento** | Já ajustado para dia útil. | | **Total previsto** | O que está na fatura: realizados, previstos e IOF, menos estornos, mais o saldo anterior. Não cobrados e cancelados não entram. (i) *"A soma dos lançamentos desta fatura, com o IOF e já descontados os estornos."* | | **Total do banco** · **Diferença** | Depois da conferência: o total da fatura do banco e quanto falta bater. (i) em **Total do banco**: *"O total que a fatura do banco mostra, informado ao conferir a fatura."* | Embaixo, uma linha diz o que vem a seguir: * Aberta: *"Fecha automaticamente na madrugada de 03/12/2026 e gera uma conta a pagar de R$ 6.348,80, com vencimento em 09/12."* * Futura: *"Fatura futura: já recebe as parcelas e as cobranças recorrentes previstas. A data de fechamento já pode ser confirmada."* * Fechada ou conferida: a conta a pagar, com o status e o vencimento — e, se o total não bateu, *"O total do banco não bate: confira os lançamentos e lance o que falta."* * Paga: *"Paga em 08/10/2026: R$ 10.142,65 saíram de Itaú — Conta Corrente. Os lançamentos estão conciliados."* ### As ações da fatura[​](#as-ações-da-fatura "Link direto para As ações da fatura") Os botões mudam com o status: | Ação | Aparece em | | --------------------------------------- | ------------------------------------------------------------------- | | **Alterar data de fechamento** | Aberta e futura (também pelo lápis do fechamento) | | **Confirmar cobranças recorrentes (n)** | Futura, aberta e fechada, quando há cobranças recorrentes previstas | | **Fechar fatura agora** | Aberta | | **Conferir com o banco** | Fechada (em destaque) e conferida | | **Pagar fatura** | Fechada e conferida, no cartão de crédito | | **Desfazer pagamento** | Paga e paga em parte | | **Reabrir** | Fechada, conferida, paga e paga em parte | | Histórico (ícone do relógio) | Sempre | Fechar, conferir, pagar, desfazer e reabrir estão em [Fechar, conferir e pagar](https://docs.finance.kobana.com.br/pt/pt/cartoes/fechar-conferir-pagar.md). ## Os lançamentos da fatura[​](#os-lançamentos-da-fatura "Link direto para Os lançamentos da fatura") A tabela lista o que está na fatura, com as colunas **Data**, **Descrição** (e o fornecedor embaixo), **Categoria**, **Parcela**, **Previsto**, **Realizado**, **IOF**, **Total** e **Status**. A primeira linha soma a fatura: a quantidade de lançamentos e os totais de cada coluna de valor, sem os não cobrados e os cancelados. * A cobrança **prevista** de uma recorrência aparece em itálico e cinza, com o selo **Recorrente**, até ser confirmada. * A compra internacional traz o selo da moeda (**USD**) e, embaixo do valor, a conta: *"US$ 135,00 × 5,4700 estimada"*. O IOF vem na coluna própria, com a alíquota. * O estorno aparece com o selo **Estorno** e o valor negativo. * Não cobrados e cancelados aparecem riscados. * Um lançamento movido à mão para esta fatura mostra um cadeado: *"Movido manualmente para esta fatura: fica nela mesmo se a data de fechamento mudar."* Busca (*"Buscar por descrição ou fornecedor"*), os filtros **Tipo** e **Categoria** e as abas **Todos**, **Previstos** e **Internacionais**, cada uma com a contagem. O menu de cada linha está em [Lançamentos e IOF](https://docs.finance.kobana.com.br/pt/pt/cartoes/lancamentos-e-iof.md#o-menu-do-lan%C3%A7amento). ## Alterar a data de fechamento[​](#alterar-a-data-de-fechamento "Link direto para Alterar a data de fechamento") O banco não fecha a fatura sempre no mesmo dia. Cada fatura guarda o **próprio** fechamento: nasce **Previsto**, calculado pelas datas do cartão, e passa a **Confirmado** quando alguém confere a data no app ou na fatura do banco. **Alterar data de fechamento** (ou o lápis do fechamento) abre *"Data de fechamento · fatura de …"*, com a data atual (**Fechamento previsto** ou **Fechamento confirmado**) e o campo **Data de fechamento no banco**. *"Compras feitas até a data de fechamento, inclusive, ficam nesta fatura. As do dia seguinte em diante vão para a próxima."* Ao escolher a data, o diálogo mostra **antes de aplicar** o que vai acontecer: * *"3 lançamentos mudam de fatura"*, com cada um e para onde vai; * *"A fatura de Jan/27 passa a começar em …"*; * ou, se nada muda, *"Nenhum lançamento muda de fatura."* Mantendo a mesma data do fechamento previsto, nada se move: *"Nenhum lançamento muda de fatura: o fechamento só passa a Confirmado."* — e o botão vira **Confirmar data**. Com outra data, **Aplicar nova data**. *"A mudança fica no histórico da fatura, com quem alterou."* observação **O que acompanha a mudança e o que não.** As parcelas acompanham a primeira: se a parcela 1 muda de fatura, as seguintes mudam junto, uma fatura depois da outra. Um lançamento **movido à mão** fica onde está, e o **saldo anterior** de um pagamento parcial também. Fatura fechada nunca recebe nem perde lançamento pela mudança da data de fechamento. **Os limites.** A nova data de fechamento não pode ser antes do começo do período da fatura nem chegar à data de fechamento da seguinte. Fatura fechada, conferida ou paga não aceita alteração: reabra-a antes (ver [Reabrir](https://docs.finance.kobana.com.br/pt/pt/cartoes/fechar-conferir-pagar.md#reabrir)). aviso **A fatura fecha na data prevista se ninguém confirmar.** O fechamento automático da madrugada não espera a confirmação. Se o banco fechou depois do previsto, as compras desses dias caem na fatura seguinte; para acertar, reabra a fatura e altere a data de fechamento. ## Histórico da fatura[​](#histórico-da-fatura "Link direto para Histórico da fatura") O ícone do relógio abre o **Histórico** da fatura: *"Tudo o que aconteceu nesta fatura, do mais recente ao mais antigo, com quem fez e por onde."* | Evento | Como aparece | | ----------------------------- | ------------------------------------------------------------------------------------- | | Data de fechamento confirmada | *"Data de fechamento confirmada: 02/12"* | | Data de fechamento alterada | *"Data de fechamento alterada de 02/12 para 04/12 · 3 lançamentos mudaram de fatura"* | | Fechada | *"Fechada · total R$ 8.908,95 · conta a pagar criada"* | | Conferida | *"Conferida: total do banco R$ 8.908,95"* | | Reaberta | *"Reaberta (estava Paga)"* | | Paga | *"Paga: R$ 8.908,95 de Itaú — Conta Corrente"* | | Pagamento desfeito | *"Pagamento desfeito: R$ 8.908,95"* | O que o fechamento automático fez aparece como **Sistema**; o resto, com o e-mail de quem fez e o canal (tela, API ou MCP). --- # Fechar, conferir e pagar ## Fechar[​](#fechar "Link direto para Fechar") **A fatura fecha automaticamente.** Toda madrugada o sistema fecha a fatura aberta cuja data de fechamento já passou e abre a seguinte. A linha da fatura aberta avisa quando: *"Fecha automaticamente na madrugada de 03/12/2026 e gera uma conta a pagar de R$ 6.348,80, com vencimento em 09/12."* **Fechar fatura agora** antecipa isso: *"Gera agora a conta a pagar de …, com vencimento em …. Se você não fechar, ela fecha automaticamente na madrugada de …. Compras desta fatura lançadas depois de fechar vão para a próxima fatura aberta."* ### A conta a pagar da fatura[​](#a-conta-a-pagar-da-fatura "Link direto para A conta a pagar da fatura") No cartão de crédito, fechar cria uma [conta a pagar](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/.md): | Campo | Valor | | ------------------------ | -------------------------------------------------------- | | Descrição | *"Fatura Itaú Empresas Visa — 11/2026"* | | Fornecedor | O **Fornecedor da fatura** do cartão, ou o banco emissor | | Valor | O total da fatura | | Vencimento e competência | O vencimento da fatura | | Pagar via | A **Conta que paga a fatura**, do cadastro do cartão | | Forma de pagamento | A do cartão | | Categoria | Nenhuma: cada compra já está na categoria dela | Ela aparece em Contas a pagar com a origem **Fatura de cartão**. Com a [aprovação de pagamento](https://docs.finance.kobana.com.br/pt/pt/aprovar-pagamentos/.md) ligada, entra na fila de aprovação como qualquer conta a pagar. aviso **O valor dessa conta a pagar é o da fatura.** Ele muda pela conferência (vira o total do banco) e pelo pagamento parcial — nunca editando a conta a pagar, que recusa a mudança de valor. Ela também não pode ser excluída enquanto a fatura existir. Descrição, vencimento e o resto continuam editáveis. O pré-pago e o benefício fecham **sem** conta a pagar, e uma fatura com total zero ou negativo também. ## Conferir com o banco[​](#conferir-com-o-banco "Link direto para Conferir com o banco") Com a fatura do banco na mão, **Conferir com o banco** abre *"Conferir com a fatura do banco"*: o **Total no sistema**, a **Diferença** ao vivo, o **Total da fatura do banco** e o **Pagamento mínimo** (opcional). | Resultado | O que acontece | | --------- | --------------------------------------------------------------------------------------------------------------------------- | | Bate | *"Bate: a fatura vira Conferida e a conta a pagar passa a …."* | | Não bate | *"Não bate: os valores ficam salvos e a fatura continua Fechada, mostrando a diferença, até que o que falta seja lançado."* | Para fazer bater: lance o que faltou (uma compra que chegou atrasada, juros e tarifas, um estorno), confirme as cobranças recorrentes com o valor real, ou ajuste a cotação das compras internacionais. Depois, confira de novo. ## Pagar[​](#pagar "Link direto para Pagar") **Pagar fatura** — na fatura fechada ou conferida, ou pelo **Pagar** do card na lista — abre o pagamento: ![Pagar a fatura fechada, integral ou outro valor](/pt/assets/images/40-card-pay-statement-22f1fa39047812cd7b792b40f1b955fd.png) | Opção | O que faz | | --------------- | ------------------------------------------------------------------------------------------------- | | **Integral** | *"Quita a fatura."* | | **Mínimo** | Só quando o pagamento mínimo foi informado na conferência. *"O resto vai para a próxima fatura."* | | **Outro valor** | Qualquer valor até o total da fatura. | **Sai de** é a conta que paga a fatura (pode trocar) e **Data do pagamento**, o dia em que o dinheiro saiu. **Registrar pagamento** grava uma **transferência** da conta que paga a fatura para a conta do cartão, dá baixa na conta a pagar e deixa os lançamentos da fatura **Conciliados**. dica **Pagar por qualquer porta dá no mesmo.** Dar baixa na conta a pagar da fatura em Contas a pagar, pela API, ou pela confirmação do banco quando o pagamento foi enviado pela [Kobana](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md) produz exatamente o mesmo resultado: a transferência, a fatura paga e os lançamentos conciliados. *"Vai pagar pelo banco? Envie a conta a pagar pela Kobana: quando o banco confirmar, o pagamento é registrado aqui automaticamente."* ### Pagamento parcial[​](#pagamento-parcial "Link direto para Pagamento parcial") Pagando menos que o total, a fatura fica **Paga em parte** e a diferença vai para a fatura seguinte como **Saldo anterior** — o lançamento *"Saldo da fatura 11/2026"*. O diálogo avisa: *"Os … que faltam vão para a fatura seguinte, como saldo anterior. Quando juros e multa aparecerem na fatura, lance-os como Juros e tarifas."* Os juros não são calculados pelo sistema. ### Desfazer o pagamento[​](#desfazer-o-pagamento "Link direto para Desfazer o pagamento") **Desfazer pagamento** pede confirmação: *"Apaga o pagamento de … (a transferência para a conta do cartão) e o saldo que foi para a fatura seguinte. A fatura volta para Conferida ou Fechada."* A conta a pagar volta a pendente, com o total da fatura. Se a fatura que recebeu o saldo anterior já fechou, o desfazer é recusado: reabra-a primeiro. ## Reabrir[​](#reabrir "Link direto para Reabrir") **Reabrir** volta a fatura para **Aberta** — para lançar uma compra que faltou, corrigir valor ou data, ou alterar a data de fechamento. *"A fatura volta para Aberta, e o histórico registra quem reabriu e quando. A conta a pagar continua; o total é recalculado quando ela fechar de novo."* Numa fatura paga: *"O pagamento continua registrado, o saldo que tinha ido para a fatura seguinte é retirado e os lançamentos voltam para Realizado. O total é recalculado quando ela fechar de novo."* Ao fechar de novo, a fatura volta a **Paga** se o pagamento cobre o novo total, ou fica **Paga em parte** com a diferença na seguinte. Só há uma fatura aberta por cartão: a que estava aberta volta a ser futura enquanto a reaberta não fechar. Se a data de fechamento da reaberta já passou, ela fecha de novo na madrugada seguinte — feche antes, com **Fechar fatura agora**, se terminou os ajustes. ## Pré-pago e benefício[​](#pré-pago-e-benefício "Link direto para Pré-pago e benefício") **Recarregar** (no card da lista ou no cabeçalho do cartão) registra uma recarga: o valor, a data e de qual conta sai (**Sai de**, a conta que faz as recargas do cartão). *"Entra como crédito na fatura aberta (…). O saldo passa a …."* A recarga é uma transferência da conta bancária para a conta do cartão; excluí-la na fatura apaga a transferência. A fatura do pré-pago tem o mesmo ciclo e a mesma conferência, mas fecha sem conta a pagar: conferida, ela termina em **Conferida**. ## No fluxo de caixa[​](#no-fluxo-de-caixa "Link direto para No fluxo de caixa") **O cartão não é caixa.** No [fluxo de caixa](https://docs.finance.kobana.com.br/pt/pt/dashboard/.md#aba-fluxo-de-caixa): * **O que já aconteceu** — a saída é o **pagamento** da fatura, no dia do pagamento, pela conta que paga a fatura. As compras não entram uma a uma. * **O que vem pela frente** — a fatura aberta e as futuras entram pelo **total previsto**, no **vencimento**, na conta que paga a fatura. Depois de fechada, a fatura entra pela conta a pagar dela (sem contar duas vezes). * **Pré-pago** — a saída de caixa é a recarga; a fatura nunca entra na projeção. Escolhendo a conta do cartão no seletor **Conta**, as abas de projeção e fluxo de caixa mostram um aviso no lugar do gráfico — *"Itaú Empresas Visa é um cartão: ele não entra no fluxo de caixa"* — com o atalho **Ver** para a conta que paga a fatura. Os saldos somam só as contas de caixa; os cartões aparecem depois, em cinza. A **Visão geral** (desempenho do mês, maiores despesas) continua vendo cada compra na data dela: é a visão da despesa, não do caixa. --- # Lançamentos e IOF **Novo lançamento**, no cabeçalho do cartão, abre o diálogo de lançamento. O tipo escolhido no topo muda os campos: | Tipo | Para quê | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **À vista** | Uma compra, numa fatura só. | | **Parcelado** | Uma compra dividida em parcelas, uma por fatura. | | **Recorrente** | Uma assinatura cobrada todo mês, trimestre ou ano. *"Cria uma cobrança recorrente: o valor previsto aparece em cada fatura, e você confirma o valor real quando a fatura chegar."* Ver [Recorrências](https://docs.finance.kobana.com.br/pt/pt/cartoes/recorrencias.md). | | **Estorno** | O banco devolveu o valor de uma compra. *"Abate o valor da fatura."* | | **Juros e tarifas** | *"Juros, multa, anuidade e IOF de financiamento. Entra na fatura como despesa, na categoria escolhida."* | Os campos comuns são **Data da compra**, **Valor**, **Descrição**, **Fornecedor**, **Categoria** e **Centro de classificação** — os dois últimos já vêm com os padrões do cartão. **Ratear** divide o centro de classificação entre vários, como nas contas a pagar. Um lançamento **realizado** entra na hora na conta do cartão, em Minhas contas — e é ele que aparece em Lançamentos, na Visão geral e nos relatórios por categoria, na data da compra. ## Em qual fatura cai[​](#em-qual-fatura-cai "Link direto para Em qual fatura cai") Antes de salvar, o diálogo diz onde o lançamento vai parar: | Situação | O diálogo diz | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | A data está no período de uma fatura aberta ou futura | *"Cai na fatura de Dez/26, com vencimento em 09/12."* | | A fatura da data já fechou | *"A fatura de Nov/26 já fechou: o lançamento vai para a de Dez/26, que está aberta. A fatura fechada não muda."* | | A data é além das faturas criadas | *"Cai na fatura de …, que será criada."* | | A data é anterior à primeira fatura do cartão | *"A data é anterior à primeira fatura do cartão no sistema (…)."* — à vista, o lançamento é recusado. | observação **Fatura fechada não muda.** Uma compra que chega depois do fechamento — o banco demorou a lançar, ou alguém esqueceu — vai para a fatura aberta, com o aviso *"A fatura da data já fechou: o lançamento foi para a fatura aberta."* O total da fatura fechada, a conta a pagar dela e a conferência ficam como estavam. Para pôr a compra na fatura fechada, reabra-a antes (ver [Reabrir](https://docs.finance.kobana.com.br/pt/pt/cartoes/fechar-conferir-pagar.md#reabrir)). ## Parcelado[​](#parcelado "Link direto para Parcelado") Informe o **Valor total** e o **Número de parcelas**. O diálogo mostra a divisão — *"6 × R$ 1.500,00"*, ou *"1ª de R$ 33,34 + 2 × R$ 33,33"* quando não fecha nos centavos: **os centavos da divisão vão na primeira parcela**. E onde cada uma cai: *"Uma parcela por fatura, de Set/26 a Fev/27."* * A parcela **k** cai **k − 1** faturas depois da compra. * Uma compra anterior à **Data de início** do cartão lança só as parcelas que caem a partir da primeira fatura, com a numeração original (**4/10** a **10/10**): *"As parcelas anteriores à primeira fatura do cartão no sistema não serão lançadas."* * **Compra internacional não pode ser parcelada aqui.** Na tabela da fatura, cada parcela aparece com o número na coluna **Parcela** (**4/6**) e a data da compra original. ## Compra internacional[​](#compra-internacional "Link direto para Compra internacional") Marque **Compra internacional** e informe a **Moeda** e o **Valor em USD** (ou na moeda escolhida). O diálogo calcula o resto ao vivo: | Campo | De onde vem | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cotação** | Estimada: a PTAX de venda do Banco Central do dia útil anterior à compra, mais o **Spread do banco** definido no cartão — *"Estimativa: cotação oficial (PTAX) de 03/11, 5,2600, mais 4% de spread do banco. Troque pela cotação real quando a fatura chegar."* | | **Alíquota de IOF** | Só leitura. (i) *"A alíquota oficial na data da compra, ou a do cartão, se ele tiver uma. Fica gravada no lançamento, mesmo se a alíquota mudar depois."* | | **IOF cobrado pelo banco** | Opcional. (i) *"Se o IOF da fatura do banco for diferente do calculado, digite o valor dela aqui."* | | **Total na fatura** | *"US$ 135,00 × 5,4700 = R$ 738,45 + IOF R$ 25,85"* | **O IOF faz parte do lançamento.** Ele entra no total da fatura, na conta do cartão e nos relatórios na mesma categoria e no mesmo centro de classificação da compra — e, no rateio, cada fatia leva a sua parte. O [relatório de IOF pago](https://docs.finance.kobana.com.br/pt/pt/cartoes/relatorios.md#iof-pago) o separa como imposto. **Estimada até a fatura do banco chegar.** Enquanto a cotação for a estimada, a tabela mostra *"estimada"* embaixo do valor. Quando a fatura do banco chegar, edite o lançamento com a cotação (ou o IOF) que veio nela. dica **O Banco Central fora do ar não trava o lançamento.** Se a PTAX não responde, a cotação fica em branco com o aviso *"O Banco Central não respondeu agora. Digite a cotação para lançar."* **Uma alíquota nova não muda o passado.** A alíquota fica gravada em cada compra: quando a tabela muda, as compras anteriores mantêm a que valia na data delas. ## Estorno[​](#estorno "Link direto para Estorno") Escolha a **Compra estornada** e o valor. O estorno entra negativo na fatura aberta e abate o total. Num estorno de compra internacional, moeda, cotação e alíquota vêm da original; marque **IOF devolvido** só se a fatura do banco devolveu o IOF também. O ícone (i) do campo lembra: *"Marque só se a fatura do banco também devolveu o IOF. Isso varia de banco para banco."* **Estornar**, no menu de uma compra realizada, abre o diálogo já com a original escolhida. ## O menu do lançamento[​](#o-menu-do-lançamento "Link direto para O menu do lançamento") | Ação | Quando aparece | | --------------------------- | ---------------------------------------------- | | **Editar** | Sempre, exceto no saldo anterior | | **Mover** | Em fatura aberta ou futura | | **Antecipar** | Em parcelas | | **Estornar** | Em compras já realizadas | | **Marcar como não cobrado** | Numa cobrança recorrente ainda prevista | | **Excluir** | Em fatura aberta ou futura, exceto recorrentes | ### Editar[​](#editar "Link direto para Editar") *"Valor e data mudam só em fatura aberta ou futura."* Numa fatura fechada, o diálogo avisa: *"A fatura de … já fechou: valor e data ficam travados. Descrição, fornecedor e classificação seguem editáveis."* **Numa série** — parcelas ou cobranças de uma recorrência —, salvar pergunta o alcance: | Opção | Parcelas | Recorrência | | ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Só esta** | Muda só esta parcela | Muda só a cobrança deste mês | | **Esta e as próximas** | Desta até a última | Muda a recorrência e as cobranças previstas dali em diante, menos as que já foram editadas | | **Todas** | A compra inteira | Muda a recorrência e todas as cobranças previstas, menos as que já foram editadas. *"O que já foi confirmado não muda."* | Uma opção cujo alcance pega uma parcela de fatura fechada aparece desabilitada, com o motivo: *"A parcela 2/6 está na fatura de Out/26, que já fechou: reabra-a para mudar o valor ou a data dela."* A data de um parcelado só muda com **Todas**; numa recorrência, a data, o rateio, a cotação, o IOF e as notas valem só para aquela cobrança. ### Mover[​](#mover "Link direto para Mover") Leva o lançamento para outra fatura aberta ou futura. *"O lançamento fica fixo na fatura escolhida, mesmo se a data de fechamento mudar."* — por isso ele ganha o cadeado na tabela. ### Antecipar[​](#antecipar "Link direto para Antecipar") Quando o banco antecipa parcelas (com ou sem desconto), **Antecipar** leva as últimas parcelas que estão em faturas futuras para a fatura aberta, e elas ficam fixas nela. O **Desconto do banco**, se houver, entra como estorno *"Desconto por antecipação"*. ### Excluir[​](#excluir "Link direto para Excluir") *"O lançamento sai da fatura e da conta do cartão."* Numa compra parcelada, o alcance pergunta quais parcelas saem. As cobranças de uma recorrência não se excluem: use **Marcar como não cobrado** ou encerre a recorrência. --- # Recorrências Assinaturas e serviços cobrados todo mês no cartão — software, hospedagem, e-mail — viram **recorrências**. Cada recorrência põe uma cobrança **prevista** em cada fatura aberta e futura; quando a fatura do banco chega, você confirma o valor real. ![Recorrências do cartão, com a sugestão de atualizar o valor](/pt/assets/images/39-card-recurrences-030b4e754f9a29cbcf8ce1c954c6e295.png) ## Criar[​](#criar "Link direto para Criar") Na aba **Recorrências** do cartão, **Nova recorrência** — ou **Novo lançamento** com o tipo **Recorrente**. Os campos: | Campo | Observações | | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **Primeira cobrança** | A partir de quando a assinatura é cobrada. | | **Valor** | O valor esperado de cada cobrança. Numa assinatura em moeda estrangeira, o valor na moeda. | | **Dia da cobrança** | O dia do mês em que a assinatura é cobrada no cartão (limitado ao último dia do mês). | | **Frequência** | **Mensal**, **Trimestral** ou **Anual**. | | **Data de término** | (i) *"Em branco, a cobrança segue sem data para acabar. Se você encerrar depois, as cobranças previstas a partir daí são canceladas."* | | **Descrição** · **Fornecedor** · **Categoria** · **Centro de classificação** | Copiados para cada cobrança prevista. | *"Uma cobrança prevista em cada fatura, a partir da de Dez/26."* Uma fatura fechada nunca recebe cobrança prevista nova. observação **A cobrança prevista ainda não é despesa.** Ela entra no **Total previsto** da fatura e no limite usado, mas não na conta do cartão, em Lançamentos nem na Visão geral. Vira despesa quando é confirmada. Numa assinatura em moeda estrangeira, a cobrança prevista é convertida pela PTAX do dia útil anterior mais o **Spread do banco** do cartão. Se o Banco Central não responde e não há cotação guardada, as cobranças previstas esperam: *"Sem cotação de USD agora: as cobranças previstas entram quando o Banco Central responder."* ## Confirmar com o valor real[​](#confirmar-com-o-valor-real "Link direto para Confirmar com o valor real") Na fatura, **Confirmar cobranças recorrentes (3)** abre a lista das cobranças previstas daquela fatura: *"Digite o valor que veio na fatura do banco. Enter confirma e passa para o próximo. Em branco, confirma o valor previsto."* * Uma variação de mais de 5% sobre o previsto aparece em âmbar. * Numa assinatura internacional, informe também a **Cotação real**. * **Não cobrado** tira a cobrança do total da fatura: o banco não cobrou neste mês. A confirmação vale também com a fatura **fechada** — é assim que se confere com a fatura do banco. Uma fatura conferida ou paga não aceita mais confirmação: reabra-a antes. Cada cobrança também tem ações no menu da linha da fatura: **Editar** (para confirmar uma só) e **Marcar como não cobrado**. ## A aba Recorrências[​](#a-aba-recorrências "Link direto para A aba Recorrências") | Coluna | O que traz | | --------------------- | ---------------------------------------------------- | | **Descrição** | Com o fornecedor e a categoria embaixo | | **Valor** | O valor esperado, na moeda da recorrência | | **Cobrança** | *"dia 4 · mensal"* | | **Próxima cobrança** | A data da próxima cobrança e a fatura em que ela cai | | **Último valor real** | O último valor confirmado e o mês | | **Variação** | Do último valor real sobre o previsto | | **Status** | **Ativa** ou **Encerrada** | Busca, as abas **Ativas** e **Encerradas** e o botão **Nova recorrência**. A aba **Recorrências** do topo mostra quantas estão ativas. ### A sugestão de atualizar o valor[​](#a-sugestão-de-atualizar-o-valor "Link direto para A sugestão de atualizar o valor") Quando as **três últimas** cobranças confirmadas vieram todas mais de 5% acima (ou abaixo) do previsto, um aviso no alto da aba propõe a média delas: > *"Hospedagem dos sites veio mais de 5% acima do previsto nos últimos 3 meses (média R$ 947,90). Atualizar o valor da recorrência?"* **Atualizar para R$ 947,90** muda o valor da recorrência e das cobranças previstas que ainda não foram editadas. **Agora não** esconde o aviso até a sugestão mudar. Um mês **não cobrado** no meio interrompe a sequência, e não há sugestão se a média ficar a menos de 5% do valor atual — o caso de uma assinatura em dólar estável com o câmbio oscilando. ## Editar, encerrar, excluir[​](#editar-encerrar-excluir "Link direto para Editar, encerrar, excluir") | Ação | O que faz | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Editar** | *"As cobranças previstas que ainda não foram editadas passam a seguir a recorrência. O que já foi confirmado não muda."* | | **Encerrar** | Pede a data do fim. *"As cobranças previstas depois desta data são canceladas. O que já foi confirmado não muda."* | | **Excluir** | *"… e as cobranças previstas dela saem das faturas. Só dá para excluir enquanto nenhuma cobrança foi confirmada; depois disso, encerre a recorrência."* | Editar uma cobrança na fatura com o alcance **Esta e as próximas** ou **Todas** também atualiza a recorrência — ver [Lançamentos e IOF](https://docs.finance.kobana.com.br/pt/pt/cartoes/lancamentos-e-iof.md#editar). ## No relatório[​](#no-relatório "Link direto para No relatório") O relatório [Previsto × realizado](https://docs.finance.kobana.com.br/pt/pt/cartoes/relatorios.md#previsto--realizado) compara, mês a mês, o que cada recorrência previa e o que foi cobrado. --- # Relatórios A pílula **Relatório** — na lista de cartões ou na tela de um cartão — abre **Gerar relatório** com dois tipos: **IOF pago** e **Previsto × realizado**. Aberto pela tela de um cartão, ele já vem com esse cartão no filtro e no tipo da aba em que você estava. | Passo | Opções | | ---------------- | ----------------------------------------------------------------------------------------------- | | **Tipo** | **IOF pago** ou **Previsto × realizado** | | **Detalhamento** | **Sintético** (os grupos) ou **Analítico** (os grupos e, embaixo de cada um, os lançamentos) | | **Agrupar por** | Só no IOF: **Mês**, **Cartão**, **Categoria** ou **Fornecedor** | | **Período** | Obrigatório. No IOF, pela **data da compra**; no previsto × realizado, pelo **mês da cobrança** | | **Filtros** | **Cartões**, **Categoria** e **Fornecedor** (opcionais) | **Incluir gráfico** acrescenta o gráfico acima da tabela. **Gerar relatório** abre o relatório numa página própria, pronta para imprimir. ![IOF pago nas compras internacionais, por fornecedor](/pt/assets/images/41-card-iof-report-b5756329b887818c307d8f1923d7b116.png) ## IOF pago[​](#iof-pago "Link direto para IOF pago") O IOF das compras internacionais tratado como imposto: para cada grupo, o **Valor da compra** (em reais, sem o IOF), o **IOF**, a **Alíquota** e a quantidade de compras, com o total no fim. * Entram só lançamentos **realizados** ou **conciliados** com IOF. Um previsto ainda não pagou imposto nenhum. * Um estorno com IOF devolvido **abate** do grupo. * **Por categoria**, uma compra rateada entre categorias reparte o IOF na mesma proporção. Filtrando por categoria, conta só a parte da compra nas categorias escolhidas. * No **Analítico**, cada compra mostra a moeda, o valor na moeda, a cotação, o valor da compra, a alíquota gravada nela e o IOF. observação **A alíquota do grupo é a efetiva: o IOF dividido pelo valor da compra.** Como o IOF de cada compra é arredondado ao centavo, ela pode sair como *3,4999%* num grupo de compras a 3,5%. A de cada compra, no analítico, é a alíquota gravada nela. ## Previsto × realizado[​](#previsto--realizado "Link direto para Previsto × realizado") Para cada recorrência, mês a mês: o **Previsto** (o valor esperado), o **Realizado** (o que foi confirmado; não cobrado conta zero), a **Diferença** e a **Diferença (%)**, sempre em reais e sem IOF — a mesma conta da coluna **Variação** da aba Recorrências. Um mês ainda previsto entra no previsto e fica sem realizado nem diferença. A coluna **Meses** mostra quantos já foram confirmados: *"6 (2 a confirmar)"*. *"A diferença compara só os meses já confirmados; o previsto soma todos."* ## Exportar em CSV ou XLSX[​](#exportar-em-csv-ou-xlsx "Link direto para Exportar em CSV ou XLSX") Na página do relatório, **Exportar para Excel** abre a exportação com a escolha do **Formato**: CSV ou XLSX. As colunas são as mesmas da tela, nos dois formatos: * **CSV** no padrão brasileiro (ponto e vírgula, vírgula decimal), como os outros relatórios do sistema; * **XLSX** com valores numéricos de verdade — moeda, porcentagem e data formatadas, cabeçalho congelado —, pronto para somar e filtrar na planilha. ## Pela API e pelo MCP[​](#pela-api-e-pelo-mcp "Link direto para Pela API e pelo MCP") Os mesmos números saem de [`GET /card-transactions/aggregates`](https://docs.finance.kobana.com.br/pt/pt/api/v1/aggregate-card-transactions), agrupando por `card`, `statement`, `category`, `person` ou `month`, com `sum_iof_amount` e `sum_base_amount` em cada grupo, e da ferramenta `finance_card_transactions_aggregates` do [servidor MCP](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/accounts.md#card_transactions). --- # Categorias Categorias (`/categories`) classificam contas a pagar, contas a receber e lançamentos. A estrutura é hierárquica, em até **três níveis**. ![Listagem de categorias](/pt/assets/images/11-categories-432d5482e17e741622ceddba7fedcb4c.png) ## Campos[​](#campos "Link direto para Campos") | Campo | Obrigatório | Descrição | | ----------------- | ----------- | -------------------------------- | | **Nome** | Sim | Nome da categoria | | **Tipo** | Sim | **Receita** ou **Despesa** | | **Empresa** | Sim | A empresa dona da categoria | | **Categoria pai** | Não | Categoria superior na hierarquia | **Em uma subcategoria, Tipo e Empresa não aparecem** — são herdados do pai. Você só escolhe os dois ao criar uma categoria raiz. ## Tipo: receita ou despesa[​](#tipo-receita-ou-despesa "Link direto para Tipo: receita ou despesa") * **Despesa** — aparece no seletor de contas a pagar e de lançamentos de saída. * **Receita** — aparece no seletor de contas a receber e de lançamentos de entrada. **Uma subcategoria é sempre do mesmo tipo do pai.** Não há como misturar: o sistema recusa a gravação com *"Uma subcategoria precisa ter o mesmo tipo da categoria pai"*. Mudar o tipo de uma categoria **raiz** é permitido, e a mudança **desce para toda a subárvore** — filhos e netos acompanham. ## Hierarquia[​](#hierarquia "Link direto para Hierarquia") ``` Despesas Operacionais (Despesa) ├── Aluguel ├── Energia e Água │ ├── Energia Elétrica │ └── Água e Esgoto └── Folha de Pagamento ├── Salários └── Encargos Receitas (Receita) ├── Mensalidades └── Serviços ├── Consultoria └── Suporte ``` observação **O limite é de três níveis.** No terceiro nível o botão **Adicionar subcategoria** deixa de aparecer, e uma tentativa por outro caminho é recusada com *"Limite de 3 níveis de hierarquia atingido."* ## A tela[​](#a-tela "Link direto para A tela") Categorias são exibidas em **cards**, não em tabela. Cada card é uma categoria raiz, com suas subcategorias listadas dentro. * **Busca** por nome. Um resultado em nível 2 ou 3 traz o card inteiro do ancestral para a tela, para você ver onde ele está. * **Abas** com contadores: **Todas** · **Despesas** · **Receitas**. Os contadores contam apenas categorias raiz — é o número de cards. * **Duplo clique no nome** abre a edição ali mesmo, sem diálogo. * **Badges:** **Receita** ou **Despesa** no card raiz, e **Não usada** quando nem a categoria nem nenhuma subcategoria dela tem vínculos. * A contagem de lançamentos de um card **soma a subárvore** — o número no pai inclui o que está nos filhos. Com o seletor de empresa em "Todas", os cards são agrupados em seções recolhíveis por empresa. Escolhendo uma empresa específica, vira uma grade única. ## Filtrar por categoria em outras telas[​](#filtrar-por-categoria-em-outras-telas "Link direto para Filtrar por categoria em outras telas") Ao filtrar lançamentos ou títulos por uma categoria pai, **as subcategorias não entram automaticamente**. Dentro do filtro de Categoria existe a opção **Incluir subcategorias** — marque para que o filtro alcance a subárvore inteira. A opção **Sem categoria**, no mesmo filtro, é mutuamente exclusiva: marcá-la desabilita o **Incluir subcategorias**. ## Rateio[​](#rateio "Link direto para Rateio") Um título pode ser dividido entre **várias categorias** — por exemplo, 60% em **Aluguel** e 40% em **Energia**. O atalho **Rateio**, ao lado do campo **Categoria** nos formulários de **contas a pagar**, **contas a receber** e **lançamentos**, abre o diálogo **"Rateio por categoria"**. O diálogo funciona exatamente como o do centro de classificação — **"Forma de rateio"** em percentual ou valor, o **"Total restante"** que precisa fechar, sem categoria repetida. Ver [Rateio em Centros de classificação](https://docs.finance.kobana.com.br/pt/pt/centros-de-classificacao/.md#rateio). Os dois rateios são **independentes**: um título pode ser rateado por categoria, por centro, pelos dois ou por nenhum. O que muda com um título rateado: * **Relatórios e visão geral** somam cada categoria pela sua fatia: um título de R$ 1.000 rateado 60/40 entra com R$ 600 em Aluguel e R$ 400 em Energia — inclusive nas ocorrências futuras de uma série recorrente. * **Filtro por categoria** encontra o título por **qualquer** das categorias dele. **Sem categoria** não traz título rateado. * **Relatórios filtrados por categoria** somam só a parte do título nas categorias filtradas: filtrar **Energia** traz R$ 400 do título acima, não R$ 1.000. O mesmo vale para o filtro por centro de classificação. * **Listagens** mostram a primeira categoria do rateio, com um **+N** indicando as demais. * **Parcelas, recorrência e baixa** herdam o rateio — o lançamento gerado pela baixa sai rateado igual. * **Regras automáticas não desfazem o rateio**: a regra mantém as categorias de um título já rateado. A **classificação em lote** (**Classificar selecionados**), por ser uma ação explícita, troca o rateio por uma categoria só. Escolher uma categoria única para um título que estava rateado desfaz o rateio. ## Importação de CSV[​](#importação-de-csv "Link direto para Importação de CSV") A importação aceita **uma categoria por linha** — o rateio por categoria se configura no formulário. Na prévia da importação, cada categoria da planilha aparece com o que vai acontecer: a que já existe é ligada; a que ainda não existe vem marcada para **criar** (se você tiver permissão de criar categorias); e um nome quase igual a uma existente — só muda acento, maiúscula ou espaço — vem marcado para **usar a existente**. Dá para trocar cada escolha, inclusive para **deixar em branco**. A categoria criada na importação é **raiz**, do tipo do lado do arquivo: **Despesa** para contas a pagar, **Receita** para contas a receber e, nos lançamentos, o tipo de cada linha. A busca é pelo nome da categoria, não pelo caminho na árvore. Detalhes nas páginas de importação de [lançamentos](https://docs.finance.kobana.com.br/pt/pt/lancamentos/importacao-csv.md), [contas a pagar](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/importacao-csv.md) e [contas a receber](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/importacao-csv.md). ## Excluir[​](#excluir "Link direto para Excluir") perigo **A exclusão apaga as subcategorias junto.** Excluir uma categoria remove ela **e toda a sua subárvore**. Os lançamentos, contas a pagar e contas a receber vinculados **não são apagados**: eles ficam **sem categoria**. **A única coisa que bloqueia a exclusão é o rateio.** Se a categoria — ou alguma subcategoria dela — é uma das fatias de um título rateado, a exclusão é recusada com *"Esta categoria está no rateio de lançamentos e não pode ser excluída. Ajuste o rateio antes."* Tirar a categoria do rateio deixaria a soma das fatias sem fechar, então é você quem decide para onde vai essa parte. O diálogo diz exatamente isso antes de você confirmar: *"Isso vai excluir esta categoria e todas as subcategorias. Esta ação não pode ser desfeita."*, seguido do que encontrou — *"Esta categoria está vinculada a 12 lançamentos, 3 contas a pagar (15 no total). Esses lançamentos ficarão sem categoria após a exclusão."* Se não houver vínculo, ele também diz. O aviso é **informativo, não impede**. Se quiser preservar a classificação, reclassifique os registros antes: nas telas de Lançamentos, Contas a pagar e Contas a receber, selecione as linhas e use **Classificar selecionados**. --- # Centros de classificação Centros de classificação (`/classification-centers`) permitem alocar despesas e receitas a departamentos, projetos ou áreas da empresa. Um único título pode ser dividido entre vários centros — o **rateio**. ![Listagem de centros de classificação](/pt/assets/images/12-classification-centers-f921d41ec147e7694902ecedc8a58f6b.png) ## Campos[​](#campos "Link direto para Campos") | Campo | Descrição | | ------------- | -------------------------------------------------------------------------------- | | **Nome** | Obrigatório | | **Tipo** | Obrigatório. **Custo**, **Receita** ou **Ambos** | | **Empresa** | Obrigatório. O centro pertence a uma empresa | | **Descrição** | Opcional | | **Ativo** | Liga/desliga. *"Centros de classificação inativos não aparecem nos formulários"* | Um centro **Ambos** serve às duas polaridades — útil para projetos ou áreas que concentram custos e receitas. **Na listagem, "Ambos" não tem selo próprio.** Um centro desse tipo aparece com **dois** selos lado a lado, **Custo** e **Receita**, cada um na cor da sua polaridade. Lê-se como "serve aos dois", não como um terceiro tipo. ## Ativo e Inativo[​](#ativo-e-inativo "Link direto para Ativo e Inativo") A coluna de status mostra **Ativo** ou **Inativo**. **Desativar não some da listagem.** O centro continua lá, com o selo **Inativo**. A promessa *"não aparecerá em novos lançamentos"* é sobre os **seletores**: ele sai dos formulários de contas a pagar, receber e lançamentos, mas o histórico que já o referencia permanece intacto. ## Exclusão[​](#exclusão "Link direto para Exclusão") O caminho depende de o centro estar em uso, e a tela decide por você: **Sem vínculo** — diálogo **"Excluir centro de classificação?"**: *"Isso vai excluir este centro de classificação. Esta ação não pode ser desfeita."* **Em uso** — não há exclusão. O diálogo é **"Centro de classificação em uso"**: > *"Este centro de classificação está em uso por lançamentos e não pode ser excluído. Deseja desativá-lo? Ele continuará no histórico mas não aparecerá em novos lançamentos."* O botão é **"Desativar"**. Ou seja: o produto **converte a exclusão em desativação** — não existe um caminho de exclusão forçada que largue os lançamentos sem centro. ## Rateio[​](#rateio "Link direto para Rateio") O rateio **não é configurado nesta tela**. Ele vive no diálogo **"Rateio por centro de classificação"**, aberto pelo atalho **Rateio** nos formulários de **contas a pagar**, **contas a receber** e **lançamentos**. ### Forma de rateio[​](#forma-de-rateio "Link direto para Forma de rateio") O campo **"Forma de rateio"** escolhe qual coluna você preenche: | Modo | Você preenche | O sistema calcula | | ----------------------------- | -------------------------- | ----------------- | | **Percentual (%)** *(padrão)* | O percentual de cada linha | O valor em reais | | **Valor (R$)** | O valor de cada linha | O percentual | A coluna do modo inativo fica **desabilitada** — as duas são sempre visíveis, mas só uma é editável. ### Fechando a conta[​](#fechando-a-conta "Link direto para Fechando a conta") O rodapé mostra o **"Total restante"**, em percentual e em reais, e fica vermelho enquanto não fechar. **"Salvar rateio"** só libera quando as três condições valem: * O total fecha (restante zero, com tolerância de um centavo). * **Toda linha tem um centro escolhido** — *"Todas as linhas precisam de um centro de classificação selecionado."* * **Não há centro repetido** — *"Centro de classificação repetido — cada linha precisa de um centro distinto."* observação **Editar uma linha não redistribui as outras.** Baixar um centro de 60% para 50% **não** repassa os 10% a ninguém: o "Total restante" passa a acusar 10%, e é você quem fecha a conta. O mesmo vale ao **adicionar** uma linha (entra com zero) e ao **remover** (a fatia dela vira sobra). O sistema **valida**; quem redistribui é você. ### O que o sistema rebalanceia sozinho[​](#o-que-o-sistema-rebalanceia-sozinho "Link direto para O que o sistema rebalanceia sozinho") Uma coisa, e só ela: **mudar o valor total do título**. Os percentuais são preservados e os valores em reais recalculados — a última linha absorve o resíduo de centavos, para a soma bater exata. É por isso que corrigir o valor de uma conta já rateada não desmonta o rateio. No modo **Valor (R$)** o efeito se inverte: os valores são preservados e os **percentuais** é que são recalculados. Uma **regra automática** não desfaz esse rateio — ver [Regras automáticas](https://docs.finance.kobana.com.br/pt/pt/regras-automaticas/.md). A categoria também pode ser rateada, de forma independente: ver [Categorias](https://docs.finance.kobana.com.br/pt/pt/categorias/.md#rateio). ## Rateio em parcelas[​](#rateio-em-parcelas "Link direto para Rateio em parcelas") Ao **criar** um título parcelado, o rateio é propagado para **todas** as parcelas do grupo, automaticamente. Ao **editar** uma parcela que já existe, não: o sistema **pergunta**. Alterando o rateio de uma parcela de um grupo, o diálogo de propagação mostra o que mudou e deixa você escolher quais parcelas irmãs herdam a mudança. Ver [Parcelas e recorrência](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/parcelas-e-recorrencia.md). ## Importação CSV[​](#importação-csv "Link direto para Importação CSV") A importação aceita **um único centro por linha**. O nome da coluna muda conforme o arquivo: | Importação | Coluna | Também aceita | | -------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | Contas a pagar / a receber | `cost_center_name` | `centro_custo`, `centro_de_custo`, `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` | | Lançamentos | `centro_custo` | `centro_de_custo`, `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` | Além desses nomes, uma coluna com a palavra **centro** no cabeçalho também é lida como centro de classificação. Na prévia, cada centro da planilha aparece com o que vai acontecer: o que já existe é ligado — sem diferenciar maiúsculas, e ignorando espaços nas pontas; o que ainda não existe vem marcado para **criar** (se você tiver permissão de criar centros de classificação); e um nome quase igual a um existente — só muda acento, maiúscula ou espaço — vem marcado para **usar o existente**. Dá para trocar cada escolha, inclusive para **deixar em branco**. O lado do arquivo decide **quais** centros valem: uma importação de contas a pagar só enxerga centros de **Custo**, e uma de contas a receber, só os de **Receita**. Um centro **Ambos** atende os dois. Havendo dois centros de mesmo nome, o do lado exato vence o **Ambos**. Um centro que só existe do outro lado vem marcado para deixar em branco; escolhendo criar, nasce outro centro, do lado do arquivo. O centro criado na importação é do lado do arquivo — nos lançamentos, um centro novo usado em entradas e saídas é criado uma vez só, do tipo **Ambos**. Detalhes nas páginas de importação de [lançamentos](https://docs.finance.kobana.com.br/pt/pt/lancamentos/importacao-csv.md), [contas a pagar](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/importacao-csv.md) e [contas a receber](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/importacao-csv.md). Para ratear entre vários centros, edite o título depois de importar. --- # Classificadores personalizados Classificadores personalizados (`/custom-classifiers`) são **dimensões de classificação que você cria** — como "Região", "Produto" ou "Canal" — para além dos eixos fixos (categoria e centro de classificação). Cada dimensão tem seus próprios **valores**, e um mesmo título pode receber **várias** dimensões ao mesmo tempo. *"Crie dimensões próprias (ex.: Região, Produto) e seus valores para classificar seus lançamentos."* ## Dois níveis: dimensão e valor[​](#dois-níveis-dimensão-e-valor "Link direto para Dois níveis: dimensão e valor") O catálogo tem dois níveis: * **Dimensão** — o eixo. Só tem um **nome** (ex.: "Região"). * **Valor** — cada opção dentro da dimensão (ex.: "Sul", "Sudeste"). Vive **dentro** da dimensão. Uma dimensão sem valores aparece na listagem marcada como **"Sem valores"** — ela existe, mas ainda não classifica nada até você adicionar ao menos um valor. ## Campos[​](#campos "Link direto para Campos") | Campo | Nível | Descrição | | -------------------- | -------- | ------------------------------------------------------------------ | | **Nome da dimensão** | Dimensão | Obrigatório. Ex.: "Região" | | **Empresa** | Dimensão | A dimensão pertence a uma empresa | | **Ativo** | Dimensão | Liga/desliga. *"Dimensões inativas não aparecem nos formulários."* | | **Valor** | Valor | Obrigatório. Ex.: "Sudeste" | | **Ativo** | Valor | Liga/desliga o valor individualmente | ## A tela[​](#a-tela "Link direto para A tela") A gestão fica em **Eixos → Classificadores personalizados**, em uma tabela onde cada linha é uma **dimensão** com seus valores em chips ao lado. * **Busca** por nome da dimensão (*"Buscar dimensão..."*). * **Nova dimensão** cria o eixo; o diálogo de valores adiciona, renomeia, ativa/desativa e exclui cada valor **ao vivo** (*"Adicionar valor"*, *"Novo valor..."*). * Um valor pode ser **ativado ou desativado** individualmente sem sair da dimensão. Quando não há nenhuma dimensão cadastrada, a tela mostra o estado vazio: *"Nenhum classificador cadastrado — Crie dimensões como 'Região' ou 'Produto' e seus valores para classificar seus lançamentos."* ## Ativo e inativo[​](#ativo-e-inativo "Link direto para Ativo e inativo") O flag **Ativo** existe nos dois níveis, e o efeito é o mesmo dos centros de classificação: **desativar não apaga**. * Uma **dimensão** inativa sai dos formulários, mas o histórico que já a referencia permanece. * Um **valor** inativo some do seletor **para novas escolhas** — mas, se um título já o usa, ele continua aparecendo ali como o valor selecionado, para não sumir do registro. ## Exclusão[​](#exclusão "Link direto para Exclusão") Como nos centros de classificação, o produto **converte a exclusão em desativação** quando há uso — não existe caminho que largue os lançamentos sem classificação. **Valor em uso** — não há exclusão: *"Valor está em uso por lançamentos. Desative em vez de excluir."* **Dimensão em uso** — o diálogo é **"Classificador em uso"**: > *"Este classificador está em uso por lançamentos e não pode ser excluído. Deseja desativá-lo?"* O botão é **"Desativar"**. Excluir a dimensão só é possível quando **nenhum** dos seus valores está atribuído a um título. ## Classificar um lançamento[​](#classificar-um-lançamento "Link direto para Classificar um lançamento") O bloco **"Classificadores personalizados"** aparece nos formulários de **contas a pagar**, **contas a receber** e **lançamentos** — as **três** telas, e também na visão de detalhe de cada uma. * Há **um seletor por dimensão ativa**. Todas as dimensões ativas ficam sempre visíveis. * A seleção é **um valor por dimensão** (seleção única) — diferente do rateio de centros de classificação, aqui não se divide um título entre valores. * O seletor faz **"selecionar ou criar"**: digitando um valor que ainda não existe, ele oferece *"Cadastrar valor '...' ao salvar"* e cria o valor na dimensão quando você grava o título. observação **A classificação não se espalha automaticamente para as parcelas 2 em diante.** Ao publicar um título parcelado, a dimensão fica na parcela âncora — o mesmo comportamento do centro de classificação. Para aplicar em várias linhas de uma vez, use **Classificar selecionados** nas listagens de Lançamentos, Contas a pagar e Contas a receber. ## Pesquisa avançada[​](#pesquisa-avançada "Link direto para Pesquisa avançada") Na pesquisa avançada de Lançamentos, Contas a pagar e Contas a receber há um facet único **"Classificador"**, que reúne os valores de **qualquer** dimensão. Marcando um ou mais valores, a busca traz os títulos que os carregam. O mesmo facet oferece **"Sem classificador"**, para achar os títulos que não receberam nenhuma dimensão. O facet só aparece quando existe ao menos uma dimensão cadastrada. ## Relatórios[​](#relatórios "Link direto para Relatórios") Os relatórios (normal e fiscal) aceitam **agrupar por classificador**: escolhida uma dimensão, cada linha do relatório é um valor dela, e os títulos sem aquela dimensão caem em **"(sem classificador)"** — nunca somem do total. ## Importação de CSV[​](#importação-de-csv "Link direto para Importação de CSV") Diferente de categorias e centros de classificação, a importação de CSV **cria os valores que faltam**. * Cada dimensão ativa vira uma **coluna** no arquivo, com o **nome da dimensão** no cabeçalho. * No momento da importação, o valor de cada linha é **procurado e criado se não existir** naquela dimensão. As dimensões em si **não** são criadas pela importação — cadastre-as antes; os valores, sim, nascem do arquivo. ## Na API[​](#na-api "Link direto para Na API") A API pública v1 expõe o catálogo em `/api/v1/custom-classifiers` (dimensões, com os valores em rotas aninhadas `/{id}/values`) sob o escopo `finance/custom_classifiers`, com o nível de acesso `read` para ler, `write` para criar e alterar e `delete` para excluir. Nos títulos, o campo `custom_classifications` acompanha **contas a pagar**, **contas a receber** e **lançamentos**: uma contagem na listagem, a lista completa no detalhe, e, na escrita, você informa o valor por id **ou** pelo nome (selecionar-ou-criar). Detalhes na **referência da API**. ## Origem Fintera[​](#origem-fintera "Link direto para Origem Fintera") Quando a integração com a Fintera está ativa, os classificadores e seus valores são **importados** de lá (somente leitura). O vínculo de um título nomeia o valor por **texto**, resolvido para o valor correspondente no Financeiro Inteligente no momento da importação. Ver [Integração Fintera](https://docs.finance.kobana.com.br/pt/pt/integracoes/fintera.md). --- # Autenticação :::caution Produtos não compartilham credenciais `KOBANA_TOKEN` guarda a credencial **de um produto por vez**. Um token do Financeiro Inteligente não autentica em nenhum outro produto Kobana, e vice-versa. ::: ## O token[​](#o-token "Link direto para O token") O Financeiro Inteligente autentica com um **JWT assinado em RS256** pelo servidor de autorização da Kobana, enviado como `Authorization: Bearer `. Veja [Autenticação da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/authentication.md) para como esse token é emitido e quais escopos ele carrega — `kobana auth login`, que é do Gateway Bancário, **não** produz esse token. :::caution O token sozinho não basta O JWT identifica a **organização** (claim `org`). Como uma organização pode ter vários espaços de trabalho, a API exige também o cabeçalho `X-Workspace-Id` dizendo em qual deles agir — sem ele a resposta é `400 WORKSPACE_REQUIRED`. As exceções são `me` e [`organization`](https://docs.finance.kobana.com.br/pt/pt/cli/resources/organization.md), de nível de organização, que não levam o cabeçalho. Veja [Autenticação da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/authentication.md). ::: Coloque o JWT em `KOBANA_TOKEN` antes de chamar o produto: ``` export KOBANA_TOKEN=$JWT_FINANCE kobana finance financial-accounts list --fields "id,name,balance" ``` Como a variável é a mesma para todos os produtos, exporte-a por comando (ou use um `.env` por projeto) se você alterna entre produtos na mesma sessão: ``` KOBANA_TOKEN=$JWT_FINANCE kobana finance financial-accounts list --fields "id,name,balance" ``` ## Prioridade de resolução[​](#prioridade-de-resolução "Link direto para Prioridade de resolução") | Prioridade | Método | Configuração | | ---------- | ---------------------- | ----------------------------------------- | | 1 | Token direto | `KOBANA_TOKEN` | | 2 | Arquivo de credenciais | `KOBANA_CREDENTIALS_FILE` | | 3 | Credenciais salvas | `kobana auth login` (só Gateway Bancário) | ## Ambientes[​](#ambientes "Link direto para Ambientes") O CLI opera em três ambientes, e cada produto tem os seus próprios hosts. **Produção é o padrão.** | Ambiente | API | `--env` | | -------- | ----------------------------------- | --------------------- | | Produção | `api.finance.kobana.com.br` | `production` (padrão) | | Sandbox | `api.finance.sandbox.kobana.com.br` | `sandbox` | O Financeiro Inteligente não tem host de desenvolvimento próprio: com `--env development` o CLI cai em produção. ``` # Produção (padrão — sem flag) kobana finance financial-accounts list # Sandbox kobana finance financial-accounts list --env sandbox # Via variável de ambiente export KOBANA_ENVIRONMENT=sandbox kobana finance financial-accounts list ``` Os tokens são **diferentes entre ambientes** — um token de sandbox não funciona em produção, e vice-versa. ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Uso](https://docs.finance.kobana.com.br/pt/pt/cli/usage/overview.md) — sintaxe, recursos, exemplos. * [Variáveis de ambiente](https://docs.finance.kobana.com.br/pt/pt/cli/overview/environment-variables.md) — a referência completa, incluindo configuração e logs. --- # Variáveis de ambiente Todas as variáveis também podem ser definidas em um arquivo `.env` (carregado via `dotenvy`). ## Autenticação[​](#autenticação "Link direto para Autenticação") | Variável | Descrição | | ------------------------- | --------------------------------------------------------------------------------- | | `KOBANA_TOKEN` | Token do produto que você vai chamar (Bearer). Não é compartilhado entre produtos | | `KOBANA_CREDENTIALS_FILE` | Caminho para um arquivo JSON de credenciais OAuth | | `KOBANA_CLIENT_ID` | OAuth client ID (Gateway Bancário) | | `KOBANA_CLIENT_SECRET` | OAuth client secret (Gateway Bancário) | ## Configuração[​](#configuração "Link direto para Configuração") | Variável | Descrição | | -------------------- | ------------------------------------------------------ | | `KOBANA_CONFIG_DIR` | Diretório de configuração (padrão: `~/.config/kobana`) | | `KOBANA_ENVIRONMENT` | `production` (padrão), `sandbox` ou `development` | ## Logs[​](#logs "Link direto para Logs") | Variável | Descrição | | ----------------- | ----------------------------------------------------------------------------- | | `KOBANA_LOG` | Nível de log no stderr (ex.: `kobana=debug`). Desligado por padrão. | | `KOBANA_LOG_FILE` | Diretório para arquivos de log JSON com rotação diária. Desligado por padrão. | ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Autenticação](https://docs.finance.kobana.com.br/pt/pt/cli/overview/authentication.md) — prioridade de resolução e credenciais por produto. * [Códigos de saída](https://docs.finance.kobana.com.br/pt/pt/cli/overview/exit-codes.md) — códigos de saída do processo, para scripts. --- # Códigos de saída Toda execução do `kobana` termina com um destes códigos, para que um script decida o que fazer sem precisar interpretar o corpo JSON do erro. | Código | Significado | | ------ | --------------------- | | `0` | Sucesso | | `1` | Erro de API (4xx/5xx) | | `2` | Erro de autenticação | | `3` | Erro de validação | | `4` | Erro de schema | | `5` | Erro interno | ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Uso](https://docs.finance.kobana.com.br/pt/pt/cli/usage/overview.md) — sintaxe, recursos, exemplos. * [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) — `--dry-run`, `--output-format` e as demais. --- # Instalação ### Homebrew (macOS e Linux)[​](#homebrew-macos-e-linux "Link direto para Homebrew (macOS e Linux)") ``` brew tap universokobana/tap brew install kobana ``` Para atualizar: ``` brew update && brew upgrade kobana ``` ### Binários pré-compilados[​](#binários-pré-compilados "Link direto para Binários pré-compilados") Baixe o binário da sua plataforma na [página de Releases](https://github.com/universokobana/kobana-cli/releases/latest) e coloque no seu `PATH`. | Plataforma | Arquivo | | ------------------- | -------------------------- | | Linux x86\_64 | `kobana-linux-amd64` | | Linux ARM64 | `kobana-linux-arm64` | | macOS Intel | `kobana-darwin-amd64` | | macOS Apple Silicon | `kobana-darwin-arm64` | | Windows x86\_64 | `kobana-windows-amd64.exe` | ### Nix[​](#nix "Link direto para Nix") ``` # Rodar direto do GitHub nix run github:universokobana/kobana-cli # Instalar no perfil nix profile install github:universokobana/kobana-cli ``` ### Build a partir do source[​](#build-a-partir-do-source "Link direto para Build a partir do source") ``` git clone https://github.com/universokobana/kobana-cli.git cd kobana-cli cargo install --path crates/kobana-cli ``` Requer [Rust](https://rustup.rs/) 1.70+. ## Completions de shell[​](#completions-de-shell "Link direto para Completions de shell") ``` # Bash kobana completions bash > /etc/bash_completion.d/kobana # Zsh kobana completions zsh > ~/.zfunc/_kobana # Fish kobana completions fish > ~/.config/fish/completions/kobana.fish # PowerShell kobana completions powershell > kobana.ps1 ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Autenticação](https://docs.finance.kobana.com.br/pt/pt/cli/overview/authentication.md) — tokens e ambientes. * [Uso](https://docs.finance.kobana.com.br/pt/pt/cli/usage/overview.md) — sintaxe, recursos, exemplos. --- # Introdução **`kobana`** é uma ferramenta de linha de comando única para as APIs de todos os produtos Kobana — o Financeiro Inteligente incluído. Ela é construída e mantida em repositório próprio ([`kobana-cli`](https://github.com/universokobana/kobana-cli)), não por este produto, e não tem endpoint algum escrito à mão: na inicialização ela lê as specs OpenAPI 3.1 embutidas no binário e monta a árvore de comandos a partir delas. Atualizar a superfície da API é questão de atualizar a spec embutida e publicar um build novo — nenhum código por endpoint. ``` kobana [flags] ``` Pensada tanto para pessoas quanto para agentes de IA: saída JSON estruturada por padrão, introspecção de schema, `--dry-run` e paginação automática. ## Produtos[​](#produtos "Link direto para Produtos") | Produto | Descrição | | ------------ | -------------------------------------------------------------------------------- | | `banking` | Gateway Bancário — cobranças, pagamentos, transferências (API v1 e v2) | | `finance` | Financeiro Inteligente — contas a pagar e a receber, lançamentos, fluxo de caixa | | `billing` | Faturamento Automático — assinaturas, planos, faturas, notas fiscais | | `inbox` | Inbox Autônomo — caixas de entrada, agentes, e-mails, webhooks | | `dunning` | Régua de Cobrança — clientes, cobranças, réguas, acordos, negativações | | `dashboards` | Dashboard Mágico — fontes de dados, entidades, portal, workspaces | O produto `finance` fala com a mesma API documentada neste site. Os recursos dele — veja o [catálogo completo](https://docs.finance.kobana.com.br/pt/pt/cli/resources/overview.md) — apontam para os mesmos endpoints da [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api/v1); o CLI é só mais um jeito de chamá-la. Ele não compartilha credenciais com os outros produtos: veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/cli/overview/authentication.md). ## Começando[​](#começando "Link direto para Começando") 1. **Instale** — veja [Instalação](https://docs.finance.kobana.com.br/pt/pt/cli/overview/installation.md). 2. **Autentique-se** no produto que você vai usar. Veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/cli/overview/authentication.md). 3. **Faça a primeira chamada**: ``` kobana finance financial-accounts list --fields "id,name,balance" ``` 4. **Explore a superfície** — todo comando aceita `--help`, e `kobana schema` mostra parâmetros e corpo de qualquer endpoint sem sair do terminal. ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Instalação](https://docs.finance.kobana.com.br/pt/pt/cli/overview/installation.md) — Homebrew, binários prontos, Nix, build a partir do source. * [Autenticação](https://docs.finance.kobana.com.br/pt/pt/cli/overview/authentication.md) — tokens, ambientes e as credenciais próprias do `finance`. * [Uso](https://docs.finance.kobana.com.br/pt/pt/cli/usage/overview.md) — sintaxe, recursos, exemplos. * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — `kobana schema` para parâmetros e formato de requisição e resposta. * [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) — as flags que todo comando aceita. * [Helpers](https://docs.finance.kobana.com.br/pt/pt/cli/usage/helpers.md) — atalhos `+verbo` para fluxos comuns. * [Variáveis de ambiente](https://docs.finance.kobana.com.br/pt/pt/cli/overview/environment-variables.md) — autenticação, configuração e logs. * [Códigos de saída](https://docs.finance.kobana.com.br/pt/pt/cli/overview/exit-codes.md) — códigos de saída do processo, para scripts. --- # Agentes de IA Instruções que o assistente executa sozinho, com as permissões da pessoa dona do token — por exemplo, um resumo diário das contas a pagar que venceram. A listagem traz só os agentes da pessoa do token no workspace, nunca os de outro membro. Cada execução gasta crédito de IA e vira uma nova conversa do assistente (`last_run.conversation_id`); uma ação destrutiva espera a confirmação da pessoa no assistente. | Comando | HTTP | Descrição | | --------------------------- | ---------------------------------------------------- | ---------------------------------------- | | `ai-agents list` | `GET /v1/ai-agents` | Listar agentes de IA | | `ai-agents create` | `POST /v1/ai-agents` | Criar agente de IA | | `ai-agents get` | `GET /v1/ai-agents/{id}` | Obter agente de IA por ID | | `ai-agents update` | `PATCH /v1/ai-agents/{id}` | Atualizar agente de IA | | `ai-agents delete` | `DELETE /v1/ai-agents/{id}` | Excluir agente de IA | | `ai-agents triggers get` | `GET /v1/ai-agents/{id}/triggers` | Listar os acionadores de um agente de IA | | `ai-agents triggers create` | `POST /v1/ai-agents/{id}/triggers` | Adicionar acionador a um agente de IA | | `ai-agents triggers update` | `PATCH /v1/ai-agents/{id}/triggers/{triggerId}` | Atualizar acionador de um agente de IA | | `ai-agents triggers delete` | `DELETE /v1/ai-agents/{id}/triggers/{triggerId}` | Remover acionador de um agente de IA | | `ai-agents triggers token` | `POST /v1/ai-agents/{id}/triggers/{triggerId}/token` | Trocar o token de um acionador de API | O agente nasce ativo com um acionador `manual`; os demais entram por `triggers create`: `event` (com `event_type`: `receipt.saved`, `fiscal_document.received`, `payable.created` ou `receivable.created`), `schedule` (com `cron` de 5 campos, no máximo a cada 15 minutos, e `timezone` opcional — padrão `America/Sao_Paulo`) e `api`. O token de um acionador `api` só aparece na resposta do `triggers create` e do `triggers token` — guarde-o; o `triggers token` invalida o anterior na hora. Por isso essas duas rotas não aceitam `--idempotency-key`. `update` com `active: false` pausa todos os acionadores automáticos e `active: true` os retoma. Excluir o agente remove os acionadores; as execuções passadas ficam no assistente. Os escopos são `finance/ai_agents` (leitura, escrita e exclusão). ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar agentes de IA kobana finance ai-agents list \ --params '{"active": true}' \ --fields "id,title,active,next_run_at,last_run" # Obter agente de IA por ID kobana finance ai-agents get \ --params '{"id": "AI_AGENT_ID"}' # Criar agente de IA kobana finance ai-agents create \ --json '{"title": "Resumo de contas vencidas", "instructions": "Liste as contas a pagar que venceram ontem, agrupadas por fornecedor, com o total."}' # Pausar todos os acionadores automáticos kobana finance ai-agents update \ --params '{"id": "AI_AGENT_ID"}' \ --json '{"active": false}' # Listar os acionadores de um agente de IA kobana finance ai-agents triggers get \ --params '{"id": "AI_AGENT_ID"}' # Agendar o agente para os dias úteis às 6h kobana finance ai-agents triggers create \ --params '{"id": "AI_AGENT_ID"}' \ --json '{"kind": "schedule", "cron": "0 6 * * 1-5", "timezone": "America/Sao_Paulo"}' # Atualizar acionador de um agente de IA kobana finance ai-agents triggers update \ --params '{"id": "AI_AGENT_ID", "triggerId": "TRIGGER_ID"}' \ --json '{"cron": "0 7 * * 1-5"}' # Trocar o token de um acionador de API kobana finance ai-agents triggers token \ --params '{"id": "AI_AGENT_ID", "triggerId": "TRIGGER_ID"}' # Remover acionador de um agente de IA kobana finance ai-agents triggers delete \ --params '{"id": "AI_AGENT_ID", "triggerId": "TRIGGER_ID"}' \ --dry-run # Excluir agente de IA kobana finance ai-agents delete \ --params '{"id": "AI_AGENT_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Habilidades de IA](https://docs.finance.kobana.com.br/pt/pt/cli/resources/ai-skills.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Habilidades de IA Conjuntos de instruções, no formato Agent Skills, que o assistente carrega quando uma tarefa casa com a `description` da habilidade — é tudo o que ele lê para decidir. A listagem traz as habilidades que a pessoa do token enxerga no workspace: as dela e as que outros membros compartilharam com ela (`is_owner` diferencia; `mine=true` filtra só as próprias). | Comando | HTTP | Descrição | | ------------------ | --------------------------- | ----------------------------- | | `ai-skills list` | `GET /v1/ai-skills` | Listar habilidades de IA | | `ai-skills create` | `POST /v1/ai-skills` | Criar habilidade de IA | | `ai-skills get` | `GET /v1/ai-skills/{id}` | Obter habilidade de IA por ID | | `ai-skills update` | `PATCH /v1/ai-skills/{id}` | Atualizar habilidade de IA | | `ai-skills delete` | `DELETE /v1/ai-skills/{id}` | Excluir habilidade de IA | `create` pede `name`, `description` e `instructions` (o corpo do SKILL.md, em Markdown); `slug` sai do `name` quando omitido e é único entre as habilidades da pessoa (`409 slug_taken`). `files` traz arquivos de texto além do SKILL.md, até 200 000 caracteres somados. A habilidade nasce ativa e `private`; `visibility` (`restricted` com `member_ids`, ou `workspace`) compartilha, e exige a permissão `ai-skills.share` da pessoa. São no máximo 100 habilidades por pessoa e workspace. Só a dona altera ou exclui (`403`, `details.reason: not_owner`); no `update`, `files` e `member_ids` substituem a lista inteira e `active: false` esconde a habilidade do assistente. Os escopos são `finance/ai_skills`. ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar habilidades de IA kobana finance ai-skills list \ --params '{"mine": true}' \ --fields "id,slug,name,visibility,active,is_owner" # Obter habilidade de IA por ID kobana finance ai-skills get \ --params '{"id": "AI_SKILL_ID"}' # Criar habilidade de IA kobana finance ai-skills create \ --json '{"name": "Fechamento do mês", "description": "Use ao fechar o mês: confere conciliações pendentes e contas vencidas.", "instructions": "1. Liste os lançamentos sem conciliação do mês.\n2. Liste as contas a pagar vencidas."}' # Compartilhar com o workspace kobana finance ai-skills update \ --params '{"id": "AI_SKILL_ID"}' \ --json '{"visibility": "workspace"}' # Excluir habilidade de IA kobana finance ai-skills delete \ --params '{"id": "AI_SKILL_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Agentes de IA](https://docs.finance.kobana.com.br/pt/pt/cli/resources/ai-agents.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Anexos Arquivos — nota, contrato, comprovante — enviados ao acervo e ligados a um ou mais títulos. `links` cria esse vínculo e `unlink` o desfaz. | Comando | HTTP | Descrição | | ---------------------- | ----------------------------------- | -------------------------------- | | `attachments list` | `GET /v1/attachments` | Listar anexos | | `attachments create` | `POST /v1/attachments` | Enviar um anexo | | `attachments get` | `GET /v1/attachments/{id}` | Obter metadados do anexo por ID | | `attachments delete` | `DELETE /v1/attachments/{id}` | Excluir anexo | | `attachments download` | `GET /v1/attachments/{id}/download` | Baixar bytes do anexo | | `attachments links` | `POST /v1/attachments/{id}/links` | Vincular anexo a um registro | | `attachments unlink` | `POST /v1/attachments/{id}/unlink` | Desvincular anexo de um registro | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar anexos kobana finance attachments list \ --fields "id,file_name,title,mime_type,file_size" # Obter metadados do anexo por ID kobana finance attachments get --params '{"id": "ATTACHMENT_ID"}' # Enviar um anexo, com título kobana finance attachments create \ --file file=nota-junho.pdf \ --json '{"title": "Nota fiscal de junho"}' # Excluir anexo kobana finance attachments delete --params '{"id": "ATTACHMENT_ID"}' --dry-run ``` `attachments create` vai como `multipart/form-data`: o arquivo segue em `--file file=…` (pdf, png, jpg/jpeg, xml, ofx, csv ou xlsx, até 10 MB), e `title` vai em `--json`, como parte de texto. Depois, `attachments links` liga o anexo a um título. Veja [Envio de arquivos](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md#envio-de-arquivos). ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Comprovantes](https://docs.finance.kobana.com.br/pt/pt/cli/resources/receipts.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Regras automáticas As regras que classificam lançamentos sozinhas, avaliadas na ordem em que estão. `reorder` é o que muda essa ordem. | Comando | HTTP | Descrição | | ------------------------- | ---------------------------------- | ----------------------------- | | `automatic-rules list` | `GET /v1/automatic-rules` | Listar regras automáticas | | `automatic-rules create` | `POST /v1/automatic-rules` | Criar regra automática | | `automatic-rules get` | `GET /v1/automatic-rules/{id}` | Obter regra automática por ID | | `automatic-rules update` | `PATCH /v1/automatic-rules/{id}` | Atualizar regra automática | | `automatic-rules delete` | `DELETE /v1/automatic-rules/{id}` | Excluir regra automática | | `automatic-rules reorder` | `POST /v1/automatic-rules/reorder` | Reordenar regras automáticas | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar regras automáticas kobana finance automatic-rules list \ --fields "id,company_id,scope,position,active" # Obter regra automática por ID kobana finance automatic-rules get --params '{"id": "AUTOMATIC_RULE_ID"}' # Criar regra automática kobana finance automatic-rules create \ --json '{"company_id": "COMPANY_ID", "scope": "transactions"}' # Atualizar regra automática kobana finance automatic-rules update \ --params '{"id": "AUTOMATIC_RULE_ID"}' \ --json '{"active": true, "account_id": "ACCOUNT_ID", "transaction_type": "debit"}' # Excluir regra automática kobana finance automatic-rules delete \ --params '{"id": "AUTOMATIC_RULE_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Pessoas](https://docs.finance.kobana.com.br/pt/pt/cli/resources/people.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Bancos A tabela de bancos suportados, para preencher os dados bancários de uma conta ou pessoa. Somente leitura. | Comando | HTTP | Descrição | | ------------ | --------------- | ------------- | | `banks list` | `GET /v1/banks` | Listar bancos | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar bancos kobana finance banks list --fields "id,code,name" ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Organização](https://docs.finance.kobana.com.br/pt/pt/cli/resources/organization.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Fluxo de caixa A projeção consolidada: entradas e saídas realizadas e previstas por período, saldo acumulado e o marco de hoje. Somente leitura — é o resultado de tudo o mais, não uma coleção editável. | Comando | HTTP | Descrição | | --------------- | ------------------- | ---------------------------------- | | `cash-flow get` | `GET /v1/cash-flow` | Obter a projeção de fluxo de caixa | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Obter a projeção de fluxo de caixa kobana finance cash-flow get \ --fields "granularity,current_balance,today_bucket,truncated,retroactive_overdue" ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Conciliações](https://docs.finance.kobana.com.br/pt/pt/cli/resources/reconciliations.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Categorias O plano de contas: a árvore de receitas e despesas pela qual todo lançamento é classificado. | Comando | HTTP | Descrição | | ------------------- | ---------------------------- | ---------------------- | | `categories list` | `GET /v1/categories` | Listar categorias | | `categories create` | `POST /v1/categories` | Criar categoria | | `categories get` | `GET /v1/categories/{id}` | Obter categoria por ID | | `categories update` | `PATCH /v1/categories/{id}` | Atualizar categoria | | `categories delete` | `DELETE /v1/categories/{id}` | Excluir categoria | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar categorias kobana finance categories list --fields "id,company_id,name,parent_id,level" # Obter categoria por ID kobana finance categories get --params '{"id": "CATEGORIE_ID"}' # Criar categoria kobana finance categories create \ --json '{"company_id": "COMPANY_ID", "name": "NAME", "type": "debit"}' # Atualizar categoria kobana finance categories update \ --params '{"id": "CATEGORIE_ID"}' \ --json '{"name": "NAME", "type": "debit"}' # Excluir categoria kobana finance categories delete --params '{"id": "CATEGORIE_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Centros de classificação](https://docs.finance.kobana.com.br/pt/pt/cli/resources/classification-centers.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Centros de classificação A segunda dimensão de classificação — centro de custo, projeto, filial —, usada para ratear um mesmo título entre áreas. | Comando | HTTP | Descrição | | ------------------------------- | ---------------------------------------- | ------------------------------------ | | `classification-centers list` | `GET /v1/classification_centers` | Listar centros de classificação | | `classification-centers create` | `POST /v1/classification_centers` | Criar centro de classificação | | `classification-centers get` | `GET /v1/classification_centers/{id}` | Obter centro de classificação por ID | | `classification-centers update` | `PATCH /v1/classification_centers/{id}` | Atualizar centro de classificação | | `classification-centers delete` | `DELETE /v1/classification_centers/{id}` | Excluir centro de classificação | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar centros de classificação kobana finance classification-centers list \ --fields "id,company_id,name,type,description" # Obter centro de classificação por ID kobana finance classification-centers get \ --params '{"id": "CLASSIFICATION_CENTER_ID"}' # Criar centro de classificação kobana finance classification-centers create \ --json '{"company_id": "COMPANY_ID", "name": "NAME", "type": "cost"}' # Atualizar centro de classificação kobana finance classification-centers update \ --params '{"id": "CLASSIFICATION_CENTER_ID"}' \ --json '{"name": "NAME", "type": "cost", "description": "DESCRIPTION"}' # Excluir centro de classificação kobana finance classification-centers delete \ --params '{"id": "CLASSIFICATION_CENTER_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Regras automáticas](https://docs.finance.kobana.com.br/pt/pt/cli/resources/automatic-rules.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Empresas As empresas do grupo. Toda conta, título e lançamento pertence a uma delas, e quase todo filtro aceita `company_id`. | Comando | HTTP | Descrição | | ------------------ | --------------------------- | -------------------- | | `companies list` | `GET /v1/companies` | Listar empresas | | `companies create` | `POST /v1/companies` | Criar empresa | | `companies get` | `GET /v1/companies/{id}` | Obter empresa por ID | | `companies update` | `PATCH /v1/companies/{id}` | Atualizar empresa | | `companies delete` | `DELETE /v1/companies/{id}` | Excluir empresa | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar empresas kobana finance companies list --fields "id,name,cnpj,type,active" # Obter empresa por ID kobana finance companies get --params '{"id": "COMPANIE_ID"}' # Criar empresa kobana finance companies create \ --json '{"name": "ACME Comércio Ltda", "cnpj": "12345678000190"}' # Atualizar empresa kobana finance companies update \ --params '{"id": "COMPANIE_ID"}' \ --json '{"name": "NAME", "active": true, "trade_name": "TRADE_NAME"}' # Excluir empresa kobana finance companies delete --params '{"id": "COMPANIE_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Impostos](https://docs.finance.kobana.com.br/pt/pt/cli/resources/taxes.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Classificadores personalizados Dimensões de classificação que a própria empresa define — projeto, contrato, filial — ao lado de categoria e centro de classificação. Cada classificador pertence a uma empresa (filtre com `company_id`) e traz os seus `values[]` embutidos; os valores são o que se atribui a contas a pagar, a receber e lançamentos. | Comando | HTTP | Descrição | | ---------------------------------- | ----------------------------------------------------- | ------------------------------------------------ | | `custom-classifiers list` | `GET /v1/custom-classifiers` | Listar classificadores personalizados | | `custom-classifiers create` | `POST /v1/custom-classifiers` | Criar classificador personalizado | | `custom-classifiers get` | `GET /v1/custom-classifiers/{id}` | Obter classificador personalizado por ID | | `custom-classifiers update` | `PATCH /v1/custom-classifiers/{id}` | Atualizar classificador personalizado | | `custom-classifiers delete` | `DELETE /v1/custom-classifiers/{id}` | Excluir classificador personalizado | | `custom-classifiers values create` | `POST /v1/custom-classifiers/{id}/values` | Adicionar valor a um classificador personalizado | | `custom-classifiers values update` | `PATCH /v1/custom-classifiers/{id}/values/{valueId}` | Atualizar valor de classificador personalizado | | `custom-classifiers values delete` | `DELETE /v1/custom-classifiers/{id}/values/{valueId}` | Excluir valor de classificador personalizado | `field_type` define o campo (`dropdown`, o padrão, `radio`, `multi_select`, `number`, `text`, `phone`, `url`, `date`, `datetime`); `number_format` só vale para `number` e `option_style` só para os tipos de lista. Um valor recebe `color` em hex (`#rrggbb`) ou uma cor da paleta quando omitida; `color: null` no `values update` volta para a paleta. Excluir um classificador, ou um valor, que já está atribuído a algum título ou lançamento dá `422` (`reason: in_use`) — nesse caso desative com `active: false`, que preserva as atribuições. Os escopos são `finance/custom_classifiers`. ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar classificadores personalizados kobana finance custom-classifiers list \ --params '{"company_id": "COMPANY_ID", "active": true}' \ --fields "id,company_id,name,field_type,active,values" # Obter classificador personalizado por ID kobana finance custom-classifiers get \ --params '{"id": "CUSTOM_CLASSIFIER_ID"}' # Criar classificador personalizado kobana finance custom-classifiers create \ --json '{"company_id": "COMPANY_ID", "name": "Projeto", "field_type": "dropdown"}' # Atualizar classificador personalizado kobana finance custom-classifiers update \ --params '{"id": "CUSTOM_CLASSIFIER_ID"}' \ --json '{"name": "Projeto (2026)"}' # Adicionar valor a um classificador personalizado kobana finance custom-classifiers values create \ --params '{"id": "CUSTOM_CLASSIFIER_ID"}' \ --json '{"value": "Obra Centro", "color": "#2a78d6"}' # Desativar um valor em uso kobana finance custom-classifiers values update \ --params '{"id": "CUSTOM_CLASSIFIER_ID", "valueId": "VALUE_ID"}' \ --json '{"active": false}' # Excluir valor de classificador personalizado kobana finance custom-classifiers values delete \ --params '{"id": "CUSTOM_CLASSIFIER_ID", "valueId": "VALUE_ID"}' \ --dry-run # Excluir classificador personalizado kobana finance custom-classifiers delete \ --params '{"id": "CUSTOM_CLASSIFIER_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Centros de classificação](https://docs.finance.kobana.com.br/pt/pt/cli/resources/classification-centers.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Contas financeiras As contas em que o dinheiro entra e sai — conta corrente, caixa, cartão. Todo lançamento, pagamento e recebimento aponta para uma conta financeira, e é o saldo dela que o fluxo de caixa projeta. | Comando | HTTP | Descrição | | ---------------------------------------- | --------------------------------------------------------- | ---------------------------------- | | `financial-accounts list` | `GET /v1/financial-accounts` | Listar contas financeiras | | `financial-accounts create` | `POST /v1/financial-accounts` | Criar conta financeira | | `financial-accounts get` | `GET /v1/financial-accounts/{id}` | Obter conta financeira por ID | | `financial-accounts update` | `PATCH /v1/financial-accounts/{id}` | Atualizar conta financeira | | `financial-accounts delete` | `DELETE /v1/financial-accounts/{id}` | Excluir conta financeira | | `financial-accounts adjust-balance` | `POST /v1/financial-accounts/{id}/adjust-balance` | Ajustar saldo da conta | | `financial-accounts balances list` | `GET /v1/financial-accounts/{id}/balances` | Listar saldos registrados da conta | | `financial-accounts balances create` | `POST /v1/financial-accounts/{id}/balances` | Registrar um saldo | | `financial-accounts balances latest get` | `GET /v1/financial-accounts/{id}/balances/latest` | Último saldo de cada origem | | `financial-accounts balances delete` | `DELETE /v1/financial-accounts/{id}/balances/{balanceId}` | Excluir saldo registrado | Os `balances` são **saldos observados**, não o saldo calculado da conta (esse é o `balance` do `get`): cada linha guarda a `source` que a produziu, para separar o que o banco informou do que alguém digitou. `balances create` só registra a observação — não move dinheiro nem cria lançamento; para corrigir o razão use `adjust-balance`. A `source` padrão é `api`; mande `cli` para a trilha de auditoria nomear o canal certo (`manual`, `banking`, `open_finance`, `calculated` e `imported` são do próprio produto e dão `422`). `balances latest get` traz a observação mais recente de cada origem numa chamada só — origem que nunca informou volta com `amount: null`. Um saldo `banking` ou `calculated` não pode ser excluído (`422`): o produtor o recriaria. ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar contas financeiras kobana finance financial-accounts list \ --fields "id,company_id,name,type,bank_id" # Obter conta financeira por ID kobana finance financial-accounts get \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' # Criar conta financeira kobana finance financial-accounts create \ --json '{"company_id": "COMPANY_ID", "name": "NAME", "type": "checking"}' # Atualizar conta financeira kobana finance financial-accounts update \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --json '{"company_id": "COMPANY_ID", "name": "NAME", "type": "checking"}' # Ajustar saldo da conta kobana finance financial-accounts adjust-balance \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --json '{"target_balance": "1500.00", "category_id": "CATEGORY_ID"}' # Excluir conta financeira kobana finance financial-accounts delete \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --dry-run # Listar saldos registrados da conta kobana finance financial-accounts balances list \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --fields "id,source,capture_date,amount,external_id" # Registrar um saldo kobana finance financial-accounts balances create \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --json '{"amount": 1530.45, "capture_date": "2026-01-31T23:59:00Z", "source": "cli", "external_id": "EXTERNAL_ID"}' # Último saldo de cada origem kobana finance financial-accounts balances latest get \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' # Excluir saldo registrado kobana finance financial-accounts balances delete \ --params '{"id": "FINANCIAL_ACCOUNT_ID", "balanceId": "BALANCE_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Lançamentos](https://docs.finance.kobana.com.br/pt/pt/cli/resources/financial-transactions.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Lançamentos O extrato de fato: cada crédito e débito ocorrido em uma conta financeira, classificado por categoria e centro de classificação. O endpoint `aggregates` devolve totais em vez da lista inteira. | Comando | HTTP | Descrição | | --------------------------------------- | ------------------------------------------- | -------------------------- | | `financial-transactions list` | `GET /v1/financial-transactions` | Listar transações | | `financial-transactions create` | `POST /v1/financial-transactions` | Criar transação | | `financial-transactions get` | `GET /v1/financial-transactions/{id}` | Obter transação por ID | | `financial-transactions update` | `PATCH /v1/financial-transactions/{id}` | Atualizar transação | | `financial-transactions delete` | `DELETE /v1/financial-transactions/{id}` | Excluir transação | | `financial-transactions aggregates get` | `GET /v1/financial-transactions/aggregates` | Somar totais de transações | | `financial-transactions ids list` | `GET /v1/financial-transactions/ids` | Listar IDs de transações | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar transações kobana finance financial-transactions list \ --fields "id,company_id,financial_account_id,description,bank_description" # Obter transação por ID kobana finance financial-transactions get \ --params '{"id": "FINANCIAL_TRANSACTION_ID"}' # Criar transação kobana finance financial-transactions create \ --json '{"company_id": "COMPANY_ID", "financial_account_id": "FINANCIAL_ACCOUNT_ID", "description": "DESCRIPTION", "amount": "1500.00", "occurred_at": "2026-01-31T12:00:00Z"}' # Atualizar transação kobana finance financial-transactions update \ --params '{"id": "FINANCIAL_TRANSACTION_ID"}' \ --json '{"description": "DESCRIPTION", "bank_description": "BANK_DESCRIPTION", "document": "DOCUMENT"}' # Somar totais de transações do mês kobana finance financial-transactions aggregates get \ --params '{"company_id": "COMPANY_ID", "month": 1, "year": 2026}' # Excluir transação kobana finance financial-transactions delete \ --params '{"id": "FINANCIAL_TRANSACTION_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Contas a pagar](https://docs.finance.kobana.com.br/pt/pt/cli/resources/payables.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Notas fiscais As notas fiscais (NF-e e NFS-e) **recebidas** contra as empresas do workspace — por NFE.io, upload de XML ou SEFAZ. São somente leitura: o produto não emite notas, então não há `create` nem cancelamento. A listagem vem ordenada pela emissão mais recente. | Comando | HTTP | Descrição | | ----------------------- | ------------------------------- | ------------------------ | | `fiscal-documents list` | `GET /v1/fiscal-documents` | Listar notas fiscais | | `fiscal-documents get` | `GET /v1/fiscal-documents/{id}` | Obter nota fiscal por ID | Os filtros incluem `kind` (`service` para NFS-e, `product` para NF-e), `situation` (`authorized`, `cancelled`, `unknown`), `source` (`nfe_io`, `xml_upload`, `sefaz`), `access_key`, `number`, `issuer_document` (CNPJ/CPF do emitente, só dígitos) e intervalos em `issued_at`, `created_at` e `updated_at` (`[gte]`, `[lte]`…) — `updated_at` é a janela de sincronização incremental. O XML não vem aqui: siga `xml_download_url`, que é do recurso [Anexos](https://docs.finance.kobana.com.br/pt/pt/cli/resources/attachments.md) e pede o escopo `finance/attachments`. O escopo deste recurso é `finance/fiscal_documents` com leitura. ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar notas fiscais de serviço autorizadas kobana finance fiscal-documents list \ --params '{"kind": "service", "situation": "authorized"}' \ --fields "id,number,issued_at,issuer_name,issuer_document,total_amount" # Notas de um fornecedor emitidas em janeiro kobana finance fiscal-documents list \ --params '{"issuer_document": "12345678000190", "issued_at[gte]": "2026-01-01", "issued_at[lte]": "2026-01-31"}' # Obter nota fiscal por ID kobana finance fiscal-documents get \ --params '{"id": "FISCAL_DOCUMENT_ID"}' \ --fields "id,access_key,number,situation,total_amount,payable_count,xml_download_url" ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Anexos](https://docs.finance.kobana.com.br/pt/pt/cli/resources/attachments.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Identidade do token Quem está por trás do token: a pessoa (`user`, nulo num token de integração), a organização e os detalhes do próprio token. Serve para testar se o token configurado vale — é o primeiro comando a rodar depois de definir `KOBANA_TOKEN`. O token em si nunca volta na resposta. | Comando | HTTP | Descrição | | -------- | ------------ | --------------------------- | | `me get` | `GET /v1/me` | Obter a identidade do token | A rota é de **nível de organização**: não leva `X-Workspace-Id`, então `KOBANA_WORKSPACE_ID` não é necessário aqui. Qualquer token válido serve — não há escopo exigido. ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Obter a identidade do token kobana finance me get # Só a organização e o token kobana finance me get \ --fields "organization,token" ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Autenticação](https://docs.finance.kobana.com.br/pt/pt/cli/overview/authentication.md) — como obter o token e escolher o workspace. * [Organização](https://docs.finance.kobana.com.br/pt/pt/cli/resources/organization.md) --- # Organização O perfil da organização do token, no topo da hierarquia: vale para todos os workspaces. O recurso é **singular** — não há `list` nem `id`, porque um token sempre alcança uma organização só, a dele. | Comando | HTTP | Descrição | | --------------------- | ------------------------ | --------------------------------- | | `organization get` | `GET /v1/organization` | Obter a organização do token | | `organization update` | `PATCH /v1/organization` | Atualizar o perfil da organização | As duas rotas são de **nível de organização**: não levam `X-Workspace-Id`, então `KOBANA_WORKSPACE_ID` não é necessário aqui. O `get` pede o escopo `finance/settings` com leitura; o `update` pede escrita e, como o perfil vale para todos os workspaces, o dono da organização ou acesso a todos eles. O `update` só altera `trade_name`, `website`, `addresses` e `custom_metadata`. Nome, e-mail e telefone vêm da Conta Kobana e a identidade fiscal (`document_type`, `document_number`) não muda pela API: enviar qualquer um deles — ou qualquer chave desconhecida — dá `422`, e um campo comercial (`courtesy`, `entitlements`…) dá `403`. `custom_metadata: null` mantém o valor guardado. ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Obter a organização do token kobana finance organization get \ --fields "id,name,trade_name,document_number,website,created_at" # Atualizar o perfil da organização kobana finance organization update \ --json '{"trade_name": "Acme", "website": "https://acme.com.br", "custom_metadata": {"crm_id": "CRM_ID"}}' ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Autenticação](https://docs.finance.kobana.com.br/pt/pt/cli/overview/authentication.md) — o escopo `finance/settings` e o workspace das outras rotas. * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Recursos Todo recurso de `finance` abaixo é gerado a partir da mesma spec OpenAPI documentada na [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api/v1) — o CLI chama exatamente os mesmos endpoints, então filtros, validação e comportamento de exclusão são idênticos. Recorra à [introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) sempre que os parâmetros exatos de um comando não estiverem óbvios nos exemplos destas páginas. ``` kobana finance [flags] ``` ## Como ler estas páginas[​](#como-ler-estas-páginas "Link direto para Como ler estas páginas") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. Veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/cli/overview/authentication.md) para as credenciais próprias do `finance`. Um subcaminho que só aceita `POST` é uma ação do recurso, com o nome do último segmento — `kobana finance automatic-rules reorder` e `kobana finance receivables charge cancel`. A forma antiga, terminada em `create`, ainda funciona. ## O catálogo[​](#o-catálogo "Link direto para O catálogo") | Recurso | Comando | Métodos | | -------------------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | [Contas financeiras](https://docs.finance.kobana.com.br/pt/pt/cli/resources/financial-accounts.md) | `financial-accounts` | list, create, get, update, delete, adjust-balance, balances list, balances create, balances latest get, balances delete | | [Lançamentos](https://docs.finance.kobana.com.br/pt/pt/cli/resources/financial-transactions.md) | `financial-transactions` | list, create, get, update, delete, aggregates get, ids list | | [Contas a pagar](https://docs.finance.kobana.com.br/pt/pt/cli/resources/payables.md) | `payables` | list, create, get, update, delete, cancel-dispatch, send-to-bank, aggregates get, ids list | | [Contas a receber](https://docs.finance.kobana.com.br/pt/pt/cli/resources/receivables.md) | `receivables` | list, create, get, update, delete, aggregates get, charge create, charge cancel, ids list | | [Fluxo de caixa](https://docs.finance.kobana.com.br/pt/pt/cli/resources/cash-flow.md) | `cash-flow` | get | | [Conciliações](https://docs.finance.kobana.com.br/pt/pt/cli/resources/reconciliations.md) | `reconciliations` | create, get, delete | | [Categorias](https://docs.finance.kobana.com.br/pt/pt/cli/resources/categories.md) | `categories` | list, create, get, update, delete | | [Centros de classificação](https://docs.finance.kobana.com.br/pt/pt/cli/resources/classification-centers.md) | `classification-centers` | list, create, get, update, delete | | [Classificadores personalizados](https://docs.finance.kobana.com.br/pt/pt/cli/resources/custom-classifiers.md) | `custom-classifiers` | list, create, get, update, delete, values create, values update, values delete | | [Regras automáticas](https://docs.finance.kobana.com.br/pt/pt/cli/resources/automatic-rules.md) | `automatic-rules` | list, create, get, update, delete, reorder | | [Pessoas](https://docs.finance.kobana.com.br/pt/pt/cli/resources/people.md) | `people` | list, create, get, update, delete, ids list | | [Empresas](https://docs.finance.kobana.com.br/pt/pt/cli/resources/companies.md) | `companies` | list, create, get, update, delete | | [Impostos](https://docs.finance.kobana.com.br/pt/pt/cli/resources/taxes.md) | `taxes` | list, create, get, update, delete | | [Anexos](https://docs.finance.kobana.com.br/pt/pt/cli/resources/attachments.md) | `attachments` | list, create, get, delete, download, links, unlink | | [Comprovantes](https://docs.finance.kobana.com.br/pt/pt/cli/resources/receipts.md) | `receipts` | list, get | | [Notas fiscais](https://docs.finance.kobana.com.br/pt/pt/cli/resources/fiscal-documents.md) | `fiscal-documents` | list, get | | [Transferências](https://docs.finance.kobana.com.br/pt/pt/cli/resources/transfers.md) | `transfers` | create, get | | [Bancos](https://docs.finance.kobana.com.br/pt/pt/cli/resources/banks.md) | `banks` | list | | [Agentes de IA](https://docs.finance.kobana.com.br/pt/pt/cli/resources/ai-agents.md) | `ai-agents` | list, create, get, update, delete, triggers get, triggers create, triggers update, triggers delete, triggers token | | [Habilidades de IA](https://docs.finance.kobana.com.br/pt/pt/cli/resources/ai-skills.md) | `ai-skills` | list, create, get, update, delete | | [Organização](https://docs.finance.kobana.com.br/pt/pt/cli/resources/organization.md) | `organization` | get, update | | [Identidade do token](https://docs.finance.kobana.com.br/pt/pt/cli/resources/me.md) | `me` | get | --- # Contas a pagar As obrigações a vencer e já pagas, com aprovação de pagamento, envio ao banco e rateio por centro de classificação. Contas pendentes de aprovação só aparecem na listagem se você filtrar por `payment_approval=pending_approval`. | Comando | HTTP | Descrição | | -------------------------- | ---------------------------------------- | ----------------------------------- | | `payables list` | `GET /v1/payables` | Listar contas a pagar | | `payables create` | `POST /v1/payables` | Criar conta a pagar | | `payables get` | `GET /v1/payables/{id}` | Obter conta a pagar por ID | | `payables update` | `PATCH /v1/payables/{id}` | Atualizar ou liquidar conta a pagar | | `payables delete` | `DELETE /v1/payables/{id}` | Excluir conta a pagar | | `payables cancel-dispatch` | `POST /v1/payables/{id}/cancel-dispatch` | Cancelar o envio ao banco | | `payables send-to-bank` | `POST /v1/payables/{id}/send-to-bank` | Enviar conta a pagar ao banco | | `payables aggregates get` | `GET /v1/payables/aggregates` | Somar totais de contas a pagar | | `payables ids list` | `GET /v1/payables/ids` | Listar IDs de contas a pagar | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar contas a pagar kobana finance payables list \ --fields "id,company_id,description,amount,interest_amount" # Obter conta a pagar por ID kobana finance payables get --params '{"id": "PAYABLE_ID"}' # Criar conta a pagar kobana finance payables create \ --json '{"company_id": "COMPANY_ID", "description": "DESCRIPTION", "amount": "1500.00", "due_date": "2026-01-31T12:00:00Z"}' # Atualizar ou liquidar conta a pagar kobana finance payables update \ --params '{"id": "PAYABLE_ID"}' \ --json '{"description": "DESCRIPTION", "amount": "1500.00", "due_date": "2026-01-31T12:00:00Z"}' # Cancelar o envio ao banco kobana finance payables cancel-dispatch --params '{"id": "PAYABLE_ID"}' # Somar totais de contas a pagar do mês kobana finance payables aggregates get \ --params '{"company_id": "COMPANY_ID", "month": 1, "year": 2026}' # Excluir conta a pagar kobana finance payables delete --params '{"id": "PAYABLE_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Contas a receber](https://docs.finance.kobana.com.br/pt/pt/cli/resources/receivables.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Pessoas Clientes e fornecedores — a contraparte de qualquer título. `ids` devolve só os identificadores, útil para não encher a janela de contexto de um agente. | Comando | HTTP | Descrição | | ----------------- | ------------------------ | ---------------------------------------- | | `people list` | `GET /v1/people` | Listar pessoas (clientes / fornecedores) | | `people create` | `POST /v1/people` | Criar pessoa (cliente / fornecedor) | | `people get` | `GET /v1/people/{id}` | Obter pessoa por ID | | `people update` | `PATCH /v1/people/{id}` | Atualizar pessoa | | `people delete` | `DELETE /v1/people/{id}` | Excluir pessoa | | `people ids list` | `GET /v1/people/ids` | Listar IDs de pessoas | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar pessoas (clientes / fornecedores) kobana finance people list --fields "id,company_id,name,legal_name,nickname" # Obter pessoa por ID kobana finance people get --params '{"id": "PEOPLE_ID"}' # Criar pessoa (cliente / fornecedor) kobana finance people create \ --json '{"company_id": "COMPANY_ID", "name": "NAME"}' # Atualizar pessoa kobana finance people update \ --params '{"id": "PEOPLE_ID"}' \ --json '{"name": "NAME", "legal_name": "LEGAL_NAME", "nickname": "NICKNAME"}' # Excluir pessoa kobana finance people delete --params '{"id": "PEOPLE_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Empresas](https://docs.finance.kobana.com.br/pt/pt/cli/resources/companies.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Comprovantes Os comprovantes de pagamento gerados pela plataforma. Somente leitura. | Comando | HTTP | Descrição | | --------------- | ----------------------- | ------------------------------------- | | `receipts list` | `GET /v1/receipts` | Listar comprovantes de pagamento | | `receipts get` | `GET /v1/receipts/{id}` | Obter comprovante de pagamento por ID | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar comprovantes de pagamento kobana finance receipts list \ --fields "id,company_id,payable_id,payable_status,financial_account_id" # Obter comprovante de pagamento por ID kobana finance receipts get --params '{"id": "RECEIPT_ID"}' ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Transferências](https://docs.finance.kobana.com.br/pt/pt/cli/resources/transfers.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Contas a receber O que você tem a receber, com emissão e cancelamento de cobrança pelo Gateway Bancário a partir do próprio título. Para movimentar o dinheiro, o comando é `charge` — o registro em si fica aqui. | Comando | HTTP | Descrição | | ---------------------------- | ----------------------------------------- | ------------------------------------------ | | `receivables list` | `GET /v1/receivables` | Listar contas a receber | | `receivables create` | `POST /v1/receivables` | Criar conta a receber | | `receivables get` | `GET /v1/receivables/{id}` | Obter conta a receber por ID | | `receivables update` | `PATCH /v1/receivables/{id}` | Atualizar ou liquidar conta a receber | | `receivables delete` | `DELETE /v1/receivables/{id}` | Excluir conta a receber | | `receivables aggregates get` | `GET /v1/receivables/aggregates` | Somar totais de contas a receber | | `receivables charge create` | `POST /v1/receivables/{id}/charge` | Gerar cobrança de uma conta a receber | | `receivables charge cancel` | `POST /v1/receivables/{id}/charge/cancel` | Cancelar a cobrança de uma conta a receber | | `receivables ids list` | `GET /v1/receivables/ids` | Listar IDs de contas a receber | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar contas a receber kobana finance receivables list \ --fields "id,company_id,description,amount,interest_amount" # Obter conta a receber por ID kobana finance receivables get --params '{"id": "RECEIVABLE_ID"}' # Criar conta a receber kobana finance receivables create \ --json '{"company_id": "COMPANY_ID", "description": "DESCRIPTION", "amount": "1500.00", "due_date": "2026-01-31T12:00:00Z"}' # Atualizar ou liquidar conta a receber kobana finance receivables update \ --params '{"id": "RECEIVABLE_ID"}' \ --json '{"description": "DESCRIPTION", "amount": "1500.00", "due_date": "2026-01-31T12:00:00Z"}' # Somar totais de contas a receber do mês kobana finance receivables aggregates get \ --params '{"company_id": "COMPANY_ID", "month": 1, "year": 2026}' # Excluir conta a receber kobana finance receivables delete --params '{"id": "RECEIVABLE_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Fluxo de caixa](https://docs.finance.kobana.com.br/pt/pt/cli/resources/cash-flow.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Conciliações O vínculo entre um lançamento do extrato e o título que ele liquida. Criar a conciliação baixa o título; excluí-la desfaz a baixa. | Comando | HTTP | Descrição | | ------------------------ | --------------------------------- | ------------------------ | | `reconciliations create` | `POST /v1/reconciliations` | Criar conciliação | | `reconciliations get` | `GET /v1/reconciliations/{id}` | Obter conciliação por ID | | `reconciliations delete` | `DELETE /v1/reconciliations/{id}` | Excluir conciliação | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Obter conciliação por ID kobana finance reconciliations get --params '{"id": "RECONCILIATION_ID"}' # Criar conciliação kobana finance reconciliations create \ --json '{"billings": [], "transaction_ids": []}' # Excluir conciliação kobana finance reconciliations delete \ --params '{"id": "RECONCILIATION_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Categorias](https://docs.finance.kobana.com.br/pt/pt/cli/resources/categories.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Impostos Os tributos retidos ou a recolher vinculados a um título. | Comando | HTTP | Descrição | | -------------- | ----------------------- | -------------------- | | `taxes list` | `GET /v1/taxes` | Listar impostos | | `taxes create` | `POST /v1/taxes` | Criar imposto | | `taxes get` | `GET /v1/taxes/{id}` | Obter imposto por ID | | `taxes update` | `PATCH /v1/taxes/{id}` | Atualizar imposto | | `taxes delete` | `DELETE /v1/taxes/{id}` | Excluir imposto | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar impostos kobana finance taxes list \ --fields "id,name,default_rate,default_withholding,active" # Obter imposto por ID kobana finance taxes get --params '{"id": "TAXE_ID"}' # Criar imposto kobana finance taxes create --json '{"name": "IRRF"}' # Atualizar imposto kobana finance taxes update \ --params '{"id": "TAXE_ID"}' \ --json '{"name": "IRRF", "default_rate": "1.50", "default_withholding": true}' # Excluir imposto kobana finance taxes delete --params '{"id": "TAXE_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Anexos](https://docs.finance.kobana.com.br/pt/pt/cli/resources/attachments.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Transferências Movimentações entre duas contas financeiras suas. Gera os dois lançamentos — saída e entrada — em uma chamada. | Comando | HTTP | Descrição | | ------------------ | ------------------------ | -------------------------- | | `transfers create` | `POST /v1/transfers` | Criar transferência | | `transfers get` | `GET /v1/transfers/{id}` | Obter transferência por ID | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Obter transferência por ID kobana finance transfers get --params '{"id": "TRANSFER_ID"}' # Criar transferência kobana finance transfers create \ --json '{"from_account_id": "FROM_ACCOUNT_ID", "to_account_id": "TO_ACCOUNT_ID", "amount": "1500.00", "occurred_at": "2026-01-31T12:00:00Z", "description": "Aporte para conta pagamentos"}' ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Bancos](https://docs.finance.kobana.com.br/pt/pt/cli/resources/banks.md) * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Flags globais | Flag | Descrição | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `--params ''` | Parâmetros de query e de URL (id, página, filtros) | | `--json ''` | Corpo da requisição (POST/PUT/PATCH) | | `--file ` | Envia um arquivo como parte de um corpo `multipart/form-data` (repetível; os campos de `--json` viram partes de texto) | | `--fields ''` | Limita os campos que voltam na resposta | | `--dry-run` | Mostra a requisição sem executá-la | | `--page-all` | Paginação automática, com saída em NDJSON | | `--page-limit ` | Máximo de páginas (padrão: 10) | | `--page-delay ` | Intervalo entre páginas (padrão: 100ms) | | `--env ` | Ambiente: `production` (padrão), `sandbox`, `development` | | `--verbose` | Detalhes da requisição no stderr | | `--output ` | Salva a resposta em arquivo | | `--output-format ` | Formato: `json`, `table`, `csv` | | `--idempotency-key ` | Chave de idempotência customizada | | `--lang ` | Idioma das mensagens: `pt`, `en` ou `es` (padrão: o do sistema) | ## Envio de arquivos[​](#envio-de-arquivos "Link direto para Envio de arquivos") `--file campo=caminho` troca o corpo JSON por `multipart/form-data`: cada `--file` vira uma parte de arquivo com o nome do campo, e os campos de `--json` seguem como partes de texto. Repita a flag para enviar mais de um arquivo. O tipo de cada parte sai da extensão (um `.eml` vai como `message/rfc822`), e `--dry-run` mostra o `content_type` e a lista `files` antes de enviar. Os nomes dos campos são os do corpo `multipart/form-data` do endpoint na [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api/v1). ``` kobana finance attachments create \ --file file=nota-junho.pdf \ --json '{"title": "Nota fiscal de junho"}' \ --dry-run ``` ## Idioma[​](#idioma "Link direto para Idioma") O CLI fala português, inglês ou espanhol: ajuda, mensagens, erros e as descrições dos comandos. O idioma vem, nesta ordem, de `--lang`, da variável `KOBANA_LANG`, das variáveis de idioma do terminal (`LC_ALL`, `LC_MESSAGES`, `LANG`) e, por fim, do idioma do sistema. ``` kobana --lang en finance --help export KOBANA_LANG=es ``` Nomes de comandos e flags, chaves do JSON e códigos de saída não mudam com o idioma. Disponível a partir da versão 0.6.0. ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Uso](https://docs.finance.kobana.com.br/pt/pt/cli/usage/overview.md) — sintaxe, recursos, exemplos. * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — parâmetros, campos obrigatórios, tipos e respostas. --- # Helpers Helpers são comandos prefixados com `+` que entregam fluxos de vários passos que os comandos dinâmicos sozinhos não dão: interfaces simplificadas, operações em lote ou chamadas compostas por vários endpoints. Eles não embrulham uma única chamada de API já disponível pelos comandos dinâmicos — cada flag de helper controla lógica de orquestração, não uma versão remodelada de `--params`/`--json`. Os helpers de hoje são do **Gateway Bancário**, e valem para qualquer produto no mesmo binário: | Helper | Descrição | | ---------------- | -------------------------------------------------------- | | `+emitir` | Emissão simplificada de boleto, com flags nomeadas | | `+cancelar-lote` | Cancelamento em lote de vários boletos por id | | `+cobrar` | Criação simplificada de cobrança Pix, com flags nomeadas | ``` # Emitir um boleto kobana +emitir --valor 150.50 --vencimento 2026-05-01 \ --nome "Maria Silva" --cpf-cnpj "012.345.678-90" --carteira 1 # Criar uma cobrança Pix kobana +cobrar --valor 99.90 --conta-pix "UID" \ --nome "João" --cpf-cnpj "012.345.678-90" # Cancelar boletos em lote kobana +cancelar-lote --ids "123,456,789" ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Uso](https://docs.finance.kobana.com.br/pt/pt/cli/usage/overview.md) — os comandos dinâmicos ao lado dos quais estes helpers vivem. * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — inspecione os endpoints que um helper chama por baixo. --- # Uso ## Sintaxe[​](#sintaxe "Link direto para Sintaxe") ``` kobana [flags] ``` * **``** — `banking`, `finance`, `billing` ou `inbox`. * **``** — pode ser aninhado: `payables`, `receivables`, `attachments links`. * **``** — a ação: `list`, `get`, `create`, `update`, `delete`, ou uma ação específica do recurso. A versão da API nunca entra no comando — o CLI resolve a URL a partir da spec OpenAPI embutida. Parâmetros de URL e de query vão em `--params`; o corpo da requisição vai em `--json`. Toda a superfície é descoberta pelo `--help`, em qualquer nível: ``` kobana --help # produtos kobana finance --help # recursos do Financeiro Inteligente kobana finance financial-accounts --help # métodos de um recurso ``` ## Recursos de `finance`[​](#recursos-de-finance "Link direto para recursos-de-finance") | Recurso | Descrição | | ------------------------ | ------------------------ | | `financial-accounts` | Contas financeiras | | `financial-transactions` | Lançamentos | | `payables` | Contas a pagar | | `receivables` | Contas a receber | | `cash-flow` | Fluxo de caixa | | `reconciliations` | Conciliações | | `categories` | Categorias | | `classification-centers` | Centros de classificação | | `automatic-rules` | Regras automáticas | | `people` | Pessoas | | `companies` | Empresas | | `taxes` | Impostos | | `attachments` | Anexos | | `receipts` | Comprovantes | | `transfers` | Transferências | | `banks` | Bancos | Cada recurso tem a sua própria página, com a tabela completa de comandos e exemplos — veja o [catálogo](https://docs.finance.kobana.com.br/pt/pt/cli/resources/overview.md). ## Exemplos[​](#exemplos "Link direto para Exemplos") ``` # Contas a pagar em aberto kobana finance payables list \ --params '{"status": "pending"}' \ --fields "id,description,amount,due_date" # Totais agregados em vez da lista inteira kobana finance payables aggregates get --params '{"month": 1, "year": 2026}' # Enviar uma conta para pagamento no banco kobana finance payables send-to-bank --dry-run --params '{"id": "PAYABLE_ID"}' # Fluxo de caixa do mês kobana finance cash-flow get \ --params '{"from": "2026-01-01", "to": "2026-01-31"}' # Conciliar um lançamento com um título kobana finance reconciliations create \ --json '{"financial_transaction_id": "TRANSACTION_ID", "payable_id": "PAYABLE_ID"}' # Listar com paginação automática (NDJSON) kobana finance financial-transactions list --page-all --fields "id,amount,date" # Saída em tabela kobana finance financial-accounts list --output-format table # Salvar a resposta em arquivo kobana finance payables get --params '{"id": "PAYABLE_ID"}' --output conta.json ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Introspecção de schema](https://docs.finance.kobana.com.br/pt/pt/cli/usage/schema.md) — inspecione parâmetros e corpo de qualquer endpoint. * [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) — todas as flags que um comando aceita. * [Helpers](https://docs.finance.kobana.com.br/pt/pt/cli/usage/helpers.md) — atalhos `+verbo` para fluxos comuns. * [Recursos](https://docs.finance.kobana.com.br/pt/pt/cli/resources/overview.md) — o catálogo completo, recurso a recurso. --- # Introspecção de schema ``` # Listar todos os produtos e seus recursos kobana schema --list # Ver o schema de um endpoint específico kobana schema finance.payables.list kobana schema finance.payables.create kobana schema finance.cash-flow.list ``` Devolve parâmetros, campos obrigatórios, tipos e respostas — tudo derivado da spec OpenAPI embutida, então está sempre em sincronia com o que o comando de fato aceita. O caminho segue a mesma forma do comando: `..`. Este é o primeiro passo recomendado para um agente de IA que ainda não conhece o formato exato de um payload: inspecione o schema antes de disparar uma chamada que altera dados, em vez de adivinhar. ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Flags globais](https://docs.finance.kobana.com.br/pt/pt/cli/usage/global-flags.md) — `--params`, `--json`, `--dry-run` e as demais. * [Uso](https://docs.finance.kobana.com.br/pt/pt/cli/usage/overview.md) — sintaxe, recursos, exemplos. --- # Comprovantes **Financeiro > Comprovantes** (`/receipts`) reúne os comprovantes dos pagamentos do espaço de trabalho. Todo pagamento enviado ao banco e confirmado gera um comprovante aqui, **automaticamente** — e o que foi pago por fora (aplicativo do banco, débito automático) você envia à mão. Em qualquer dos dois casos, quem precisa receber o comprovante é [avisado por e-mail](#quem-recebe-por-e-mail). observação **Comprovante é do dinheiro que SAI.** A tela é do lado de contas a pagar. Do lado de contas a receber o equivalente é a cobrança que o cliente paga — veja [Cobrança por boleto e Pix](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/cobranca-kobana.md). ## De onde vem cada comprovante[​](#de-onde-vem-cada-comprovante "Link direto para De onde vem cada comprovante") | Origem | Como aparece | Pode excluir? | | ---------------- | -------------------------------------------------------------- | ------------- | | **Banco** | sozinho, quando um pagamento enviado ao banco é **confirmado** | ❌ não | | **Envio manual** | você envia o arquivo em **"Enviar comprovante"** | ✅ sim | informação **O comprovante capturado não pode ser excluído.** Ele é a prova de um pagamento que realmente aconteceu, e a próxima captura o traria de volta — apagá-lo seria uma promessa que o banco desfaz. Já o que você enviou é seu arquivo, e sai junto com o anexo. ## A faixa de números[​](#a-faixa-de-números "Link direto para A faixa de números") Acima da tabela, cinco números do período filtrado: | Número | O que conta | | ---------------- | ------------------------------------------------------------------------------------------------ | | **Comprovantes** | quantos existem no recorte | | **Disponível** | com o documento já guardado — o desfecho feliz | | **Sem vínculo** | sem conta a pagar associada | | **Com falha** | a captura não conseguiu trazer o documento | | **Valor somado** | a soma dos valores — separado dos demais por um fio, porque é o único que não conta comprovantes | observação **Esses números ignoram a busca e a aba.** Eles respondem *"quantos existem lá?"*, não *"quantos sobraram do que estou vendo"* — senão o contador da aba encolheria enquanto você digita. ## As quatro abas[​](#as-quatro-abas "Link direto para As quatro abas") * **Todos** — tudo no período. * **Sem vínculo** — comprovantes que ainda não apontam para nenhuma conta a pagar. Só o envio manual produz esses: pelo caminho do banco o título sempre é conhecido. * **Título em aberto** — o comprovante aponta para uma conta a pagar que ninguém baixou. Ver [Comprovante não dá baixa no título](#comprovante-n%C3%A3o-d%C3%A1-baixa-no-t%C3%ADtulo). * **Com falha** — a captura não conseguiu o documento. Cada linha mostra o motivo. ## Situação de um comprovante[​](#situação-de-um-comprovante "Link direto para Situação de um comprovante") | Situação | O que significa | | -------------- | --------------------------------------------------------------- | | **Baixando** | o comprovante foi identificado e o documento está sendo buscado | | **Disponível** | pronto para abrir e baixar | | **Falhou** | não foi possível trazer o documento; use **"Tentar de novo"** | informação **"Baixando" por alguns instantes é normal.** A busca do documento acontece em segundo plano e é feita com parcimônia — o banco limita quantas consultas cabem por hora, e essas consultas são compartilhadas com as sincronizações e com o acompanhamento de status dos pagamentos. ## Filtros e busca[​](#filtros-e-busca "Link direto para Filtros e busca") A busca do topo procura por **beneficiário** (nome ou documento) e pela **descrição do título**. A **Pesquisa avançada** recorta por: * **Data de pagamento** (período) * **Empresa** — só na visão consolidada; com uma empresa escolhida no topo, ela é o escopo da tela inteira * **Conta financeira** — de onde o dinheiro saiu * **Liquidação** — boleto, Pix, tributo, transferência… * **Origem** — banco ou envio manual ## O que dá para fazer em cada linha[​](#o-que-dá-para-fazer-em-cada-linha "Link direto para O que dá para fazer em cada linha") | Ação | Quando aparece | | ------------------------- | ---------------------------------------------- | | **Baixar comprovante** | com o documento disponível | | **Abrir o título** | quando há conta a pagar vinculada | | **Vincular a um título** | quando não há, e só nos enviados manualmente | | **Desvincular do título** | quando há, e só nos enviados manualmente | | **Marcar como pago** | quando o título vinculado ainda está em aberto | | **Tentar de novo** | só nos capturados que falharam | | **Excluir** | só nos enviados manualmente | Clicar no documento abre a **pré-visualização**. **Imagens** aparecem ali mesmo; o **PDF abre em nova aba** — a política de segurança do sistema não permite exibi-lo dentro da tela, e a própria pré-visualização avisa isso em vez de mostrar um quadro vazio. observação **Alguns bancos só entregam o comprovante como página, não como arquivo.** Nesse caso não há o que guardar aqui: o comprovante continua acessível pelo botão **"Abrir na origem"**, e a linha segue como **Disponível** — não é falha. ## Vincular a uma conta a pagar[​](#vincular-a-uma-conta-a-pagar "Link direto para Vincular a uma conta a pagar") **"Vincular a um título"** associa o comprovante a uma conta a pagar. **O anexo vai junto**: o comprovante passa a aparecer também na tela do título, sem você precisar anexá-lo de novo. Desvincular remove essa associação. É o caminho para o pagamento que você fez pelo aplicativo do banco: envie o comprovante e ligue-o ao título correspondente — na hora do envio ou depois, pela ação da linha. dica **Não achou o título na lista? Digite.** Sem nada digitado a lista mostra os títulos que vencem **perto da data do pagamento**, que é onde o correspondente quase sempre está — e marca com **"Mesmo valor"** e **"Mesma data"** os que batem com o comprovante. Assim que você digita, a busca passa a valer para **todo o período**: é assim que se acha o título de um pagamento feito com dois meses de atraso. A linha embaixo do campo sempre diz qual recorte está valendo e quantos títulos ficaram de fora. observação **Vincular e desvincular só existem no envio manual.** No comprovante capturado o título já vem do próprio pagamento, e a captura seguinte o traria de volta — mexer ali seria uma promessa que o banco desfaz. ## Comprovante não dá baixa no título[​](#comprovante-não-dá-baixa-no-título "Link direto para Comprovante não dá baixa no título") **Vincular um comprovante não marca a conta a pagar como paga.** São dois fatos diferentes: o comprovante é a *prova* de que o dinheiro saiu; a baixa é o registro do pagamento no sistema, que cria o lançamento na conta financeira. Quando o pagamento sai pelo banco, a baixa já acontece sozinha na confirmação. No envio manual, não — e é por isso que um título pode aparecer como **Atrasado** mesmo com o comprovante anexado. A tela avisa em vez de decidir por você: o título vinculado ganha a marca **"Título em aberto"** embaixo da descrição, a aba de mesmo nome junta todos eles, e a ação **"Marcar como pago"** abre a confirmação de pagamento de sempre — já preenchida com a data e a conta do comprovante. informação **Por que não automático?** O valor do comprovante nem sempre é o do título: juros, desconto e pagamento parcial fazem os dois divergirem. Dar baixa sozinho registraria o valor errado justamente nos casos que mais importam — então a confirmação fica com você, que sabe o que aconteceu. ## Enviar um comprovante à mão[​](#enviar-um-comprovante-à-mão "Link direto para Enviar um comprovante à mão") **"Enviar comprovante"** abre o formulário. Obrigatórios: o **arquivo**, a **data de pagamento** e o **valor**. Opcionais: **conta a pagar**, beneficiário, conta financeira e forma de liquidação — dá para vincular o título agora ou depois. A empresa não é escolhida aqui: vale a que estiver selecionada no topo da tela. observação **O arquivo precisa ser PDF ou imagem** (`pdf`, `png`, `jpg`). Planilha e extrato — `xlsx`, `csv`, `xml`, `ofx` — são aceitos em **[Anexos](https://docs.finance.kobana.com.br/pt/pt/anexos/.md)**, porque servem a outros fins, mas nenhum deles prova um pagamento. O limite de tamanho é o mesmo dos anexos. ## Quem recebe por e-mail[​](#quem-recebe-por-e-mail "Link direto para Quem recebe por e-mail") O aviso sai para **duas listas**, que convivem: | Lista | Onde se configura | Quem pode entrar | O que recebe | | ------------------------- | ------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------- | | **Do espaço de trabalho** | **"Configurar envio"**, nesta tela | só membros do espaço | um aviso, com link para o título e os [arquivos anexados](#o-que-vai-anexado) | | **Do título** | no formulário da conta a pagar, em **"Envio do comprovante"** | qualquer e-mail | **os [arquivos anexados](#o-que-vai-anexado)**, sem link | ### A lista do espaço de trabalho[​](#a-lista-do-espaço-de-trabalho "Link direto para A lista do espaço de trabalho") **"Configurar envio"** abre a lista de quem é avisado em **todo** comprovante do espaço. informação **Só membros do espaço de trabalho aparecem aqui.** Nesta lista não existe campo de e-mail livre: um endereço solto valendo para o espaço inteiro seria um cadastro paralelo, sem dono e sem como revogar. Retirar a pessoa do espaço de trabalho já a tira dos envios; não é preciso desmarcar aqui também. ### A lista do título[​](#a-lista-do-título "Link direto para A lista do título") No formulário da conta a pagar, **"Envio do comprovante"** aceita **qualquer endereço** — o contador do fornecedor, o próprio favorecido. Essas pessoas recebem **o comprovante e os demais anexos do título** no e-mail, e nenhum link para o sistema: são pessoas de fora, e um botão para uma tela onde elas não entram seria uma porta trancada. informação **Por que aqui pode ser e-mail livre e na outra lista não?** Comprovante é documento que se manda para fora — exigir que o contador do fornecedor vire membro do seu espaço de trabalho para receber um não é controle, é um muro. O que mantém esta lista sob controle é o alcance: ela pertence **àquele título**, é editada no formulário dele e vai embora com ele, então não sobra endereço herdado que ninguém lembra de tirar. A lista **se repete na série**: ao criar um parcelamento ou uma recorrência, cada parcela e cada ocorrência nasce com os mesmos destinatários, porque cada uma gera o seu próprio comprovante. Alterá-la depois muda só o título editado. ### Quando o e-mail sai[​](#quando-o-e-mail-sai "Link direto para Quando o e-mail sai") Em qualquer uma das três formas de um comprovante chegar a um título: * a **captura automática**, quando o banco confirma o pagamento; * o **envio manual já vinculado** a uma conta a pagar; * **"Vincular a um título"**, num comprovante que estava sem vínculo. Sem ninguém nas duas listas, nenhum e-mail é enviado — e nada falha por causa disso. O aviso no **sino** continua acontecendo de qualquer forma. Quem está nas duas listas recebe **uma vez só**. observação **O e-mail sai sempre no idioma padrão do produto.** O aviso no sino, esse sim, aparece no idioma de cada pessoa. ### O que vai anexado[​](#o-que-vai-anexado "Link direto para O que vai anexado") O e-mail leva o **comprovante** e, junto, **todos os anexos do título** — a nota fiscal, o boleto, o contrato —, porque quem precisa do comprovante quase sempre precisa deles também. O comprovante vem primeiro; os demais, na ordem em que foram anexados ao título. **Os outros comprovantes do mesmo título não vão.** Um título pode ter mais de um (parcelas, um reenvio), e cada e-mail fala de um pagamento só — os anteriores já tiveram o aviso deles. observação **O e-mail tem limite de tamanho.** Se os arquivos somados passarem de **25 MB**, os que não couberem ficam de fora, e o próprio e-mail diz quais foram — melhor chegar o resto do que não chegar nada. observação **Comprovante que o banco só entrega como página não tem arquivo para anexar.** O e-mail sai mesmo assim, só com os demais anexos do título. ## Comprovantes de pagamentos antigos[​](#comprovantes-de-pagamentos-antigos "Link direto para Comprovantes de pagamentos antigos") A captura é disparada pela confirmação do pagamento, então ela não alcança o passado: pagamentos confirmados **antes** de o recurso existir não têm comprovante aqui. Quem administra o ambiente pode rodar uma varredura única para buscá-los — ela é propositalmente lenta, para não consumir o limite de consultas do banco. ## Relacionado[​](#relacionado "Link direto para Relacionado") * [Contas a pagar — envio ao banco](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md) — o que produz a confirmação que gera o comprovante * [Anexos](https://docs.finance.kobana.com.br/pt/pt/anexos/.md) — a biblioteca onde o documento capturado é guardado * [Integração Gateway Bancário](https://docs.finance.kobana.com.br/pt/pt/integracoes/kobana.md) — a conexão que torna a captura possível * [Contas a pagar — o formulário](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/.md#envio-do-comprovante) — onde se cadastram os destinatários de um título * [API — Comprovantes](https://docs.finance.kobana.com.br/pt/pt/api/v1/list-receipts) — para ler os comprovantes de fora do sistema (somente leitura) * [API — Atualizar conta a pagar](https://docs.finance.kobana.com.br/pt/pt/api/v1/update-payable) — o campo `receipt_emails`, para cadastrar os destinatários de fora do sistema --- # Conciliação A tela **Conciliação** (`/conciliacao`) fecha as linhas do extrato bancário de uma conta. Cada linha é dinheiro que já saiu ou entrou; conciliar é dizer a que **título** ela corresponde — uma conta a pagar ou a receber — ou, quando não há título (uma tarifa, um aluguel que ninguém cadastrou, um dinheiro que só mudou de conta), lançar o que falta na hora. ## Conceito[​](#conceito "Link direto para Conceito") * **Lançamento** — a linha do extrato, como o banco a mandou (Open Finance, Gateway Bancário Kobana, arquivo OFX/QIF ou a importação da Fintera ou da Nibo). Ela já é um lançamento da conta, normalmente classificado pelas [regras automáticas](https://docs.finance.kobana.com.br/pt/pt/regras-automaticas/.md) quando chega. * **Título** — a conta a pagar ou a receber. Uma linha está **aberta** enquanto não tem título, não faz parte de um grupo de conciliação e não é perna de uma transferência. Só as linhas abertas aparecem na tela; a linha conciliada sai dela. O que não é movimento do banco nunca aparece: uma linha de valor zero, um **ajuste de saldo** feito na conta e o saldo inicial que a importação da Nibo grava. Quando a Nibo quitou um agendamento em várias linhas do extrato, a importação já concilia todas elas com o título: essas linhas não aparecem aqui, e o título mostra todas na conciliação dele. Quando a baixa acontece pelo próprio título (**"Marcar como pago"** / **"Marcar como recebido"**), o sistema cria um lançamento ligado a ele. Se depois a linha do extrato chega, a conciliação troca esse lançamento automático pela linha do banco. ## Pré-requisitos[​](#pré-requisitos "Link direto para Pré-requisitos") * **Uma conta escolhida.** A conciliação é feita conta a conta: com **Todas as contas** no topo da tela, ela pede *"Escolha uma conta"*. * **Conta que concilia.** A conta precisa estar ativa e com a conciliação habilitada; senão a tela mostra *"Conciliação desativada nesta conta"* (ou *"Nenhuma conta disponível"* quando nenhuma concilia). * **Conta com empresa.** Os títulos são por empresa: uma conta sem empresa mostra *"Conta sem empresa associada"*. ## O topo[​](#o-topo "Link direto para O topo") * **Manual** / **Em lote** — os dois modos. A escolha fica lembrada. * **Voltar para o extrato** — o extrato da conta, onde também se desfaz uma conciliação. * **Regras automáticas** — a tela de [regras](https://docs.finance.kobana.com.br/pt/pt/regras-automaticas/.md). * **Importar** — **Arquivo OFX ou QIF**, **Planilha** ou **Extratos importados**, na página da conta. * **O bloco da conta** — banco, agência e conta, o selo **Conectada Open Finance** quando é o caso, **Alterar conta** e a hora em que o extrato foi lido pela última vez: a última leitura do Open Finance ou do Gateway Bancário, ou a última importação de arquivo numa conta manual. ### Filtros e ordem[​](#filtros-e-ordem "Link direto para Filtros e ordem") Os dois modos filtram por **Período**, **Descrição ou nome**, **Valor** (Mín e Máx) e **Tipo** (Entradas ou Saídas). Os filtros valem ao clicar em **Filtrar** e ficam lembrados. O período começa vazio: todas as linhas abertas da conta. A ordem pode ser **por data** (o padrão, da mais antiga para a mais nova), **por descrição**, **por valor** ou **por relevância**. A **relevância** de uma linha é quantas linhas abertas da conta têm o mesmo texto do banco: ordenar por ela traz primeiro o que mais se repete — tarifas, aluguel, folha. ## Manual[​](#manual "Link direto para Manual") Uma linha por cartão. À esquerda, o que o banco mandou: data, valor (seta para a esquerda e verde na entrada, para a direita e vermelho na saída, como em Lançamentos), o texto do banco e a contraparte, quando conhecida. Embaixo, **Criar regra** e a lixeira. À direita, três abas e o botão **OK**. O cartão abre em **Sugestão** quando há uma; senão, em **Novo lançamento**. ### Sugestão[​](#sugestão "Link direto para Sugestão") O título que fecha a linha: * **mesmo valor**, sempre; * da **mesma empresa** e do sentido certo (saída com conta a pagar, entrada com conta a receber); * **pendente ou atrasado**, ou já **baixado pelo lançamento automático** e ainda sem conciliação; * escolhido pela **contraparte** — o documento da pessoa do título escrito na linha, a pessoa que a regra já pôs na linha, o nome — e pela **proximidade da data**, até 45 dias. Sem nenhum sinal de contraparte, a sugestão só aparece para um título sozinho a até 7 dias. Quando dois títulos empatam, não há sugestão: a escolha fica com você, em **Buscar / Criar vários**. A sugestão também pode ser a **outra ponta de uma transferência**: a única linha aberta de outra conta do espaço, no sentido oposto, com o mesmo valor e até 3 dias de distância — *"Transferência para (conta)"* numa saída, *"Transferência de (conta)"* numa entrada. **OK** concilia: o título fica pago ou recebido com a linha do extrato. A mesma sugestão pode aparecer em várias linhas iguais; depois do OK, a outra linha passa à sugestão seguinte. ### Novo lançamento[​](#novo-lançamento "Link direto para Novo lançamento") Quando nada fecha a linha, ela vira um título novo, **já baixado** com o valor, a data e a conta da linha: * **Tipo** — **Pagamento** numa saída, **Recebimento** numa entrada, ou **Transferência**. * **Fornecedor** ou **Cliente**, **Descrição**, **Categoria** e **Centro de classificação**. A descrição vem com o texto do banco. * O **clipe** anexa um arquivo ao título criado. * **Criar agendamento detalhado** abre o formulário completo da conta a pagar ou a receber, preenchido com o que está no cartão (um contato **Novo** e o anexo não vão junto). Ao salvar, ele volta conciliado. O título criado aqui não passa pela aprovação de pagamento nem vai ao banco: ele já nasce pago. A classificação dele também vai para a linha do extrato; o que o título não traz, a linha mantém. Fornecedor ou cliente, categoria e centro precisam ser da empresa da conta. #### Palpites[​](#palpites "Link direto para Palpites") Com **Exibir palpites** ligado (ao lado de *"Extrato no Financeiro Inteligente"*), o formulário vem preenchido, com a faixa **palpite**: 1. o que a linha já carrega — a pessoa, a categoria e o centro que uma regra automática pôs nela; 2. senão, a última classificação usada para o **mesmo texto do banco**, na mesma empresa e no mesmo sentido, no último ano; 3. senão, a pessoa cujo CPF/CNPJ está escrito na linha e a categoria do último título dela. Quando a linha traz um **CNPJ que não é de ninguém cadastrado** (o pagador ou recebedor do Open Finance, ou o documento no texto do banco), o fornecedor ou cliente vem com o selo **Novo** e a razão social registrada na Receita. O OK cria a pessoa junto com o título. Desligar **Exibir palpites** deixa contato, categoria e centro em branco. A escolha fica lembrada. #### Transferência[​](#transferência "Link direto para Transferência") Com **Tipo** = **Transferência**, o formulário pede a **Conta de destino** e a descrição. A linha vira uma perna da transferência: * se a conta de destino tem uma linha aberta no sentido oposto, com o mesmo valor e até 3 dias de distância, as duas são pareadas; * senão, a outra perna é escrita na conta de destino. Nunca nascem duas pernas novas. Contas de cartão de crédito não aparecem como destino. #### Conciliar todos[​](#conciliar-todos "Link direto para Conciliar todos") No OK de um novo lançamento, se há outras linhas abertas da conta com **o mesmo valor, sentido e texto do banco**, a tela pergunta *"Conciliar todos de uma vez?"*: * **Só este** — concilia só a linha do cartão; * **Conciliar todos** — cria um título igual para cada linha, numa ação só. Uma linha que não pôde acompanhar (alguém a conciliou no meio do caminho, por exemplo) fica aberta, e o aviso diz quantas. ### Buscar / Criar vários[​](#buscar--criar-vários "Link direto para Buscar / Criar vários") Para a linha que fecha com **mais de um título** — um TED que pagou três notas — ou com um título que a sugestão não achou: Ao abrir a aba, a busca aparece **embaixo do cartão, na largura toda**; no lugar do formulário fica o que já foi escolhido. 1. **Pagamentos** (ou **Recebimentos**, numa entrada) e **Transferências**. 2. Filtros **Nome**, **Período**, **Descrição ou referência**, **Valor** (exato) e **Categoria**, e **Filtrar**. Sem filtro, a lista vem por valor, até 100 por vez. 3. Marque os títulos. A seleção **acumula entre buscas** e sobe para o cartão, com o clipe e o X de cada um — e o lápis, quando há um título só e pendente. 4. O cartão mostra *"Faltam (valor) para conciliar"* até a soma fechar — ou *"Passam (valor) do valor deste lançamento"*, quando passa. 5. **Criar novo lançamento** (ou o link *"crie um novo pagamento"*, antes de marcar algum) abre *"Novo pagamento"* ou *"Novo recebimento"* com o valor que falta: **Descrição**, **Fornecedor** ou **Cliente**, **Categoria** e **Centro de classificação**. **Salvar** o põe no cartão; o **OK** concilia tudo junto. O **OK** só habilita com a soma exata. Com um título só, o lápis abre **Juros e desconto**: o valor do título mais juros, menos desconto, precisa dar o valor da linha. Em **Transferências**, a lista traz as linhas abertas de outras contas do espaço; parear exige o mesmo valor. Títulos e transferência não se misturam na mesma conciliação. ### Criar regra e excluir[​](#criar-regra-e-excluir "Link direto para Criar regra e excluir") * **Criar regra** abre uma [regra automática](https://docs.finance.kobana.com.br/pt/pt/regras-automaticas/.md) nova, pré-preenchida com a conta, o sentido, o texto do banco e a classificação do cartão. Salva, ela volta para a conciliação. * A lixeira exclui o lançamento importado, depois de confirmar: *"Ele sai do extrato da conta e a próxima sincronização ou importação não o traz de volta."* ## Em lote[​](#em-lote "Link direto para Em lote") Uma tabela com uma linha por lançamento aberto, para lançar **muitas linhas novas de uma vez** — tarifas, transferências entre contas próprias, o que se repete todo mês: | Lado | Colunas | | ---------------------- | -------------------------------------------------------- | | **O importado** | Data, Descrição, Pagador/beneficiário, Valor, Relevância | | **O que será lançado** | Tipo, Descrição, Fornecedor/Cliente ou conta, Categoria | As colunas Data, Descrição, Valor e Relevância ordenam a tabela; clicar de novo inverte. A parte da direita já vem preenchida pelo palpite, e a descrição, com o texto do banco. * **Pronta** — a linha fica **verde** quando tem descrição, contato e categoria; numa transferência, descrição e conta de destino. Ao marcar linhas, aparece logo acima da tabela a barra de ações em lote, como nas outras listagens: quantas estão selecionadas, quantas estão prontas para conciliar, **Editar** e **Conciliar**. * **Editar** — abre *"Editar N lançamentos"*: os campos preenchidos valem para todas as marcadas (**Modificar**), e os vazios ficam como estão. A categoria só pode ser mudada quando as marcadas são todas entradas ou todas saídas. * **⋮ → Criar regra** — a mesma regra pré-preenchida do Manual. * **Conciliar** — concilia as marcadas que estão prontas; as outras ficam. Cada linha vai por conta própria: uma que falha (porque alguém a conciliou antes, por exemplo) não impede as outras, e o motivo aparece embaixo da descrição dela. O filtro **Lançamentos conhecidos** deixa só as linhas que o palpite conhece: as que já têm pessoa ou categoria, ou cujo texto do banco foi classificado no último ano. observação **O Em lote sempre cria um título novo** (ou uma transferência) por linha, sem centro de classificação. Uma linha que fecha com um título que já existe se concilia no **Manual**. ## Desfazer uma conciliação[​](#desfazer-uma-conciliação "Link direto para Desfazer uma conciliação") A tela não tem desfazer: a linha conciliada sai dela. Desfaz-se pelo extrato da conta (**Voltar para o extrato**), no detalhe do lançamento: * **Desvincular** — o título volta a pendente e a linha volta a ficar aberta. Num título criado pela conciliação, excluir o título também solta a linha. * **Desfazer conciliação** — no cartão de transferência de uma linha que veio do banco: a perna que a conciliação escreveu é apagada; uma linha pareada volta a ficar aberta. Só vale para a transferência de uma linha do extrato: a transferência lançada à mão se exclui na própria tela. observação **Conciliação importada não se desvincula.** Uma conciliação espelhada do Fintera é somente leitura: ela reflete o sistema de origem, e a próxima importação a traria de volta. ## Contagens de outras telas[​](#contagens-de-outras-telas "Link direto para Contagens de outras telas") A listagem de [lançamentos](https://docs.finance.kobana.com.br/pt/pt/lancamentos/.md) tem o filtro **Conciliados**, que olha só o vínculo com títulos. A Conciliação também trata como resolvida a linha que virou perna de transferência — por isso uma linha pode estar fora da Conciliação e ainda aparecer como não conciliada na listagem de lançamentos. ## Estados vazios[​](#estados-vazios "Link direto para Estados vazios") * **"Nada a conciliar"** — todas as linhas da conta, com os filtros aplicados, estão conciliadas. Um período ou valor diferente pode trazer outras. ## Pela API e pelo MCP[​](#pela-api-e-pelo-mcp "Link direto para Pela API e pelo MCP") As mesmas ações existem na API v1, sob o escopo `finance/reconciliations`: * [as sugestões de uma linha](https://docs.finance.kobana.com.br/pt/pt/api/v1/get-reconciliation-suggestions) — o título ou a transferência que a fecha, o palpite e as linhas gêmeas; * [o título novo já baixado](https://docs.finance.kobana.com.br/pt/pt/api/v1/reconcile-with-new-billing), com conciliar todos; * [a transferência](https://docs.finance.kobana.com.br/pt/pt/api/v1/reconcile-as-transfer); * [o lote](https://docs.finance.kobana.com.br/pt/pt/api/v1/reconcile-transactions-batch). A conciliação de títulos que já existem, inclusive vários com vários lançamentos, é a [criação de conciliação](https://docs.finance.kobana.com.br/pt/pt/api/v1/create-reconciliation). No MCP, as mesmas ações são as tools de [lançamentos](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/transactions.md). --- # Contas a pagar Contas a pagar (`/payables`) registram os compromissos de saída da organização: faturas de fornecedores, despesas operacionais, tributos, folha de pagamento e qualquer obrigação de desembolso futuro ou passado. ![Listagem de contas a pagar](/pt/assets/images/01-payables-ff5ad615c47a0aa4fce7054199b7469c.png) ![Detalhe de conta a pagar](/pt/assets/images/02-payable-detail-42f742e0eec8c573adb32d8beaa3ae45.png) ## Nesta seção[​](#nesta-seção "Link direto para Nesta seção") ## [📄️Ciclo de vida](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/ciclo-de-vida.md) [Estados, transições e o portão de aprovação — Rascunho → Pendente → Pago.](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/ciclo-de-vida.md) ## [📄️Parcelas e recorrência](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/parcelas-e-recorrencia.md) [Dividir em parcelas ou repetir periodicamente — os três tipos de conta e o comportamento das séries.](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/parcelas-e-recorrencia.md) ## [📄️Operação e pagamento](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/operacao-e-pagamento.md) [Tipo de operação, documento (boleto, conta de consumo, tributo, PIX), transferência (TED, PIX) ou débito automático, e as coordenadas de pagamento.](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/operacao-e-pagamento.md) ## [📄️Tributos](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/tributos.md) [DARF, DARE, GRU, GPS, FGTS, ICMS, ISS, IPTU e ITBI — como informar a guia e o que vai ao banco.](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/tributos.md) ## [📄️Envio ao banco (Gateway Bancário)](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md) [Enviar contas a pagar aprovadas ao banco pelo Gateway Bancário — pré-requisitos, status e liquidação automática.](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md) ## [📄️Importação CSV](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/importacao-csv.md) [Importar lotes de contas a pagar via planilha — colunas aceitas, formato tolerante e o portão de aprovação.](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/importacao-csv.md) ## A listagem[​](#a-listagem "Link direto para A listagem") O cabeçalho abre com três totais do período — **A pagar**, **Pago** e **Total** — e um subtítulo acionável: havendo atraso, *"Você tem 3 contas atrasadas"* traz o trecho em vermelho como botão que aplica o filtro de vencidas; sem atraso, *"Você está em dia com as contas."* No cabeçalho ficam o botão de **período**, **"Nova conta a pagar"** e — **só com o gateway conectado** — **"Enviar pagamentos"**, que abre o inbox de envio em lote. O contador vermelho ao lado conta tudo o que o inbox vai listar: os títulos **vencidos e a vencer nos próximos 7 dias**, prontos ou bloqueados. É por ali que sai o lote; da listagem não há atalho por linha para o banco. À direita dos totais, as pílulas **"Importar"** (abre o painel abaixo e limpa busca e filtros) e **"Relatório"** (abre em diálogo). Importar exige uma **empresa específica** selecionada. ### Filtros[​](#filtros "Link direto para Filtros") * **Busca** — por descrição ou número de documento. * **Filtros rápidos** — **Todas**, **Com anexos**, **Pagas**, **Conciliadas**, **Rascunhos**. * **Filtros avançados** — painel com os critérios combinados, contador de ativos e um resumo para limpar ou editar. ### Colunas[​](#colunas "Link direto para Colunas") Descrição, Vencimento, Categoria, **Status geral**, **Status no banco**, Valor e **Liquidação** — mais **Empresa**, só na visão consolidada. **IR** e **Observações** vêm ocultas; **Liquidação** também. Ative-as pelo menu de colunas. observação **Status geral e Status no banco são duas colunas, ordenáveis, lado a lado** — não um status com um chip grudado. Uma diz o que o Financeiro Inteligente sabe; a outra, o que o banco reporta. Ver [Ciclo de vida](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/ciclo-de-vida.md). ### Ações de linha[​](#ações-de-linha "Link direto para Ações de linha") As mesmas nove do lado de receber, com os rótulos do pagar: | Ação | Quando aparece | | -------------------- | ----------------------------------------------------------------------- | | **Marcar como pago** | Enquanto a baixa manual for possível | | **Conciliar** | Já paga e ainda não conciliada | | **Parcelas** | Tipo Parcelado | | **Recorrências** | Tipo Recorrente, dentro de uma série | | **Classificar** | Sempre | | **Editar** | Sempre | | **Desfazer** | Já paga | | **Cancelar** | Só pendente, e **fora** do trilho do gateway | | **Excluir** | Fora do banco: nunca enviado, ou com o pagamento rejeitado ou cancelado | aviso **Título já despachado ao banco não oferece "Marcar como pago", "Cancelar" nem "Excluir".** Anular ou apagar aqui deixaria o pagamento vivo no gateway, sem o título que o explica. Depois de pago, ele também fica: é o registro do que saiu da conta. O caminho é **"Cancelar envio"**, no card do gateway na tela de detalhe. Cancelar o envio **não desfaz o despacho**: o título continua no trilho do gateway, agora com o selo **Cancelado**. Quem volta é só o **"Marcar como pago"** — o envio não efetivou, então o título segue pendente e alguém precisa fechá-lo por fora. **"Cancelar" não volta:** uma vez enviado ao banco, o título nunca mais é cancelável pela listagem. Ver [Envio ao banco](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md). ### Ações em lote[​](#ações-em-lote "Link direto para Ações em lote") **"Classificar selecionados"** (só com empresa específica), **"Marcar como pagas"** e **"Excluir"**, com os totais **A pagar**, **Pago** e **Total** da seleção ao vivo. **"Marcar como pagas"** abre um diálogo com a **Data de pagamento** (hoje, por padrão). Cada conta é paga pelo próprio valor, da **conta de origem** prevista nela; se alguma selecionada não tiver uma, o diálogo pede a conta para essas. Juros e descontos ficam de fora — para eles, dê baixa em uma de cada vez. O que a linha não deixaria marcar como pago (já paga, enviada ao banco, esperando aprovação) fica de fora, e o diálogo diz quantas. ## O formulário[​](#o-formulário "Link direto para O formulário") **A empresa não é campo** — vem do seletor do cabeçalho. ### ESSENCIAL[​](#essencial "Link direto para ESSENCIAL") | Campo | Observações | | ---------------------- | -------------------------------------------------------------------------------------------------- | | **Valor (R$)** | Obrigatório. Campo de moeda com máscara | | **Vencimento** | Obrigatório. Ao criar, há atalhos de data relativa | | **Pagar via** | Conta financeira esperada para a saída | | **Descrição** | Obrigatório | | **Fornecedor** | Obrigatório. Escolher um fornecedor já cadastrado **pré-carrega as informações de pagamento dele** | | **Mês de competência** | Obrigatório. Seletor de mês | observação **"Pagar via" é a conta prevista, e é o único campo de conta do formulário.** A conta que **efetivamente** pagou não se digita aqui: ela é escolhida na baixa, no campo **"Conta de origem"** do diálogo "Confirmar pagamento". ### CLASSIFICAÇÃO[​](#classificação "Link direto para CLASSIFICAÇÃO") **Tipo** (obrigatório: **À vista**, **Recorrente**, **Parcelado**, revelando **Recorrência** ou **Nº de parcelas**), **Categoria** e **Centro de classificação**, cada um com o atalho **Rateio**. ### OPERAÇÃO & DOCUMENTO[​](#operação--documento "Link direto para OPERAÇÃO & DOCUMENTO") O eixo que distingue contas a pagar de contas a receber: * **Tipo de operação** — **Pagamento de documento** ou **Transferência**. * O campo seguinte **só aparece depois** dessa escolha, e muda de nome com ela: **"Documento"** (Boleto, Conta de consumo, Tributo, PIX…) ou **"Tipo de transferência"** (**Transferência (TED)**, PIX). Trocar a operação limpa um método incompatível. * **Nº de documento** e **Data do doc.** A escolha destrava as coordenadas de pagamento — código de barras, PIX, dados bancários, dados da guia. Ver [Operação e pagamento](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/operacao-e-pagamento.md) e [Tributos](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/tributos.md). ### ENVIO DO COMPROVANTE[​](#envio-do-comprovante "Link direto para ENVIO DO COMPROVANTE") Quem recebe o **comprovante** deste pagamento por e-mail, **com o arquivo anexado** — e, junto, os [demais anexos do título](https://docs.finance.kobana.com.br/pt/pt/comprovantes/.md#o-que-vai-anexado) —, assim que um comprovante for anexado ao título. Aceita **qualquer endereço** — o contador do fornecedor, o favorecido —, com um **rótulo** opcional para identificar cada um. A lista vale **para este título**. Ao criar um parcelamento ou uma recorrência, cada parcela e cada ocorrência **nasce com os mesmos destinatários**, porque cada uma gera o seu próprio comprovante — mas alterar a lista depois muda **só o título que você está editando**. Ela **não substitui** os membros marcados em [Comprovantes](https://docs.finance.kobana.com.br/pt/pt/comprovantes/.md#quem-recebe-por-e-mail): esses continuam recebendo os avisos deles. observação **Este bloco não depende da operação escolhida.** Ao contrário das coordenadas de pagamento, ele não muda nem se limpa quando você troca o documento ou o tipo de transferência — e continua editável mesmo depois de o banco confirmar o pagamento, porque diz a quem avisar, não o que o banco fez. ### Impostos retidos · Observação e IR[​](#impostos-retidos--observação-e-ir "Link direto para Impostos retidos · Observação e IR") **Impostos retidos** (pílulas de tributos na fonte), a pílula **"Relevante para IR"** e **"Adicionar observação"**. ### Anexos[​](#anexos "Link direto para Anexos") Ao criar, é possível anexar arquivos antes de salvar. ## Confirmar pagamento[​](#confirmar-pagamento "Link direto para Confirmar pagamento") Duas abas: * **Pagar** — **Data de pagamento** e **Conta de origem**. Marca como paga e cria o lançamento de débito. * **Pagar e conciliar** — *"Pague esta conta vinculando-a a um lançamento que já existe no extrato — sem gerar um duplicado."* Nas duas abas, a seção **"Ajustes do pagamento"** (opcional) aceita **Juros** e **Desconto**. Abaixo dela, o **Valor pago** mostra quanto sai da conta. Em **Pagar**, é esse valor, e não o do título, que vira o lançamento de débito; em **Pagar e conciliar**, é com ele que o lançamento escolhido é comparado, e os juros e o desconto ficam registrados na conta. aviso **Pagamento confirmado pelo banco trava parte do formulário.** *"O que descreve o pagamento — valor, vencimento, fornecedor e as informações de pagamento — não pode mais ser alterado. A classificação interna (categoria, centro, anexos, observações) continua editável."* Ver [Ciclo de vida](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/ciclo-de-vida.md). --- # Ciclo de vida das contas a pagar Uma conta a pagar é descrita por **três camadas independentes**. Elas não se substituem — convivem, e a tela mostra todas: | Camada | O que responde | Onde aparece | | ------------------------ | ------------------------------------------------------------------------- | ---------------------------- | | **1. Status do título** | Onde o título está no Financeiro Inteligente (Rascunho → Pendente → Pago) | Coluna **"Status geral"** | | **2. Aprovação** | Uma pessoa liberou este pagamento? (portão de entrada) | Selo ao lado do status geral | | **3. Status no gateway** | Se foi enviado ao banco, em que pé está **lá** | Coluna **"Status no banco"** | observação A camada 3 só existe se o título foi enviado ao banco. Na listagem ela tem **coluna própria**: **"Status geral"** e **"Status no banco"** ficam lado a lado, ambas ordenáveis — o gateway nunca é um chip pendurado no status do título. São dois sinais distintos: um diz o que o Financeiro Inteligente sabe, o outro o que o banco reporta. Fora do trilho do gateway, a coluna mostra "-". O que aparece **ao lado** do status geral é a **camada 2**: o selo de aprovação. E na tela de detalhe o status do gateway não fica no cabeçalho — vive dentro do **card do gateway**. ## Camada 1 — Status do título[​](#camada-1--status-do-título "Link direto para Camada 1 — Status do título") | Estado | Descrição | | ------------- | ------------------------------------------------- | | **Rascunho** | Criado mas não publicado. Não aparece nos totais. | | **Pendente** | Confirmado, aguardando pagamento. | | **Pago** | Vinculado a um lançamento. | | **Cancelado** | Anulado, não gera movimentação. | A coluna mostra ainda um quinto selo, que **não é um estado**: **Atrasado** — todo título **Pendente** cujo vencimento já passou. É derivado da data, não gravado: nada "vira" atrasado, e pagar ou reagendar o faz sumir sozinho. * **Publicar** (Rascunho → Pendente): confirma o título — mas ele ainda passa pela camada 2. * **Marcar como pago** (Pendente → Pago): há dois caminhos — ver "Como um título vira Pago", abaixo. * **Cancelar** (Pendente → Cancelado): anula. Só aparece em título pendente, e **não é irreversível** — o diálogo diz *"Você pode reabri-la depois editando o status."* ## Camada 2 — Aprovação de pagamento[​](#camada-2--aprovação-de-pagamento "Link direto para Camada 2 — Aprovação de pagamento") Portão anti-fraude: um título criado por formulário, CSV ou API **não entra na lista oficial** até que uma pessoa o aprove em [Aprovar pagamentos](https://docs.finance.kobana.com.br/pt/pt/aprovar-pagamentos/.md) (`/payables/approvals`). O portão é uma configuração do espaço de trabalho, **ligada por padrão**; desligada, os títulos criados já nascem oficiais e pulam a fila. | Estado | Significado | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | **Aguardando aprovação** | Aguardando alguém aprovar. **Fora da lista oficial** — não conta em totais nem no fluxo de caixa, e não pode ir ao banco. | | **Aprovado** | Liberado — entra na lista oficial e fica elegível para envio ao banco. | | **Recusado** | Bloqueado definitivamente. | | *(sem selo)* | Já nasce oficial, sem passar pela fila. | O portão vale para quem **entra pela porta da frente**: formulário, importação CSV e API. Nascem **oficiais, sem aprovação**, os títulos que o próprio sistema gera a partir de algo que já foi decidido antes — as ocorrências de uma recorrência já aprovada e o que vem importado do Fintera. As ocorrências de uma recorrência que ainda aguarda aprovação nascem aguardando também, com o mesmo autor — quem a criou não aprova nenhuma delas. aviso **Salvar como rascunho não escapa do portão.** O rascunho não tem selo porque ainda não é obrigação nenhuma — mas **publicar** é o momento em que ele vira uma, e é aí que ele entra na fila, como qualquer título criado direto. Rascunho não é atalho. Enquanto aguarda aprovação, **o "Marcar como pago" manual também some** — o título ainda não é oficial. ## Camada 3 — Status no gateway[​](#camada-3--status-no-gateway "Link direto para Camada 3 — Status no gateway") Só passa a existir depois do envio ao banco. Espelha o estado **real** do pagamento no gateway — de **Pendente** e **Aguardando aprovação do banco** até **Confirmado**, passando por **Agendado**, **Aguardando saldo** e afins. A lista completa, com o que cada um significa, está em [Envio ao banco](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md). observação **Duas aprovações, sem parentesco.** A da camada 2 é de uma pessoa do seu espaço de trabalho, e libera a **entrada na lista**. A do banco é a da instituição, e acontece só depois do envio. Um título pode estar aprovado aqui e recusado lá. aviso **"Aprovado" no gateway não é o fim.** Significa que o lote foi aprovado pelo banco — a instituição **ainda não confirmou**. Quem fecha o ciclo é o **Confirmado**. Os estados finais são Confirmado, Cancelado, Rejeitado, Reprovado e Falhou. **"Enviar para o banco" não é ação de linha da listagem.** Ela existe em dois lugares, os dois na tela de **detalhe**: o cabeçalho e o card do gateway. Da listagem, o caminho é **"Enviar pagamentos"**, no cabeçalho — o inbox que despacha em **lote**. ## Como um título vira Pago — dois trilhos[​](#como-um-título-vira-pago--dois-trilhos "Link direto para Como um título vira Pago — dois trilhos") Há **dois caminhos** para o título ser pago, e eles são mutuamente exclusivos. ### Trilho manual — o pagamento aconteceu por fora[​](#trilho-manual--o-pagamento-aconteceu-por-fora "Link direto para Trilho manual — o pagamento aconteceu por fora") Você pagou o título **fora do sistema** (internet banking, dinheiro, caixa…). Use **"Marcar como pago"**: * Informe a data de pagamento e a conta financeira utilizada. * O sistema marca como **Pago** e cria o lançamento de saída nessa conta. * Juros e descontos podem ser registrados na baixa. ### Trilho gateway — o envio foi feito pelo sistema[​](#trilho-gateway--o-envio-foi-feito-pelo-sistema "Link direto para Trilho gateway — o envio foi feito pelo sistema") Você clicou **"Enviar para o banco"**. A partir daí **você não dá baixa** — o sistema faz sozinho: * Quando o gateway chega a **Confirmado**, o título é marcado **Pago** **automaticamente** e o lançamento de saída é criado na conta de origem. * Por isso, no trilho do gateway, o botão **"Marcar como pago" desaparece** — é o que evita a baixa dupla. aviso **Requisito da baixa automática:** a conta de origem (**"Pagar via"**) precisa estar definida. Sem ela o sistema não tem de onde lançar a saída e **não** baixa — o título fica Confirmado e em aberto (ver abaixo). ### Quando o "Marcar como pago" volta a aparecer[​](#quando-o-marcar-como-pago-volta-a-aparecer "Link direto para Quando o \"Marcar como pago\" volta a aparecer") Se o envio **terminou** e mesmo assim o título ficou em aberto, o botão manual é reexposto para você fechá-lo por fora: * **Confirmado sem conta de origem** — o banco confirmou, mas o sistema não tinha onde lançar. * **Cancelado, Rejeitado, Reprovado ou Falhou** — o pagamento não se efetivou; precisa acontecer por fora. ## Fluxo completo[​](#fluxo-completo "Link direto para Fluxo completo") **Rascunho é um desvio opcional, não a porta de entrada.** Criar pelo formulário, pelo CSV ou pela API grava o título direto como Pendente e aguardando aprovação. Só quem clica **"Salvar rascunho"** passa por ali — e publicar dali cai no mesmo portão, não o contorna. ## Criar uma conta a pagar[​](#criar-uma-conta-a-pagar "Link direto para Criar uma conta a pagar") 1. Acesse `/payables/new`. 2. Preencha os campos obrigatórios: **Valor (R$)**, **Vencimento**, **Descrição**, **Fornecedor**, **Mês de competência** e **Tipo**. 3. Defina o tipo de operação e o documento — ver [Operação e pagamento](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/operacao-e-pagamento.md). Categoria e centro de classificação são opcionais. 4. Conclua com **Adicionar conta**, **Adicionar e criar outra** ou **Salvar rascunho**. **O fornecedor não é opcional.** Sem ele o formulário não envia: *"Selecione ou crie um fornecedor"*. Você pode escolher um fornecedor que já existe **ou digitar um nome novo** — nesse caso ele é cadastrado junto. A **Empresa** também é obrigatória, mas não é um campo do formulário: vem do seletor no cabeçalho. observação **"Publicar" não existe na tela de criação.** Os botões ali são os três acima. **Publicar** aparece só no **detalhe**, e só enquanto a conta é um rascunho. Em ambos os casos o título entra sob aprovação (camada 2) antes de contar nos números. ## Editar[​](#editar "Link direto para Editar") **Conta paga não é somente leitura.** Não existe trava por estado: o formulário abre normalmente em qualquer status, inclusive Pago. A trava real é outra, e vem do banco — não do estado do título. **Quando o gateway chega a Confirmado**, parte do formulário fecha, e a tela avisa: > *"Pagamento confirmado pelo banco. O que descreve o pagamento — valor, vencimento, fornecedor e as informações de pagamento — não pode mais ser alterado. A classificação interna (categoria, centro, anexos, observações) continua editável."* Ou seja: **a trava é parcial e tem um motivo**. Congela o que descreve uma transação bancária **já executada** — valor, vencimento, fornecedor, "Pagar via", tipo de operação, documento e as coordenadas de pagamento. Continua aberto o que descreve **como você classifica** aquilo: categoria, centro, competência, descrição, anexos, observações e os destinatários do **envio do comprovante** — esse último porque diz a quem avisar, não o que o banco fez. Classificar é trabalho contábil que segue depois de o dinheiro sair. aviso **A trava não é só visual.** O servidor recusa a alteração desses campos mesmo por API — a tela desabilitar os campos é a cortesia; a regra vale de qualquer porta. Essa trava **não existe em contas a receber** — elas não passam pelo envio ao banco. Editando uma conta que faz parte de um grupo, o sistema oferece **"Aplicar às demais parcelas"**, mostrando antes o que exatamente vai mudar. São **todas** as parcelas do grupo — inclusive as **anteriores** à que você está editando, não só as seguintes. Ficam de fora apenas as já liquidadas e a própria parcela editada. A seleção vem marcada por inteiro; desmarque o que não deve herdar — ou salve só na parcela aberta, em **"Apenas esta parcela"** (numa recorrência, **"Apenas esta ocorrência"**). observação **Os destinatários do comprovante não entram nesse "aplicar às demais".** Eles são copiados para todas as parcelas **na criação** da série; alterá-los depois vale só para a parcela que você está editando. Precisando mudar em todas, edite uma por uma. ## Excluir[​](#excluir "Link direto para Excluir") Em uma conta que faz parte de um grupo — **parcelada ou recorrente** —, a exclusão pergunta o alcance: * **Excluir apenas esta** * **Excluir esta e as futuras** O mesmo seletor cobre os dois casos: o que ele olha é o grupo, não o tipo. Em conta avulsa, ele não aparece. observação O seletor aparece **na listagem e no detalhe** da conta. --- # Envio de pagamentos ao banco O Financeiro Inteligente envia contas a pagar ao banco através do **Gateway Bancário**. O envio é uma ação **manual** — feita por uma pessoa, título a título ou em lote pelo inbox — **nunca** por um disparador automático, a não ser que o envio automático depois da aprovação esteja ligado nas [Configurações de Aprovação](https://docs.finance.kobana.com.br/pt/pt/aprovar-pagamentos/.md#ligar-ou-desligar). O acompanhamento do status roda em segundo plano. Antes de qualquer envio, valem as regras de [Segurança](https://docs.finance.kobana.com.br/pt/pt/seguranca/.md) do espaço de trabalho — limites, contas, favorecidos, tipos de operação, canais e horário noturno. Ver [Bloqueios de segurança](#bloqueios-de-seguran%C3%A7a). ## Pré-requisitos[​](#pré-requisitos "Link direto para Pré-requisitos") 1. [Gateway Bancário](https://docs.finance.kobana.com.br/pt/pt/integracoes/kobana.md) conectado e ativo, com a conta de origem já sincronizada. 2. Título **oficial**: só é enviável depois de passar pela [aprovação de pagamento](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/ciclo-de-vida.md) — ou de já nascer oficial, como as ocorrências de uma recorrência já aprovada e os títulos importados do Fintera. Um título aguardando essa aprovação ou recusado é barrado. Não confunda com a aprovação **do banco**, que só existe depois do envio. 3. **Tipo de operação** definido e as coordenadas de pagamento preenchidas — código de barras, chave PIX, dados bancários. Ver [Operação e pagamento](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/operacao-e-pagamento.md). 4. **"Pagar via"** definida — é dela que o dinheiro sai. 5. Permitido pela [Segurança](https://docs.finance.kobana.com.br/pt/pt/seguranca/.md): canal, tipo de operação, conta, favorecido, horário e limites. ## Fluxo de envio[​](#fluxo-de-envio "Link direto para Fluxo de envio") observação **Não existe "agendar" na tela.** O envio é sempre o seu clique — nada sai sozinho, em nenhuma data. O que o sistema manda ao banco, junto com o pagamento, é a data em que ele deve liquidar: o **vencimento** do título. Se o título já está vencido, vai **hoje** — o gateway não paga com data retroativa. ## Bloqueios de segurança[​](#bloqueios-de-segurança "Link direto para Bloqueios de segurança") As regras de [Segurança](https://docs.finance.kobana.com.br/pt/pt/seguranca/.md) são conferidas a cada envio — pelo botão, em lote ou no envio automático. **Nada é reagendado**: um título barrado fica com o motivo à vista e precisa ser enviado de novo quando a regra permitir. ### Motivos na lista de envio[​](#motivos-na-lista-de-envio "Link direto para Motivos na lista de envio") ![Lista de envio com bloqueios e aviso de limite da Segurança](/pt/assets/images/29-dispatch-inbox-db7804577f57796515275620e3093fad.png) No diálogo **Enviar pagamentos para o banco**, um título barrado por uma regra que só depende dele aparece **desabilitado**, com o motivo — passe o mouse para ler a mensagem completa: | Motivo | Onde se resolve | | -------------------------------------- | --------------------------------------------- | | **Canal sem permissão de envio** | Segurança → Canais (Pagar) | | **Tipo de operação desligado** | Segurança → Tipos de operações | | **Conta bloqueada para esta operação** | Segurança → Contas | | **Favorecido não liberado** | Segurança → Beneficiários (só transferências) | | **Envio noturno bloqueado** | Esperar o período diurno | | **Acima do limite por operação** | Segurança → Limites | Os limites que dependem do que **já foi enviado** aparecem como **aviso**, e a linha continua selecionável: * *Passaria do limite do período* * *Passaria do limite diário da conta* * *Passaria do limite diário do favorecido* * *Passaria do limite mensal do favorecido* O aviso é uma previsão: a conta final é feita no momento do envio. Num envio em lote, os títulos vão em ordem de vencimento, e quando um limite é atingido os seguintes que passariam dele **não são enviados**. O resultado lista cada título não enviado com o motivo. Se o envio automático depois da aprovação foi recusado por uma regra, a linha traz o selo **Envio automático bloqueado** — o título volta para a lista e espera um envio manual. observação **Forçar reenvio não escapa das regras.** Reenviar e reenviar um cancelado passam pelas mesmas checagens, e o envio anterior continua contando no limite enquanto não houver prova de que ele não existe no banco. ### Envio noturno desligado[​](#envio-noturno-desligado "Link direto para Envio noturno desligado") Com **Permitir envio ao banco no período noturno** desligado em Segurança, nada vai ao banco entre o início da noite e o início do dia. A lista mostra o aviso **"Envio ao banco bloqueado até 06:00"** (com o horário do seu espaço de trabalho). **Nada é reagendado para a manhã.** O que foi aprovado à noite — inclusive com o envio automático ligado — fica na lista e precisa ser enviado de novo no período diurno. ### Retidos no banco[​](#retidos-no-banco "Link direto para Retidos no banco") Um pagamento criado no fim do dia pode ter a aprovação automática do lote caindo já no período noturno. Com o envio noturno desligado, o lote **não é aprovado** e fica **retido no banco**: * o card do pagamento, no título, mostra o selo **"Retido no banco: envio noturno bloqueado"**; * a lista de envio ganha a seção **Retidos no banco**; * o botão **Aprovar no banco** (no card e na seção) só funciona no período diurno: confere as regras de novo, aprova o lote e retoma o acompanhamento. O **"Atualizar status"** e o acompanhamento automático não aprovam um lote retido. ## Status do gateway[​](#status-do-gateway "Link direto para Status do gateway") O status espelha o estado **real** do pagamento no gateway: | Status | O que significa | | ------------------------------------------- | --------------------------------------- | | **Pendente** | Criado no gateway, ainda não processado | | **Aguardando aprovação do banco** | Na fila de aprovação da instituição | | **Aprovado** | Aprovado — mas **ainda não liquidado** | | **Agendado** · **Aguardando data agendada** | Marcado para uma data futura | | **Aguardando saldo** | Sem fundos na conta para liquidar | | **Vencido** | Passou da data e não foi liquidado | | **Finalizando** | Em processamento final | | **Confirmado** | Liquidado — o dinheiro saiu | | **Reprovado** · **Rejeitado** | Recusado pela instituição | | **Falhou** | Erro no processamento | | **Cancelado** | Envio cancelado | aviso **"Aprovado" não é o fim.** É o estado que mais engana: o lote foi aprovado, mas a instituição **ainda não liquidou**. Quem fecha o ciclo é o **Confirmado**. Os estados finais são Confirmado, Cancelado, Rejeitado, Reprovado e Falhou. ## Liquidação automática[​](#liquidação-automática "Link direto para Liquidação automática") A baixa acontece quando o gateway chega a **Confirmado** — e não no Aprovado, que ainda é intermediário. Chegando lá, o sistema marca a conta como paga e cria o lançamento de saída na conta de origem. aviso **Sem "Pagar via" definida, não há baixa automática.** O sistema não teria de onde lançar a saída: o título fica Confirmado e em aberto. Ver [Ciclo de vida](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/ciclo-de-vida.md). O botão **"Atualizar status"** busca o estado atual sob demanda, sem esperar o acompanhamento automático. ## Comprovante[​](#comprovante "Link direto para Comprovante") Chegando a **Confirmado**, o comprovante do pagamento é **capturado sozinho**: fica guardado nos [Anexos](https://docs.finance.kobana.com.br/pt/pt/anexos/.md) do título e listado em [Comprovantes](https://docs.finance.kobana.com.br/pt/pt/comprovantes/.md). Quem estiver marcado para receber é avisado por e-mail, e os endereços cadastrados em **"Envio do comprovante"** no formulário do título recebem o **arquivo anexado**; o sino avisa de qualquer forma. Ver [Quem recebe por e-mail](https://docs.finance.kobana.com.br/pt/pt/comprovantes/.md#quem-recebe-por-e-mail). Enquanto ele está sendo buscado, a situação é **Baixando** — normal, e leva alguns instantes. ## Cancelar envio[​](#cancelar-envio "Link direto para Cancelar envio") **"Cancelar envio"** desfaz o envio enquanto o pagamento **não chegou a um estado final**. O título continua no trilho do gateway, agora com o selo **"Cancelado"**, e o **"Marcar como pago"** volta a aparecer — para você fechar o título por fora, se o pagamento acabar acontecendo de outro jeito. É por isso que um título já enviado **não** oferece "Cancelar": anular por aqui deixaria o pagamento vivo no gateway. O caminho é cancelar o envio primeiro. ## Editar depois do envio[​](#editar-depois-do-envio "Link direto para Editar depois do envio") Depois que o envio começa, **valor, favorecido, conta e dados de pagamento ficam travados**: *"Título já enviado ao banco — valor, favorecido, conta e dados de pagamento não podem mais ser alterados."* O título tem de continuar correspondendo ao que foi pago. Antes do envio, mudar esses campos num título aprovado o devolve para a [aprovação](https://docs.finance.kobana.com.br/pt/pt/aprovar-pagamentos/.md#editar-um-t%C3%ADtulo-aprovado). --- # Importação CSV — Contas a pagar Importe lotes de contas a pagar via arquivo CSV. ## Onde fica[​](#onde-fica "Link direto para Onde fica") **Não existe "Importação" no menu**, nem uma tela de importação. O caminho é: **Contas a pagar** → pílula **Importar**, na própria listagem. Sem nenhuma conta cadastrada ainda, a listagem mostra o quadro vazio com o botão **Importar** ao lado de **Nova conta a pagar**, que abre o mesmo painel. É preciso ter uma **empresa específica** selecionada no cabeçalho. Em "todas as empresas", o painel só avisa: *"Selecione uma empresa específica para importar contas a pagar."* O botão **Baixar modelo** entrega um CSV de exemplo com o cabeçalho correto — é o ponto de partida mais seguro, porque já vem no encoding certo. ## Colunas do CSV[​](#colunas-do-csv "Link direto para Colunas do CSV") | Coluna | Obrigatório | Descrição | | ---------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `description` | ✅ | Descrição da conta a pagar | | `amount` | ✅ | Valor em reais (ex.: `3500,00`) | | `due_date` | ✅ | Data de vencimento (`dd/MM/yyyy`) | | `competence_date` | — | Data de competência (`dd/MM/yyyy`) | | `document` | — | Identificador do documento | | `document_date` | — | Data de emissão (`dd/MM/yyyy`) | | `document_number` | — | Número da nota fiscal | | `person_name` | — | Nome do fornecedor (se ainda não existir, a prévia pergunta se cria) | | `category_name` | — | Nome da categoria (se ainda não existir, a prévia pergunta se cria) | | `cost_center_name` | — | Nome do centro de classificação (se ainda não existir, a prévia pergunta se cria) | | `payment_method` | — | Método: `boleto`, `concessionaria`, `tributo`, `ted`, `pix`, `cartao_credito`, `cartao_debito`, `dinheiro`, `cheque`, `debito_automatico`, `outro` ou `nenhum` (os literais em inglês do produto também valem) | | `notes` | — | Observações | | `ir_relevant` | — | `true` ou `false` | | `operation_kind` | — | `pagamento` ou `transferencia` | | `barcode` | — | Código de barras (boleto ou conta de consumo) | | `pix_copia_e_cola` | — | Payload PIX Copia e Cola | | `pix_key` | — | Chave PIX | | `pix_key_type` | — | Tipo da chave: `cpf`, `cnpj`, `email`, `phone`, `random` | | `bank_code` | — | Código COMPE do banco (TED) | | `bank_ispb` | — | ISPB do banco (TED) | | `agency` | — | Agência bancária | | `agency_digit` | — | Dígito da agência | | `account_number` | — | Número da conta | | `account_digit` | — | Dígito da conta | | `transfer_purpose` | — | Finalidade da transferência (TED) | | `tax_kind` | — | Tipo de tributo: `darf`, `gru`, `gps`, `fgts`, `icms`, `iss`, `iptu`, `itbi` ou `dare` | | `beneficiary_name` | — | Nome do beneficiário (envio ao banco) | | `beneficiary_document` | — | CPF ou CNPJ do beneficiário | | `scheduled_to` | — | Data/hora de agendamento do envio ao banco | Os nomes acima são os canônicos, mas **todo cabeçalho aceita o equivalente em português** — `descricao`, `valor`, `vencimento`, `fornecedor`, `categoria`, `observacao` e assim por diante. Planilhas de outros sistemas também funcionam para fornecedor, centro de classificação e categoria: `contraparte` vale como `person_name`; `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` valem como `cost_center_name`, e `plano_de_contas`, `categoria_financeira`, `category` como `category_name`. Se o espaço tiver um classificador com o mesmo nome de uma dessas colunas (ex.: *Centro de Resultado*), a coluna vai para o classificador. Se a planilha tiver mais de uma coluna para o mesmo campo (ex.: `Centro de Custo` e `Centro de Receita`), cada linha usa a primeira que estiver preenchida. Além desses nomes, um cabeçalho com a palavra **centro** é lido como centro de classificação; um com **categoria** ou **plano de contas**, como categoria (por exemplo, `Centro de Lucro`, `Categoria DRE`); e um com **pessoa**, **cliente** ou **fornecedor** acompanhada só de palavras de nome, como pessoa (por exemplo, `Nome do Fornecedor`, `Cliente / Fornecedor` — mas não `CNPJ do Fornecedor`). Colunas que o sistema não conhece são **ignoradas em silêncio**. ## Formato[​](#formato "Link direto para Formato") O parser é mais tolerante do que parece. Você não precisa normalizar o arquivo antes: * **Cabeçalho** — maiúsculas, acentos e espaços não importam: `Descrição`, `DESCRICAO` e `descricao` são a mesma coluna. * **Separador** — `,` ou `;`, detectado **pela linha de cabeçalho**. Em caso de empate, `;`. * **Datas** — `31/12/2026`, `31-12-2026` ou `2026-12-31`. * **Valores** — `1234.56`, `1.234,56`, `1234,56`, com ou sem `R$`. O valor precisa ser **maior que zero**. * **`ir_relevant`** — `true`/`false`, `sim`/`nao`, `yes`/`no`, `1`/`0`, `s`/`y`/`n`. Sem acento, maiúscula ou minúscula. Vazio deixa o campo em branco. aviso **A codificação precisa ser UTF-8, e é aqui que a maioria dos arquivos tropeça.** O Excel em português salva CSV em Windows-1252 por padrão, e o sistema recusa: *"Arquivo não está em UTF-8. Salve novamente em UTF-8 e tente novamente."* No Excel, use **Salvar como → CSV UTF-8**; ou parta do modelo baixado. Outras recusas do arquivo inteiro: extensão diferente de `.csv`, tamanho acima de **5 MB**, arquivo vazio, e **coluna obrigatória ausente** — *"Colunas obrigatórias ausentes: amount"*. Nesses casos não há preview: o problema é do arquivo, não de uma linha. ## Importar[​](#importar "Link direto para Importar") 1. Envie o arquivo. O sistema lê e mostra o preview. 2. **As linhas válidas já vêm marcadas.** Clique numa linha para desmarcá-la. 3. Clique em **Importar N linhas**. ### Linhas com erro[​](#linhas-com-erro "Link direto para Linhas com erro") Linhas inválidas aparecem no preview com um marcador vermelho, **e não podem ser selecionadas nem editadas ali**. Não há correção dentro do sistema. A própria tela diz o caminho: *"Desmarque as linhas com erro ou corrija-as no arquivo e envie novamente."* O número em **Linha N** é o número da linha **no arquivo**, contando o cabeçalho — a primeira linha de dados é a 2. ### A gravação roda em segundo plano[​](#a-gravação-roda-em-segundo-plano "Link direto para A gravação roda em segundo plano") Ao confirmar, você recebe *"Importação iniciada em segundo plano"* e um diálogo de progresso. **Pode fechar o diálogo** — a importação continua, e o progresso fica visível no canto inferior direito. ### Vínculos[​](#vínculos "Link direto para Vínculos") **Fornecedores, categorias e centros de classificação aparecem na prévia**, cada um com o que vai acontecer na importação: os que já existem são ligados; os que ainda não existem vêm marcados para **criar** (ou para **deixar em branco**, se você não tiver permissão de criar); um nome quase igual a um existente — só muda acento, maiúscula ou espaço — vem marcado para **usar o existente**; e um centro de classificação que só existe do outro lado (ex.: um do tipo Receita numa conta a pagar) vem marcado para deixar em branco. O fornecedor é procurado só pelo nome: uma pessoa já cadastrada como cliente também serve, e passa a ser fornecedor também. Grafias do mesmo nome que só mudam acento, maiúscula ou espaço (ex.: *Água e Luz* e *agua e luz*) contam como um nome só. Dá para trocar qualquer escolha antes de importar. As [regras automáticas](https://docs.finance.kobana.com.br/pt/pt/regras-automaticas/.md) são aplicadas aos registros importados. ## Histórico[​](#histórico "Link direto para Histórico") Abaixo do painel, a seção **Histórico** lista as importações com data, arquivo, status (**Na fila**, **Processando**, **Concluído**, **Falha**, **Cancelado**), quantas linhas entraram do total e quem pediu. ## Aprovação[​](#aprovação "Link direto para Aprovação") Contas a pagar importadas entram sob o **portão de aprovação de pagamentos**: nascem **aguardando aprovação** e **não aparecem na lista oficial** (nem em totais/fluxo de caixa) até serem aprovadas por uma pessoa em [Aprovar pagamentos](https://docs.finance.kobana.com.br/pt/pt/aprovar-pagamentos/.md). Só depois de aprovadas podem ser enviadas ao banco. Isso vale com o portão **ligado** (o padrão); desligado, as linhas importadas já entram oficiais. Ver [Ciclo de vida](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/ciclo-de-vida.md). --- # Operação e pagamento O formulário de conta a pagar separa **duas coisas diferentes**, em dois blocos: | Bloco | Responde | | ---------------------------- | ----------------------------------------------------------------------------- | | **OPERAÇÃO & DOCUMENTO** | O que é esta obrigação e qual documento a representa | | **INFORMAÇÕES DE PAGAMENTO** | As coordenadas para executá-la (código de barras, Pix, dados bancários, guia) | observação **Não existe um campo genérico "Método de pagamento" na conta a pagar.** O segundo campo é **rotulado pela operação** escolhida — e a lista de opções muda junto com ela. ## OPERAÇÃO & DOCUMENTO[​](#operação--documento "Link direto para OPERAÇÃO & DOCUMENTO") ### Tipo de operação[​](#tipo-de-operação "Link direto para Tipo de operação") O eixo primário. Três opções: | Opção | O que significa | | -------------------------- | ------------------------------------------------------------------------------------------------ | | **Pagamento de documento** | Quitar um documento que já existe: boleto, conta de consumo, guia de tributo ou uma cobrança Pix | | **Transferência** | Enviar dinheiro a um favorecido | | **Débito automático** | O banco debita a conta sozinho na data, sem nada a enviar | Enquanto o tipo de operação não for escolhido, **o segundo campo nem aparece**. ### Débito automático[​](#débito-automático "Link direto para Débito automático") Para a conta que o banco debita por conta própria: financiamento, tarifa, conta de consumo em débito em conta. **Não há segundo campo nem painel de pagamento**, e a conta **nunca é enviada ao banco** — não aparece no inbox de envio nem oferece "Enviar para o banco". Quando o débito acontecer, dê baixa: na linha ou em lote, com **"Marcar como pagas"** (ver [Ações em lote](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/.md#a%C3%A7%C3%B5es-em-lote)). ### O segundo campo muda de nome conforme a operação[​](#o-segundo-campo-muda-de-nome-conforme-a-operação "Link direto para O segundo campo muda de nome conforme a operação") | Tipo de operação | Rótulo do campo | Opções | | -------------------------- | ------------------------- | ----------------------------------------- | | **Pagamento de documento** | **Documento** | Boleto · Conta de consumo · Tributo · PIX | | **Transferência** | **Tipo de transferência** | Transferência (TED) · PIX | * Trocar o tipo de operação **reseta** o segundo campo quando a opção escolhida não pertence à nova operação. * **Tributo é um documento, não uma "forma de pagamento"** — por isso aparece sob *Documento*, e nunca numa lista de métodos. * **PIX aparece nos dois eixos**, com sentidos diferentes: em *Pagamento de documento* é o **copia-e-cola** de uma cobrança; em *Transferência* é **chave ou dados bancários** de um favorecido. ### Documento[​](#documento "Link direto para Documento") Ainda neste bloco: **Nº de documento** e **Data do doc.** — a identificação da nota/boleto. ## INFORMAÇÕES DE PAGAMENTO[​](#informações-de-pagamento "Link direto para INFORMAÇÕES DE PAGAMENTO") Este painel só aparece quando a combinação *operação × documento* tem coordenadas a informar. O título é **"INFORMAÇÕES DE PAGAMENTO"** — ou **"DADOS DA GUIA"** quando o documento é um tributo. | Operação → Documento | O que o painel pede | | -------------------------------- | ---------------------------------------------------------------------------------- | | Pagamento → **Boleto** | Código de barras | | Pagamento → **Conta de consumo** | Código de barras | | Pagamento → **Tributo** | **Tipo de tributo** + **Como informar**: **Código de barras** ou **Dados da guia** | | Pagamento → **PIX** | **Código Pix** (copia-e-cola) | | Transferência → **PIX** | Abas **Chave Pix** ou **Dados bancários** — você escolhe um caminho | | Transferência → **TED** | **Dados bancários**: banco, agência + dígito, conta + dígito | ### Favorecido (só em transferência)[​](#favorecido-só-em-transferência "Link direto para Favorecido (só em transferência)") As duas transferências — TED e PIX — levam também **quem recebe**: | Campo | Obrigatório para enviar ao banco | | ------------------------------- | -------------------------------- | | **Nome do favorecido** | Sim | | **CPF/CNPJ do favorecido** | Sim | | **Finalidade da transferência** | Não | aviso **Sem esses dois campos o [envio ao banco](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md) não sai.** A instituição exige nome e documento de quem recebe em qualquer transferência, e o inbox de envio recusa a linha até que estejam preenchidos. **No PIX, o favorecido é sempre o fornecedor.** Por chave ou por dados bancários, os dois campos aparecem **somente leitura**, com o nome e o CPF/CNPJ do cadastro do fornecedor, e a nota *"No Pix, o favorecido é sempre o fornecedor da conta a pagar. Para mudar, troque o fornecedor ou corrija o cadastro dele."* O envio ao banco usa esse cadastro, mesmo que a conta guarde outro favorecido de antes. Um fornecedor sem CPF/CNPJ trava o envio até o cadastro dele ser completado. Pela API, um PIX com o CPF/CNPJ de outra pessoa no favorecido é recusado. **Na TED, escolher um fornecedor preenche o favorecido para você** — nome e CPF/CNPJ vêm da pessoa, junto com os dados bancários da conta principal dela. Isso acontece no momento em que você seleciona a pessoa no campo Fornecedor, e **substitui o que estiver preenchido**. Os campos continuam editáveis: na TED o favorecido pode legitimamente ser outro (um funcionário do fornecedor, um terceiro autorizado). observação **Este painel não paga nada.** Ele apenas guarda as coordenadas no registro. O pagamento acontece de duas formas — por fora (e você dá baixa) ou pelo [envio ao banco](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md). Ver [Ciclo de vida](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/ciclo-de-vida.md). ### PIX — copia-e-cola[​](#pix--copia-e-cola "Link direto para PIX — copia-e-cola") Ao colar o código, o sistema **desenha o QR Code** na hora — dá para escanear no app do banco e pagar por fora. **"Consultar dados do QR"** vai além: busca a cobrança e mostra **Beneficiário**, **Valor no QR**, **Vencimento** e se ela **pode ser paga**. É só leitura — serve para conferir antes de enviar. Com os dados na tela, **"Preencher com estes dados"** os traz para o formulário: | Do QR | Vai para | | ------------ | -------------------------------------------------------------------------- | | Valor | **Valor (R$)** | | Vencimento | **Vencimento** | | Descrição | **Descrição** — só se estiver vazia; o que você escreveu não é sobrescrito | | Beneficiário | **Fornecedor** | **O beneficiário do QR vira o Fornecedor.** Não há campo "Favorecido" aqui — ele só existe em transferência. O sistema procura um fornecedor já cadastrado **pelo documento** do beneficiário (CPF ou CNPJ); achando, seleciona. Não achando, deixa o **nome** preenchido como fornecedor novo, que é cadastrado ao salvar. ### PIX — chave[​](#pix--chave "Link direto para PIX — chave") O **tipo da chave** (CPF, CNPJ, e-mail, telefone, aleatória) é **detectado automaticamente** a partir da chave digitada — é um campo somente leitura; você não seleciona. ### Tributo — código ou dados[​](#tributo--código-ou-dados "Link direto para Tributo — código ou dados") São **nove** tipos: DARF, GRU, GPS, FGTS, DARE, ICMS, ISS, IPTU e ITBI. observação **Só quatro aceitam a guia estruturada.** **DARF, GRU, GPS e FGTS** ganham o campo **"Como informar"**, para escolher entre **Código de barras** (padrão) e **Dados da guia** — e aí os campos variam por tipo. Os outros cinco aceitam **apenas o código de barras**; para eles, o "Como informar" nem aparece. Isso **não** limita o envio ao banco: os nove são enviáveis. Ver [Tributos](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/tributos.md). ### Bloqueio pós-confirmação[​](#bloqueio-pós-confirmação "Link direto para Bloqueio pós-confirmação") Depois que o banco confirma o pagamento, o painel inteiro fica **somente leitura**: as coordenadas passam a descrever uma transação bancária já executada e não podem mais mudar. ## E dinheiro, cartão, cheque?[​](#e-dinheiro-cartão-cheque "Link direto para E dinheiro, cartão, cheque?") Dinheiro, cartão de crédito, cartão de débito, cheque e "outro" existem no sistema e podem chegar por **importação de CSV** ou pela **API** — mas **nenhum formulário os oferece**. Não há esse campo em contas a pagar, nem em contas a receber, nem em lançamentos. O **débito automático** é a exceção: tem opção própria no **Tipo de operação** (ver acima). Onde eles aparecem é **na leitura**: a listagem de contas a pagar tem a coluna **Liquidação** e a de lançamentos tem **Forma de pag.**, ambas ocultas por padrão e ativáveis pelo seletor de colunas. Um título importado com "dinheiro" mostra "dinheiro" ali — você só não consegue digitá-lo. Se a obrigação não é um documento nem uma transferência, **deixe o tipo de operação sem preencher**: como o dinheiro efetivamente saiu é registrado na baixa (conta financeira + data), não aqui. O select abre vazio num título novo — mas ele só tem as três opções, sem um "Nenhum": escolhida uma operação, não dá para voltar ao vazio pela tela. --- # Parcelas e recorrência Contas a pagar suportam dois modos além do pagamento simples: parcelamento e recorrência. ## Os três tipos[​](#os-três-tipos "Link direto para Os três tipos") O campo **Tipo**, obrigatório, oferece: | Tipo | O que é | | -------------- | -------------------------------------------------- | | **À vista** | Conta única, sem repetição | | **Parcelado** | Dividida em N parcelas com vencimentos sequenciais | | **Recorrente** | Repete sozinha num intervalo fixo | ## Parcelado[​](#parcelado "Link direto para Parcelado") Escolhido o tipo, aparece o campo **Nº de parcelas**: de **2** a **120**. aviso **O valor é por parcela, não o total.** Em **Valor (R$)** você informa quanto vale **cada** parcela — 12 × R$ 100 se cadastra como valor 100 e 12 parcelas, não como 1.200. O resumo ao lado do formulário mostra os dois: **Valor de cada parcela** e **Total em 12 parcelas**. Salvando, o sistema cria as N contas de uma vez, com **vencimentos mensais a partir do primeiro vencimento** (um mês a cada parcela) e numeração sequencial — **Parcela 1/12**, **Parcela 2/12**… Quando o dia não existe no mês (31 em fevereiro), a parcela cai no último dia daquele mês. Cada parcela é uma conta independente: pode ser paga sozinha e ter vencimento ou valor ajustado depois, uma a uma. informação **O parcelamento se escolhe ao criar.** Numa conta que já faz parte de uma série, **Tipo** e **Nº de parcelas** ficam travados — *"Faz parte de uma série: o tipo e o número de parcelas não mudam."* Uma conta **À vista** já salva pode virar **Recorrente**, mas não **Parcelado**. ### Navegar entre parcelas[​](#navegar-entre-parcelas "Link direto para Navegar entre parcelas") No detalhe de uma parcela, as setas levam à anterior e à próxima da mesma série. A ação **Parcelas**, no menu da linha, lista a série inteira. ## Recorrente[​](#recorrente "Link direto para Recorrente") Escolhido o tipo, aparece o campo **Recorrência**, obrigatório, com cinco períodos: | Opção | Intervalo | | ------------------ | --------- | | **Toda semana** | 7 dias | | **Toda quinzena** | 14 dias | | **Todo mês** | 1 mês | | **A cada 3 meses** | 3 meses | | **Todo ano** | 12 meses | **Nas listagens o rótulo encurta** — a mesma recorrência aparece como **Semanal**, **Quinzenal**, **Mensal**, **Trimestral** ou **Anual**. É a mesma coisa, escrita curta para caber na linha. ### As próximas ficam lançadas com antecedência[​](#as-próximas-ficam-lançadas-com-antecedência "Link direto para As próximas ficam lançadas com antecedência") observação **Uma recorrência já nasce com os próximos meses lançados.** Ao criar, o sistema grava as ocorrências até **12 meses à frente** (o padrão), e a janela anda sozinha: todo dia as séries são completadas até o novo limite. Cada ocorrência é uma conta de verdade — entra no fluxo de caixa, pode ter o valor alterado e pode ser baixada **antes** da anterior. O prazo fica em **Configurações de recorrência**, na engrenagem da listagem de contas a pagar ou a receber: **Meses para provisionamento**, de 0 a 36. Aumentar completa as séries na hora; diminuir não apaga o que já foi lançado, só para de lançar além do novo prazo. Com **0**, cada série mantém só a próxima conta em aberto, e a seguinte nasce quando ela é baixada. Com a [aprovação de pagamento](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/ciclo-de-vida.md) ligada, as ocorrências de uma série nova entram todas na fila de aprovação. **As ocorrências contam a partir da primeira.** Uma série mensal que começa num dia 31 cai no último dia dos meses mais curtos e volta ao 31 quando o mês tem 31 dias. Mudar o vencimento de uma ocorrência mexe só nela: as seguintes continuam no dia original da série. **Cada ocorrência lançada copia a última da série** — valor, categoria, centro de classificação, forma de pagamento, impostos e retenções, documento e observações. Uma conta **À vista** já salva pode virar **Recorrente**: editando o tipo e escolhendo a recorrência, o sistema começa a série a partir dela. **Repetir até** (opcional, ao lado da recorrência) é o último vencimento da série; vazio, a série não tem fim. A data vale para a série inteira: encurtar remove as contas em aberto depois do novo fim, e estender volta a lançar. Não pode ficar antes do vencimento da conta que você está editando. Numa série importada (Fintera, Nibo), o fim é o da origem e o campo não aparece. Para mudar o valor dos próximos meses, edite uma ocorrência: o diálogo de propagação deixa escolher quais outras da série herdam a mudança — ou nenhuma, em **"Apenas esta ocorrência"**. As ocorrências lançadas a partir daí seguem o valor da última. Além do prazo, a projeção do fluxo de caixa continua a série na hora de exibir, sem gravar. Ver [Dashboard](https://docs.finance.kobana.com.br/pt/pt/dashboard/.md). A ação **Recorrências**, no menu da linha, lista as ocorrências lançadas da série. No detalhe da conta, **Vencimento anterior** e **Próximo vencimento** navegam por elas. ### Excluir[​](#excluir "Link direto para Excluir") Ao excluir uma conta que pertence a um grupo, o sistema oferece: * **Excluir apenas esta** — remove só a ocorrência atual. Numa recorrência, ela não volta a ser lançada: a série segue a partir da seguinte. * **Excluir esta e as futuras** — remove a atual e todas as seguintes do grupo. Numa recorrência, também encerra a série ali: as contas removidas não voltam a ser lançadas. observação **O que já foi pago fica.** *"Ocorrências já pagas ou conciliadas são mantidas."* Se alguma das seguintes não puder ser excluída, o aviso diz quantas ficaram. **Série importada não se exclui daqui.** Numa série que veio de uma integração (Fintera, Nibo), **Excluir esta e as futuras** é recusado — *"Esta série vem de uma integração; exclua-a na origem"*. O fim dela também é o da origem. **O alcance não é exclusivo de recorrências.** O seletor olha o **grupo**, então **parceladas e recorrentes** se comportam igual. Em conta avulsa ele não aparece. O seletor está **na listagem**. Excluindo pelo detalhe, apaga-se sempre só aquela conta. --- # Tributos Uma conta a pagar cujo **documento é um Tributo** representa uma guia de tributo federal, estadual ou municipal. No formulário: **Tipo de operação = Pagamento de documento** → **Documento = Tributo** (tributo é um documento, não uma "forma de pagamento" — ver [Operação e pagamento](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/operacao-e-pagamento.md)). O campo **Tipo de tributo** determina os campos específicos da guia. ## Tipos de tributo[​](#tipos-de-tributo "Link direto para Tipos de tributo") Nove, como aparecem no seletor **"Tipo de tributo"**: | Tributo | Guia estruturada? | | ------------------------------------------------------------- | ----------------- | | **ITBI** — Imposto sobre Transmissão de Bens Imóveis | Não | | **ICMS** — Imposto sobre Circulação de Mercadorias e Serviços | Não | | **ISS** — Imposto Sobre Serviços | Não | | **IPTU** — Imposto Predial e Territorial Urbano | Não | | **FGTS** — Fundo de Garantia do Tempo de Serviço | **Sim** | | **DARE** — Documento de Arrecadação de Receitas Estaduais | Não | | **DARF** — Documento de Arrecadação de Receitas Federais | **Sim** | | **GRU** — Guia de Recolhimento da União | **Sim** | | **GPS** — Guia da Previdência Social | **Sim** | ## Como informar a guia[​](#como-informar-a-guia "Link direto para Como informar a guia") Escolhido o tipo, **DARF, GRU, GPS e FGTS** ganham um segundo campo — **"Como informar"** — com duas opções: * **Código de barras** (padrão) — um campo só: **"Código de barras / linha digitável"**. * **Dados da guia** — abre as seções estruturadas do documento, descritas abaixo. observação **Os outros cinco tipos não têm essa escolha.** ICMS, ISS, IPTU, ITBI e DARE aceitam **apenas o código de barras** — o campo "Como informar" nem aparece para eles. ## Campos da guia[​](#campos-da-guia "Link direto para Campos da guia") Só no modo **Dados da guia**, e só nos quatro tipos acima. Cada guia se organiza em seções que espelham o documento oficial. ### DARF[​](#darf "Link direto para DARF") | Seção | Campos | | --------------------------------- | ------------------------------------------------------------------------------- | | **Identificação do contribuinte** | Tipo de contribuinte · CPF/CNPJ do contribuinte · Nome do contribuinte | | **Dados da guia** | Código da receita / pgto. · Número de referência · Data do cálculo · Vencimento | | **Encargos e rendimento** | Multa · Juros · Rendimento bruto | O **Tipo de contribuinte** do DARF é o mais amplo: CNPJ, CPF, NIT, PIS, PASEP, CEI, NB, Nº do título, DEBCAD e Referência. ### GRU[​](#gru "Link direto para GRU") | Seção | Campos | | ------------------------------- | ------------------------------------------------------------------- | | **Vencimento e referência** | Vencimento · Número de referência · Valor total | | **Ajustes de valor (opcional)** | Desconto · Outras deduções · Outras adições · **Multa** · **Juros** | ### GPS[​](#gps "Link direto para GPS") | Seção | Campos | | --------------------------------- | ----------------------------------------------------------------------- | | **Identificação do contribuinte** | Tipo de contribuinte · CPF/CNPJ do contribuinte · Nome do contribuinte | | **Dados da guia** | Código da receita / pgto. · Competência · Vencimento · Outras entidades | | **Encargos (opcional)** | Atualização monetária · Multa · Juros | O **Tipo de contribuinte** da GPS é mais curto que o do DARF: CNPJ, CPF, NIT, PIS, PASEP e CEI. ### FGTS[​](#fgts "Link direto para FGTS") | Seção | Campos | | ----------------- | ------------------------------------------------------------------ | | **Identificação** | Código do contribuinte · Número PIS/PASEP · Código de recolhimento | | **Dados do FGTS** | Código FGTS · Percentual JAM (%) · Selo conectividade | O FGTS não tem seção de contribuinte nem de encargos — a identificação é feita pelos códigos. ## Envio pelo Gateway Bancário[​](#envio-pelo-gateway-bancário "Link direto para Envio pelo Gateway Bancário") observação **Os nove tipos podem ser enviados ao banco.** O roteamento olha a combinação **operação × documento** — "Pagamento de documento" + "Tributo" resolve para o recurso de tributo do gateway, **qualquer que seja o tipo de tributo**. Um IPTU informado por código de barras sai tão bem quanto um DARF. O que é exclusivo de DARF, GRU, GPS e FGTS **não é o envio, é o modo de informar**: só eles aceitam a guia estruturada. Os demais viajam pelo código de barras. **O envio não é automático.** Nada sai sozinho: é você quem clica — **"Enviar para o banco"**, na tela de detalhe, ou **"Enviar pagamentos"**, para despachar em lote a partir da listagem. Ver [Envio ao banco](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md) e [Ciclo de vida](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/ciclo-de-vida.md). --- # Contas a receber Contas a receber (`/receivables`) registram os compromissos de entrada da organização: mensalidades de clientes, vendas, serviços prestados e qualquer valor a ser recebido. ![Listagem de contas a receber](/pt/assets/images/03-receivables-5cae52f06f1b9b1c71169ef0a71fe75b.png) ![Detalhe de conta a receber](/pt/assets/images/04-receivable-detail-a2cf7a48bc6fe16ea51408c26e046e00.png) ## Nesta seção[​](#nesta-seção "Link direto para Nesta seção") ## [📄️Ciclo de vida](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/ciclo-de-vida.md) [Estados, transições e recebimento — Rascunho → Pendente → Recebido.](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/ciclo-de-vida.md) ## [📄️Parcelas e recorrência](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/parcelas-e-recorrencia.md) [Dividir em parcelas ou repetir periodicamente — mesmo comportamento das contas a pagar.](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/parcelas-e-recorrencia.md) ## [📄️Cobrança por boleto e Pix](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/cobranca-kobana.md) [Gerar boleto ou Pix de uma conta a receber pelo Gateway Bancário — pré-requisitos, estados e cancelamento.](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/cobranca-kobana.md) ## [📄️Importação CSV](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/importacao-csv.md) [Importar lotes de contas a receber via planilha — colunas aceitas e formato tolerante.](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/importacao-csv.md) ## A listagem[​](#a-listagem "Link direto para A listagem") O cabeçalho abre com três totais do período — **A receber** (o que ainda está pendente), **Recebido** e **Total** — e um subtítulo que resume a situação. Ele é **acionável**: quando há atraso, a frase *"Você tem 3 contas atrasadas"* traz o trecho em vermelho como botão, e clicar nele aplica o filtro de atrasadas. Sem atraso, vira *"Você está em dia com os recebimentos."* O botão de **período** fica no cabeçalho, ao lado de **"Nova conta a receber"**. À direita dos totais ficam duas pílulas de ação: **"Importar"** (abre o painel de importação abaixo, e limpa busca e filtros para deixar a lista num estado limpo) e **"Relatório"** (abre em diálogo, sem mexer na listagem). Importar exige uma **empresa específica** selecionada — na visão consolidada a pílula avisa em vez de abrir. ### Filtros[​](#filtros "Link direto para Filtros") * **Busca** — por descrição ou número de documento. * **Filtros rápidos** — **Todas**, **Com anexos**, **Recebidas**, **Conciliadas**, **Rascunhos**. * **Filtros avançados** — painel com os critérios combinados; um contador mostra quantos estão ativos, e um resumo permite limpar ou editar sem reabrir o painel. ### Colunas[​](#colunas "Link direto para Colunas") Descrição, Vencimento, Categoria, Status, Valor — mais **Empresa**, que só aparece na visão consolidada (com uma empresa selecionada, toda linha teria o mesmo valor). **IR** e **Observações** existem mas vêm **ocultas**; ative-as pelo menu de colunas. **"Status no banco"** mostra o estado da [cobrança](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/cobranca-kobana.md) — Registrando, Registrada, Vencida, Paga, Cancelada — e traz **"-"** para o título que nunca foi cobrado. observação **"Liquidação" é exclusiva de contas a pagar** — aqui a forma de recebimento se materializa no lançamento, na hora da baixa. E a coluna de status geral se chama só **"Status"**, não "Status geral": contas a receber não passam por aprovação. ### Ações de linha[​](#ações-de-linha "Link direto para Ações de linha") Nove ações, várias condicionais ao estado da linha: | Ação | Quando aparece | | ------------------------ | ------------------------------------ | | **Marcar como recebido** | Enquanto a baixa manual for possível | | **Conciliar** | Já recebida e ainda não conciliada | | **Parcelas** | Tipo Parcelado | | **Recorrências** | Tipo Recorrente, dentro de uma série | | **Classificar** | Sempre | | **Editar** | Sempre | | **Desfazer** | Já recebida | | **Cancelar** | Só pendente | | **Excluir** | Sempre | **Editar** e **Excluir** aparecem sempre, mas com uma cobrança de pé a operação é limitada: os campos que descrevem o que foi cobrado ficam travados e a exclusão é bloqueada — ver [Cobrança](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/cobranca-kobana.md). ### Ações em lote[​](#ações-em-lote "Link direto para Ações em lote") Selecionando linhas, a barra oferece **"Classificar selecionados"**, **"Marcar como recebidas"** e **"Excluir"**, e mostra ao vivo os totais **A receber**, **Recebido** e **Total** **da seleção**. "Classificar selecionados" só existe com uma **empresa específica** selecionada: criar um cliente ou categoria novo pelo nome precisa de uma empresa sem ambiguidade. **"Marcar como recebidas"** abre um diálogo com a **Data de recebimento** (hoje, por padrão). Cada conta é recebida pelo próprio valor, na **conta de destino** prevista nela; se alguma selecionada não tiver uma, o diálogo pede a conta para essas. Juros e descontos ficam de fora — para eles, dê baixa em uma de cada vez. O que a linha não deixaria marcar como recebido (já recebida, cancelada) fica de fora, e o diálogo diz quantas. ## O formulário[​](#o-formulário "Link direto para O formulário") Os campos são agrupados em seções. **A empresa não é um campo** — vem do seletor do cabeçalho, e a tela devolve você para lá se nenhuma estiver escolhida. ### ESSENCIAL[​](#essencial "Link direto para ESSENCIAL") | Campo | Observações | | ---------------------- | ------------------------------------------------------------------------------------------------------ | | **Valor (R$)** | Obrigatório. Campo de moeda, com máscara — você digita o valor, não uma string decimal | | **Vencimento** | Obrigatório. Ao criar, há atalhos de data relativa | | **Receber em** | Conta financeira esperada para a entrada | | **Descrição** | Obrigatório | | **Cliente** | Obrigatório. Busca entre as pessoas marcadas como cliente, e permite **cadastrar pelo nome** ao salvar | | **Mês de competência** | Obrigatório. Seletor de mês, não de dia | ### CLASSIFICAÇÃO[​](#classificação "Link direto para CLASSIFICAÇÃO") * **Tipo** (obrigatório) — **À vista**, **Recorrente** ou **Parcelado**. A escolha revela o campo seguinte: **Recorrência** (o período) para recorrente, **Nº de parcelas** para parcelado. * **Categoria** — categoria de receita; também aceita cadastrar pelo nome. Tem o atalho **Rateio** ao lado, para dividir o título entre categorias. Ver [Categorias](https://docs.finance.kobana.com.br/pt/pt/categorias/.md#rateio). * **Centro de classificação** — com o atalho **Rateio** ao lado. Marcado, abre o diálogo de rateio e o campo único dá lugar ao resumo da divisão. Ver [Centros de classificação](https://docs.finance.kobana.com.br/pt/pt/centros-de-classificacao/.md). ### DOCUMENTO & PAGAMENTO[​](#documento--pagamento "Link direto para DOCUMENTO & PAGAMENTO") **Nº de documento** (NF, boleto…) e **Data do doc.** Só isso — apesar do nome, a seção não tem campos de pagamento no lado de receber. ### Impostos retidos · Observação e IR[​](#impostos-retidos--observação-e-ir "Link direto para Impostos retidos · Observação e IR") Duas seções lado a lado. **Impostos retidos** é o editor de tributos retidos na fonte, em pílulas. Ao lado, a pílula **"Relevante para IR"** (liga/desliga) e **"Adicionar observação"**, que abre o campo de texto livre. ### Anexos[​](#anexos "Link direto para Anexos") Ao **criar**, é possível anexar arquivos antes de salvar — eles são vinculados junto no momento do salvamento. ## Confirmar recebimento[​](#confirmar-recebimento "Link direto para Confirmar recebimento") O diálogo **"Confirmar recebimento"** tem duas abas: * **Receber** — informe **Data de recebimento** e **Conta de destino**. O sistema marca a conta como recebida e cria o lançamento de **entrada**. * **Receber e conciliar** — *"Receba esta conta vinculando-a a um lançamento que já existe no extrato — sem gerar um duplicado."* Escolha o lançamento; os candidatos trazem a dica **"mesmo valor"** / **"valor próximo"**. Nas duas abas, a seção **"Ajustes do recebimento"** (opcional) aceita **Juros** e **Desconto**. Abaixo dela, o **Valor recebido** mostra quanto entra na conta. Em **Receber**, é esse valor, e não o do título, que vira o lançamento de entrada; em **Receber e conciliar**, é com ele que o lançamento escolhido é comparado, e os juros e o desconto ficam registrados na conta. ## Diferenças em relação a contas a pagar[​](#diferenças-em-relação-a-contas-a-pagar "Link direto para Diferenças em relação a contas a pagar") | | Contas a receber | Contas a pagar | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | **Estado final** | **Recebido** | **Pago** | | **Portão de aprovação** | Não passa — não existe aprovação do lado de receber | Todo título novo aguarda [aprovação](https://docs.finance.kobana.com.br/pt/pt/aprovar-pagamentos/.md) quando o portão está ligado (o padrão) | | **Tipo de operação e documento** | Não há — o modo de recebimento se materializa no lançamento, quando a baixa acontece | Definem como o título será pago e destravam as coordenadas | | **Coordenadas de pagamento e dados de guia** | Não há. **"Impostos retidos"** existe, mas é outra coisa: o que a fonte retém do que você tem a receber, não uma guia a pagar | Código de barras, Pix, dados bancários, dados da guia | | **Gateway bancário** | [Gerar cobrança](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/cobranca-kobana.md) — boleto ou Pix para o cliente pagar | [Envio ao banco](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md) — o pagamento sai da sua conta | | **Comprovante** | Não há: o comprovante é do dinheiro que sai | Capturado sozinho na confirmação — ver [Comprovantes](https://docs.finance.kobana.com.br/pt/pt/comprovantes/.md) | --- # Ciclo de vida das contas a receber ## Estados[​](#estados "Link direto para Estados") | Estado | Descrição | | ------------- | ------------------------------------------------------- | | **Rascunho** | Criado mas ainda não publicado. Não aparece nos totais. | | **Pendente** | Aguardando recebimento. | | **Recebido** | Vinculado a um lançamento de entrada. | | **Cancelado** | Anulado, sem movimentação financeira. | Além desses quatro, a listagem mostra dois selos que **não são estados**, e sim derivados: * **Atrasado** — uma conta **Pendente** cujo vencimento já passou. * **Conciliada** — o recebimento está ligado a um lançamento do extrato. Quando aparece, substitui o selo "Recebido": é a informação mais forte. ## Transições[​](#transições "Link direto para Transições") * **Publicar** (Rascunho → Pendente) — passa a contar nos totais. * **Marcar como recebido** (Pendente → Recebido) — registra o recebimento e gera o lançamento de entrada. * **Cancelar** (Pendente → Cancelado) — anula a conta. ## Criar[​](#criar "Link direto para Criar") 1. Acesse `/receivables/new`. 2. Preencha os campos obrigatórios: **Valor (R$)**, **Vencimento**, **Descrição**, **Cliente**, **Mês de competência** e **Tipo**. 3. Conclua com **Adicionar conta**, **Adicionar e criar outra** ou **Salvar rascunho**. **O cliente não é opcional.** Sem ele o formulário não envia: *"Selecione ou crie um cliente"*. Você pode escolher um cliente que já existe **ou digitar um nome novo** — nesse caso ele é cadastrado junto. A **Empresa** também é obrigatória, mas não é um campo do formulário: vem do seletor no cabeçalho. observação **"Publicar" não existe na tela de criação.** Os botões ali são os três acima. **Publicar** aparece só no **detalhe**, e só enquanto a conta é um rascunho. O caminho é: salvar rascunho → abrir a conta → Publicar. ## Marcar como recebido[​](#marcar-como-recebido "Link direto para Marcar como recebido") Na listagem ou no detalhe, use **Marcar como recebido**. O diálogo **Confirmar recebimento** tem duas abas: * **Receber** — informe a data e a **Conta de destino**. O sistema cria o lançamento de entrada. * **Receber e conciliar** — liga a conta a um lançamento que **já existe** no extrato, sem gerar um duplicado. As duas abas também trazem **Ajustes do recebimento**, opcionais: **Juros** e **Desconto**. Abaixo deles, o **Valor recebido** mostra quanto entra na conta, com a conta feita. ## Desfazer e conciliar[​](#desfazer-e-conciliar "Link direto para Desfazer e conciliar") * **Desfazer** — disponível em conta recebida. Ela volta para pendente; se o lançamento tiver sido gerado pelo recebimento, é excluído junto. * **Conciliar** — disponível em conta recebida que ainda não foi conciliada. ## Cancelar[​](#cancelar "Link direto para Cancelar") **Cancelar só aparece em contas pendentes** — não é uma saída disponível a partir de qualquer estado. E **não é irreversível**: o próprio diálogo diz *"Você pode reabri-la depois editando o status."* A conta deixa de aparecer entre as pendentes; lançamentos automáticos vinculados são removidos, e lançamentos importados do extrato permanecem — apenas o vínculo é desfeito. observação A ação existe **na listagem**. Abrindo o detalhe direto, esse caminho não está lá. ## Editar[​](#editar "Link direto para Editar") **Conta recebida não é somente leitura.** Não existe trava por estado: o formulário abre normalmente e é editável em qualquer status, inclusive **Recebido** e **Cancelado**. A única trava vem de uma [cobrança de pé](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/cobranca-kobana.md), que congela o que descreve o que foi cobrado. Essa é uma **diferença em relação a contas a pagar**: lá existe uma trava — parcial — quando o banco confirma o pagamento. Contas a receber não passam pelo envio ao banco, então não têm o que travar. Editando uma conta que faz parte de um grupo, o sistema oferece **"Aplicar às demais parcelas"**, mostrando antes o que exatamente vai mudar. São **todas** as parcelas do grupo — inclusive as **anteriores** à que você está editando, não só as seguintes. Ficam de fora apenas as já liquidadas e a própria parcela editada. A seleção vem marcada por inteiro; desmarque o que não deve herdar — ou salve só na parcela aberta, em **"Apenas esta parcela"** (numa recorrência, **"Apenas esta ocorrência"**). ## Excluir[​](#excluir "Link direto para Excluir") Em uma conta que faz parte de um grupo — **parcelada ou recorrente** —, a exclusão pergunta o alcance: * **Excluir apenas esta** * **Excluir esta e as futuras** O mesmo seletor cobre os dois casos: o que ele olha é o grupo, não o tipo. Em conta avulsa, ele não aparece. observação O seletor aparece **na listagem e no detalhe** da conta. --- # Cobrança por boleto e Pix De uma conta a receber, o Financeiro Inteligente gera uma **cobrança** pelo [Gateway Bancário](https://docs.finance.kobana.com.br/pt/pt/integracoes/kobana.md) — um **boleto** ou um **Pix** — para o cliente pagar. É o espelho do [envio de pagamentos](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md), na direção do dinheiro que entra. A ação é **"Gerar cobrança"**, na tela de detalhe do título. ## Pré-requisitos[​](#pré-requisitos "Link direto para Pré-requisitos") | Exigência | Boleto | Pix | | -------------------------------------------------------------------- | ------ | --- | | Gateway Bancário conectado | ✅ | ✅ | | Cliente vinculado ao título | ✅ | ✅ | | CPF/CNPJ do cliente | ✅ | ✅ | | Data de vencimento no título | ✅ | ✅ | | **Endereço completo do cliente** (CEP, rua, bairro, cidade e estado) | ✅ | — | | **Convênio de boleto** cadastrado na conta do gateway | ✅ | — | | **Conta Pix de cobrança** cadastrada na conta do gateway | — | ✅ | observação **Os dois trilhos não são a mesma cobrança com um botão diferente.** Mudam o que o cliente recebe e o que precisa estar cadastrado antes — por isso a escolha é feita em **dois cartões**, cada um dizendo o seu pré-requisito. Se algo faltar, o sistema **diz exatamente o quê** em vez de dar um erro genérico: *"O cliente precisa de CPF ou CNPJ"*, *"O boleto exige o endereço completo do cliente"*, *"Nenhuma conta Pix de cobrança está cadastrada"*, e assim por diante. ## Fluxo[​](#fluxo "Link direto para Fluxo") aviso **Cobrança recém-gerada ainda não pode ser entregue ao cliente.** O registro na instituição financeira é assíncrono: enquanto o estado for **Registrando**, o boleto ainda não existe no banco e o Pix ainda não tem QR code. Espere chegar a **Registrada**. ## Estados da cobrança[​](#estados-da-cobrança "Link direto para Estados da cobrança") Aparecem no cartão da cobrança e na coluna **Status no banco** da listagem de contas a receber. | Estado | O que significa | | ------------------------------------------------------------------ | ---------------------------------------------------- | | **Registrando** | criada; a instituição ainda não confirmou o registro | | **Registrada** | registrada — pode ser entregue ao cliente | | **Vencida** | passou do vencimento sem pagamento | | **Paga** | o cliente pagou | | **Registro recusado** · **Falha no registro** · **Falha ao gerar** | a instituição não aceitou; a cobrança não vale | | **Cancelada** | desfeita | O botão **"Atualizar"** busca o estado atual sob demanda, sem esperar o acompanhamento automático. ## Baixa automática[​](#baixa-automática "Link direto para Baixa automática") Quando a cobrança chega a **Paga**, o título é baixado sozinho: vira **Recebido**, com a data de hoje, e o lançamento de entrada é criado. aviso **Sem "Receber em" definida, não há baixa automática.** É ela que diz em qual conta o dinheiro entrou — sem essa informação o sistema não adivinha, e a baixa fica para você fazer na mão. A cobrança continua marcada como Paga. ## Enquanto a cobrança está de pé, o título não muda[​](#enquanto-a-cobrança-está-de-pé-o-título-não-muda "Link direto para Enquanto a cobrança está de pé, o título não muda") Com uma cobrança **Registrando**, **Registrada**, **Vencida** ou **Paga**, alguém lá fora pode pagá-la — ou já pagou. Por isso o título fica travado no que descreve a cobrança: **valor, vencimento, cliente e afins não podem ser alterados**, e o título **não pode ser excluído**. informação **Editar aqui não reemitiria nada.** O boleto que o cliente tem em mãos continuaria o mesmo — o sistema é que passaria a mentir sobre o que foi cobrado. Para corrigir, **cancele a cobrança primeiro**. Cobranças **recusadas** ou **canceladas** não travam nada: elas não existem para ninguém. ## Cancelar a cobrança[​](#cancelar-a-cobrança "Link direto para Cancelar a cobrança") **"Cancelar cobrança"** desfaz a cobrança no gateway. Os dois trilhos se comportam de forma diferente, e a diferença importa para o seu cliente: * **Boleto** — deixa de valer assim que o gateway confirmar, e o cliente não consegue mais pagá-lo. * **Pix** — o cancelamento é confirmado pela **instituição financeira**. **Até a confirmação chegar, o cliente ainda consegue pagar.** Por isso a resposta distingue **"Cobrança cancelada"** de **"Cancelamento solicitado — aguardando a confirmação da instituição"**. No segundo caso, acompanhe até o estado virar **Cancelada**. Uma cobrança **paga**, **já cancelada** ou **que falhou** não tem o que cancelar. ## Relacionado[​](#relacionado "Link direto para Relacionado") * [Contas a receber — ciclo de vida](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/ciclo-de-vida.md) — os estados do título em si * [Integração Gateway Bancário](https://docs.finance.kobana.com.br/pt/pt/integracoes/kobana.md) — conectar, sincronizar e acompanhar * [Pessoas](https://docs.finance.kobana.com.br/pt/pt/pessoas/.md) — onde ficam o documento e o endereço que a cobrança exige --- # Importação CSV — Contas a receber Importe lotes de contas a receber via arquivo CSV. ## Onde fica[​](#onde-fica "Link direto para Onde fica") **Não existe "Importação" no menu**, nem uma tela de importação. O caminho é: **Contas a receber** → pílula **Importar**, na própria listagem. Sem nenhuma conta cadastrada ainda, a listagem mostra o quadro vazio com o botão **Importar** ao lado de **Nova conta a receber**, que abre o mesmo painel. É preciso ter uma **empresa específica** selecionada no cabeçalho. Em "todas as empresas", o painel só avisa: *"Selecione uma empresa específica para importar contas a receber."* O botão **Baixar modelo** entrega um CSV de exemplo com o cabeçalho correto — é o ponto de partida mais seguro, porque já vem no encoding certo. ## Colunas do CSV[​](#colunas-do-csv "Link direto para Colunas do CSV") | Coluna | Obrigatório | Descrição | | ------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `description` | ✅ | Descrição da conta a receber | | `amount` | ✅ | Valor em reais (ex.: `299,00`) | | `due_date` | ✅ | Data de vencimento (`dd/MM/yyyy`) | | `competence_date` | — | Data de competência (`dd/MM/yyyy`) | | `document` | — | Identificador do documento (o campo **Documento** do formulário) | | `document_date` | — | Data de emissão (`dd/MM/yyyy`) | | `document_number` | — | Número da nota fiscal (o campo **Nº de documento**) | | `person_name` | — | Nome do cliente (se ainda não existir, a prévia pergunta se cria) | | `category_name` | — | Nome da categoria (se ainda não existir, a prévia pergunta se cria) | | `cost_center_name` | — | Nome do centro de classificação (se ainda não existir, a prévia pergunta se cria) | | `payment_method` | — | Método: `pix`, `boleto`, `ted`, `cartao_credito`, `cartao_debito`, `dinheiro`, `cheque`, `debito_automatico`, `outro` ou `nenhum` — aceito e gravado no título, embora o formulário de contas a receber não exponha o campo | | `notes` | — | Observações | | `ir_relevant` | — | `true` ou `false` | Os nomes acima são os canônicos, mas **todo cabeçalho aceita o equivalente em português** — `descricao`, `valor`, `vencimento`, `cliente`, `categoria`, `observacao` e assim por diante. Planilhas de outros sistemas também funcionam para cliente, centro de classificação e categoria: `contraparte` vale como `person_name`; `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` valem como `cost_center_name`, e `plano_de_contas`, `categoria_financeira`, `category` como `category_name`. Se o espaço tiver um classificador com o mesmo nome de uma dessas colunas (ex.: *Centro de Resultado*), a coluna vai para o classificador. Se a planilha tiver mais de uma coluna para o mesmo campo (ex.: `Centro de Custo` e `Centro de Receita`), cada linha usa a primeira que estiver preenchida. Além desses nomes, um cabeçalho com a palavra **centro** é lido como centro de classificação; um com **categoria** ou **plano de contas**, como categoria (por exemplo, `Centro de Lucro`, `Categoria DRE`); e um com **pessoa**, **cliente** ou **fornecedor** acompanhada só de palavras de nome, como pessoa (por exemplo, `Nome do Fornecedor`, `Cliente / Fornecedor` — mas não `CNPJ do Fornecedor`). Colunas que o sistema não conhece são **ignoradas em silêncio**. O arquivo de contas a receber aceita as mesmas colunas de pagar, exceto as de pagamento (código de barras, Pix, dados bancários, tributo, agendamento) — elas existem só no lado de pagar, que é quem envia dinheiro ao banco. ## Formato[​](#formato "Link direto para Formato") O parser é mais tolerante do que parece. Você não precisa normalizar o arquivo antes: * **Cabeçalho** — maiúsculas, acentos e espaços não importam: `Descrição`, `DESCRICAO` e `descricao` são a mesma coluna. * **Separador** — `,` ou `;`, detectado **pela linha de cabeçalho**. Em caso de empate, `;`. * **Datas** — `31/12/2026`, `31-12-2026` ou `2026-12-31`. * **Valores** — `1234.56`, `1.234,56`, `1234,56`, com ou sem `R$`. O valor precisa ser **maior que zero**. * **`ir_relevant`** — `true`/`false`, `sim`/`nao`, `yes`/`no`, `1`/`0`, `s`/`y`/`n`. Sem acento, maiúscula ou minúscula. Vazio deixa o campo em branco. aviso **A codificação precisa ser UTF-8, e é aqui que a maioria dos arquivos tropeça.** O Excel em português salva CSV em Windows-1252 por padrão, e o sistema recusa: *"Arquivo não está em UTF-8. Salve novamente em UTF-8 e tente novamente."* No Excel, use **Salvar como → CSV UTF-8**; ou parta do modelo baixado. Outras recusas do arquivo inteiro: extensão diferente de `.csv`, tamanho acima de **5 MB**, arquivo vazio, e **coluna obrigatória ausente** — *"Colunas obrigatórias ausentes: amount"*. Nesses casos não há preview: o problema é do arquivo, não de uma linha. ## Importar[​](#importar "Link direto para Importar") 1. Envie o arquivo. O sistema lê e mostra o preview. 2. **As linhas válidas já vêm marcadas.** Clique numa linha para desmarcá-la. 3. Clique em **Importar N linhas**. ### Linhas com erro[​](#linhas-com-erro "Link direto para Linhas com erro") Linhas inválidas aparecem no preview com um marcador vermelho, **e não podem ser selecionadas nem editadas ali**. Não há correção dentro do sistema. A própria tela diz o caminho: *"Desmarque as linhas com erro ou corrija-as no arquivo e envie novamente."* O número em **Linha N** é o número da linha **no arquivo**, contando o cabeçalho — a primeira linha de dados é a 2. ### A gravação roda em segundo plano[​](#a-gravação-roda-em-segundo-plano "Link direto para A gravação roda em segundo plano") Ao confirmar, você recebe *"Importação iniciada em segundo plano"* e um diálogo de progresso. **Pode fechar o diálogo** — a importação continua, e o progresso fica visível no canto inferior direito. ### Vínculos[​](#vínculos "Link direto para Vínculos") **Clientes, categorias e centros de classificação aparecem na prévia**, cada um com o que vai acontecer na importação: os que já existem são ligados; os que ainda não existem vêm marcados para **criar** (ou para **deixar em branco**, se você não tiver permissão de criar); um nome quase igual a um existente — só muda acento, maiúscula ou espaço — vem marcado para **usar o existente**; e um centro de classificação que só existe do outro lado (ex.: um do tipo Custo numa conta a receber) vem marcado para deixar em branco. O cliente é procurado só pelo nome: uma pessoa já cadastrada como fornecedor também serve, e passa a ser cliente também. Grafias do mesmo nome que só mudam acento, maiúscula ou espaço (ex.: *Água e Luz* e *agua e luz*) contam como um nome só. Dá para trocar qualquer escolha antes de importar. As [regras automáticas](https://docs.finance.kobana.com.br/pt/pt/regras-automaticas/.md) são aplicadas aos registros importados. ## Histórico[​](#histórico "Link direto para Histórico") Abaixo do painel, a seção **Histórico** lista as importações com data, arquivo, status (**Na fila**, **Processando**, **Concluído**, **Falha**, **Cancelado**), quantas linhas entraram do total e quem pediu. ## Aprovação[​](#aprovação "Link direto para Aprovação") observação **Contas a receber importadas não passam por aprovação.** O portão de aprovação de pagamentos existe só no lado de **pagar**, porque é lá que dinheiro sai. Um recebimento importado já entra na lista normal e nos totais. --- # Parcelas e recorrência — Contas a receber O comportamento é o mesmo das [Contas a pagar](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/parcelas-e-recorrencia.md): mesmos tipos, mesmos períodos, mesmo agrupamento. ## Tipos[​](#tipos "Link direto para Tipos") O campo **Tipo** oferece três opções: | Tipo | Descrição | | -------------- | ---------------------------------------- | | **À vista** | Conta única | | **Parcelado** | N parcelas com vencimentos sequenciais | | **Recorrente** | Gerada automaticamente em intervalo fixo | ## Parcelamento[​](#parcelamento "Link direto para Parcelamento") Informe o valor **de cada parcela** e o **Nº de parcelas**, de **2** a **120**. O sistema gera N contas ligadas pelo mesmo grupo, com **vencimentos mensais a partir do primeiro vencimento**, e **cada parcela é recebida individualmente**. Depois de criadas, vencimento e valor se ajustam uma a uma. Numa conta que já faz parte de uma série, **Tipo** e **Nº de parcelas** ficam travados. Uma conta **À vista** já salva pode virar **Recorrente**, mas não **Parcelado**. ## Recorrência[​](#recorrência "Link direto para Recorrência") O campo **Recorrência** aparece quando o tipo é **Recorrente** e é obrigatório. São **cinco** períodos: | Opção | Intervalo | | ------------------ | --------- | | **Toda semana** | 7 dias | | **Toda quinzena** | 14 dias | | **Todo mês** | 1 mês | | **A cada 3 meses** | 3 meses | | **Todo ano** | 12 meses | dica **Não existem períodos bimestral nem semestral.** Se você precisa de um intervalo fora dessa lista, o caminho é o parcelamento: as parcelas nascem mensais, e você ajusta o vencimento de cada uma depois. As ocorrências contam a partir da primeira: mudar o vencimento de uma não mexe nas seguintes, que continuam no dia original da série. Cada ocorrência lançada copia a última — valor, categoria, impostos e retenções, observações. Na listagem, a recorrência aparece abreviada junto ao vencimento — *Semanal*, *Quinzenal*, *Mensal*, *Trimestral*, *Anual*. É a mesma coisa, escrita curto para caber na coluna. ## Excluir[​](#excluir "Link direto para Excluir") A exclusão de uma conta que pertence a um grupo pergunta o alcance: * **Excluir apenas esta** * **Excluir esta e as futuras** — *"Ocorrências já recebidas ou conciliadas são mantidas."* Numa série importada (Fintera, Nibo), **Excluir esta e as futuras** é recusado: *"Esta série vem de uma integração; exclua-a na origem"*. **O alcance não é exclusivo de recorrências.** O seletor olha o **grupo**, então **parceladas e recorrentes** se comportam igual. Em conta avulsa ele não aparece. O seletor está **na listagem**. Excluindo pelo detalhe, apaga-se sempre só aquela conta. --- # Contas financeiras Contas financeiras (`/financial-accounts`) representam as contas bancárias e de caixa das empresas do espaço de trabalho. O saldo de cada conta é calculado a partir dos lançamentos registrados. Duas operações vivem **dentro** da conta, e estão documentadas à parte: ## [📄️Extratos bancários](https://docs.finance.kobana.com.br/pt/pt/extratos-bancarios/.md) [Importar OFX e QIF na conta financeira — deduplicação, histórico e desfazer.](https://docs.finance.kobana.com.br/pt/pt/extratos-bancarios/.md) ## [📄️Transferências](https://docs.finance.kobana.com.br/pt/pt/transferencias/.md) [Mover dinheiro entre contas do espaço de trabalho — dois lançamentos espelhados.](https://docs.finance.kobana.com.br/pt/pt/transferencias/.md) ![Listagem de contas financeiras](/pt/assets/images/07-accounts-f96d79882097564dda22a8c7c1ac7e14.png) ![Detalhe de conta financeira](/pt/assets/images/08-account-detail-b61b947754f5a37d89e6a451abb829ca.png) ## Tipos de conta[​](#tipos-de-conta "Link direto para Tipos de conta") **Corrente** · **Poupança** · **Caixa** · **Investimento** · **Crédito** O tipo escolhido muda o formulário: **Caixa não tem dados bancários** — a seção inteira desaparece, e o que já estava preenchido é limpo. **Uma conta de Crédito pode virar cartão.** Em [Cartões](https://docs.finance.kobana.com.br/pt/pt/cartoes/.md), ela passa a ter faturas, limite e compras parceladas — e cada cartão novo cria a sua conta de Crédito aqui. No seletor **Conta** do cabeçalho, a conta de um cartão leva o selo **Cartão**; o saldo dela é a dívida do cartão e fica fora do caixa (ver [Fechar, conferir e pagar](https://docs.finance.kobana.com.br/pt/pt/cartoes/fechar-conferir-pagar.md#no-fluxo-de-caixa)). ## Campos[​](#campos "Link direto para Campos") ### Essencial[​](#essencial "Link direto para Essencial") | Campo | Obrigatório | Observação | | ----------------- | ----------- | ------------------------------------ | | **Nome** | Sim | Ex.: "Conta corrente principal" | | **Tipo** | Sim | — | | **Saldo inicial** | Sim | **Só na criação** | | **Empresa** | **Não** | Vincular permite filtrar por empresa | ### Banco — não aparece em contas do tipo Caixa[​](#banco--não-aparece-em-contas-do-tipo-caixa "Link direto para Banco — não aparece em contas do tipo Caixa") | Campo | Obrigatório | | ----------------------- | ----------- | | **Banco** | **Sim** | | **Agência** | **Sim** | | **Dígito** (da agência) | Não | | **Número da conta** | **Sim** | | **Dígito** (da conta) | Não | ### Status[​](#status "Link direto para Status") Uma única opção: **Não permitir conciliação**, para contas que não devem entrar na conciliação (uma caixinha manual, por exemplo). aviso **Atenção à obrigatoriedade, que costuma ser lida ao contrário:** a **Empresa é opcional** — uma conta pode existir sem empresa. Já o **Banco é obrigatório** em Corrente, Poupança, Investimento e Crédito; agência e número da conta, em Corrente, Poupança e Investimento — uma conta de **Crédito** não tem agência nem número. Só em **Caixa** nenhum deles existe. ## Saldo[​](#saldo "Link direto para Saldo") O **Saldo inicial** é informado **apenas na criação**. Depois disso o campo some do formulário, que passa a exibir o aviso *"O saldo é atualizado automaticamente pelos lançamentos."* Para corrigir o saldo de uma conta que já existe, use **Ajustar saldo** — clique no valor do saldo, no detalhe da conta. Você informa o saldo real e a data, e o sistema cria **um lançamento de ajuste** que iguala a conta ao valor informado. observação **Um ajuste não pode ser editado depois — só excluído.** Para corrigir um ajuste errado, registre um novo. ## Listagem[​](#listagem "Link direto para Listagem") Colunas: **Nome** (com o banco na linha de baixo), **Tipo**, **Empresa** (só no modo "Consolidado"), **Agência**, **Conta**, **Lançamentos** e **Saldo**. A seta ao final leva aos lançamentos da conta. Filtros: busca **por nome**, abas por tipo (**Todas** · **Corrente** · **Poupança** · **Caixa** · **Investimento** · **Crédito**) e o filtro **Status** (**Ativas** / **Arquivadas**). O cabeçalho tem **Nova conta** e **Nova transferência**. ## Arquivar[​](#arquivar "Link direto para Arquivar") Uma conta arquivada **continua na listagem**, com o badge **Arquivada**. O filtro **Status** nasce **sem seleção** — ou seja, você vê ativas e arquivadas juntas até escolher. Arquivar e desarquivar são ações do menu da linha (**Arquivar** / **Desarquivar**), não um campo do formulário. O menu também traz **Editar** e **Excluir**. ## Detalhe da conta[​](#detalhe-da-conta "Link direto para Detalhe da conta") Além dos lançamentos, o detalhe traz três ações: **Extratos**, **Importar** e **Relatório**. Elas aparecem quando a conta já tem lançamentos. **Extratos** e **Importar** exigem uma **empresa específica** selecionada no cabeçalho — em "Consolidado" o painel apenas avisa isso. ## Gerentes[​](#gerentes "Link direto para Gerentes") A seção **Gerentes**, no detalhe da conta, guarda os gerentes do banco que atendem a conta — **com histórico**. Pode haver mais de um gerente ativo ao mesmo tempo. * **Adicionar gerente** tem duas abas, com a data de **Início** em comum. Em **Gerente cadastrado** você escolhe, entre as pessoas da empresa da conta com o papel **Gerente de conta**, quem atende. Em **Novo gerente** você preenche nome, e-mail, telefone e observações, e **Cadastrar e adicionar** cria a pessoa já como gerente — ela passa a existir também em [Pessoas](https://docs.finance.kobana.com.br/pt/pt/pessoas/.md), onde você completa o restante do cadastro. * Cada gerente ativo aparece num cartão com seus telefones e e-mails e os atalhos **Conversar no WhatsApp** (só para celular), **Ligar** e **Enviar e-mail**. * **Encerrar** registra a data de **Saída**: o gerente deixa os ativos e vai para o **Histórico de gerentes**, recolhido abaixo dos cartões. * **Editar datas** corrige início e saída. **Excluir** apaga o registro — use só para desfazer um cadastro feito por engano. observação **O gerente é uma pessoa da empresa da conta.** Uma conta sem empresa não tem gerentes — a seção pede que você vincule a conta a uma empresa. Se o mesmo gerente atende duas empresas, ele é cadastrado em cada uma. Excluir a pessoa encerra os mandatos ativos dela na data do dia; eles continuam no histórico. ## Acessos[​](#acessos "Link direto para Acessos") A seção **Acessos**, também no detalhe da conta, registra quem da equipe opera a conta no banco e com qual nível — **Proprietário**, **Administrador**, **Gestor**, **Visualizador** ou **Sem acesso**. **Sem acesso** é um nível registrado de propósito, diferente de a pessoa não estar na lista. * **Adicionar acesso** escolhe uma pessoa da empresa da conta (ou cadastra uma nova pelo nome) e o **Nível de acesso**. A pessoa ganha o papel **Time**. * Cada pessoa tem **um** nível por conta — para mudar, troque o nível direto na lista. * **Remover acesso** tira a pessoa da lista. Acessos **não têm histórico**: o que foi removido não fica guardado. Como nos gerentes, só pessoas da empresa da conta, e uma conta sem empresa não tem acessos. ## Integração com o Gateway Bancário[​](#integração-com-o-gateway-bancário "Link direto para Integração com o Gateway Bancário") Contas **corrente** e **poupança** podem ser sincronizadas com o Gateway Bancário, habilitando a sincronização de extrato e o envio de pagamentos. Contas de tipo Caixa, Investimento e Crédito não são suportadas e ficam de fora. Há dois caminhos para o vínculo, e eles se encontram no mesmo lugar: * **De lá para cá** — o botão **Sincronizar contas bancárias**, na tela de integração, importa as contas cadastradas no gateway e vincula sozinho as que já existem aqui. Veja [Gateway Bancário](https://docs.finance.kobana.com.br/pt/pt/integracoes/kobana.md). * **Daqui para lá** — a conta que só existe aqui ganha o botão **Adicionar no Gateway Bancário** na sua própria página. Você escolhe qual enviar; o envio cria a conta no gateway com o banco, a agência e o número cadastrados aqui, e pede uma confirmação antes. observação **Nada é duplicado.** O encontro é pelo **banco, número da agência e número da conta**. Se a conta que você enviar já existir no gateway com essas mesmas coordenadas, ela é apenas **vinculada**, não criada de novo. Os **dígitos verificadores não entram na comparação**: eles saem do próprio número, então um lado tê-los e o outro não — ou cadastrá-los grudados, como `5555-0` — não faz dela outra conta. Da agência valem os **quatro primeiros algarismos**, então `1234-5`, `12345` e `1234` são a mesma agência. A mesma regra vale para a [importação da Fintera](https://docs.finance.kobana.com.br/pt/pt/integracoes/fintera.md): uma conta que já existe aqui (cadastrada à mão ou vinda do gateway) é vinculada à conta da Fintera, não importada de novo. E se o próprio gateway tiver duas contas com o mesmo banco, agência e número, só a primeira é trazida — a outra aparece na prévia como **Duplicada no gateway**. Uma conta já vinculada exibe um badge **Kobana** na listagem e na própria página, e o botão de enviar some — não há para onde mandá-la. --- # Visão geral **Visão geral** (`/dashboard`) é a tela inicial do Financeiro Inteligente. Consolida a saúde financeira da organização em duas abas: **Desempenho** (o que já aconteceu) e **Fluxo de caixa** (a projeção do que está por vir). ![Dashboard — visão geral](/pt/assets/images/00-dashboard-605ad611acedba63b265008f6fae5449.png) ## Filtros[​](#filtros "Link direto para Filtros") * **Período** — seletor de intervalo de datas, no cabeçalho. Cada aba abre no seu preset padrão. * **Empresa** — vem do seletor do topo, ou consolida todas as empresas do espaço de trabalho. * **Granularidade** — **Dia**, **Semana**, **Mês** ou **Ano**, no topo da aba. As duas abas têm a sua. * **Conta** — **só na aba Fluxo de caixa**, para projetar sobre uma conta específica. ## Aba Desempenho[​](#aba-desempenho "Link direto para Aba Desempenho") Olha para trás: os números do período já efetivado. ### Cartões de métricas[​](#cartões-de-métricas "Link direto para Cartões de métricas") Quatro indicadores, cada um com um **minigráfico** de tendência: | Métrica | Descrição | Variação % | | ----------------------- | ----------------------------------- | ---------- | | **Saldo total** | Saldo somado das contas financeiras | — | | **Receitas no período** | Entradas realizadas | **Sim** | | **Despesas no período** | Saídas realizadas | **Sim** | | **Margem operacional** | (receitas − despesas) / receitas | — | **Só Receitas e Despesas comparam com o período anterior.** O selo de variação percentual existe nesses dois. Saldo total e Margem operacional mostram o minigráfico, mas não trazem selo de variação — não há com o que comparar de forma honesta. ### Fluxo realizado[​](#fluxo-realizado "Link direto para Fluxo realizado") Gráfico do **saldo** ao longo do período, com o histograma de entradas e saídas já efetivadas embaixo e as abas **Dia**, **Semana**, **Mês** e **Ano** para escolher o tamanho do balde. O pico e o menor saldo ficam marcados no próprio ponto, e passar o mouse mostra os maiores lançamentos daquele ponto. **As opções que não fazem sentido para o período ficam desabilitadas.** Uma granularidade que renderia uma barra só não é oferecida: em "Este mês", **Mês** sai (viraria um único bloco) e a visão abre em **Semana**. Em "Hoje", sobra **Dia**. É a mesma regra da aba Fluxo de caixa. ### Maiores despesas[​](#maiores-despesas "Link direto para Maiores despesas") As **4 maiores categorias de despesa** do período, com atalho para a listagem de despesas. ### Análise de curto prazo[​](#análise-de-curto-prazo "Link direto para Análise de curto prazo") Compara **Esta semana** com os **Últimos 30 dias**, e mostra o ticket médio por lançamento no período de 30 dias. aviso **Este painel ignora o seletor de período.** As janelas são fixas — esta semana e os últimos 30 dias corridos — e não mudam quando você troca o período no cabeçalho. É a fonte de confusão mais comum da tela: os números dele não "batem" com os cartões de propósito, porque medem outra coisa. ## Aba Fluxo de caixa[​](#aba-fluxo-de-caixa "Link direto para Aba Fluxo de caixa") Olha para frente. A antiga rota `/cash-flow` **redireciona** para cá (`/dashboard?tab=cash-flow`). Além da granularidade, esta aba tem o seletor de **Conta**, para projetar sobre uma conta específica. ### Os quatro cartões[​](#os-quatro-cartões "Link direto para Os quatro cartões") | Cartão | O que traz | | ----------------------- | ---------------------------------------------------------------------------------------------------- | | **Saldo atual** | Saldo de hoje, com a contagem de contas | | **Entradas projetadas** | O que há a receber na janela | | **Saídas projetadas** | O que há a pagar na janela | | **Saldo projetado** | O saldo ao fim do período, com o **menor saldo projetado daqui para a frente** e a variação vs. hoje | **Numa janela sem futuro, os títulos mudam.** Olhando só para o passado, os três últimos viram **"Entradas realizadas"**, **"Saídas realizadas"** e **"Saldo final"** — deixam de prometer projeção quando não há o que projetar. O menor saldo é um alerta sobre o que **vem pela frente**: ele varre só os períodos futuros, porque um vale que já passou não é aviso de nada. E só aparece quando fica **abaixo** do saldo do fim do período — se o pior momento é o último, repetir o número não diria nada. observação **"Saldo projetado" não é "saldo de fim de mês".** É o saldo de fechamento do **último período do intervalo escolhido**. Num intervalo de 90 dias, é o saldo ao fim dos 90 dias — não do mês corrente. ### O que entra na projeção[​](#o-que-entra-na-projeção "Link direto para O que entra na projeção") Quatro fontes somadas: 1. **Títulos pendentes** — contas a pagar e a receber, pela **data de vencimento**. Contas a pagar entram só depois de aprovadas, quando a aprovação está ligada (o padrão). 2. **Lançamentos previstos** — os marcados como provisórios, pela data. 3. **Ocorrências virtuais de recorrências** — este é o ponto sutil. Uma recorrência fica lançada só até o prazo de provisionamento (12 meses por padrão; ver [Parcelas e recorrência](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/parcelas-e-recorrencia.md)). Numa projeção que vai além dele, o sistema continua a série **na leitura**, gerando as ocorrências que ainda não existem como registro. Elas não são gravadas — existem só na projeção. 4. **Faturas de cartão** — a fatura aberta e as futuras de cada cartão de crédito, pelo total previsto, no vencimento, na conta que paga o cartão. Depois de fechada, a fatura entra como conta a pagar. As compras no cartão não entram uma a uma: o cartão não é caixa (ver [Cartões](https://docs.finance.kobana.com.br/pt/pt/cartoes/fechar-conferir-pagar.md#no-fluxo-de-caixa)). observação **O que está vencido não some: é empurrado para hoje.** Um título com vencimento na semana passada e ainda pendente não fica no passado nem desaparece — ele entra no grupo de **hoje**, porque continua sendo dinheiro que vai sair ou entrar. O detalhamento marca isso: *"Inclui R$ 1.200,00 em contas vencidas"*. ### Vencidas e A vencer[​](#vencidas-e-a-vencer "Link direto para Vencidas e A vencer") **Dois** painéis, não um: **"Vencidas"** e **"A vencer (30 dias)"**. Cada um separa o que é a pagar e o que é a receber, e diz há quantos dias venceu ou em quantos vence. ### Gráfico, detalhamento e cenários[​](#gráfico-detalhamento-e-cenários "Link direto para Gráfico, detalhamento e cenários") * **Gráfico** do saldo por período: a linha é o saldo (sólida no realizado, tracejada a partir de **Hoje**), com o pico e o menor saldo marcados no ponto e a linha do zero em destaque; embaixo, o histograma de Entradas e Saídas do mesmo período. Passar o mouse mostra entradas, saídas, saldo e os maiores lançamentos daquele ponto. No topo dele ficam as abas **Resumo** e **Por categoria**, que **comandam o gráfico e a tabela ao mesmo tempo** — não são da tabela, embora seja lá que a diferença mais aparece. Em **Por categoria** o gráfico troca a curva do saldo por uma linha por categoria, com as **entradas acima do zero e as saídas abaixo**: os dois lados aparecem juntos, e a linha do zero é a linha d'água. A legenda embaixo separa as categorias de cada lado. * **"Detalhamento por período"** — tabela com Saldo inicial, Entradas, Saídas, Saldo do período e Saldo final. Essas cinco linhas são a aba **Resumo**: em **Por categoria** as linhas de saldo **saem**, e ficam só Entradas e Saídas, abertas por categoria — é uma leitura de fluxo, não de saldo. Clicar num período abre os lançamentos que o compõem, marcando o que é **Realizado**, **Projetado**, **Vencido** e o que veio de **recorrência**. * **Cenário** — simulação what-if: **Adiar** ou **Remover** títulos da projeção para ver o efeito no **Saldo projetado** e no **Pior saldo projetado**, sem alterar nada de verdade. **Limpar** desfaz. --- # MCP da Documentação Esta documentação tem um **servidor MCP próprio**. Com ele, um assistente de IA (Claude, ChatGPT, Cursor, VS Code, Claude Code) busca e lê as páginas deste site sem que você precise copiar e colar nada. Assim, as respostas sobre o Financeiro Inteligente saem do conteúdo publicado, no idioma que você escolher. ``` https://docs.finance.kobana.com.br/mcp ``` > **Não é o MCP do produto:** O MCP da Documentação só **lê a documentação**. Ele não acessa sua conta, não vê contas a pagar, contas a receber nem lançamentos e não altera nada. Para um agente operar o Financeiro Inteligente, use o **MCP do produto** (`mcp.finance.kobana.com.br`), que pede login e respeita as suas permissões. Veja [MCP › Clientes](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/clients.md). ## Como funciona[​](#como-funciona "Link direto para Como funciona") * **Público e só de leitura:** não pede login nem token. Expõe o mesmo conteúdo que qualquer pessoa vê no site. * **Sempre atualizado:** lê a versão publicada da documentação. Uma página nova ou alterada aparece no MCP assim que o site é publicado. * **Três idiomas:** português (`pt`), inglês (`en`) e espanhol (`es`). Sem idioma informado, usa o português. * **Transporte:** Streamable HTTP, sem sessão. Qualquer cliente MCP que conecte a um servidor remoto por URL funciona. ## Tools[​](#tools "Link direto para Tools") | Tool | O que faz | Parâmetros | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `search_docs` | Busca páginas por palavras-chave, no título, no caminho e no resumo, sem diferenciar acento nem maiúsculas. Devolve as melhores páginas com caminho e resumo | `query` (obrigatório), `locale`, `limit` (1 a 25, padrão 8) | | `get_page` | Devolve o conteúdo completo de uma página em Markdown | `path`: o caminho que `search_docs` ou `list_pages` devolveu (por exemplo, `/pt/conciliacao`) ou a URL completa | | `list_pages` | Lista todas as páginas, com caminho e resumo | `locale` | | `search_openapi` | Busca operações (endpoints) da API REST por palavras-chave, no resumo, no caminho e na descrição. Devolve as melhores operações com método, caminho e `operationId` | `query` (obrigatório), `version`, `locale`, `limit` (1 a 25, padrão 8) | | `get_operation` | Devolve uma operação da API completa: descrição, parâmetros, corpo da requisição e respostas com seus schemas | `operation_id`, ou `method` e `path`; `version`, `locale` | O assistente decide sozinho quando chamar cada tool. Normalmente ele busca com `search_docs` e lê com `get_page` as páginas que interessam. ## Como instalar[​](#como-instalar "Link direto para Como instalar") O jeito mais rápido é pelo menu **Copiar página**, no topo de cada página deste site. Em **MCP da Documentação**, você encontra: * **Conectar ao Cursor** e **Conectar ao VS Code:** instalam o servidor com um clique. * **Copiar config do MCP:** copia o bloco JSON para clientes configurados por arquivo. * **Copiar comando do MCP:** copia o comando de instalação para o terminal. Se preferir configurar à mão, os passos de cada cliente estão abaixo. ### Qualquer cliente, pelo terminal[​](#qualquer-cliente-pelo-terminal "Link direto para Qualquer cliente, pelo terminal") O [`add-mcp`](https://www.npmjs.com/package/add-mcp) detecta os clientes instalados na máquina e adiciona o servidor a eles: ``` npx add-mcp "https://docs.finance.kobana.com.br/mcp" ``` ### Claude Code[​](#claude-code "Link direto para Claude Code") ``` claude mcp add --transport http kobana-finance-docs https://docs.finance.kobana.com.br/mcp ``` ### Cursor[​](#cursor "Link direto para Cursor") Use **Conectar ao Cursor** no menu da página, ou adicione ao `~/.cursor/mcp.json` (para todos os projetos) ou ao `.cursor/mcp.json` do projeto: ``` { "mcpServers": { "kobana-finance-docs": { "url": "https://docs.finance.kobana.com.br/mcp" } } } ``` ### VS Code[​](#vs-code "Link direto para VS Code") Use **Conectar ao VS Code** no menu da página, ou crie o `.vscode/mcp.json` no projeto. No VS Code a chave é `servers`, não `mcpServers`: ``` { "servers": { "kobana-finance-docs": { "type": "http", "url": "https://docs.finance.kobana.com.br/mcp" } } } ``` ### Claude e ChatGPT[​](#claude-e-chatgpt "Link direto para Claude e ChatGPT") Em **Configurações › Conectores**, adicione um conector personalizado e cole a URL `https://docs.finance.kobana.com.br/mcp`. Não há login a fazer. ### Outros clientes configurados por arquivo[​](#outros-clientes-configurados-por-arquivo "Link direto para Outros clientes configurados por arquivo") ``` { "mcpServers": { "kobana-finance-docs": { "type": "http", "url": "https://docs.finance.kobana.com.br/mcp" } } } ``` ## Exemplos de perguntas[​](#exemplos-de-perguntas "Link direto para Exemplos de perguntas") Com o servidor conectado, pergunte normalmente. O assistente consulta a documentação antes de responder: * "Como funciona a conciliação de um lançamento do extrato com uma conta a pagar?" * "Como cadastro uma conta a pagar parcelada ou recorrente?" * "Como crio regras automáticas para classificar os lançamentos?" * "Monte um exemplo de chamada à API para criar uma conta a receber, com base na documentação." ## Testar sem cliente[​](#testar-sem-cliente "Link direto para Testar sem cliente") ``` curl -s https://docs.finance.kobana.com.br/mcp \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"conciliação","locale":"pt"}}}' ``` ## Limites[​](#limites "Link direto para Limites") * As páginas de referência de cada endpoint da API não fazem parte de `search_docs`/`get_page`: elas são geradas a partir da especificação OpenAPI e, por isso, o MCP as lê direto dela, com `search_openapi` e `get_operation`. A especificação completa continua em [API › OpenAPI](https://docs.finance.kobana.com.br/pt/pt/api/overview/openapi.md). * A busca é por palavras-chave, não semântica. Se não encontrar, tente outros termos ou peça ao assistente para usar `list_pages`. * Também dá para ler qualquer página como Markdown acrescentando `.md` à URL, ou baixar a documentação inteira em [`llms-full.txt`](https://docs.finance.kobana.com.br/pt/llms-full.txt). --- # Empresas Empresas (`/companies`) representam as entidades jurídicas (CNPJs) administradas dentro do espaço de trabalho. O Financeiro Inteligente é multi-empresa: um único espaço de trabalho pode cuidar do back-office financeiro de várias empresas ao mesmo tempo. ![Listagem de empresas](/pt/assets/images/17-companies-f540bf4799c039e60bee1659adddb6e7.png) ## Cadastro[​](#cadastro "Link direto para Cadastro") O formulário tem **dois campos**, e o segundo depende do primeiro: | Campo | Obrigatório | Descrição | | -------- | ----------- | ----------------------------------------------------------------------------- | | **CNPJ** | Sim | O CNPJ da empresa. Assim que ele fica completo, o sistema consulta a Receita. | | **Nome** | Sim | Preenchido pela consulta. Só aceita digitação quando a consulta não responde. | **Ativo** e **Contas financeiras** aparecem **apenas na edição** — uma empresa nova nasce ativa, e no momento da criação ainda não há contas para vincular. O fluxo é criar a empresa e depois criar as contas. ### O CNPJ aceita letras[​](#o-cnpj-aceita-letras "Link direto para O CNPJ aceita letras") observação **O CNPJ tem 14 caracteres, não 14 dígitos.** No formato alfanumérico da Receita Federal, os 12 primeiros caracteres (raiz e ordem do estabelecimento) aceitam **letras e números**; só os 2 dígitos verificadores no final são exclusivamente numéricos. A máscara do campo trata isso, e letras digitadas viram maiúsculas automaticamente. O CNPJ é validado no próprio campo antes de qualquer consulta: dígito verificador inválido nem chega a consultar a Receita. ### Consulta automática à Receita[​](#consulta-automática-à-receita "Link direto para Consulta automática à Receita") **Assim que o CNPJ fica completo** — digitado ou colado, sem precisar sair do campo —, o sistema consulta a Receita Federal e usa a resposta para preencher o resto: * **Razão social preenchida e travada.** O campo **Nome** já começa bloqueado, com o aviso *"Informe o CNPJ acima"* — ele existe para receber a razão social, não para você digitar. Quando a consulta responde, o nome chega pronto. * **Aviso de situação cadastral.** Se a empresa não estiver **ATIVA** na Receita, aparece um alerta com a situação encontrada — *"Situação cadastral na Receita: SUSPENSA."*, por exemplo. É **só um aviso**: não impede o cadastro. * **CNPJ duplicado bloqueia.** Se o CNPJ já pertence a outra empresa **ativa deste espaço de trabalho**, o aviso *"CNPJ já cadastrado."* aparece e o botão Salvar não conclui. Essa checagem é local: o CNPJ de uma empresa **inativa não reserva o lugar**, e a unicidade vale por espaço de trabalho, não globalmente. Se a Receita não localizar o CNPJ (*"CNPJ não localizado na Receita — informe o nome manualmente."*) ou a consulta falhar (*"Não foi possível consultar a Receita — informe o nome manualmente."*), o campo **Nome destrava** e você digita. Uma consulta que não responde nunca trava o cadastro. ### Tipo (matriz ou filial) não é um campo[​](#tipo-matriz-ou-filial-não-é-um-campo "Link direto para Tipo (matriz ou filial) não é um campo") Você não escolhe. O tipo é **deduzido do próprio CNPJ**, pelos quatro caracteres da ordem do estabelecimento — o `0001` em `12.345.678/0001-95`. `0001` é **matriz**; qualquer outro valor é **filial**. O tipo aparece como badge na listagem e como filtro (**Todas** · **Matriz** · **Filial**), nunca como campo editável. Se você corrigir o CNPJ de uma empresa já cadastrada, o tipo é recalculado junto. ## Contas financeiras[​](#contas-financeiras "Link direto para Contas financeiras") Cada empresa pode ter várias contas financeiras, vinculadas na seção **Contas financeiras** do formulário de edição (**Adicionar conta** vincula uma conta que já existe). **A empresa é opcional na conta financeira**, não obrigatória. Uma conta pode existir sem empresa. Vincular é o que permite filtrar a Visão geral e os relatórios por empresa — é útil, mas o sistema não exige. ## Filtro por empresa[​](#filtro-por-empresa "Link direto para Filtro por empresa") O seletor de empresa no cabeçalho da aplicação persiste entre as telas e filtra os dados exibidos. Ele lista **apenas empresas ativas**. ## Inativar[​](#inativar "Link direto para Inativar") Inativar **não** tira a empresa da tela de Empresas. Ela continua na listagem, com o badge **Inativo** na coluna Status. O que a inativação faz é **tirar a empresa do seletor do cabeçalho e dos formulários** — ela deixa de ser uma opção em novos lançamentos, e o histórico permanece intacto. * **Para inativar:** abra **Editar** na linha da empresa e desligue o switch **Ativo**. * **Para reativar:** o mesmo caminho, religando o switch. * **Para ver as inativas:** elas já aparecem por padrão. O filtro **Status** (**Ativo** / **Inativo**) serve para restringir — pinar **Ativo** é o que as esconde. ## Excluir[​](#excluir "Link direto para Excluir") A exclusão é permanente e não pode ser desfeita. O diálogo avisa: *"Tem certeza que quer excluir esta empresa? Todas as contas financeiras associadas serão removidas."* observação **Movimentação financeira bloqueia a exclusão.** Se a empresa tiver **lançamentos**, **contas a pagar**, **contas a receber** ou **pessoas cadastradas**, o sistema recusa e diz o que encontrou: *"Não foi possível excluir esta empresa porque existem 3 lançamentos, 1 conta a pagar vinculados a ela. Exclua esses registros antes de tentar novamente."* Não bloqueiam — **são apagados junto** com a empresa: * **Contas financeiras** (é o que o diálogo avisa) * **Categorias** e **centros de classificação** da empresa Na prática o bloqueio quase sempre vence: uma conta financeira com movimento implica lançamentos, e lançamento bloqueia. Se a empresa tem histórico e você quer apenas tirá-la de circulação, **inative** em vez de excluir. ## Integração WhatsApp[​](#integração-whatsapp "Link direto para Integração WhatsApp") Cada empresa pode ter configurações próprias de WhatsApp (via Evolution API) para exibir fotos de perfil de clientes e fornecedores. Consulte [WhatsApp](https://docs.finance.kobana.com.br/pt/pt/integracoes/whatsapp.md). --- # Extratos bancários Extratos bancários importam o extrato de uma conta e criam lançamentos a partir dele. Os formatos aceitos são OFX e QIF. ## Onde fica[​](#onde-fica "Link direto para Onde fica") Extratos **não é uma tela própria** e não tem item de menu. É uma aba dentro da conta: **Contas financeiras** → abra a conta → aba **Extratos**. Por isso não existe passo de "escolher a conta de destino": **a conta é aquela em que você já está**. É preciso ter uma **empresa específica** selecionada no cabeçalho — em "todas as empresas" o painel apenas avisa isso. ## Formatos aceitos[​](#formatos-aceitos "Link direto para Formatos aceitos") | Formato | Extensão | Descrição | | ------- | -------- | -------------------------------------------------------------------------- | | OFX | `.ofx` | Open Financial Exchange — padrão da maioria dos bancos | | QIF | `.qif` | Quicken Interchange Format — formato legado, ainda usado por alguns bancos | O botão **Baixar exemplo** oferece um arquivo de cada formato. São **exemplos para você conhecer o formato**, não modelos para preencher — um extrato se exporta do banco, não se escreve à mão. ## Importar[​](#importar "Link direto para Importar") 1. Exporte o extrato do seu banco em OFX ou QIF. 2. Na aba **Extratos** da conta, envie o arquivo. 3. O sistema lê o arquivo e mostra o que encontrou: quantos lançamentos são importáveis e quantos foram ignorados. 4. **Todas as linhas já vêm marcadas.** Clique numa linha para desmarcá-la se não quiser importá-la. 5. Clique em **Importar N lançamentos**. A importação **roda em segundo plano**: você recebe o aviso *"Importação iniciada em segundo plano"* e acompanha por um diálogo de progresso — a tela não fica travada esperando. Os lançamentos importados entram **não conciliados**. Para ligá-los aos títulos, use a [Conciliação](https://docs.finance.kobana.com.br/pt/pt/conciliacao/.md). ### O que é ignorado[​](#o-que-é-ignorado "Link direto para O que é ignorado") Três casos são descartados na leitura e **contados**, com o resumo na tela — *"Ignorados: 2 com data futura, 1 com valor zero, 0 com data inválida."*: * **Data futura** * **Valor zero** * **Data inválida** (um valor ilegível também cai aqui) ## Deduplicação[​](#deduplicação "Link direto para Deduplicação") observação **A dedup identifica a linha pelo identificador que o banco dá a ela (o FITID do OFX) — não por "mesmo valor, data e descrição".** Quando o arquivo não traz esse identificador (o que é sempre o caso no QIF), o sistema gera uma chave a partir de data, valor e descrição **mais a ordem de ocorrência**, justamente para que duas linhas idênticas **não** sejam confundidas. **O que a deduplicação garante:** reenviar **o mesmo arquivo** para **a mesma conta** não duplica nada. As linhas já conhecidas são puladas, e o histórico informa quantas foram. **O lançamento que o ERP já trouxe também não duplica.** Se a conta tem o histórico importado do Fintera ou da Nibo, a linha do arquivo que é o mesmo movimento — mesma direção, mesmo valor, mesmo dia — não cria outro lançamento: ela se junta ao que veio do ERP, que fica com a descrição e a classificação do financeiro e ganha o texto do banco. **O que ela não garante — e importa saber:** * **Dois lançamentos genuinamente iguais entram os dois.** Dois saques de R$ 50 no mesmo dia, com a mesma descrição, são dois lançamentos reais. O sistema os preserva de propósito. * **Não há dedup entre origens de extrato.** O mesmo lançamento vindo por OFX, por QIF e pela sincronização do Gateway Bancário conta como **três** — cada origem gera sua própria chave. (Entre o extrato e o ERP há, ver acima.) * **A dedup é por conta**, não por espaço de trabalho. * **Nada é marcado na tela.** A verificação acontece no servidor, **na hora de importar** — não no momento em que você revisa a lista. ## Histórico[​](#histórico "Link direto para Histórico") Abaixo do painel de importação, a seção **Histórico** lista os arquivos já importados: data, arquivo, status, quantos lançamentos entraram do total, e quem pediu. A seção só aparece quando há histórico. Os status são **Na fila**, **Processando**, **Concluído**, **Falha** e **Cancelado**. ### Desfazer[​](#desfazer "Link direto para Desfazer") A ação **Desfazer** apaga **os lançamentos que aquele arquivo criou** e remove o extrato do histórico. O diálogo avisa: *"Isso exclui os N lançamentos importados deste extrato. Não dá para reverter."* Se algum desses lançamentos já estava conciliado, **desfazer também desmancha a conciliação**. O lançamento que veio do ERP e recebeu uma linha do arquivo **não é apagado**: desfazer só o desliga do extrato. Enviar o arquivo de novo junta a linha a ele outra vez. A ação não aparece enquanto o extrato está **Na fila** ou **Processando** — espere terminar. Também não aparece em extratos vindos do Fintera: *"Extratos vindos do Fintera não podem ser desfeitos aqui — desfaça no Fintera."* ### Apagar um lançamento do extrato[​](#apagar-um-lançamento-do-extrato "Link direto para Apagar um lançamento do extrato") Apagar **um lançamento** que veio de um extrato é diferente de desfazer o extrato inteiro, e a diferença aparece na próxima importação: * **Apagou o lançamento** — ele **não volta**. Importar o mesmo arquivo de novo, ou sincronizar o Gateway Bancário outra vez, não o traz de volta: o sistema lembra que você o removeu. * **Desfez o extrato** — aí sim, importar o arquivo de novo traz tudo. É o caminho para recomeçar. **É por isso que apagar a linha resolve, mesmo sem Desfazer.** O extrato do Gateway Bancário não tem lote para desfazer, e a sincronização traz o histórico inteiro da conta toda vez. Sem essa garantia, a linha que você apagasse voltaria na sincronização seguinte — e se você já tivesse lançado a correção à mão, o valor apareceria **duas vezes**. ## Outras origens de extrato[​](#outras-origens-de-extrato "Link direto para Outras origens de extrato") Além do arquivo, o extrato pode vir de: * **Gateway Bancário** — o botão **Sincronizar extrato**, na tela de integração, traz os lançamentos das contas vinculadas da empresa selecionada. * **Fintera** — importa o extrato espelhado da plataforma. **Nenhuma das duas roda sozinha.** Não há agendamento: as duas são um botão que você aperta. observação **O extrato do Gateway Bancário não aparece no Histórico desta aba.** Ele não é um arquivo — o gateway devolve uma lista de lançamentos, sem o conceito de "extrato importado". Os **lançamentos** aparecem normalmente na conta; o **lote** não, e por isso **não há Desfazer** para ele. Para tirar uma linha, apague o lançamento: ele não volta na próxima sincronização (ver [Apagar um lançamento do extrato](#apagar-um-lan%C3%A7amento-do-extrato)). O registro dessas execuções fica na própria tela do [Gateway Bancário](https://docs.finance.kobana.com.br/pt/pt/integracoes/kobana.md). --- # Impostos A seção de Impostos (`/taxes`) gerencia o cadastro de taxas e tributos que podem ser **vinculados a contas a pagar e a receber** (retenções/impostos sobre o título). ![Listagem de impostos](/pt/assets/images/13-taxes-5e067f947501b4746ced52d60a2d82bc.png) ## Campos[​](#campos "Link direto para Campos") | Campo | Descrição | | ------------------- | ----------------------------------------------------------------------------------------------- | | **Nome** | Identificação do tributo (ex.: "INSS Patronal", "ISS Municipal") — único por espaço de trabalho | | **Taxa padrão (%)** | Percentual sugerido do tributo | | **Retido** | Marca o imposto como retido na fonte. Padrão: sim | | **Ativo** | Se o imposto aparece para seleção | ## Uso[​](#uso "Link direto para Uso") Os impostos cadastrados podem ser **atribuídos como encargo** a uma conta a pagar ou a receber — o título guarda quais impostos incidem sobre ele. observação **Cadastrar um imposto não é pagar uma guia.** Para registrar o **pagamento** de uma guia específica (DARF, GPS, GRU, FGTS…), use uma conta a pagar com **Documento = Tributo** — ver [Tributos em Contas a pagar](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/tributos.md). ## API[​](#api "Link direto para API") O recurso de impostos está disponível na [API pública](https://docs.finance.kobana.com.br/pt/pt/api.md), com o escopo `finance/taxes` e o nível de acesso `read` para ler, `write` para criar e alterar e `delete` para excluir. --- # Integrações **Integrações** (`/settings/integrations`) conecta a organização a serviços externos. É um item do grupo **Sistema** do menu. ![Tela de integrações](/pt/assets/images/19-integrations-30a33b4b6e0b56090083bc38d644b91f.png) ## Integrações disponíveis[​](#integrações-disponíveis "Link direto para Integrações disponíveis") ## [📄️Gateway Bancário](https://docs.finance.kobana.com.br/pt/pt/integracoes/kobana.md) [Envio de pagamentos ao banco e sincronização de contas, extratos e pessoas via Kobana.](https://docs.finance.kobana.com.br/pt/pt/integracoes/kobana.md) ## [📄️Open Finance](https://docs.finance.kobana.com.br/pt/pt/integracoes/open-finance.md) [Conecte as contas bancárias da empresa pelo Open Finance e receba saldos e extratos automaticamente.](https://docs.finance.kobana.com.br/pt/pt/integracoes/open-finance.md) ## [📄️Fintera](https://docs.finance.kobana.com.br/pt/pt/integracoes/fintera.md) [Importação de dados financeiros da Fintera — onze recursos, vínculo de empresas e agendamentos.](https://docs.finance.kobana.com.br/pt/pt/integracoes/fintera.md) ## [📄️WhatsApp](https://docs.finance.kobana.com.br/pt/pt/integracoes/whatsapp.md) [Fotos de perfil de clientes e fornecedores via Evolution API — configuração por empresa.](https://docs.finance.kobana.com.br/pt/pt/integracoes/whatsapp.md) Cada card leva à página da integração, com as instruções de conexão. ## Status[​](#status "Link direto para Status") O selo de status fica ao lado do nome da integração, e **só aparece em dois casos**: | Situação | O que você vê | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | **Conectado** | Um **ícone redondo verde**. O texto "Conectado" não é escrito na tela — ele está no tooltip, ao passar o mouse | | **Com erro** | Um **selo vermelho escrito "Com erro"** — credencial inválida ou falha de conexão | | **Não configurado** | **Nada.** O selo simplesmente não é desenhado | observação **A ausência de selo é a informação.** Uma integração ainda não conectada não exibe "Não configurado": o espaço fica vazio. O texto existe no sistema, mas nenhuma tela o mostra. **O card do WhatsApp não tem selo nenhum**, nem quando está configurado. O status só é calculado para o Gateway Bancário e o Fintera — a conexão do WhatsApp é por empresa e vive em outro lugar. Para saber se está de pé, abra a página dele. --- # Integração Fintera **Sistema > Integrações > Fintera** (`/settings/integrations/fintera`). Importa dados de uma conta Fintera para o Financeiro Inteligente — para quem está migrando ou mantém as duas plataformas em paralelo. ## Conectar[​](#conectar "Link direto para Conectar") A faixa do topo mostra **Status**, **Token** e quantas **Empresas** estão vinculadas. Sem conexão, **"Conectar"**: cole o token de API da Fintera. Uma vez conectado, o diálogo "Gerenciar conexão Fintera" mostra o token como *"Armazenado criptografado"* — ele nunca é exibido de volta. Conectado, o botão vira **"Gerenciar conexão"** — e é dentro desse diálogo que ficam o **vínculo de empresas**, **Atualizar** o token e **Desconectar**. ## Vínculo de empresas[​](#vínculo-de-empresas "Link direto para Vínculo de empresas") **A Fintera traz as empresas, não as contas.** *"Essas empresas vêm da Fintera (pelo seu token). Aqui você só escolhe pra qual empresa cadastrada no Financeiro Inteligente cada uma vai mandar os dados."* ## Dois portões[​](#dois-portões "Link direto para Dois portões") As importações ficam bloqueadas até que ambos estejam satisfeitos: 1. **Token válido** — *"Salve um token válido da Fintera para liberar as importações."* 2. **Pelo menos uma empresa vinculada** — *"Vincule pelo menos uma empresa Fintera a uma empresa do Financeiro Inteligente para liberar as importações."* ## O que é importado[​](#o-que-é-importado "Link direto para O que é importado") **Onze recursos**, em dois grupos. A ordem importa: **Movimentações** *"dependem dos cadastros acima"*. ### Cadastros base[​](#cadastros-base "Link direto para Cadastros base") | Recurso | Observações | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Categorias** | Replicadas por empresa; categorias bidirecionais geram um **par** (receita + despesa) | | **Centros de classificação** | Para todas as empresas vinculadas | | **Pessoas** | Clientes e fornecedores | | **Impostos** | Catálogo do espaço de trabalho. **Precede** contas a pagar/receber, cujos impostos por título resolvem contra ele | | **Contas financeiras** | Contas bancárias da Fintera. Uma conta que já existe aqui com o mesmo banco, agência e número (à mão ou vinda do Gateway Bancário) é **vinculada**, não duplicada | ### Movimentações[​](#movimentações "Link direto para Movimentações") | Recurso | Depende de | | -------------------- | -------------------------------------------------------------------------------------------------- | | **Contas a pagar** | Pessoas + categorias + centros | | **Contas a receber** | Pessoas + categorias + centros | | **Lançamentos** | — (a primeira importação de cada conta traz o histórico inteiro; as seguintes, os últimos 90 dias) | | **Conciliações** | Títulos + lançamentos | | **Anexos** | Títulos + lançamentos | | **Extratos** | Lançamentos | observação **Extratos não baixa arquivo OFX.** A importação *"espelha o histórico de importação de extratos da Fintera e vincula cada lançamento ao seu extrato"* — mas **o arquivo em si não vem**: a API da Fintera não o fornece. Você recebe a estrutura e os vínculos, não o documento. **Conciliações preserva o n:m.** O vínculo da Fintera entre títulos e lançamentos é espelhado como está. Ver [Conciliação](https://docs.finance.kobana.com.br/pt/pt/conciliacao/.md) — uma conciliação importada é somente leitura. **Contas a pagar trazem os dados de pagamento.** O que está em *Dados de Pagamento* na Fintera — boleto, TED ou Pix (chave, dados bancários ou copia-e-cola) — chega em **Informações de pagamento** do título. O favorecido não vem: vazio, o envio ao banco usa o fornecedor. Quando o título na Fintera não tem dados de pagamento, a importação não mexe no que você preencheu aqui. E, depois que alguém altera os dados de pagamento aqui ou o título é enviado ao banco, a importação também não os substitui mais. **O que você faz aqui a importação não desfaz.** Ela só atualiza o que ainda está como a Fintera mandou da última vez. A classificação que você, uma [regra automática](https://docs.finance.kobana.com.br/pt/pt/regras-automaticas/.md) ou a [conciliação](https://docs.finance.kobana.com.br/pt/pt/conciliacao/.md) deu a um lançamento continua; a linha conciliada aqui como transferência continua transferência; e o título baixado aqui continua pago, mesmo em aberto na Fintera. A conciliação que vem da Fintera deixa de fora o que já foi conciliado aqui, e o lançamento excluído aqui não volta. ## Importar[​](#importar "Link direto para Importar") **"Importar tudo"** roda os onze em sequência, respeitando a dependência. Cada linha também tem seu **"Importar"**, para rodar um recurso isolado. As importações **rodam em segundo plano** e seguem os vínculos de empresa. Cada linha mostra o progresso e o resultado — quantos criados, atualizados, com erro, ou *"sem mudanças"* / *"nada a importar"*. **Contas a pagar e a receber trazem só o que mudou.** Depois da primeira importação de cada empresa, as seguintes pedem à Fintera apenas os títulos criados ou alterados desde a anterior — nunca o acervo inteiro de novo. Quando a Fintera não informa a data de alteração, pedem os títulos que vencem ou foram pagos nos últimos 90 dias (ou desde a importação anterior, se ela for mais antiga). Por isso o total de uma reimportação costuma ser pequeno: são as mudanças. **Título excluído na Fintera vira cancelado aqui.** A cada importação, o Financeiro Inteligente compara quantos títulos a Fintera tem com os daqui — sem trazer o acervo — e, quando sobra algum, confirma título a título antes de marcá-lo como cancelado: sai dos totais, relatórios e do fluxo de caixa, mas não é apagado. Se ele voltar a aparecer na Fintera, a importação seguinte o restaura. Títulos já enviados ao banco ou conciliados não são tocados. Para importar a partir de um dia específico, algumas linhas têm, ao lado do botão de importar, um ícone de calendário: * **Contas a pagar** e **Contas a receber** — os títulos criados ou alterados desde a data (ou, quando a Fintera não informa a alteração, os que vencem ou foram pagos desde ela). Na primeira importação de uma empresa, ele também evita trazer o histórico inteiro: a importação começa naquele dia. * **Lançamentos** — os lançamentos ocorridos desde a data até hoje, em todas as contas. * **Extratos** — os extratos dos lançamentos já importados desse período. * **Anexos** — só os anexos enviados à Fintera desde a data. Os que já estão aqui não são baixados de novo. Os cadastros, as contas financeiras e as conciliações não têm o calendário: a Fintera não filtra esses recursos por data, e eles são lidos inteiros a cada importação. **Não existe um botão "Importar dados" com seletor de período.** São os onze recursos, cada um com o seu, mais o "Importar tudo". ## Modo token do módulo Financeiro[​](#modo-token-do-módulo-financeiro "Link direto para Modo token do módulo Financeiro") Um token restrito ao módulo Financeiro da Fintera não lista empresas. Nesse caso não há o que vincular, e a tela avisa: *"Importações disponíveis aplicadas às empresas ativas do espaço de trabalho."* Só um subconjunto dos recursos fica habilitado. ## Agendamentos[​](#agendamentos "Link direto para Agendamentos") *"Configure execuções automáticas das importações."* Com **"Novo agendamento"**, uma importação passa a rodar sozinha na frequência escolhida. Cada linha mostra o recurso, a frequência, a **próxima execução** e o resultado da última, com o selo **Ativo** ou **Desativado** e as ações **Editar**, **Pausar** / **Retomar** e **Excluir**. É o que diferencia a Fintera das ferramentas de [Manutenção](https://docs.finance.kobana.com.br/pt/pt/manutencao/.md): aqui **existe** agendamento. ## Histórico de importações[​](#histórico-de-importações "Link direto para Histórico de importações") Registro das execuções, em quatro colunas: **Data**, **Importações**, **Resultado** e **Usuário** — quem disparou. ## Desconectar[​](#desconectar "Link direto para Desconectar") Dentro de **"Gerenciar conexão"**. Os dados já importados permanecem. --- # Integração Gateway Bancário (Kobana) **Sistema > Integrações > Kobana** (`/settings/integrations/kobana`). A integração permite: 1. **Envio de pagamentos ao banco** — despachar contas a pagar aprovadas, título a título ou em lote. 2. **Sincronização de contas bancárias** — entre a Kobana e o Financeiro Inteligente. 3. **Sincronização de extrato** — trazer os lançamentos das contas vinculadas. 4. **Sincronização de pessoas** — manter o cadastro igual dos dois lados. Traz tudo que está na Kobana; daqui, envia só os clientes. 5. **Liquidação automática** — confirmado o pagamento, a conta é baixada e o lançamento criado. Depende de o título ter **"Pagar via"** definida: sem saber de qual conta o dinheiro saiu, o sistema não adivinha, e a baixa fica para você fazer na mão. 6. **Geração de cobranças** — emitir **boleto ou Pix** a partir de uma conta a receber, para o cliente pagar. 7. **Comprovantes de pagamento** — capturar sozinho o comprovante de cada pagamento confirmado. ## Conectar[​](#conectar "Link direto para Conectar") A faixa do topo mostra o **Status** — **Conectado**, **Não conectado** ou **Erro de conexão** — e o token. Sem conexão, o botão é **"Conectar"**: cole o token de API gerado no painel da Kobana. *"O token é armazenado criptografado."* O sistema valida e informa quantas contas estão visíveis. Já conectado, o botão vira **"Gerenciar conexão"**. **"Desconectar" não fica na página.** Ele mora dentro do diálogo **"Gerenciar conexão Kobana"**, junto de "Atualizar". A confirmação tranquiliza: *"Apenas a conexão é desfeita. As contas e dados já sincronizados permanecem no Financeiro Inteligente."* ## Sincronizações[​](#sincronizações "Link direto para Sincronizações") observação **As sincronizações exigem uma empresa específica** no seletor do topo: *"Selecione uma empresa específica no seletor do topo, não 'Todas as empresas'. As contas sincronizadas entram na empresa que você escolher."* ### Contas bancárias[​](#contas-bancárias "Link direto para Contas bancárias") Não existe listagem para vincular contas à mão. Há **um botão** — **"Sincronizar contas bancárias"** — que faz o trabalho inteiro e vincula sozinho. **Esta sincronização só traz.** O card leva o selo **"Do gateway"**: ela importa as contas cadastradas na Kobana e **não cria nada lá**. Ainda assim há uma confirmação, porque a rodada pode **reescrever contas que já existem aqui** — e o modal mostra exatamente quais, e quais campos mudam, antes de você autorizar. **O caminho de volta é conta a conta.** Para mandar uma conta daqui para a Kobana, abra a conta e use **"Adicionar no Gateway Bancário"** — veja [Contas financeiras](https://docs.finance.kobana.com.br/pt/pt/contas-financeiras/.md). Criar conta no gateway altera o sistema externo, então quem escolhe o que vai é você, uma conta por vez, e não uma rodada em massa. ### Extrato[​](#extrato "Link direto para Extrato") **"Sincronizar extrato"** *"importa o extrato das contas vinculadas (na empresa selecionada): traz os lançamentos da Kobana para o Financeiro Inteligente, sem duplicar os já importados."* **O botão é um só e cobre todas as contas vinculadas da empresa** — não há um botão por conta. As linhas importadas alimentam a [Conciliação](https://docs.finance.kobana.com.br/pt/pt/conciliacao/.md). ### Pessoas[​](#pessoas "Link direto para Pessoas") **"Enviar pessoas"** sincroniza o cadastro nos dois sentidos: traz da Kobana quem só existe lá e envia daqui os **clientes** da empresa selecionada que ainda não existem na Kobana. O card também traz o selo **"Bidirecional"**. informação **Fornecedor não é enviado.** O cadastro na Kobana é de quem paga — um fornecedor ocuparia lugar lá sem nunca ser cobrado. Quem é cliente **e** fornecedor ao mesmo tempo é enviado normalmente, por ser cliente também. Na volta não há esse filtro, porque a Kobana não separa papel: **quem vem de lá entra aqui como cliente**. Se a pessoa importada for, na verdade, um fornecedor seu, marque o papel na ficha dela — a marcação é sua e as sincronizações seguintes não a desfazem. aviso **Também ESCREVE na Kobana**, e por isso pede confirmação: *"Criar cadastros na Kobana altera o sistema externo."* **Ninguém é duplicado.** O encontro é pelo **CPF/CNPJ** — e, para quem já foi enviado daqui antes, pelo próprio vínculo gravado no envio anterior. Quem já existe dos dois lados apenas passa a ficar vinculado; os dados que você cadastrou aqui **não são sobrescritos**. informação **Pessoa sem CPF/CNPJ não é enviada.** Sem o documento não há como saber se ela já está lá, e o envio prefere deixar de fora a arriscar um cadastro repetido. Ao final, a sincronização diz quantas ficaram nessa situação — basta completar o documento e rodar de novo. A **importação** não tem esse limite. Cada execução envia até **200 pessoas**. Se a sua base for maior, rode outra vez: o que já foi não é reenviado. ## Aprovação de pagamentos[​](#aprovação-de-pagamentos "Link direto para Aprovação de pagamentos") Quando a aprovação está **ligada** (o padrão do espaço de trabalho), um título criado por formulário, CSV ou API **não** fica disponível para envio até ser **aprovado por uma pessoa** em [Aprovar pagamentos](https://docs.finance.kobana.com.br/pt/pt/aprovar-pagamentos/.md). Com a aprovação desligada, o título já nasce oficial e enviável. Ver [Ciclo de vida](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/ciclo-de-vida.md). ## Envio de pagamentos[​](#envio-de-pagamentos "Link direto para Envio de pagamentos") Com a integração ativa e o título aprovado, use **"Enviar para o banco"** — ação **manual**, na tela de detalhe. Da listagem, o caminho é **"Enviar pagamentos"**, que despacha em lote. Ver [Envio ao banco](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/disparo-kobana.md). ## Geração de cobranças[​](#geração-de-cobranças "Link direto para Geração de cobranças") A integração também funciona na direção do dinheiro que **entra**: de uma conta a receber, **"Gerar cobrança"** emite um **boleto** ou um **Pix** para o cliente pagar, e a cobrança paga baixa o título sozinha. Cada trilho tem o seu pré-requisito na conta do gateway — o boleto precisa de um **convênio**, o Pix de uma **conta Pix de cobrança** —, e o boleto ainda exige o **endereço completo** do cliente. Ver [Cobrança por boleto e Pix](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/cobranca-kobana.md). ## Comprovantes[​](#comprovantes "Link direto para Comprovantes") Confirmado um pagamento enviado ao banco, o comprovante é **capturado sozinho**: fica guardado na biblioteca de [Anexos](https://docs.finance.kobana.com.br/pt/pt/anexos/.md), aparece na tela do título e é listado em [Comprovantes](https://docs.finance.kobana.com.br/pt/pt/comprovantes/.md). Quem estiver marcado em **"Configurar envio"** recebe um e-mail, e os endereços cadastrados no próprio título recebem o comprovante **anexado**; o sino avisa de qualquer forma. Ver [Quem recebe por e-mail](https://docs.finance.kobana.com.br/pt/pt/comprovantes/.md#quem-recebe-por-e-mail). ## Sincronização automática[​](#sincronização-automática "Link direto para Sincronização automática") observação **Esta seção só aparece se o servidor tiver um endereço público de webhook configurado.** Sem isso não há como o gateway avisar de nada, e nem ela nem as duas seções seguintes são desenhadas. Um interruptor: *"Atualiza o status dos pagamentos enviados sozinho, sem você precisar clicar em 'Atualizar status'."* **É opcional, e desligada você não fica sem informação** — só precisa buscar o status na mão, pelo **"Atualizar status"** de cada título. ## Notificações[​](#notificações "Link direto para Notificações") Outro interruptor: *"Receba um aviso no sino quando o status de um pagamento mudar (confirmado, agendado, recusado…)."* Os dois interruptores conversam: sem a sincronização automática ligada, *"os avisos podem chegar com atraso"* — o sino só avisa quando o sistema descobre a mudança. ## Entregas do webhook[​](#entregas-do-webhook "Link direto para Entregas do webhook") Tabela de diagnóstico: *"Registro de cada evento de mudança de status que o gateway de pagamentos da Kobana envia. Se algum falhar, você pode reenviá-lo."* Tem **"Atualizar"** e, por linha, o reenvio. É onde olhar quando um pagamento parece travado: se o evento não chegou, o status daqui fica para trás do banco. **Esta tabela só existe com a sincronização automática ligada.** É ela que faz o gateway mandar os eventos — desligada, não há entrega para registrar, e a seção some da página. ## Histórico[​](#histórico "Link direto para Histórico") Registro das sincronizações executadas, por **Data**, **Tipo** (**Contas**, **Extrato** ou **Pessoas**) e **Resultado** — com quantas foram criadas, atualizadas, enviadas ou puladas. Na sincronização de pessoas, que corre nos dois sentidos, o resultado os separa: o que **veio** da Kobana aparece como criado ou atualizado, e o que **foi** daqui aparece como enviado. As pessoas deixadas de fora por não ter CPF/CNPJ entram como puladas. A de contas só traz, então ali só há criadas e atualizadas. --- # Open Finance **Sistema > Integrações > Open Finance** (`/settings/integrations/open-finance`). Conecte as contas bancárias das suas empresas pelo **Open Finance**, o sistema de compartilhamento de dados regulado pelo Banco Central, e o Financeiro Inteligente passa a receber sozinho: 1. **Saldos** — várias vezes ao dia, registrados na aba **Saldos** da conta com a origem **Open Finance**. 2. **Extrato** — os lançamentos efetivados entram como lançamentos da conta, classificados pelas suas [regras automáticas](https://docs.finance.kobana.com.br/pt/pt/regras-automaticas/.md). Nada aqui movimenta dinheiro: o Open Finance só **lê** as contas que você autorizar. ## Conectar um banco[​](#conectar-um-banco "Link direto para Conectar um banco") Clique em **"Conectar banco"**. São dois passos: 1. **Empresa** — escolha a empresa e informe o **CPF de quem vai autorizar no banco**. Para contas de empresa, o banco pede o CPF de uma pessoa com acesso à conta. O CPF não fica guardado. Clique em **"Continuar"**. 2. **Autorização** — abre-se a janela de autorização, já com a empresa e o CPF: escolha o banco, confira os dados que serão compartilhados, a finalidade e o prazo, e confirme. Se a janela não abrir sozinha, clique em **"Escolher o banco"**. Você é levado ao **próprio banco**, entra com seus dados de acesso e escolhe ali quais contas compartilhar. Ninguém além do banco vê sua senha. Ao terminar, o banco traz você de volta ao Financeiro Inteligente. observação O prazo do compartilhamento aparece na revisão, antes de você confirmar, e é confirmado no banco. Você pode encerrar antes, aqui ou no seu banco. ## Escolher o que fazer com cada conta[​](#escolher-o-que-fazer-com-cada-conta "Link direto para Escolher o que fazer com cada conta") Na volta do banco, a tela mostra as contas compartilhadas. Para cada uma: | Opção | O que acontece | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Vincular a uma conta existente** | A conta que você já tem aqui passa a receber saldo e extrato. O sistema sugere a conta certa pela agência e número | | **Criar nova conta** | Uma conta nova é criada na empresa, já vinculada | | **Ignorar esta conta** | Nada é importado dela | E, para cada conta, **"Importar extrato"** com a data **"a partir de"**. aviso **A data de início evita lançamentos repetidos.** Se a conta já tem extrato aqui — importado por OFX ou digitado —, comece depois do último lançamento. O sistema já sugere essa data. Uma conta que já recebe extrato pelo [Gateway Bancário](https://docs.finance.kobana.com.br/pt/pt/integracoes/kobana.md) chega com o extrato **desligado**. Ligando aqui, o extrato passa a vir só pelo Open Finance — nunca pelos dois, para o mesmo lançamento não entrar duas vezes. O saldo das duas origens convive. ## Acompanhar as conexões[​](#acompanhar-as-conexões "Link direto para Acompanhar as conexões") Cada conexão (empresa × banco) aparece com o status: | Status | Significado | | ---------------------- | ------------------------------------------------------------- | | **Aguardando o banco** | A autorização no banco ainda não foi concluída | | **Conectado** | Saldos e extratos sendo atualizados | | **Não autorizado** | A autorização foi recusada ou não terminou a tempo | | **Encerrado** | O compartilhamento foi encerrado — por você, aqui ou no banco | | **Expirado** | O prazo acabou | No menu de cada conexão: **Atualizar agora**, **Revisar contas**, **Renovar** (antes de expirar), **Desconectar** e, depois de encerrada, **Remover da lista**. Você recebe um aviso na central de notificações quando a conexão é autorizada, quando as contas ficam prontas para importar, perto do vencimento e quando ela é encerrada. **Desconectar não apaga nada.** Os lançamentos e saldos já importados continuam nas contas. ## Agendar a sincronização e ver o histórico[​](#agendar-a-sincronização-e-ver-o-histórico "Link direto para Agendar a sincronização e ver o histórico") Na mesma tela, **Agendamento da sincronização** define quando as conexões de uma empresa atualizam sozinhas (saldos, extratos, cartões e investimentos). Selecione a empresa no topo e use **Novo agendamento**; é um por empresa. Sem agendamento, o sistema atualiza a cada 6 horas e sempre que o banco avisa de novos dados. O **Histórico de sincronizações** lista as últimas execuções — banco, origem (aviso do banco, agendada, manual ou nova conexão) e o que mudou. ## Na conta[​](#na-conta "Link direto para Na conta") Uma conta vinculada mostra o selo **Open Finance**. Na aba **Saldos**: * **"Atualizar via Open Finance"** lê o saldo na hora; * **"Extrato via Open Finance"** liga ou desliga o extrato e muda a data de início. Um lançamento importado que você excluir **não volta** na próxima atualização. --- # Integração WhatsApp (Evolution API) **Sistema > Integrações > WhatsApp** (`/settings/integrations/whatsapp`). Com a Evolution conectada, a ferramenta **Buscar fotos** (em [Manutenção](https://docs.finance.kobana.com.br/pt/pt/manutencao/.md)) passa a tentar a foto do WhatsApp dos contatos. ## O que ela faz — e o que não faz[​](#o-que-ela-faz--e-o-que-não-faz "Link direto para O que ela faz — e o que não faz") observação **Esta integração não exibe foto nenhuma por conta própria.** Ela é uma **fonte** para a busca de fotos, não um recurso autônomo. Sem ela, a busca usa **só o Gravatar** — *"e ele raramente tem foto de número brasileiro"*, que é justamente o motivo de a integração existir. A foto encontrada é **guardada** no cadastro da pessoa. Não é buscada a cada visita, nem por baixo dos panos: só quando alguém roda **Buscar fotos**. **A foto aparece em [Pessoas](https://docs.finance.kobana.com.br/pt/pt/pessoas/.md)** — na listagem e no detalhe. **Não** aparece nas telas de contas a pagar ou a receber. ## Configuração por empresa[​](#configuração-por-empresa "Link direto para Configuração por empresa") As credenciais são **por empresa**, não por espaço de trabalho — cada uma pode ter a sua instância. Sem uma empresa selecionada, a página não mostra a configuração: fica em **"Selecione uma empresa"**. **A empresa vem do seletor do topo**, não de um passo dentro da página. São **três** campos, e o botão só libera com os três preenchidos: | Campo | Exemplo | | ------------------------ | ---------------------------------------------------------------------------------- | | **URL da API Evolution** | `https://evolution.exemplo.com` | | **Nome da instância** | `minha-instancia` | | **API Key** | A chave da instância. *"A chave é armazenada criptografada e nunca volta no GET."* | O botão é **"Conectar"** — ou **"Atualizar"**, se já houver credenciais. ## Privacidade e segurança[​](#privacidade-e-segurança "Link direto para Privacidade e segurança") * A **API Key é criptografada** em repouso e nunca é devolvida na leitura. * O sistema **recusa destinos privados**: endereços de loopback, redes internas e link-local são bloqueados, o que impede usar a integração para alcançar serviços da infraestrutura. aviso **Não é obrigatório ser HTTPS.** `http://` é aceito — o que o sistema recusa é o **destino**, não o protocolo. Ainda assim, um endpoint em HTTP trafega a API Key em claro: prefira HTTPS. ## Buscar fotos[​](#buscar-fotos "Link direto para Buscar fotos") A busca é **manual**, em [Manutenção](https://docs.finance.kobana.com.br/pt/pt/manutencao/.md) → **Buscar fotos**. Não há worker periódico. Cada execução: * Tenta o **Gravatar primeiro** (pelo e-mail) e o **WhatsApp depois** (pelo telefone), parando na primeira fonte que responder. * Percorre **apenas quem ainda não tem foto** — quem já tem é pulado. * Processa no máximo **100 pessoas por vez**. * Espera **30 dias** antes de tentar de novo quem falhou. ## Remover[​](#remover "Link direto para Remover") O botão é **"Remover"**. A confirmação diz o efeito exato: *"As credenciais da empresa serão apagadas. A próxima execução de 'Buscar fotos' para essa empresa não tentará o WhatsApp — só Gravatar."* As fotos **já buscadas continuam** no cadastro: remover a credencial não apaga o que foi encontrado. --- # Lançamentos Lançamentos (`/financial-transactions`) são as movimentações das contas financeiras: entradas e saídas de dinheiro. São a base da conciliação com contas a pagar e a receber. ![Listagem de lançamentos](/pt/assets/images/05-transactions-e460b3c680998f87894c24e188412b86.png) ![Detalhe de lançamento](/pt/assets/images/06-transaction-detail-1572701de5297b403b2a7ff73b2c806a.png) ## Nesta seção[​](#nesta-seção "Link direto para Nesta seção") ## [📄️Importação CSV](https://docs.finance.kobana.com.br/pt/pt/lancamentos/importacao-csv.md) [Importar lançamentos em lote via planilha — dentro da conta financeira, com cabeçalho em português.](https://docs.finance.kobana.com.br/pt/pt/lancamentos/importacao-csv.md) ## A listagem[​](#a-listagem "Link direto para A listagem") O cabeçalho traz três totais — **Entradas**, **Saídas** e **Saldo** — com seta verde para entrada e vermelha para saída. observação **Os totais são do cabeçalho, não do rodapé, e têm escopo próprio.** Eles somam **empresa + período** e nada mais: buscar por texto ou aplicar filtros **não os estreita**. Filtrar por uma categoria e ver o total continuar o mesmo não é defeito — a faixa de totais responde "quanto entrou e saiu no período", não "quanto a lista mostra". ### Filtros[​](#filtros "Link direto para Filtros") * **Busca** — por descrição ou documento. * **Filtros rápidos** — **Todos**, **Com anexos**, **Conciliados**, **Transferências**. * **Filtros avançados** — aceitam cláusulas **negativas**, não só positivas. São de dois tipos: pílulas que existem nas duas formas (**Conciliados** / **Não conciliados**, **Transferências** / **Não transferências**, **Com anexos** / **Sem anexos**), e a opção **Sem categoria** dentro do seletor de categorias — o mesmo valendo para **Sem cliente / fornecedor** e **Sem centro de classificação**. Escolher categorias sempre **inclui**: não há como excluir uma categoria específica. Ao lado da faixa de totais fica ainda **Exportar** — que não é filtro, e sim uma ação: gera o arquivo de exportação dos lançamentos. ### Colunas[​](#colunas "Link direto para Colunas") Descrição, Data, Categoria, Conta e Valor — mais **Empresa**, só na visão consolidada. **Forma de pag.** existe como coluna ativável, e a última coluna é uma **ficha** do lançamento (vínculos, pessoa, documento, competência, rateio, observações), visível no desktop. **Forma de pag. é somente leitura.** Não há esse campo no formulário: a coluna só mostra o que veio por **CSV ou API**. Criando um lançamento pela tela, ela fica vazia. ### Os selos da coluna Descrição[​](#os-selos-da-coluna-descrição "Link direto para Os selos da coluna Descrição") Não existe um campo "Origem". A procedência é **derivada** e aparece como ícones ao lado da descrição: | Selo | Significa | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Conciliado** | Vinculado a um título | | **Gerado pela liquidação de…** | Criado pela baixa de um título | | **Transferência** | Uma das pontas de uma transferência | | **Provisório** | Ainda não efetivado | | **Clipe** | Tem anexos | | **Cartão** | Uma compra de [cartão](https://docs.finance.kobana.com.br/pt/pt/cartoes/.md), com o fornecedor e a fatura embaixo | | **Pagamento de fatura** · **Recarga** | As pontas da transferência que paga a fatura de um cartão ou recarrega um pré-pago | ### Ações[​](#ações "Link direto para Ações") Por linha: **Classificar**, **Conciliar**, **Editar** e **Excluir**. Em lote: **Conciliar selecionados**, **Classificar selecionados** e **Excluir**. observação **Conciliar e Classificar em lote exigem uma empresa só.** Categorias e títulos são por empresa, então uma seleção que mistura empresas não tem como abrir o diálogo — na visão consolidada, o sistema avisa e cancela em vez de escolher uma empresa por conta própria. **Classificar** pede ainda que a seleção seja toda do mesmo tipo: entradas e saídas juntas também são recusadas, porque as categorias de uma não servem à outra. **Excluir** não tem nenhuma dessas travas — apaga a seleção como ela estiver. ## Campos[​](#campos "Link direto para Campos") | Campo | Observações | | ------------------------------------------- | ----------------------------------------------- | | **Valor (R$)** | Obrigatório | | **Data** | Obrigatório | | **Conta financeira** | Obrigatório — onde a movimentação ocorreu | | **Descrição** | Obrigatório | | **Mês de competência** | Seletor de mês | | **Tipo de lançamento** | Entrada ou saída | | **Categoria** · **Centro de classificação** | Classificação, cada uma com o atalho **Rateio** | | **Cliente/Fornecedor** | Pessoa associada | | **Nº de documento** · **Data do doc.** | O documento externo | | **Provisório** | Marca o lançamento como previsão | | **Observação** | Texto livre | | **Anexos** | Arquivos ligados ao lançamento | ### Provisório[​](#provisório "Link direto para Provisório") A pílula **"Provisório"** marca o lançamento como uma previsão, ainda não efetivada. Ele **aparece na listagem com selo, mas não entra no saldo da conta nem nos números realizados da visão geral** — conta na **projeção** do fluxo de caixa, não no realizado. ## Criação automática[​](#criação-automática "Link direto para Criação automática") Alguns lançamentos você não digita — o sistema cria: * **Baixa de uma conta a pagar** → saída na conta escolhida. * **Baixa de uma conta a receber** → entrada na conta escolhida. * **Transferência** → saída na origem e entrada no destino. * **Extrato bancário importado**, ao confirmar a importação. * **Sincronização do Gateway Bancário**. * **Compra no cartão** → saída na conta do cartão, na data da compra, quando o lançamento do cartão é realizado. É gerida pelo cartão: editar, classificar, conciliar e excluir ficam desabilitados aqui, com o motivo, e **"Abrir no cartão"** leva à fatura. O mesmo vale para o pagamento da fatura e a recarga — ver [Cartões](https://docs.finance.kobana.com.br/pt/pt/cartoes/.md#o-cart%C3%A3o-e-as-suas-contas). ## Conciliação[​](#conciliação "Link direto para Conciliação") Um lançamento pode ser vinculado a contas a pagar e a receber. O vínculo aparece no detalhe do lançamento e na tela de [Conciliação](https://docs.finance.kobana.com.br/pt/pt/conciliacao/.md), que fecha, linha a linha, o que veio do extrato. --- # Importação CSV — Lançamentos Importe lançamentos em lote via arquivo CSV. ## Onde fica[​](#onde-fica "Link direto para Onde fica") **Não existe "Importação" no menu**, nem uma tela de importação. E, ao contrário do que se poderia esperar, **a tela de Lançamentos não importa** — a importação vive dentro da conta: **Contas financeiras** → abra a conta → pílula **Importar**. observação **Não há seletor de conta de destino.** A conta é aquela em que você já está: todos os lançamentos do arquivo entram nela. Para importar em duas contas, são duas importações. É preciso ter uma **empresa específica** selecionada no cabeçalho, e **a conta precisa estar vinculada a uma empresa**. Nos dois casos o painel avisa: *"Selecione uma empresa específica para importar lançamentos."* O botão **Baixar modelo** entrega um CSV de exemplo com o cabeçalho correto — é o ponto de partida mais seguro, porque já vem no encoding certo. ## Colunas do CSV[​](#colunas-do-csv "Link direto para Colunas do CSV") | Coluna | Obrigatório | Descrição | | -------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | ✅ | Data do lançamento | | `descricao` | ✅ | Descrição do lançamento | | `valor` | ✅ | Valor em reais, sempre positivo | | `tipo` | ✅ | `entrada` (crédito) ou `saida` (débito) | | `categoria` | — | Nome da categoria (se ainda não existir, a prévia pergunta se cria). Também aceita: `plano_de_contas`, `categoria_financeira`, `category` | | `pessoa` | — | Nome da pessoa (se ainda não existir, a prévia pergunta se cria). Também aceita: `cliente_fornecedor`, `cliente`, `fornecedor`, `favorecido`, `contraparte` | | `centro_custo` | — | Nome do centro de classificação (se ainda não existir, a prévia pergunta se cria). Também aceita: `centro_de_custo`, `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` | | `documento` | — | Identificador do documento | | `observacao` | — | Observações | aviso **O cabeçalho deste arquivo é em português, e só em português.** Diferente do CSV de contas a pagar e a receber — que aceita tanto `description` quanto `descricao` —, aqui os nomes canônicos **já são** os portugueses e **as colunas obrigatórias não têm equivalente em inglês**. Um arquivo com `description`, `amount` e `date` é recusado inteiro, por coluna obrigatória ausente. Maiúsculas, acentos e espaços no cabeçalho não importam: `Centro de Receita` vale como `centro_de_receita`. Se o espaço tiver um classificador com o mesmo nome de uma dessas colunas (ex.: *Centro de Resultado*), a coluna vai para o classificador. Se a planilha tiver mais de uma coluna para o mesmo campo (ex.: `Centro de Custo` e `Centro de Receita`), cada linha usa a primeira que estiver preenchida. Além desses nomes, um cabeçalho com a palavra **centro** é lido como centro de classificação; um com **categoria** ou **plano de contas**, como categoria (por exemplo, `Centro de Lucro`, `Categoria DRE`); e um com **pessoa**, **cliente** ou **fornecedor** acompanhada só de palavras de nome, como pessoa (por exemplo, `Nome do Fornecedor`, `Cliente / Fornecedor` — mas não `CNPJ do Fornecedor`). Colunas que o sistema não conhece são **ignoradas em silêncio**. ## Formato[​](#formato "Link direto para Formato") * **Cabeçalho** — maiúsculas, acentos e espaços não importam: `Descrição`, `DESCRICAO` e `descricao` são a mesma coluna. * **Separador** — `,` ou `;`, detectado **pela linha de cabeçalho**. Em caso de empate, `;`. * **Datas** — `31/12/2026`, `31-12-2026` ou `2026-12-31`. * **Valores** — `1234.56`, `1.234,56`, `1234,56`, com ou sem `R$`. O valor precisa ser **maior que zero**: quem decide se é entrada ou saída é a coluna `tipo`, nunca o sinal do valor. aviso **A codificação precisa ser UTF-8, e é aqui que a maioria dos arquivos tropeça.** O Excel em português salva CSV em Windows-1252 por padrão, e o sistema recusa: *"Arquivo não está em UTF-8. Salve novamente em UTF-8 e tente novamente."* No Excel, use **Salvar como → CSV UTF-8**; ou parta do modelo baixado. Outras recusas do arquivo inteiro: extensão diferente de `.csv`, tamanho acima de **5 MB**, arquivo vazio, e **coluna obrigatória ausente** — *"Colunas obrigatórias ausentes: tipo"*. Nesses casos não há preview: o problema é do arquivo, não de uma linha. ## Importar[​](#importar "Link direto para Importar") 1. Envie o arquivo. O sistema lê e mostra o preview. 2. **As linhas válidas já vêm marcadas.** Clique numa linha para desmarcá-la. 3. Clique em **Importar N linhas**. ### Linhas com erro[​](#linhas-com-erro "Link direto para Linhas com erro") Linhas inválidas aparecem no preview com um marcador vermelho, **e não podem ser selecionadas nem editadas ali**. Não há correção dentro do sistema. A própria tela diz o caminho: *"Desmarque as linhas com erro ou corrija-as no arquivo e envie novamente."* O número em **Linha N** é o número da linha **no arquivo**, contando o cabeçalho — a primeira linha de dados é a 2. ### A gravação roda em segundo plano[​](#a-gravação-roda-em-segundo-plano "Link direto para A gravação roda em segundo plano") Ao confirmar, você recebe *"Importação iniciada em segundo plano"* e um diálogo de progresso. **Pode fechar o diálogo** — a importação continua, e o progresso fica visível no canto inferior direito. ### Vínculos[​](#vínculos "Link direto para Vínculos") **Pessoas, categorias e centros de classificação aparecem na prévia**, cada um com o que vai acontecer na importação: os que já existem são ligados; os que ainda não existem vêm marcados para **criar** (ou para **deixar em branco**, se você não tiver permissão de criar); um nome quase igual a um existente — só muda acento, maiúscula ou espaço — vem marcado para **usar o existente**; e um centro de classificação que só existe do outro lado (ex.: um do tipo Custo numa entrada) vem marcado para deixar em branco. A pessoa é procurada só pelo nome, seja cliente ou fornecedor, e passa a ter o papel das linhas em que aparece (cliente nas entradas, fornecedor nas saídas); uma pessoa nova usada em entradas e saídas é criada uma vez só, como cliente e fornecedor. Um centro de classificação novo usado em entradas e saídas é criado uma vez só, do tipo Ambos. Grafias do mesmo nome que só mudam acento, maiúscula ou espaço (ex.: *Água e Luz* e *agua e luz*) contam como um nome só. Dá para trocar qualquer escolha antes de importar. As [regras automáticas](https://docs.finance.kobana.com.br/pt/pt/regras-automaticas/.md) são aplicadas aos registros importados. ## Histórico[​](#histórico "Link direto para Histórico") Abaixo do painel, a seção **Histórico** lista as importações com data, arquivo, status (**Na fila**, **Processando**, **Concluído**, **Falha**, **Cancelado**), quantas linhas entraram do total e quem pediu. --- # Manutenção **Manutenção** (`/settings/maintenance`) reúne as ferramentas de higiene dos dados de **pessoas**: padronizar telefones e nomes, achar duplicados, limpar cadastros vazios e buscar fotos. E uma de **lançamentos**: juntar os que a importação gravou em dobro. ## Escopo[​](#escopo "Link direto para Escopo") observação **As ferramentas agem sobre uma empresa por vez.** O escopo vem do seletor do topo, e a tela avisa: *"Aplicadas apenas à empresa selecionada."* Em **"Consolidado"**, ela pede que você escolha uma antes de rodar qualquer coisa. ## As seis ferramentas[​](#as-seis-ferramentas "Link direto para As seis ferramentas") | Ferramenta | O que faz | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Ajustar telefones** | Classifica cada telefone como celular ou fixo pelas regras da Anatel — 11 dígitos com o terceiro igual a 9 é celular; 10 dígitos com o terceiro entre 2 e 5 é fixo. O que não encaixa fica como não classificável | | **Normalizar nomes** | Converte os nomes das pessoas para letras maiúsculas, **mantendo a acentuação** | | **Detectar duplicados** | Procura cadastros repetidos por **mesmo nome**, **primeiro + último nome**, **mesmo e-mail**, **mesmo telefone** ou **mesmo CPF/CNPJ**, e agrupa para você juntar | | **Limpar pessoas vazias** | Lista pessoas **sem CPF/CNPJ, sem e-mail, sem telefone e sem lançamentos vinculados**, para remoção | | **Buscar fotos** | Busca a foto de cada pessoa no **Gravatar** (pelo e-mail) e no **WhatsApp** (quando o número é público e a empresa tem credenciais Evolution). **Quem já tem foto é pulado** | | **Deduplicar lançamentos** | Numa conta, junta os lançamentos que a importação do ERP (Fintera, Nibo) e o extrato do banco (Gateway Bancário, Open Finance ou um OFX enviado) gravaram em dobro | | **Apagar lançamentos de uma fonte** | Apaga os lançamentos que uma integração trouxe — Fintera, Nibo, Conta Azul, Open Finance ou Gateway Bancário —, na empresa toda ou numa conta, para recomeçar a importação | ## Nada roda sozinho[​](#nada-roda-sozinho "Link direto para Nada roda sozinho") **Estas ferramentas não são agendáveis: rodam quando você clica, e só então.** Não há execução periódica nem gatilho automático — nenhuma delas dispara ao criar uma pessoa ou ao importar um arquivo. Isso não quer dizer que a tela trave enquanto elas trabalham: uma vez iniciadas, algumas **executam em segundo plano e mostram o progresso ali mesmo**. As duas coisas convivem — o que não existe é **agendamento**, não é assincronia. ## Juntar duplicados[​](#juntar-duplicados "Link direto para Juntar duplicados") Detectados os grupos, você escolhe quais juntar. Em cada grupo, um cadastro é marcado como **Sobrevivente** — é ele que fica, recebendo os dados e os vínculos dos outros. O botão é **"Juntar selecionados"**, e a confirmação diz quantos grupos serão processados e quantas pessoas serão juntadas ao sobrevivente. observação **Juntar não mexe nas regras de [Segurança](https://docs.finance.kobana.com.br/pt/pt/seguranca/.md#benefici%C3%A1rios).** As listas de favorecidos liberados e bloqueados, e os limites de cada um, são por **CPF/CNPJ**, não por cadastro: o documento bloqueado continua bloqueado e o liberado continua liberado depois da junção. Se os cadastros juntados tinham documentos diferentes, confira em Segurança qual deles está na regra. ## Limpar pessoas vazias[​](#limpar-pessoas-vazias "Link direto para Limpar pessoas vazias") A lista mostra cada pessoa vazia e quando foi cadastrada, com **"Selecionar todas"** e **"Limpar selecionadas"**. perigo **A remoção é a mesma exclusão de [Pessoas](https://docs.finance.kobana.com.br/pt/pt/pessoas/.md), e é irreversível.** A confirmação é explícita — *"Esta ação não pode ser desfeita pela UI."* Os cadastros somem das telas, o histórico financeiro deles permanece, e o CPF/CNPJ é liberado. ## Buscar fotos[​](#buscar-fotos "Link direto para Buscar fotos") Ver [Pessoas](https://docs.finance.kobana.com.br/pt/pt/pessoas/.md) para como a foto é escolhida e onde aparece. Em resumo: **Gravatar primeiro, WhatsApp como fallback**, teto de 100 pessoas por execução, e quem falhou espera **30 dias** antes da próxima tentativa. ## Deduplicar lançamentos[​](#deduplicar-lançamentos "Link direto para Deduplicar lançamentos") Quando a mesma conta recebe o histórico do ERP **e** o extrato do banco — automático ou por arquivo OFX/QIF —, cada movimento pode ter entrado duas vezes — uma cópia classificada, vinda do ERP, e uma crua, vinda do extrato. As importações de hoje já reconhecem o mesmo movimento e não duplicam mais; esta ferramenta limpa o que entrou em dobro antes disso. Escolha a **conta** e clique em **"Procurar duplicados"**. A tela diz quantos lançamentos serão juntados e lista os pares: o que **fica** e o que **sai**, com a origem de cada um. **É o mesmo movimento** quando os dois estão na mesma conta, com a mesma direção, o mesmo valor e o mesmo dia, e os documentos (o código do banco) não se contradizem. **Fica a cópia do ERP**, com a descrição e a classificação que o financeiro fez. **A do extrato sai**, e antes passa para a que fica: * o vínculo com o banco — a próxima leitura do extrato encontra a linha que ficou e não cria outra; * o título pago ou recebido, a conciliação, os anexos e os itens da caixa de entrada; * o que a que fica não tinha: texto e código do banco, categoria, pessoa, centro, observação, rateios. observação **Um par em que os dois lados já estão ligados a coisas diferentes** — dois títulos, duas conciliações ou duas transferências — **fica de fora** e aparece marcado na lista. Escolher um perderia o outro; resolva esse à mão. perigo **A junção exclui o lançamento do extrato e não pode ser desfeita.** Confira os pares antes de confirmar. ## Apagar lançamentos de uma fonte[​](#apagar-lançamentos-de-uma-fonte "Link direto para Apagar lançamentos de uma fonte") Para recomeçar a importação de uma integração, ou limpar o que uma fonte gravou em dobro. Escolha a **fonte** (Fintera, Nibo, Conta Azul, Open Finance ou Gateway Bancário) e, se quiser, uma **conta** — sem conta, vale para a empresa toda — e clique em **"Procurar lançamentos"**. A tela diz quantos serão apagados, o período e quantos por conta. Um lançamento é da fonte quando veio dela. **Ficam, e a tela diz quantos:** * os que **também vieram de outra fonte** (o mesmo movimento reconhecido no extrato e no ERP): apagar levaria os dados da outra junto; * os **ligados a um título** (baixa), a uma **conciliação**, a uma **transferência**, a um **cartão** ou gerados por uma baixa. Cada um se desfaz pelo seu fluxo. O que é apagado leva junto a classificação e os anexos, e **não há como desfazer**. A exclusão **não impede** a integração de trazer os lançamentos de novo: na próxima leitura eles voltam, e é assim que se recomeça. Roda em lotes de 500, com o andamento na tela. ## E as configurações da conta?[​](#e-as-configurações-da-conta "Link direto para E as configurações da conta?") Não existe uma tela única de "Configurações" no produto — cada configuração tem o seu item no grupo **Sistema** do menu, como **Integrações**, **Segurança** e **Manutenção**. * Dados da sua conta e como o login funciona: [Meu perfil](https://docs.finance.kobana.com.br/pt/pt/meus-dados/.md). * Conexões com plataformas externas: [Integrações](https://docs.finance.kobana.com.br/pt/pt/integracoes/.md). * Regras anti-fraude para pagamentos e transferências: [Segurança](https://docs.finance.kobana.com.br/pt/pt/seguranca/.md). --- # Autenticação O servidor MCP aceita um **Bearer token** no cabeçalho `Authorization`, e nada além disso — sem cookie, sem certificado de cliente, **sem token na URL**. Uma requisição com `?access_token=` (ou `?token=`, `?api_key=` e afins) é recusada com `401` e `error="invalid_request"`, mesmo acompanhada de um cabeçalho válido: na URL o token vaza para logs, histórico do navegador e intermediários. Esse token é um **access token OAuth 2.1 emitido pelo authorization server da Kobana** (`https://account.kobana.com.br`), um JWT assinado em RS256 e emitido **para este recurso**: o `aud` dele é `https://mcp.finance.kobana.com.br`. Ele chega por um de dois caminhos — o fluxo OAuth, feito pelo próprio cliente, ou um **token pessoal** que você cria na sua Conta Kobana — e é verificado do mesmo jeito nos dois casos. ``` Authorization: Bearer eyJhbGciOiJSUzI1NiIs… ``` :::info Cada superfície tem a sua audience Um token emitido para o MCP **não vale** na API REST (`api.finance.*`), e um token da API não vale aqui. É o que impede que o token entregue a um assistente seja reaproveitado contra a API — e o contrário. ::: ## Dois jeitos de conectar[​](#dois-jeitos-de-conectar "Link direto para Dois jeitos de conectar") | | Fluxo OAuth | Token pessoal | | ------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Como você obtém | Cola a URL no cliente; ele abre o login da Kobana e você autoriza | Cria em **Conta Kobana → Tokens e Acesso → Novo Token Pessoal**: app **Financeiro Inteligente**, uso **MCP**, recursos e acessos, validade | | Como o cliente usa | Sozinho, depois da autorização | Você cola no cliente como `Authorization: Bearer ` | | Validade | Curta, renovada pelo cliente | De 7 dias a 1 ano, escolhida por você | | Escopo | Os recursos do Financeiro Inteligente e os níveis de acesso que você aprova, um a um, na tela de consentimento | Os recursos e acessos que você marcou | | Bom para | Claude, ChatGPT, IDEs e qualquer cliente com OAuth | Clientes sem suporte a OAuth e scripts | O token pessoal tem que ser criado com o uso **MCP**. Um token criado para **API REST** tem a audience da API e é recusado aqui com `401` — e o contrário também vale. ## O workspace[​](#o-workspace "Link direto para O workspace") O `org` do token diz a organização; o **workspace** em que cada tool age é decidido **a cada chamada**, nesta ordem: | Ordem | De onde vem | | ----- | --------------------------------------------------------- | | 1 | O argumento `workspace_id` da tool, quando vem na chamada | | 2 | O workspace padrão da conexão (abaixo) | | — | Nenhum dos dois: a tool volta o erro `workspace_required` | A URL do servidor não precisa de workspace — `https://mcp.finance.kobana.com.br` basta —, e conectar nunca falha por falta dele. Para saber onde pode agir, o agente chama `finance_workspaces_list`, sem argumentos: ela lista os workspaces da organização que a pessoa do token alcança. ``` { "data": [ { "id": "2b93f876-769a-4bdc-b23e-304957f313b4", "name": "Matriz", "default": true }, { "id": "7c1d0e52-…", "name": "Filial Sul", "default": false } ] } ``` Toda outra tool — menos `finance_me`, `finance_organization_get`/`_update` (de nível de organização: valem para a organização inteira), `finance_schemas_get` e a própria `finance_workspaces_list` — aceita o argumento opcional `workspace_id` (uuid): ``` { "name": "finance_payables_list", "arguments": { "workspace_id": "2b93f876-769a-4bdc-b23e-304957f313b4", "limit": 10 } } ``` ### O workspace padrão[​](#o-workspace-padrão "Link direto para O workspace padrão") É o que vale quando a chamada não traz `workspace_id`, e é o que vem marcado `default: true` em `finance_workspaces_list`: | Onde | Exemplo | | --------------------------------------- | -------------------------------------------------------------------- | | Cabeçalho `X-Workspace-Id` (opcional) | `X-Workspace-Id: 2b93f876-769a-4bdc-b23e-304957f313b4` | | Parâmetro na URL do servidor (opcional) | `https://mcp.finance.kobana.com.br/?workspace_id=2b93f876-…` | | Nenhum dos dois | O único workspace que a pessoa alcança, se ela alcança exatamente um | O cabeçalho e o parâmetro de URL continuam aceitos, mas agora são **opcionais e só definem o padrão**: o argumento `workspace_id` sempre ganha deles. Em qualquer caso o valor é **seletor, não concessão** — ele é conferido contra a organização do token e o acesso da pessoa: * Sem `workspace_id` e sem padrão — a pessoa alcança vários workspaces —, a tool volta `workspace_required`. É um resultado de tool com `isError: true`, não um erro HTTP: ``` { "error": { "code": "workspace_required", "message": "…" } } ``` * Um `workspace_id` que a pessoa não alcança, ou que não existe, volta o erro de tool `workspace_access_denied` — a mesma resposta nos dois casos. * Um cabeçalho ou parâmetro de URL com um workspace de outra organização continua recusado com HTTP `403` `UNKNOWN_WORKSPACE`. * Um padrão da conexão que é da organização, mas que a pessoa não alcança, não bloqueia nada: `tools/list` continua listando o que ela pode rodar em algum workspace, e uma chamada com um `workspace_id` válido roda. Só a chamada que depende desse padrão volta `workspace_access_denied`. Resources (`kobana://finance/…`) e completions não têm argumento de workspace: usam o padrão da conexão. Sem padrão, ler um resource de registro falha com `workspace_required` — use as tools —, e as completions não sugerem nada. Veja [Resources e prompts](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md). ## O fluxo OAuth[​](#o-fluxo-oauth "Link direto para O fluxo OAuth") Você não executa nenhum destes passos: o cliente MCP (Claude, ChatGPT, uma IDE) faz tudo sozinho a partir da URL. Eles estão aqui para quando algo falhar no meio. 1. **Desafio.** Uma requisição sem token recebe `401` com o desafio que todo resource server OAuth 2.1 deve mandar ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)): ``` WWW-Authenticate: Bearer realm="kobana-finance-mcp", error="invalid_token", resource_metadata="https://mcp.finance.kobana.com.br/.well-known/oauth-protected-resource" ``` 2. **Metadata do recurso.** O cliente lê o documento apontado. Ele é público e não carrega segredo nenhum — só ponteiros: ``` curl https://mcp.finance.kobana.com.br/.well-known/oauth-protected-resource ``` ``` { "resource": "https://mcp.finance.kobana.com.br", "authorization_servers": ["https://account.kobana.com.br"], "bearer_methods_supported": ["header"], "scopes_supported": [ "finance/accounts", "finance/ai_agents", "finance/ai_skills", "finance/attachments", "finance/automatic_rules", "finance/banks", "finance/cash_flow", "finance/categories", "finance/companies", "finance/cost_centers", "finance/custom_classifiers", "finance/fiscal_documents", "finance/payable_dispatches", "finance/payables", "finance/people", "finance/receipts", "finance/receivable_charges", "finance/receivables", "finance/reconciliations", "finance/settings", "finance/taxes", "finance/transactions", "read", "write", "delete", "import", "export", "all" ], "resource_documentation": "https://docs.finance.kobana.com.br/pt/mcp/overview/introduction", "resource_name": "Financeiro Inteligente", "kobana_scopes": { "finance/accounts": "Ver as contas financeiras", "finance/ai_agents": "Ver os agentes de IA", "finance/ai_skills": "Ver as habilidades de IA", "finance/attachments": "Ver os anexos", "finance/automatic_rules": "Ver as regras automáticas", "finance/banks": "Ver os bancos cadastrados", "finance/cash_flow": "Ver o fluxo de caixa", "finance/categories": "Ver as categorias", "finance/companies": "Ver as empresas", "finance/cost_centers": "Ver os centros de custo", "finance/custom_classifiers": "Ver os classificadores personalizados", "finance/fiscal_documents": "Ver os documentos fiscais", "finance/payable_dispatches": "Ver os envios de pagamento ao banco", "finance/payables": "Ver as contas a pagar", "finance/people": "Ver as pessoas (clientes e fornecedores)", "finance/receipts": "Ver os recibos", "finance/receivable_charges": "Ver as cobranças emitidas", "finance/receivables": "Ver as contas a receber", "finance/reconciliations": "Ver as conciliações", "finance/settings": "Ver as configurações da organização", "finance/taxes": "Ver os impostos", "finance/transactions": "Ver as transações", "finance/all": "Ver todos os dados do Financeiro Inteligente" } } ``` `scopes_supported` é exatamente o que o cliente pede na tela de consentimento: um `finance/{recurso}` por recurso do Financeiro Inteligente — os de dinheiro inclusive (`finance/payable_dispatches`, `finance/receivable_charges`) — e todo nível de acesso que a Conta Kobana emite: `read`, `write`, `delete`, `import` e `export`. Você decide, nível a nível, o que conceder. O token que o cliente recebe carrega os recursos aprovados, então são eles que definem o alcance (veja o eixo 1 abaixo). Fica de fora só o coringa de recurso, `finance/all` ou `all` (os dois são o mesmo). `resource_name` é o nome do produto e `kobana_scopes` dá, para cada escopo de recurso do Financeiro Inteligente (`finance/all` inclusive), o texto que a Conta Kobana mostra na tela de consentimento. O cliente MCP não precisa ler esses dois membros. 3. **Metadata do authorization server** ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)), em `https://account.kobana.com.br/.well-known/oauth-authorization-server`. 4. **Registro dinâmico do cliente** ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)). O cliente se registra sozinho; a tela de consentimento avisa que ele não é um app verificado. 5. **Autorização com PKCE e `resource`** ([RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707)). Você faz login na Kobana, escolhe a organização (se tiver mais de uma) e autoriza. 6. **Token.** O cliente troca o código por um access token de vida curta e passa a mandá-lo em toda requisição, renovando quando expira. O token carrega quem você é (`sub`) e a organização que você autorizou (`org`); o workspace vem de cada chamada, como acima. Nenhuma tool aceita organização como argumento. ## Dois eixos de autorização[​](#dois-eixos-de-autorização "Link direto para Dois eixos de autorização") O que um chamador vê é **mais estreito** que o catálogo, por dois filtros independentes. Nenhum dos dois pode *alargar* a superfície. ### Eixo 1 — o escopo do token[​](#eixo-1--o-escopo-do-token "Link direto para Eixo 1 — o escopo do token") O teto do cliente, no claim `scope`. Cada tool exige **um** nível de acesso — o mesmo que o endpoint da API que ela chama exige: leitura (tool de leitura, resource, prompt e completion) exige `read`; as tools de exclusão (`*_delete`) exigem `delete`; todo o resto que altera dados exige `write` — inclusive `finance_attachments_unlink`, que desfaz um vínculo e não apaga nada, e as tools que movem dinheiro. Um nível não substitui o outro: `write` não exclui, e `delete` não escreve. **Token com recursos** — o caso do token do fluxo OAuth e do token pessoal. Os recursos definem até onde o token chega, e os níveis valem só dentro deles: | Escopo do token | Resultado | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `finance/payables finance/people read write` | Lê e escreve contas a pagar e pessoas — não exclui, e não alcança mais nada | | `finance/payables read write delete` | Lê, escreve e exclui contas a pagar | | `finance/payables read` | Só lê contas a pagar | | `finance/all read` | Lê tudo, não escreve nada | | `finance/all write` | Lê e escreve tudo, inclusive enviar ao banco e cobrar (o coringa alcança os recursos de dinheiro) — mas não exclui | | `finance/payables finance/payable_dispatches read write` | Escreve contas a pagar e as envia ao banco — pelo MCP, só com um token de até 24 horas: veja [Mover dinheiro pelo MCP](#mover-dinheiro-pelo-mcp) | Enviar ao banco e cobrar são `write` no recurso próprio — `finance/payable_dispatches` e `finance/receivable_charges`; `finance/payables write` não basta. **Token sem recursos** — um token que só traz o nível de acesso, sem nenhum escopo `finance/…` nem `all` (ou só com recursos de outro app), **não alcança nada**: só a `finance_me` responde. `all` não é nível: é o coringa de recurso, como `finance/all` — sozinho só lê, e os verbos vêm explícitos (`all write`). :::info Clientes conectados pelo fluxo OAuth alcançam o que você aprovou O documento `/.well-known/oauth-protected-resource` anuncia todos os recursos do Financeiro Inteligente e todos os níveis de acesso, e é isso que o cliente (Claude, ChatGPT, o MCP Inspector, IDEs) pede na tela de consentimento; o token que ele recebe carrega os recursos e os níveis que você aprovou. O MCP lista só as tools que o token alcança; uma tool fora dele volta `insufficient_scope`, e a saída é autorizar de novo concedendo o acesso que faltou — `delete` para excluir, o recurso de dinheiro para enviar ao banco ou cobrar. ::: A mesma regra vale na API REST — veja [Escopos](https://docs.finance.kobana.com.br/pt/pt/api/overview/authentication.md#escopos). ### Eixo 2 — as permissões da pessoa do token[​](#eixo-2--as-permissões-da-pessoa-do-token "Link direto para Eixo 2 — as permissões da pessoa do token") O `sub` do token é a pessoa que consentiu. **No MCP, as tools são estreitadas para o que essa pessoa pode fazer no dashboard da organização**, resolvido a cada requisição — as mesmas funções e permissões da tela **Membros**. | Situação | Resultado | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | A pessoa nunca entrou no Financeiro Inteligente, ou não é membro da organização | **Nega todas as tools.** Quem não é membro não alcança nada pelo MCP. | | Membro ativo, com acesso ao workspace | As permissões dela, tool a tool. O dono (`*`) libera tudo; `payables.*` libera a família. | | Membro ativo **sem acesso ao workspace** | **Nega todas as tools** daquele workspace. | | Membro suspenso, com convite pendente, removido, ou sem permissão nenhuma | **Nega todas as tools.** Um token sobrevivendo ao acesso da pessoa é exatamente o caso a fechar. | | A consulta de permissões falha | **Nega todas as tools.** Falha fechada. | As permissões são lidas a cada chamada: tirar uma permissão no dashboard vale já na tool seguinte, sem esperar o token expirar. :::tip Postura recomendada para agentes Conecte o assistente com uma conta que só tem as permissões que o agente precisa, e, num token pessoal, marque só os recursos e acessos que ele vai usar. Os dois eixos se somam: o token de um analista somente-leitura expõe só as tools de leitura, faça o que fizer o modelo do outro lado. ::: ### Como os dois compõem[​](#como-os-dois-compõem "Link direto para Como os dois compõem") O conjunto final é a **interseção**: `tools ∩ escopos do token ∩ permissões da pessoa`. Uma tool que o chamador não pode rodar **não é listada**. Quando `tools/call` recusa, o código diz **quem resolve**: | Código | Quem resolve | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `insufficient_scope` | Usar um token que alcance o recurso com o acesso pedido — por exemplo, um token pessoal com escrita nesse recurso. | | `insufficient_permission` | Um admin da organização, concedendo a permissão (o erro nomeia qual). | | `workspace_required` | O agente passa `workspace_id` — um dos `id` de `finance_workspaces_list` —, ou a conexão define um [workspace padrão](#o-workspace-padr%C3%A3o). | | `workspace_access_denied` | Um admin concede o workspace à pessoa, ou o agente passa outro `workspace_id`. | | `membership_inactive` | Incluir a pessoa na organização ou reativá-la — nenhuma permissão conserta um vínculo que não existe ou está inativo. | | `token_not_accepted` | A tool move dinheiro e o token vive mais de 24 horas (todo token pessoal): conecte pelo fluxo OAuth, mova dinheiro pela API REST ou pelo app — veja [Mover dinheiro pelo MCP](#mover-dinheiro-pelo-mcp). Ou a chamada é destrutiva e o token foi verificado pela chave fixa provisória: conecte pelo fluxo OAuth ou com um token pessoal. | :::caution O que o eixo 2 não cobre O estreitamento por permissão vale **só para o MCP**. Um token da API, chamado direto em `api.finance.*`, continua limitado apenas pelos escopos. ::: ### Segurança › Canais[​](#segurança--canais "Link direto para Segurança › Canais") As regras da aba [Segurança › Canais](https://docs.finance.kobana.com.br/pt/pt/seguranca/.md#canais) continuam valendo por cima dos dois eixos — elas são aplicadas pelo próprio endpoint. Um agente de IA age pelo canal **MCP - Inteligência Artificial**, onde, por padrão, **enviar ao banco começa fechado**: `finance_payables_send_to_bank` só funciona depois que a solicitação for aprovada. **Cobrar** — emitir boleto ou Pix para um cliente — também começa fechado no MCP. E um título que o agente cria, ou cujo valor, favorecido, conta ou dados de pagamento ele altera, vai para a fila de **aprovação de pagamentos** mesmo com a aprovação desligada no workspace: uma instrução escondida numa nota ou num e-mail não vira pagamento oficial sem uma pessoa aprovar. ## Revogação do token pessoal[​](#revogação-do-token-pessoal "Link direto para Revogação do token pessoal") Revogar um token pessoal na sua Conta Kobana **não corta o acesso na hora**: o Financeiro Inteligente verifica o token sozinho, sem consultar a Kobana a cada chamada, e ele continua aceito até a validade dele. Por isso: * escolha a **validade mais curta** que o uso permite; * marque só os **recursos e acessos** de que o agente precisa; * para cortar um agente imediatamente, suspenda ou remova a pessoa na organização, ou tire o acesso dela ao workspace — as permissões são lidas a cada chamada e valem na hora. ### Mover dinheiro pelo MCP[​](#mover-dinheiro-pelo-mcp "Link direto para Mover dinheiro pelo MCP") Como a revogação não chega aqui antes da validade, as tools que movem dinheiro — `finance_payables_send_to_bank`, `finance_payables_cancel_dispatch`, `finance_receivables_charge` e `finance_receivables_charge_cancel` — só aparecem e só rodam com um token de **vida curta**: no máximo **24 horas** entre a emissão e a validade. Além disso elas exigem `write` no recurso de dinheiro (`finance/payable_dispatches`, `finance/receivable_charges`), ou o nível `write` num token sem escopos por recurso. Na prática: um cliente conectado pelo **fluxo OAuth** (token de vida curta, renovado pelo cliente) move dinheiro se você aprovou o recurso de dinheiro e `write` no consentimento — e cada chamada ainda passa pela confirmação do servidor e pelas regras de [Segurança › Canais](#seguran%C3%A7a--canais). Um **token pessoal** vale no mínimo 7 dias e nunca move dinheiro pelo MCP (a tool volta `token_not_accepted`): use o fluxo OAuth, a [API REST](https://docs.finance.kobana.com.br/pt/pt/api/overview/authentication.md#escopos) ou o app. ## Modos de falha[​](#modos-de-falha "Link direto para Modos de falha") | HTTP | `code` | Causa | | ---- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `-32022` (JSON-RPC) | Versão do protocolo não suportada, no cabeçalho `MCP-Protocol-Version` ou no `_meta`; `data.supported` lista as que são. Veja [Transporte](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/transport.md#vers%C3%B5es-do-protocolo). | | 401 | `invalid_token` / `token_expired` / `token_revoked` | Token ausente, malformado, inválido, emitido para outro recurso (a API, por exemplo) ou para mais de uma audience (`invalid_token`); expirado (`token_expired`); revogado (`token_revoked`). | | 401 | `invalid_request` | Credencial na URL (`?access_token=`, `?token=`, `?api_key=` e afins), mesmo com um cabeçalho válido. | | 403 | `UNKNOWN_ORGANIZATION` / `UNKNOWN_WORKSPACE` | O `org` do token não é um cliente, ou o workspace de `X-Workspace-Id` / `?workspace_id=` não é da organização. | | 403 | `ORGANIZATION_SUSPENDED` | A organização do token está suspensa ou inativa. Nada passa, nem leitura, até a Kobana reativá-la. | | 403 | `FORBIDDEN` | `Origin` fora da allowlist (`origin_not_allowed`). | | 404 | `NOT_FOUND` | A requisição chegou por um host que não serve MCP, ou pediu um caminho que não existe no servidor. | | 429 | `RATE_LIMITED` | Limite de requisições atingido — veja [Limite de requisições](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/rate-limit.md). | | 503 | `SERVICE_UNAVAILABLE` | A Conta Kobana não respondeu para validar o token. Não é problema do token: tente de novo depois do `Retry-After`. | Todo `401` carrega o desafio `WWW-Authenticate` acima, que manda o cliente de volta ao fluxo OAuth. No desafio, toda falha de token aparece como `error="invalid_token"` — é o `code` do corpo que distingue o token expirado do revogado —, e a credencial na URL como `error="invalid_request"`. Negativas de escopo e de permissão **não** são erros HTTP: elas voltam como resultado de tool marcado `isError`, para que o modelo leia e reaja — veja [Erros](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/errors.md). ## Host e borda[​](#host-e-borda "Link direto para Host e borda") O endpoint só é alcançável por `mcp.finance.*` — nunca pelo host do app nem pelo da API, que apontam para a mesma origin. Qualquer outro caminho responde `404`, sempre em JSON e para qualquer método — `{ "error": { "code": "NOT_FOUND", "message": "Not found." } }`, nunca uma página HTML. O identificador de recurso OAuth é derivado da **configuração do servidor**, nunca do `Host` da requisição, para que um `Host` forjado não consiga apontar um cliente para outro identificador. --- # Clientes Qualquer cliente que fale **Streamable HTTP** MCP e saiba fazer o fluxo **OAuth 2.1** do MCP consegue conectar. Você só informa a URL e o cliente descobre sozinho onde autenticar, abre o login da Kobana no navegador e guarda o token. Veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). Cliente sem suporte a OAuth também conecta, com um **token pessoal**: crie em **Conta Kobana → Tokens e Acesso → Novo Token Pessoal**, com o app **Financeiro Inteligente** e o uso **MCP**, e configure o cliente para mandá-lo no cabeçalho `Authorization: Bearer `. A URL não leva workspace. O agente escolhe onde agir a cada chamada: `finance_workspaces_list` lista os workspaces que você alcança, e as outras tools aceitam `workspace_id` (menos as de nível de organização, como `finance_me` e `finance_organization_get`/`_update`, que não levam workspace). Se você alcança um só, nem isso é preciso. Para fixar um **workspace padrão** na conexão, acrescente `?workspace_id=` à URL ou, quando o cliente deixa, o cabeçalho `X-Workspace-Id` — os dois são opcionais. Veja [Autenticação → O workspace](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md#o-workspace). ## Claude Code[​](#claude-code "Link direto para Claude Code") ``` claude mcp add --transport http kobana-finance https://mcp.finance.kobana.com.br ``` Depois, rode `/mcp` numa sessão e escolha **Authenticate** para fazer login na Kobana. Para definir um workspace padrão — opcional —, use a URL com ele: ``` claude mcp add --transport http kobana-finance \ "https://mcp.finance.kobana.com.br/?workspace_id=$WORKSPACE_ID" ``` Com um token pessoal, sem fluxo OAuth: ``` claude mcp add --transport http kobana-finance https://mcp.finance.kobana.com.br \ --header "Authorization: Bearer " ``` ## Clientes configurados por arquivo[​](#clientes-configurados-por-arquivo "Link direto para Clientes configurados por arquivo") Clientes que leem um arquivo JSON de configuração pedem a URL e o transporte. Pelo fluxo OAuth, não há cabeçalho de autenticação: ``` { "mcpServers": { "kobana-finance": { "type": "http", "url": "https://mcp.finance.kobana.com.br" } } } ``` Na primeira conexão o cliente abre o navegador para você autorizar. Você escolhe a organização na tela de consentimento, e ela fica gravada no token; o workspace vem de cada chamada (ou do padrão, se você puser `?workspace_id=` na URL). Com um token pessoal, acrescente os cabeçalhos — a organização é a da conta em que você criou o token: ``` { "mcpServers": { "kobana-finance": { "type": "http", "url": "https://mcp.finance.kobana.com.br", "headers": { "Authorization": "Bearer " } } } } ``` Para um workspace padrão, acrescente `"X-Workspace-Id": ""` aos `headers` — opcional. Trate o arquivo como segredo: quem o lê usa o token. ## Clientes que conectam por URL[​](#clientes-que-conectam-por-url "Link direto para Clientes que conectam por URL") Claude e ChatGPT conectam um servidor remoto colando a URL — `https://mcp.finance.kobana.com.br`, sem mais nada — nas configurações de conectores. O fluxo OAuth roda dentro do próprio app, e o assistente descobre os workspaces sozinho, com `finance_workspaces_list`. ## Usando o Faturamento junto[​](#usando-o-faturamento-junto "Link direto para Usando o Faturamento junto") As tools deste servidor começam com `finance_`, e as do [Faturamento Automático](https://docs.billing.kobana.com.br) com `billing_`; os resources, com `kobana://finance/` e `kobana://billing/`. Os dois servidores convivem no mesmo cliente sem colisão — conecte os dois quando o agente precisa das duas pontas. ## Postura recomendada para agentes[​](#postura-recomendada-para-agentes "Link direto para Postura recomendada para agentes") * **Autorize com a conta certa.** O MCP estreita as tools para o que a pessoa que autorizou pode fazer no dashboard. Um cliente autorizado por um analista somente-leitura expõe só as tools de leitura, faça o que fizer o modelo do outro lado. É a forma mais forte de restringir um agente. * **Um token por cliente.** Cada cliente faz o próprio fluxo e recebe o próprio token, que só vale no MCP — ele não serve para chamar a API REST. Para desligar um agente, remova a autorização dele na Kobana sem afetar as suas integrações. * **Token pessoal: validade curta e escopo mínimo.** Marque só os recursos e acessos de que o agente precisa, e a validade mais curta que o uso permite: revogar o token na Kobana não corta o acesso antes da validade — veja [Revogação do token pessoal](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md#revoga%C3%A7%C3%A3o-do-token-pessoal). Um agente que lança títulos não precisa de `finance/payable_dispatches`. Pelo MCP, nenhum token move dinheiro hoje — nem o pessoal, nem o do fluxo OAuth: veja [Mover dinheiro pelo MCP](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md#mover-dinheiro-pelo-mcp). * **Deixe o canal MCP fechado para pagar e cobrar.** Por padrão, a aba [Segurança › Canais](https://docs.finance.kobana.com.br/pt/pt/seguranca/.md#canais) não deixa agentes de IA enviarem ao banco nem emitirem cobrança. Abra só se for intencional. * **Comece no sandbox.** O servidor pede confirmação nas tools destrutivas, mas a primeira exploração não deve ser em produção. * **Tools destrutivas pedem um cliente que confirme.** Apagar, mandar ao banco, cobrar, transferir, conciliar ou ajustar saldo pede a sua aprovação: em qualquer cliente, a tool volta um link que você abre logado no Kobana Finance para escolher **Continuar** ou **Cancelar**. O resto funciona normalmente. Veja [Confirmação de tools destrutivas](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md#confirma%C3%A7%C3%A3o-de-tools-destrutivas). ## Verificando a conexão[​](#verificando-a-conexão "Link direto para Verificando a conexão") O jeito mais simples é pedir ao assistente: "em quais workspaces você pode agir?" — ele chama `finance_workspaces_list`. Depois, "quais empresas existem no workspace Matriz?" chama `finance_companies_list` com o `workspace_id` dele. Com um token emitido para o MCP — um token pessoal com uso **MCP**, por exemplo —, dá para conferir por `curl`: ``` # Quantas tools este token alcança? curl -s https://mcp.finance.kobana.com.br/ \ -H "Authorization: Bearer $MCP_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length' # Os workspaces que a pessoa do token alcança curl -s https://mcp.finance.kobana.com.br/ \ -H "Authorization: Bearer $MCP_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call", "params":{"name":"finance_workspaces_list","arguments":{}}}' # As empresas de um workspace curl -s https://mcp.finance.kobana.com.br/ \ -H "Authorization: Bearer $MCP_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call", "params":{"name":"finance_companies_list", "arguments":{"workspace_id":"'"$WORKSPACE_ID"'","fields":["name","cnpj"]}}}' ``` Se o número de tools for menor do que você esperava, são as permissões de quem autorizou ou o escopo do token — veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). Não é um erro. --- # Endpoints ## Servidor MCP[​](#servidor-mcp "Link direto para Servidor MCP") No mesmo domínio da API, com o prefixo `mcp`: | Ambiente | URL do servidor MCP | API REST | | -------- | ------------------------------------------- | ---------------------------------------------- | | Produção | `https://mcp.finance.kobana.com.br` | `https://api.finance.kobana.com.br/v1` | | Sandbox | `https://mcp.finance.sandbox.kobana.com.br` | `https://api.finance.sandbox.kobana.com.br/v1` | A URL do servidor é a **raiz do host** — é esse endereço que você cola num cliente MCP, sem mais nada: o workspace é escolhido a cada chamada, pelo argumento `workspace_id` das tools. `?workspace_id=` continua aceito, mas só define um workspace padrão para a conexão — veja [Autenticação → O workspace](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md#o-workspace). A raiz é também o *resource identifier* OAuth, e é por isso que não carrega caminho nenhum. ## Rotas servidas[​](#rotas-servidas "Link direto para Rotas servidas") | Método | Caminho | Para quê | | -------- | --------------------------------------- | --------------------------------------------------------------------- | | `POST` | `/` | Uma mensagem JSON-RPC por requisição. Toda a superfície de tools. | | `GET` | `/.well-known/oauth-protected-resource` | Metadata do recurso protegido (RFC 9728). Pública, sem autenticação. | | `GET` | `/` | `405` — este servidor é stateless e não abre stream servidor→cliente. | | `DELETE` | `/` | `204` — não há sessão para encerrar. | dica Cada ambiente tem banco e authorization server próprios: um token emitido em sandbox não vale em produção. Comece pelo sandbox: as tools destrutivas apagam títulos e mandam pagamentos ao banco de verdade. :::info Host separado, de propósito O servidor MCP tem host próprio em vez de um caminho no host da API ou do app. O documento de descoberta OAuth precisa morar na raiz do host, e nenhum cookie do dashboard é enviado para esta origin — o que elimina por construção uma classe inteira de problemas de *confused deputy*. ::: ## Desenvolvimento local[​](#desenvolvimento-local "Link direto para Desenvolvimento local") Em desenvolvimento o endpoint responde em `/mcp` no host do app (`http://localhost:3029/mcp`), e o documento de descoberta em `/.well-known/oauth-protected-resource`. Em sandbox e produção, fora de `mcp.finance.*`, o endpoint responde `404`. --- # Erros As falhas chegam por **dois canais diferentes**, e a distinção importa: um é requisição quebrada, o outro é algo que o modelo deve ler e reagir. ## Erros de tool[​](#erros-de-tool "Link direto para Erros de tool") Tudo sobre o que o chamador pode agir — validação, não encontrado, escopo ou permissão insuficiente, um erro do endpoint — volta como uma **resposta JSON-RPC bem-sucedida** cujo resultado está marcado `isError`, carregando o envelope de erro da própria API como texto: ``` { "jsonrpc": "2.0", "id": 2, "result": { "isError": true, "content": [{ "type": "text", "text": "{ \"error\": { \"code\": \"NOT_FOUND\", \"message\": \"Payable not found.\" } }" }] } } ``` O vocabulário de `code` é o [da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/errors.md), sem mudança. Os que você mais vai encontrar: | `code` | Quando | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `VALIDATION_ERROR` | O corpo falhou na validação do endpoint; `details.issues[]` nomeia cada campo. Também quando os argumentos da tool (id, filtros) não batem com o schema dela — inclusive `limit`, `cursor`, `sort_by` ou `fields` dentro de `filters`, que são argumentos nomeados; aí o `details` não traz `issues[]`, e sim `{ "formErrors": [...], "fieldErrors": { "": [...] } }` — `formErrors` para o que não é de um argumento só (um argumento desconhecido, por exemplo), `fieldErrors` por argumento. | | `BAD_REQUEST` | Filtro, operador ou campo de `fields` desconhecido. | | `NOT_FOUND` | Não existe esse registro, ou ele é de outro workspace. | | `CONFLICT` | Duplicidade, ou um registro ainda em uso. | | `UNPROCESSABLE_ENTITY` | Regra de negócio — apagar uma categoria que tem filhas, baixar um título sem conta. | | `SECURITY_BLOCKED` | A aba Segurança barrou a ação neste canal. | | `ENTITLEMENT_REQUIRED` | O espaço não tem plano contratado e a tool é de uso efetivo (enviar ao banco, emitir cobrança); `details.reason` diz `no_plan`. Contratar resolve, repetir não. | | `RATE_LIMITED` | O orçamento da API para esta pessoa na organização acabou — veja [Limite de requisições](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/rate-limit.md). | E os cinco que o próprio MCP acrescenta, porque são sobre *autorização*, não sobre o recurso: | `code` | Quem resolve | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `insufficient_scope` | O escopo do token não alcança a tool: o recurso não está no token, ou falta o nível de acesso que ela exige — `write` para alterar (mover dinheiro inclusive, no recurso de dinheiro), `delete` para excluir. Use um token que alcance o recurso com o acesso pedido: pelo fluxo OAuth, autorize de novo concedendo o acesso que faltou. | | `token_not_accepted` | O token não serve para esta tool: ela move dinheiro e o token vive mais de 24 horas (todo token pessoal) — mova dinheiro pela API REST ou pelo app —, ou a chamada é destrutiva e o token foi verificado pela chave fixa provisória — conecte pelo fluxo OAuth ou com um token pessoal. | | `insufficient_permission` | Um admin da organização, concedendo a permissão que o erro nomeia. | | `workspace_access_denied` | O `workspace_id` não é um que a pessoa alcança (ou não existe). Um admin concede o workspace à pessoa, ou o agente passa outro, de `finance_workspaces_list`. | | `membership_inactive` | Incluir a pessoa do token na organização ou reativá-la — nenhuma permissão conserta um vínculo que não existe ou está inativo. | São separados **de propósito**: cinco conversas diferentes, com pessoas diferentes. Um erro único diria "você não pode" sem dizer a quem pedir. Veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). Há também `workspace_required`: a chamada não trouxe `workspace_id` e a conexão não tem workspace padrão — a pessoa alcança vários. O agente chama `finance_workspaces_list` e repete a chamada com um dos `id`. Veja [Autenticação → O workspace](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md#o-workspace). E os da [confirmação de tools destrutivas](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md#confirma%C3%A7%C3%A3o-de-tools-destrutivas) — em todos eles, nada foi alterado: | `code` | Quando | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `confirmation_required` | Tool destrutiva chamada por um cliente que não pode confirmar e por um token sem pessoa por trás, que não teria quem abrisse o link de aprovação. Com uma pessoa, a tool volta o link (`status: approval_required`) — ver [Aprovação por link](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md#aprova%C3%A7%C3%A3o-por-link). | | `USER_DECLINED` | Na era `2026-07-28`, a pessoa recusou ou cancelou a confirmação. | | `confirmation_replayed` | A confirmação reenviada já rodou a tool uma vez. Chame de novo sem `requestState` para perguntar outra vez. | | `confirmation_unavailable` | O servidor não conseguiu garantir a confirmação naquele momento. Tente mais tarde. | | `confirmation_subject_unreadable` | A tool move dinheiro e a pergunta mostra o registro, mas a pessoa do token não pode lê-lo. Um admin concede a permissão de leitura que o erro nomeia. | ### `input_required` não é erro[​](#input_required-não-é-erro "Link direto para input_required-não-é-erro") Na era `2026-07-28`, o primeiro `tools/call` de uma tool destrutiva pode voltar `resultType: "input_required"` com um pedido de confirmação à pessoa. É o fluxo normal, não uma falha: o cliente mostra a pergunta e reenvia a mesma chamada com a resposta. Veja [Confirmação de tools destrutivas](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md#confirma%C3%A7%C3%A3o-de-tools-destrutivas). ## Erros de protocolo[​](#erros-de-protocolo "Link direto para Erros de protocolo") Uma mensagem malformada recebe um objeto de erro JSON-RPC, não um resultado: | Código | Significado | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `-32700` | Parse error — o corpo não é JSON válido | | `-32600` | Invalid request — não é um objeto JSON-RPC, ou é um array (batching não é suportado) | | `-32601` | Method not found | | `-32602` | Invalid params — tool, prompt ou argumento inexistente, `name` ausente; na era `2026-07-28`, também resource não encontrado | | `-32002` | Resource não encontrado — só na era 2025 (a `2026-07-28` usa `-32602`) | | `-32603` | Internal error — falha inesperada ao rodar a tool | | `-32020` | Header mismatch — na `2026-07-28`, um cabeçalho `MCP-Protocol-Version`, `Mcp-Method` ou `Mcp-Name` que não bate com o corpo (HTTP `400`) | | `-32022` | Unsupported protocol version — a versão pedida não é suportada; `data.supported` lista as que são (HTTP `400`) | ## Erros de transporte[​](#erros-de-transporte "Link direto para Erros de transporte") Recusas que acontecem **antes** da mensagem JSON-RPC ser lida são respostas HTTP comuns: token ausente, inválido, expirado, revogado ou emitido para outro recurso (`401`, com `code` `invalid_token`, `token_expired` ou `token_revoked`), credencial na URL (`401` `invalid_request`), workspace padrão (`X-Workspace-Id` / `?workspace_id=`) de outra organização, `Origin` fora da allowlist, limite de requisições do protocolo, Conta Kobana indisponível para validar o token (`503`), corpo acima de 14 MB (`413`, com o erro JSON-RPC `-32600` `Request body too large (limit 14680064 bytes)` e `id: null`). Estão listadas em [Autenticação → Modos de falha](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md#modos-de-falha). ## Por que `isError` e não erro JSON-RPC[​](#por-que-iserror-e-não-erro-json-rpc "Link direto para por-que-iserror-e-não-erro-json-rpc") Um `404` num título não é um defeito do cliente MCP — é informação sobre o mundo, e o modelo do outro lado precisa dela para se corrigir. Enterrá-la num erro de protocolo faria o cliente tratá-la como falha de transporte, esconder o texto e, no melhor caso, tentar de novo idêntico. Por isso a regra: **se o chamador pode agir, é resultado; se a requisição está quebrada, é erro.** ## Observabilidade[​](#observabilidade "Link direto para Observabilidade") Cada `tools/call` escreve uma linha estruturada com a tool, o workspace, a pessoa, o tipo do token (`oauth` ou `personal`), o status e a duração. As **escritas** ficam gravadas com o canal **`mcp`** e com a pessoa do token, então o que um agente fez aparece ao lado do que uma pessoa fez, nas mesmas telas. --- # Idempotência As tools de criação e alteração aceitam um argumento `idempotency_key`. Ele é enviado ao endpoint como o cabeçalho `X-Idempotency-Key` que a API REST já honra — veja [Idempotência](https://docs.finance.kobana.com.br/pt/pt/api/overview/idempotency.md) na API. ``` { "name": "finance_payables_create", "arguments": { "company_id": "…", "description": "Aluguel de novembro", "amount": 4500, "due_date": "2026-11-10T00:00:00Z", "person": { "name": "Imobiliária Centro" }, "idempotency_key": "7c4a8d09-ca37-4f21-b1f0-3d2f2b8c9a11" } } ``` | | | | --------------------------------- | ------------------------------------------------------------ | | **Formato** | String opaca, 1 a 255 caracteres. Um UUID é a escolha usual. | | **Repetição com o mesmo corpo** | Devolve a resposta original, sem rodar a operação de novo. | | **Repetição com corpo diferente** | Conflito (`IDEMPOTENCY_KEY_REUSED`). | Tools que apagam não aceitam o argumento: a rota não o lê, e apagar duas vezes já dá o mesmo resultado. ## Por que um agente precisa disto mais que o seu backend[​](#por-que-um-agente-precisa-disto-mais-que-o-seu-backend "Link direto para Por que um agente precisa disto mais que o seu backend") Um cliente MCP que dá timeout e tenta de novo, ou um modelo que decide "não tenho certeza se aquilo funcionou, vou refazer", é exatamente o padrão que cria o segundo título e o segundo lançamento. Seu backend tem um laço de retry que você escreveu; o agente tem um julgamento. **Mande uma chave sempre que a operação criar algo.** Uma chave nova é uma tentativa nova; para repetir com segurança, repita a mesma. ## As que movem dinheiro: a chave é obrigatória[​](#as-que-movem-dinheiro-a-chave-é-obrigatória "Link direto para As que movem dinheiro: a chave é obrigatória") Nestas quatro a chave **não é opcional** — a tool recusa a chamada sem ela, como a rota: | Tool | O que faz | | ----------------------------------- | -------------------------------------- | | `finance_payables_send_to_bank` | Manda o pagamento ao banco pela Kobana | | `finance_payables_cancel_dispatch` | Cancela o envio ao banco | | `finance_receivables_charge` | Emite boleto ou Pix para o cliente | | `finance_receivables_charge_cancel` | Cancela a cobrança | Um envio duplicado é um pagamento duplicado, e uma cobrança duplicada é uma dívida duplicada — nenhum `_delete` desfaz isso. São também tools **destructive**: o servidor só as roda depois de confirmar com a pessoa — veja [Confirmação de tools destrutivas](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md#confirma%C3%A7%C3%A3o-de-tools-destrutivas). --- # Introdução O **servidor MCP do Financeiro Inteligente** é um servidor [Model Context Protocol](https://modelcontextprotocol.io) remoto que expõe as operações da API pública — contas a pagar e a receber, lançamentos, conciliações, contas financeiras, fluxo de caixa e cadastros — como **tools** que um cliente de IA pode chamar. Você o conecta por URL; não há nada para instalar. Ele é servido em host próprio, `mcp.finance.kobana.com.br`, no mesmo domínio da API, com transporte **Streamable HTTP** em modo stateless e autenticação por **Bearer token** emitido para o MCP pela Conta Kobana. Nenhum certificado de cliente está envolvido. :::info Disponibilidade O servidor, suas **96 tools**, os resources e os prompts estão implementados, e a autenticação é pelo authorization server da Kobana: pelo fluxo **OAuth 2.1**, em que o cliente recebe só a URL e faz o login sozinho, ou por um **token pessoal** criado na sua Conta Kobana. O endpoint é servido pela borda dedicada `mcp.finance.*`, com distribution, WAF e DNS próprios. ::: ## Quando usar[​](#quando-usar "Link direto para Quando usar") | | API REST (`/v1`) | Servidor MCP (este) | | ------------ | --------------------------------------- | -------------------------------------------------------------------------------- | | Consumidor | seu backend | um cliente de IA (Claude, ChatGPT, uma IDE) | | Configuração | token e `X-Workspace-Id`, fora de banda | só uma URL; o workspace vai em cada chamada | | Transporte | HTTPS/REST | Streamable HTTP (JSON-RPC 2.0) | | Autenticação | Bearer token emitido para a API | OAuth 2.1 ou token pessoal, sempre emitido para o MCP | | Autorização | escopo do token | escopo do token **e** permissões da pessoa | | Superfície | os endpoints de `/v1` | 96 tools, uma por operação desses endpoints, mais resources e prompts sobre elas | O servidor MCP **não substitui** a API REST. Cada tool despacha in-process para o endpoint que implementa a operação, então filtros, validação, regras de baixa, rateio e isolamento por workspace são exatamente os mesmos. Se você está escrevendo código, use a [API REST](https://docs.finance.kobana.com.br/pt/pt/api/overview/introduction.md). Se está conectando um assistente, use isto. ## O princípio[​](#o-princípio "Link direto para O princípio") **Uma capability só existe no MCP se existir na API pública.** Não há uma segunda implementação de nada. A tool chama o handler do endpoint com a identidade que o token do chamador já provou — a mesma pessoa, a mesma organização, o mesmo workspace —, então ele roda, confere o escopo e audita como faria para qualquer requisição HTTP. Uma tool faz o que o endpoint faz por REST — nunca mais. A consequência prática: o que hoje só existe no dashboard (aprovar pagamentos, importar extratos, gerenciar membros) não vira tool antes de virar endpoint. ## O que você vê é mais estreito que o catálogo[​](#o-que-você-vê-é-mais-estreito-que-o-catálogo "Link direto para O que você vê é mais estreito que o catálogo") `tools/list` devolve apenas as tools que **este chamador pode rodar**: as que os escopos do token alcançam **e** que a pessoa do token tem permissão de fazer na organização. Um agente não é informado de capacidades que só levariam negativa. Os dois eixos estão em [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). ## Primeiros passos[​](#primeiros-passos "Link direto para Primeiros passos") 1. **Aponte seu cliente para a URL do servidor** — `https://mcp.finance.kobana.com.br`, sem mais nada. Veja [Endpoints](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/endpoints.md) e [Clientes](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/clients.md). 2. **Autorize.** O cliente abre o login da Kobana; entre com uma conta da organização e autorize o acesso. Veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). 3. **Escolha o workspace.** O agente chama `finance_workspaces_list` e passa o `id` escolhido como `workspace_id` nas outras tools. Se você alcança um workspace só, ele é o padrão e o argumento é dispensável. Veja [Autenticação → O workspace](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md#o-workspace). 4. **Liste as tools** para confirmar o que o seu acesso alcança — peça ao assistente, ou, com um token emitido para o MCP em mãos: ``` curl https://mcp.finance.kobana.com.br/ \ -H "Authorization: Bearer $MCP_TOKEN" \ -H "Content-Type: application/json" \ -H "MCP-Protocol-Version: 2025-06-18" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }' ``` 5. **Explore o catálogo** em [Tools](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/overview.md). ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md) — o fluxo OAuth, o token pessoal, o workspace, o escopo e as permissões aplicados, e os modos de falha. * [Endpoints](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/endpoints.md) — URLs por ambiente e rotas servidas. * [Transporte](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/transport.md) — JSON-RPC, cabeçalhos e métodos. * [Clientes](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/clients.md) — como conectar Claude Code e clientes por arquivo. * [Listagem, filtros e campos](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/pagination.md) — `cursor`, `filters`, `sort_by`, `fields`. * [Idempotência](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/idempotency.md) — e as ações que movem dinheiro. * [Resources e prompts](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md) — documentos por URI, roteiros prontos, autocomplete e a confirmação de tools destrutivas. * [Erros](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/errors.md) — os dois canais de falha, e por que a distinção importa. * [Tools](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/overview.md) — o catálogo completo. --- # Listagem, Filtros e Campos As tools `*_list` usam a mesma paginação da API REST: **por cursor**. | Argumento | Padrão | Máximo | | --------- | ------ | --------------------------------- | | `limit` | `25` | `100` (`10000` nas tools `*_ids`) | | `cursor` | — | — | ``` { "name": "finance_payables_list", "arguments": { "limit": 50 } } ``` O resultado traz o envelope de sempre: ``` { "data": [ /* ... */ ], "meta": { "next_cursor": "eyJpZCI6Mn0" } } ``` Para a próxima página, mande o `meta.next_cursor` como `cursor`, **com os mesmos filtros**. `next_cursor: null` significa que esta é a última página. Veja [Listagem e paginação](https://docs.finance.kobana.com.br/pt/pt/api/overview/pagination.md) na API. ## Filtros[​](#filtros "Link direto para Filtros") `filters` é um objeto com **exatamente** os filtros que a listagem aceita — o `inputSchema` da tool os enumera, com os operadores de cada um. Um filtro ou operador fora da lista é recusado antes de chegar ao endpoint. Paginação, ordenação e colunas (`limit`, `cursor`, `sort_by`, `sort_order`, `fields` — e `page`, `per_page` e `sort`, de outras APIs) são **argumentos nomeados**: dentro de `filters` são recusados com `VALIDATION_ERROR`, que nomeia as chaves, e nunca sobrescrevem o argumento. | Forma | Significa | Vira | | --------------------------------------------------------- | ---------- | --------------------------------- | | `"status": "pending"` | igual a | `?status=pending` | | `"status": ["pending", "paid"]` | está em | `?status[in]=pending,paid` | | `"due_date": { "gte": "2026-11-01", "lt": "2026-12-01" }` | operadores | `?due_date[gte]=…&due_date[lt]=…` | ``` { "name": "finance_payables_list", "arguments": { "filters": { "company_id": "…", "status": "pending", "due_date": { "lte": "2026-11-30" } }, "sort_by": "due_date", "sort_order": "asc" } } ``` A gramática completa está em [Filtros e ordenação](https://docs.finance.kobana.com.br/pt/pt/api/overview/filtering.md). ## Ordenação[​](#ordenação "Link direto para Ordenação") | Argumento | Valores | Padrão | | ------------ | ------------------------------------------------------------- | ----------------- | | `sort_by` | Uma das colunas que a listagem ordena (o `inputSchema` lista) | varia por recurso | | `sort_order` | `asc` ou `desc` | `asc` | ## Campos (`fields`)[​](#campos-fields "Link direto para campos-fields") As tools de leitura de registro aceitam `fields`, um array de nomes de coluna. Omitido, volta o registro inteiro; informado, volta só aquilo: ``` { "name": "finance_payables_list", "arguments": { "filters": { "status": "pending" }, "fields": ["description", "amount", "due_date"] } } ``` | Regra | Por quê | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **`id` sempre volta** | Uma projeção que você não consegue seguir não serve para nada, e derrubar o `id` em silêncio quebraria a chamada seguinte, não esta. | | **Só o nível de cima** | `fields: ["reconciliation"]` devolve o objeto inteiro; não há sintaxe `reconciliation.kind`. | | **Só em leitura de registro** | Escritas devolvem o registro inteiro; totais, `*_ids` e download não oferecem o argumento. | | **Nome desconhecido é erro** | `400` com `details.unknown` e `details.available`. Ignorar devolveria menos campos que o pedido, com cara de que o registro não os tem. | É o mesmo [`?fields=` da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/fields.md). E é a forma mais barata de reduzir o contexto que um agente gasta. ## `finance_schemas_get` — o catálogo de campos[​](#finance_schemas_get--o-catálogo-de-campos "Link direto para finance_schemas_get--o-catálogo-de-campos") `fields` só serve se você souber o que pedir. `finance_schemas_get` responde com os schemas do contrato publicado: ``` { "name": "finance_schemas_get", "arguments": {} } { "name": "finance_schemas_get", "arguments": { "schema": "PayableV1" } } ``` Sem argumento, devolve o catálogo; com `schema`, os campos daquele schema — nome, tipo, enum, se aceita nulo e descrição. É o mesmo OpenAPI que gera a [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/introduction.md). ## Contrato de dados[​](#contrato-de-dados "Link direto para Contrato de dados") O que vale para a API vale aqui, porque é o mesmo código: * **snake\_case em tudo**, argumentos e respostas. * **Dinheiro é número em BRL**, com até 2 casas: `1500.5` é R$ 1.500,50. Títulos e lançamentos são sempre positivos — a direção vem do tipo, não do sinal. * **Datas em ISO 8601.** * **Escritas aceitam `idempotency_key`** — veja [Idempotência](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/idempotency.md). --- # Limite de Requisições O servidor MCP gasta **os mesmos limites da API REST**, contados **por pessoa na organização** — não por token —, mais um limite próprio para o protocolo. Gerar um token novo, ou reautorizar o cliente, não zera o orçamento. | Orçamento | O que conta | Limite (produção) | | ------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | | Protocolo MCP | toda requisição a `/` (`initialize`, `tools/list`, `ping`, `tools/call`) | 1000/hora por pessoa na organização | | Leituras da API | cada `tools/call` de uma tool **read** | o mesmo da [API](https://docs.finance.kobana.com.br/pt/pt/api/overview/rate-limit.md) | | Escritas da API | cada `tools/call` de uma tool **write** ou **destructive** | o mesmo da [API](https://docs.finance.kobana.com.br/pt/pt/api/overview/rate-limit.md) | | Ações que movem dinheiro | `send_to_bank`, `cancel_dispatch`, `charge`, `charge_cancel` | o mesmo da [API](https://docs.finance.kobana.com.br/pt/pt/api/overview/rate-limit.md) | Uma chamada de tool **nunca é mais barata que o endpoint que ela espelha**: ela é contada no orçamento do protocolo e, de novo, no orçamento da API que a mesma chamada REST gastaria — com o mesmo tamanho de orçamento da API, por pessoa. Um agente que varre listagens em laço não contorna o limite que a mesma varredura pagaria por REST. Há também um teto por IP, bem acima de qualquer uso legítimo. ## Quando o limite é atingido[​](#quando-o-limite-é-atingido "Link direto para Quando o limite é atingido") **No protocolo**, o servidor responde `429` e a mensagem JSON-RPC não chega a ser processada: ``` HTTP/1.1 429 Too Many Requests Retry-After: 37 Content-Type: application/json { "error": { "code": "RATE_LIMITED", "message": "MCP request rate limit exceeded for this person in this organization." } } ``` **No orçamento da API**, a tool devolve um resultado com erro, para o modelo ler e esperar: ``` { "isError": true, "content": [{ "type": "text", "text": "{ \"error\": { \"code\": \"RATE_LIMITED\", \"details\": { \"retry_after_seconds\": 37 } } }" }] } ``` Nos dois casos, espere os segundos indicados antes de tentar de novo. ## Gastando menos[​](#gastando-menos "Link direto para Gastando menos") Um agente consome o mesmo orçamento que o seu backend — e, nas leituras, esse orçamento é pequeno. Três hábitos resolvem quase tudo: * **Filtre antes de paginar.** `finance_payables_list { filters: { status: "pending", due_date: { lte: "2026-11-30" } } }` custa uma chamada; trazer tudo para filtrar no modelo custa dezenas. * **Use os totais prontos.** "Quanto vence este mês" é uma chamada de `finance_payables_aggregates`, não uma varredura de `finance_payables_list`. * **Peça só as colunas que interessam.** `fields` não reduz o número de chamadas, mas reduz muito o contexto gasto — veja [Listagem, filtros e campos](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/pagination.md). --- # Resources e prompts Além das tools, o servidor oferece três coisas que o **cliente** usa por conta própria: **resources** (documentos que você anexa à conversa), **prompts** (roteiros prontos que você escolhe) e **completions** (autocomplete dos argumentos dos dois). Na era `2026-07-28`, ele também pede **confirmação** antes de rodar uma tool destrutiva — inclusive as que movem dinheiro. Nada disso abre um caminho novo até os seus dados: tudo passa pelas mesmas tools, sob as mesmas permissões e o mesmo [nível de acesso](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). Todo resource e todo prompt daqui só lê, então um token `read` alcança todos eles — desde que a pessoa possa rodar as tools por trás. ## Resources[​](#resources "Link direto para Resources") Um resource é um documento identificado por uma URI. Você escolhe, por exemplo, uma conta a pagar, e o cliente lê o registro e o põe no contexto, sem que o modelo precise chamar uma tool. As URIs ficam sob `kobana://finance/`, então convivem com as de outros produtos Kobana no mesmo cliente. | URI | O que volta | | ------------------------------------------------------------------ | ---------------------------------------------------------- | | `kobana://finance/schemas` | O catálogo de schemas do contrato da API (JSON) | | `kobana://finance/schemas/{schema}` | Um schema: os campos que uma tool devolve ou aceita (JSON) | | `kobana://finance/payables/{id}` | Uma conta a pagar (JSON) | | `kobana://finance/receivables/{id}` | Uma conta a receber (JSON) | | `kobana://finance/financial-transactions/{id}` | Um lançamento (JSON) | | `kobana://finance/financial-accounts/{account_id}` | Uma conta financeira (JSON) | | `kobana://finance/financial-accounts/{account_id}/balances/latest` | O saldo registrado mais recente da conta (JSON) | | `kobana://finance/people/{id}` | Uma pessoa — fornecedor, cliente ou os dois (JSON) | | `kobana://finance/companies/{id}` | Uma empresa do workspace (JSON) | | `kobana://finance/fiscal-documents/{id}` | Um documento fiscal recebido (JSON) | | `kobana://finance/attachments/{attachment_id}` | Os dados de um anexo e a que ele está vinculado (JSON) | | `kobana://finance/attachments/{attachment_id}/download` | O arquivo do anexo — comprovante, boleto, XML | `resources/list` traz as URIs fixas e `resources/templates/list` os templates com parâmetro. * **Permissões.** Cada resource é lido pela tool correspondente (`kobana://finance/payables/{id}` é `finance_payables_get`). Ele só aparece, e só é lido, se você pode rodar essa tool. * **Arquivos.** O arquivo de um anexo volta como bytes em base64 (`blob`), ou como texto quando é texto (um XML), até **10 MB**. Diferente da tool, que só descreve o arquivo, aqui o documento é a resposta: foi o cliente que pediu por ele. * **Não encontrado.** URI desconhecida, ou registro que não existe neste workspace, é `-32002` na era 2025 e `-32602` na `2026-07-28` — veja [Erros](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/errors.md). * **Workspace.** A URI não carrega workspace: o resource é lido no [workspace padrão da conexão](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md#o-workspace-padr%C3%A3o). Sem padrão — a pessoa alcança vários workspaces e a conexão não fixou um —, ler um resource de registro falha com o erro JSON-RPC `-32602`, com `data.code: "workspace_required"` e uma dica; use as tools, que aceitam `workspace_id`. O catálogo de schemas não depende de workspace. * **Sem assinatura de mudanças.** O servidor é stateless: não há `resources/subscribe` nem aviso de lista alterada. ## Prompts[​](#prompts "Link direto para Prompts") Um prompt é uma instrução pronta que você escolhe no cliente e que vira a primeira mensagem da conversa. Ele só aparece se você pode rodar **todas** as tools em que se apoia. Nenhum deles move dinheiro, edita ou apaga: mandar ao banco ou cobrar fica para você pedir explicitamente. | Prompt | Argumentos | O que faz | | --------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------- | | `overdue_payables` | `company_id` (opcional) | Lista as contas a pagar vencidas e ainda em aberto, da mais antiga, com o total devido. | | `overdue_receivables` | `person_id` (opcional) | Lista as contas a receber vencidas e agrupa por cliente, maiores totais primeiro. | | `cash_flow_outlook` | `until` (opcional, `YYYY-MM-DD`; padrão: 90 dias) | O saldo de hoje e para onde o caixa vai, semana a semana, com o ponto mais baixo. | | `monthly_summary` | `month` (opcional, `YYYY-MM`) | O que foi pago, recebido e ficou em aberto no mês. | | `person_overview` | `person_id` | Um fornecedor ou cliente: os dados e o que está em aberto de cada lado. | Argumento obrigatório ausente, ou `month`/`until` fora do formato, é `-32602`. ## Completions[​](#completions "Link direto para Completions") `completion/complete` sugere valores enquanto você digita um argumento: * **Ids** (`person_id`, `company_id`, `account_id` e o parâmetro dos templates de registro): os registros mais recentes da listagem correspondente, pelo prefixo digitado, sob a mesma permissão dela. Se você não pode listar, não há sugestão. Os registros saem do workspace padrão da conexão; sem padrão, a lista volta vazia. * **`{schema}` de `kobana://finance/schemas/{schema}`**: os nomes do contrato, pelo prefixo. * **`month`**: os últimos doze meses. Sem fonte de sugestão, a resposta é uma lista vazia, e você continua digitando. ## Confirmação de tools destrutivas[​](#confirmação-de-tools-destrutivas "Link direto para Confirmação de tools destrutivas") Tools que apagam, cancelam, mandam pagamento ao banco, cobram, transferem entre contas, conciliam ou ajustam saldo são marcadas com `destructiveHint`. O cliente pode ou não pedir confirmação por causa disso — então o **servidor** exige a sua aprovação, e uma tool destrutiva só roda com ela. Em toda revisão do protocolo e em qualquer cliente, a tool destrutiva volta um **link de aprovação** (veja [Aprovação por link](#aprova%C3%A7%C3%A3o-por-link)) — mesmo num cliente que declare elicitation de formulário, porque há clientes que a declaram e nunca mostram o formulário, e a chamada ficaria parada sem nada registrado. A pergunta na conversa é só o caminho de reserva de quando não há aprovação a gravar (um token sem pessoa por trás) e o cliente fala a `2026-07-28` com elicitation de formulário: 1. O primeiro `tools/call` não roda nada. Ele volta `resultType: "input_required"` com um formulário de uma pergunta: rodar esta ação, com estes argumentos? 2. O cliente mostra a pergunta e reenvia a mesma chamada com a sua resposta. 3. Só um **sim** explícito executa. Recusar ou cancelar volta um resultado `isError` com `USER_DECLINED`, e nada muda. Duas tools são destrutivas só conforme os argumentos: `finance_payables_update` pede confirmação quando a chamada muda o `status` para `paid` ou `cancelled`, e `finance_receivables_update` quando o muda para `received` ou `cancelled`. As duas são anunciadas com `destructiveHint`, mas qualquer outra alteração por elas roda sem pergunta. Nas tools que movem dinheiro, a pergunta mostra **o registro em que a ação age**, lido pelo servidor: valor, vencimento, favorecido, chave Pix, conta bancária, código de barras. Se o título mudar entre a pergunta e o **sim** — a chave Pix trocada, por exemplo —, o sim não vale e o servidor pergunta de novo, com os dados novos. Se a pessoa do token não puder ler o registro, a tool volta `confirmation_subject_unreadable` e nada roda. A confirmação protege contra um agente enganado por texto de terceiros — uma instrução escondida numa descrição ou num e-mail. Ela **não** substitui o escopo, a validade do token, as permissões e a aba Canais: quem tem o token pode escrever um cliente que responde sim sozinho. A confirmação vale **só para aquela chamada** e **uma vez só**: a mesma tool, os mesmos argumentos, a mesma pessoa, organização e workspace, por **5 minutos**. Uma resposta não pode ser reaproveitada para outro título ou outra ação; se algo não bater, o servidor simplesmente pergunta de novo. Reenviar uma confirmação que já rodou a tool volta `confirmation_replayed` — para repetir a ação, chame a tool de novo sem `requestState` e confirme outra vez. **Sem aprovação nem pergunta possível, a tool não roda.** Sem pessoa por trás do token não há quem abra o link, e o servidor só consegue perguntar na era `2026-07-28`, a clientes que declaram suporte a formulários de elicitation (`elicitation: {}` ou `elicitation: { form: {} }` nas `clientCapabilities`). Fora disso, um `tools/call` de tool destrutiva volta `isError` com `confirmation_required` e nada é alterado — leituras e escritas comuns continuam rodando. Se o próprio servidor não puder garantir a confirmação naquele momento, a resposta é `confirmation_unavailable`, também sem alterar nada. ## Aprovação por link[​](#aprovação-por-link "Link direto para Aprovação por link") É o caminho de toda tool destrutiva chamada por um token com pessoa, em qualquer revisão e em qualquer cliente — com ou sem elicitation de formulário. A tool destrutiva **não roda**: o servidor grava a operação como pendente e responde, como resultado normal (sem `isError`), um texto JSON: ``` { "status": "approval_required", "approval": { "id": "…", "url": "https://app.finance.kobana.com.br/approvals/…", "expires_at": "2026-11-01T12:15:00.000Z" }, "message": "… show them this URL … Do not call the tool again." } ``` O assistente mostra a URL. Você a abre **logado no Kobana Finance** (sem login, o app pede o login e volta para ela), confere o que vai acontecer — valor, favorecido, conta de origem e saldo nas tools de dinheiro, o registro afetado nas demais e todos os argumentos — e escolhe: * **Continuar**: a operação roda na hora, uma vez só, com os argumentos gravados e as **suas permissões de agora**. Se você perdeu a permissão nesse meio-tempo, ou o acesso do aplicativo foi revogado, ela falha e nada muda. * **Cancelar**: nada roda. O link vale **15 minutos** e decide **uma vez só**. Só você o abre: para qualquer outra pessoa, mesmo da sua organização, ele não existe. As suas aprovações ficam em **Sistema › Aprovações**; clicar numa delas abre o que foi pedido, só para leitura. ### Consultar o resultado[​](#consultar-o-resultado "Link direto para Consultar o resultado") O assistente não é avisado quando você decide. Depois que você disser que decidiu, ele consulta o resultado com `finance_operation_approvals_get`, passando o `approval.id` da resposta — uma vez, sem ficar repetindo a chamada. `finance_operation_approvals_list` lista as suas aprovações no workspace da chamada, mais recentes primeiro (`status`, `created_after`, `created_before`, `page`, `per_page`; volta `{ data, meta: { total, page, per_page, total_pages } }`). ``` { "data": { "id": "…", "status": "executed", "action": "finance_categories_delete", "title": "Excluir a categoria", "resource": "categories", "operation": "delete", "amount": null, "requested_at": "2026-11-01T12:00:00.000Z", "expires_at": "2026-11-01T12:15:00.000Z", "decided_at": "2026-11-01T12:03:10.000Z", "executed_at": "2026-11-01T12:03:11.000Z", "error": null, "result": { "data": { "id": "…", "deleted": true } }, "result_hidden": false } } ``` * `status`: `pending`, `approved` (confirmada, em processamento), `executed`, `failed`, `declined` (cancelada) ou `expired` — a pendente que passou do prazo já sai como `expired`. * `title`: o que a operação faz, no idioma do cabeçalho `Accept-Language` da conexão (português, inglês ou espanhol; sem ele, português). * `error`: `{ code, message }` quando `failed`. `result`: o retorno da operação quando `executed`, com segredos (tokens, chaves, senhas) mascarados — o valor em claro aparece uma vez só, na tela. * Nunca voltam o link, o token do link nem os argumentos. Qualquer token com uma pessoa por trás e algum escopo de recurso do Financeiro (`finance/…` ou `all`) consulta as **próprias** aprovações; não há escopo de recurso nem permissão próprios. Mas `error`, `result` e o valor lido do registro são dado do recurso da operação: só saem quando o token lê esse recurso e você **ainda** tem permissão de ler esse recurso no workspace (quem perdeu a permissão depois da operação deixa de ver o retorno) (por exemplo, `finance/categories` com `read` para a exclusão de uma categoria; nas operações de dinheiro — mandar ao banco, cobrar — o recurso de dinheiro e o do título juntos: `finance/payable_dispatches` com `finance/payables`, `finance/receivable_charges` com `finance/receivables`). Sem isso, a aprovação vem com a situação, o título e as datas, `error` e `result` em `null` e `"result_hidden": true`; o valor que o próprio assistente mandou nos argumentos continua aparecendo. Aprovação de outra pessoa, de outra organização, de outro workspace ou um id que não existe voltam o mesmo `NOT_FOUND`. As duas tools só leem: nenhuma aprova, cancela ou reabre nada. Um token sem pessoa por trás não tem quem abra o link e continua recebendo `confirmation_required`. --- # Transporte **Streamable HTTP, stateless.** Uma mensagem JSON-RPC 2.0 por `POST`, uma resposta JSON. Não há `Mcp-Session-Id`, não há resumabilidade e não há stream servidor→cliente: a aplicação roda várias réplicas, e nenhuma operação precisa empurrar mensagens para o cliente. ## Versões do protocolo[​](#versões-do-protocolo "Link direto para Versões do protocolo") O servidor fala duas eras do protocolo no mesmo endpoint: | Versão | Era | Status | | ------------ | ------------------------------------------------------------------------------ | --------- | | `2026-07-28` | Stateless, sem handshake — descoberta por `server/discover` | Suportada | | `2025-06-18` | Handshake por `initialize` — é a versão em que o `initialize` fecha por padrão | Suportada | | `2025-03-26` | Handshake por `initialize` | Suportada | A era é decidida **pelo corpo** da requisição, com os cabeçalhos como conferência: * **`params._meta` traz `io.modelcontextprotocol/protocolVersion`** → era `2026-07-28` (veja abaixo). * **Sem esse envelope**, com `MCP-Protocol-Version` de 2025 ou sem o cabeçalho → era 2025, com `initialize`. * **`MCP-Protocol-Version: 2026-07-28` sem o envelope** → `400` com `-32602`. O servidor não cai para a era antiga em silêncio: você pediu a semântica stateless e receberia a outra. Uma versão que o servidor não fala — no cabeçalho ou no envelope, em qualquer era — é respondida com `400` e o erro JSON-RPC `-32022`, listando as suportadas: ``` { "jsonrpc": "2.0", "id": 1, "error": { "code": -32022, "message": "Unsupported protocol version", "data": { "supported": ["2026-07-28", "2025-06-18", "2025-03-26"], "requested": "1999-01-01" } } } ``` A versão em uso volta no cabeçalho `MCP-Protocol-Version` da resposta. ### Era `2026-07-28`[​](#era-2026-07-28 "Link direto para era-2026-07-28") Não há handshake: **toda** requisição carrega a própria versão e as capacidades do cliente em `params._meta`, e o servidor não lembra nada entre uma requisição e outra. | Chave de `params._meta` | Obrigatória | Significado | | -------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `io.modelcontextprotocol/protocolVersion` | sim | `2026-07-28` | | `io.modelcontextprotocol/clientCapabilities` | sim | Capacidades do cliente (um objeto; `{}` serve). As tools destrutivas voltam um link de aprovação com ou sem `elicitation` de formulário — veja [confirmação de tools destrutivas](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md#confirma%C3%A7%C3%A3o-de-tools-destrutivas) | | `io.modelcontextprotocol/clientInfo` | recomendada | `name` e `version` do cliente | Os cabeçalhos repetem o que está no corpo, para que intermediários possam rotear sem lê-lo — e por isso têm que concordar com ele: | Cabeçalho | Tem que ser igual a | | ---------------------- | --------------------------------------------------------------- | | `MCP-Protocol-Version` | A versão do envelope | | `Mcp-Method` | O `method` da mensagem | | `Mcp-Name` | Só no `tools/call`: o `params.name`, cru ou como `=?base64?…?=` | Qualquer divergência é `400` com `-32020` (`Header mismatch: …`). Faltar `clientCapabilities` é `400` com `-32602`. Os resultados dessa era sempre trazem `resultType: "complete"` e o servidor em `_meta["io.modelcontextprotocol/serverInfo"]`. `server/discover`, `tools/list`, `resources/list`, `resources/templates/list`, `resources/read` e `prompts/list` trazem também `ttlMs: 0` e `cacheScope: "private"`: o que volta é filtrado pelo escopo e pelas permissões de quem chama, então não deve ser reaproveitado nem compartilhado. Um `tools/call` de tool destrutiva pode voltar `resultType: "input_required"` — veja [Confirmação de tools destrutivas](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md#confirma%C3%A7%C3%A3o-de-tools-destrutivas). ## Cabeçalhos da requisição[​](#cabeçalhos-da-requisição "Link direto para Cabeçalhos da requisição") | Cabeçalho | Obrigatório | Significado | | ---------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | sim | `Bearer ` emitido para o MCP — veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md) | | `X-Workspace-Id` | não | Workspace padrão da conexão, usado quando a tool não recebe `workspace_id` — o mesmo que `?workspace_id=` na URL. Veja [Autenticação → O workspace](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md#o-workspace) | | `Content-Type` | sim | `application/json` | | `Accept` | recomendado | `application/json` | | `MCP-Protocol-Version` | sim na era `2026-07-28`; recomendado na de 2025 | Revisão do protocolo | | `Mcp-Method` | sim na era `2026-07-28` | O método da mensagem | | `Mcp-Name` | sim no `tools/call` da era `2026-07-28` | O nome da tool | | `Origin` | condicional | Mandado por clientes de navegador; validado contra uma allowlist | ## Cabeçalhos da resposta[​](#cabeçalhos-da-resposta "Link direto para Cabeçalhos da resposta") | Cabeçalho | Significado | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MCP-Protocol-Version` | Revisão em uso | | `Cache-Control` | `no-store` em toda resposta, inclusive as de erro (`400`, `401`, `403`, `404`, `405`, `413`, `429`, `503`) e o `204` do `DELETE`. Só o documento `/.well-known/oauth-protected-resource`, público e igual para todos, usa `public, max-age=300` | | `Content-Security-Policy` | `default-src 'none'` em toda resposta, inclusive a do documento de metadata — o servidor só devolve JSON | | `Retry-After` | Em `429` — veja [Limite de requisições](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/rate-limit.md) — e em `503` | ## Métodos[​](#métodos "Link direto para Métodos") | Método | Era `2026-07-28` | Era 2025 | Para quê | | -------------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------ | | `server/discover` | sim | — | Versões suportadas, capacidades do servidor e instruções | | `initialize` | — | sim | Negociação de versão, capacidades do servidor e instruções | | `ping` | — | sim | Teste de vida; responde um resultado vazio | | `tools/list` | sim | sim | As tools que este chamador pode rodar, com JSON Schema e anotações | | `tools/call` | sim | sim | Roda uma tool | | `resources/list` | sim | sim | Os documentos de URI fixa que este chamador pode ler | | `resources/templates/list` | sim | sim | Os templates de URI (`kobana://finance/payables/{id}`, …) que este chamador pode ler | | `resources/read` | sim | sim | Lê um documento pela URI | | `prompts/list` | sim | sim | Os roteiros prontos que este chamador pode usar | | `prompts/get` | sim | sim | Monta um roteiro com os argumentos dados | | `completion/complete` | sim | sim | Sugestões para um argumento de prompt ou de template | Resources, prompts e completions estão em [Resources e prompts](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md). Qualquer outro método é `-32601 Method not found` — na era `2026-07-28`, com HTTP `404`; na de 2025, no corpo de um `200`. **Batching JSON-RPC não é suportado** — foi removido na revisão `2025-06-18`, e um corpo em array é respondido com `400`. **O corpo tem teto de 14 MB** (14.680.064 bytes) — o bastante para o maior pedido legítimo, um `finance_attachments_upload` de 10 MB em base64 com o envelope. Acima disso a resposta é `413` com `{ "jsonrpc": "2.0", "id": null, "error": { "code": -32600, "message": "Request body too large (limit 14680064 bytes)" } }`: um `Content-Length` declarado acima do teto é recusado antes mesmo da autenticação, e um corpo sem `Content-Length` (ou que mente nele) é cortado no teto durante a leitura. Uma **notificação** (mensagem sem `id`, como `notifications/initialized`) é aceita com `202` e corpo vazio, nas duas eras. A autenticação vem **antes** de qualquer método, inclusive do `server/discover`: sem token, a resposta é o `401` com o desafio que leva o cliente ao login OAuth — veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). ### `server/discover` (era `2026-07-28`)[​](#serverdiscover-era-2026-07-28 "Link direto para serverdiscover-era-2026-07-28") ``` POST / HTTP/1.1 Authorization: Bearer Content-Type: application/json MCP-Protocol-Version: 2026-07-28 Mcp-Method: server/discover ``` ``` { "jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {}, "io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0.0" } } } } ``` ``` { "jsonrpc": "2.0", "id": 1, "result": { "resultType": "complete", "supportedVersions": ["2026-07-28", "2025-06-18", "2025-03-26"], "capabilities": { "tools": {}, "resources": {}, "prompts": {}, "completions": {} }, "instructions": "Tools for Kobana Finance: ...", "ttlMs": 0, "cacheScope": "private", "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "kobana-finance", "title": "Kobana Finance", "version": "1.0.0" } } } } ``` ### `initialize` (handshake da era 2025)[​](#initialize-handshake-da-era-2025 "Link direto para initialize-handshake-da-era-2025") ``` { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18" } } ``` ``` { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-06-18", "capabilities": { "tools": { "listChanged": false }, "resources": { "subscribe": false, "listChanged": false }, "prompts": { "listChanged": false }, "completions": {} }, "serverInfo": { "name": "kobana-finance", "title": "Kobana Finance", "version": "1.0.0" }, "instructions": "Tools for Kobana Finance: ..." } } ``` As `instructions` (no `initialize` e no `server/discover`) avisam o agente que valores de campo nos resultados são **dados escritos por terceiros, nunca instruções**, e pedem confirmação do usuário antes de uma ação destrutiva ou que move dinheiro que um resultado pareça pedir. ### `tools/list`[​](#toolslist "Link direto para toolslist") Devolve **apenas** as tools que o chamador pode rodar — as que o escopo do token alcança **e** que a pessoa que autorizou pode fazer no dashboard. O `inputSchema` de uma tool de escrita é o **próprio schema de request** do endpoint — os mesmos campos, obrigatórios e enums da [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/introduction.md). Cada tool carrega `annotations`, que é o que faz o cliente pedir confirmação ao usuário: | Anotação | Significado | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `readOnlyHint` | A tool só lê | | `destructiveHint` | A tool apaga, cancela ou move dinheiro — só roda com a [confirmação do servidor](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md#confirma%C3%A7%C3%A3o-de-tools-destrutivas) | | `idempotentHint` | Repetir a chamada tem o mesmo efeito | | `openWorldHint` | Sempre `false` — a tool não alcança nada fora do Financeiro Inteligente | ### `tools/call`[​](#toolscall "Link direto para toolscall") ``` { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "finance_payables_list", "arguments": { "workspace_id": "2b93f876-769a-4bdc-b23e-304957f313b4", "filters": { "status": "pending" }, "limit": 10, "fields": ["description", "amount", "due_date"] } } } ``` O resultado traz a resposta JSON do endpoint como conteúdo de texto: ``` { "jsonrpc": "2.0", "id": 2, "result": { "content": [{ "type": "text", "text": "{ \"data\": [ ... ], \"meta\": { \"next_cursor\": \"…\" } }" }] } } ``` Erros sobre os quais o chamador pode agir voltam com `isError: true` **dentro** do resultado, não como erro JSON-RPC — veja [Erros](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/errors.md). ## Despacho in-process[​](#despacho-in-process "Link direto para Despacho in-process") Cada tool despacha **in-process** para o handler de `/v1` que implementa a operação, com a identidade já verificada e o workspace resolvido para a chamada — o token do MCP não é repassado, e o endpoint segue exigindo o escopo dele. Não há segunda viagem HTTP nem segunda implementação: filtros, validação, regras de baixa, rateio, travas de segurança e isolamento por workspace são o mesmo código que a API REST roda. As escritas ficam registradas com o canal **`mcp`** (`created_via` / `updated_via`), distinguíveis das feitas pela API ou pelo dashboard. ## Arquivos[​](#arquivos "Link direto para Arquivos") * **Download** — `finance_attachments_download` **não** devolve os bytes: um PDF em base64 no contexto de um modelo é caro e inútil. O resultado traz o `content_type`, o tamanho e o caminho para baixar o arquivo na API — com um token emitido para a API, já que o do MCP não vale lá. * **Upload** — `finance_attachments_upload` recebe o arquivo em `content_base64` (até 10 MB) e o envia ao endpoint como `multipart/form-data`. Depois, `finance_attachments_link` o anexa a um título ou lançamento. --- # Contas financeiras e fluxo de caixa As contas financeiras, o saldo calculado e os saldos observados de cada fonte, o catálogo de bancos, a projeção do fluxo de caixa e os cartões de crédito com suas faturas, lançamentos e recorrências e as alíquotas de IOF. ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | -------------------------------------------------- | ----- | ---- | ----- | ----------- | | `financial_accounts` — Contas financeiras e saldos | 10 | 4 | 3 | 3 | | `banks` — Bancos | 1 | 1 | 0 | 0 | | `cash_flow` — Fluxo de caixa | 1 | 1 | 0 | 0 | | `credit_cards` — Cartões de crédito | 5 | 2 | 2 | 1 | | `card_statements` — Faturas do cartão | 9 | 3 | 2 | 4 | | `card_transactions` — Lançamentos do cartão | 8 | 3 | 3 | 2 | | `card_recurrences` — Recorrências do cartão | 5 | 2 | 2 | 1 | | `iof_rates` — Alíquotas de IOF | 1 | 1 | 0 | 0 | ## `financial_accounts`[​](#financial_accounts "Link direto para financial_accounts") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | -------------------------------------------- | ----------- | -------- | ------------------ | ------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `finance_financial_accounts_list` | read | `read` | `finance/accounts` | `accounts.list` | `GET /v1/financial-accounts` | List financial accounts (bank accounts, cash, cards…). | | `finance_financial_accounts_get` | read | `read` | `finance/accounts` | `accounts.show` | `GET /v1/financial-accounts/{account_id}` | Fetch one financial account with its computed `balance` (live, from posted transactions). | | `finance_financial_accounts_create` | write | `write` | `finance/accounts` | `accounts.create` | `POST /v1/financial-accounts` | Create a financial account. | | `finance_financial_accounts_update` | write | `write` | `finance/accounts` | `accounts.update` | `PATCH /v1/financial-accounts/{account_id}` | Partially update a financial account. | | `finance_financial_accounts_delete` | destructive | `delete` | `finance/accounts` | `accounts.delete` | `DELETE /v1/financial-accounts/{account_id}` | Delete a financial account. | | `finance_financial_accounts_adjust_balance` | destructive | `write` | `finance/accounts` | `accounts.adjust-balance` | `POST /v1/financial-accounts/{account_id}/adjust-balance` | Correct the account's computed balance to `target_balance` by inserting an adjustment transaction for the difference. | | `finance_financial_accounts_balances_list` | read | `read` | `finance/accounts` | `accounts.show` | `GET /v1/financial-accounts/{account_id}/balances` | List the recorded balance observations of an account (bank-reported, manual, calculated), newest `capture_date` first. | | `finance_financial_accounts_balances_latest` | read | `read` | `finance/accounts` | `accounts.show` | `GET /v1/financial-accounts/{account_id}/balances/latest` | The most recent balance observation of every source, one row per source. | | `finance_financial_accounts_balances_create` | write | `write` | `finance/accounts` | `accounts.update` | `POST /v1/financial-accounts/{account_id}/balances` | Record a balance observation for an account (e.g. | | `finance_financial_accounts_balances_delete` | destructive | `delete` | `finance/accounts` | `accounts.update` | `DELETE /v1/financial-accounts/{account_id}/balances/{balance_id}` | Delete a balance observation. | ## `banks`[​](#banks "Link direto para banks") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | -------------------- | ---- | ------ | --------------- | ----------- | --------------- | ----------------------------------------------------------------------------------------- | | `finance_banks_list` | read | `read` | `finance/banks` | — (nenhuma) | `GET /v1/banks` | The Brazilian bank catalog (COMPE/BACEN codes) — use it to find `bank_id` for an account. | ## `cash_flow`[​](#cash_flow "Link direto para cash_flow") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ----------------------- | ---- | ------ | ------------------- | ---------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `finance_cash_flow_get` | read | `read` | `finance/cash_flow` | `cash-flow.show` | `GET /v1/cash-flow` | Cash-flow projection of the workspace between `from` and `to`, bucketed by `granularity`, optionally narrowed to one company or account. | ## `credit_cards`[​](#credit_cards "Link direto para credit_cards") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ----------------------------- | ----------- | ------- | ---------------------- | --------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `finance_credit_cards_list` | read | `read` | `finance/credit_cards` | `credit-cards.list` | `GET /v1/credit-cards` | List the credit, prepaid and benefit cards, with limit used and the statement in progress. | | `finance_credit_cards_get` | read | `read` | `finance/credit_cards` | `credit-cards.show` | `GET /v1/credit-cards/{card_id}` | Fetch one card: cycle (closing and due day), limit, paying account and IOF settings. | | `finance_credit_cards_create` | write | `write` | `finance/credit_cards` | `credit-cards.create` | `POST /v1/credit-cards` | Create a card and its statements. | | `finance_credit_cards_update` | write | `write` | `finance/credit_cards` | `credit-cards.update` | `PATCH /v1/credit-cards/{card_id}` | Partially update a card (limit, paying account, cycle days, defaults, status, start date). | | `finance_credit_cards_top_up` | destructive | `write` | `finance/credit_cards` | `card-statements.pay` | `POST /v1/credit-cards/{card_id}/top-ups` | Top up a prepaid or benefit card: a transfer from a bank account to the card's account, shown as a credit in the open statement. | ## `card_statements`[​](#card_statements "Link direto para card_statements") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ----------------------------------------- | ----------- | -------- | ---------------------- | ------------------------ | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_card_statements_list` | read | `read` | `finance/credit_cards` | `credit-cards.show` | `GET /v1/credit-cards/{card_id}/statements` | List a card's statements (closed, open and future), with cutoff, due date and expected total. | | `finance_card_statements_get` | read | `read` | `finance/credit_cards` | `credit-cards.show` | `GET /v1/card-statements/{statement_id}` | Fetch one card statement with its period, cutoff, due date and totals. | | `finance_card_statements_cutoff_update` | write | `write` | `finance/credit_cards` | `card-statements.update` | `PATCH /v1/card-statements/{statement_id}/cutoff` | Set the real cutoff of an open or future statement, as the issuer's app shows it. | | `finance_card_statements_close` | destructive | `write` | `finance/credit_cards` | `card-statements.close` | `POST /v1/card-statements/{statement_id}/close` | Close an open statement now, as the daily job does the day after the cutoff, and open the next one. | | `finance_card_statements_review` | write | `write` | `finance/credit_cards` | `card-statements.update` | `POST /v1/card-statements/{statement_id}/review` | Record the total of the issuer's real statement on a closed statement. | | `finance_card_statements_reopen` | destructive | `write` | `finance/credit_cards` | `card-statements.close` | `POST /v1/card-statements/{statement_id}/reopen` | Reopen a closed, reviewed, paid or partially paid statement so its cutoff and launches can change again. | | `finance_card_statements_pay` | destructive | `write` | `finance/credit_cards` | `card-statements.pay` | `POST /v1/card-statements/{statement_id}/payments` | Pay a closed or reviewed statement: a transfer from the paying account to the card's account settles its payable. | | `finance_card_statements_payments_delete` | destructive | `delete` | `finance/credit_cards` | `card-statements.pay` | `DELETE /v1/card-statements/{statement_id}/payments` | Undo a statement's payment: the transfer is deleted, the payable goes back to pending and the carried-over balance is removed. | | `finance_card_statements_events_list` | read | `read` | `finance/credit_cards` | `credit-cards.show` | `GET /v1/card-statements/{statement_id}/events` | List a card statement's history (cutoff changes with the launches they moved, closing, review, reopening, payment), oldest first, with who did it. | ## `card_transactions`[​](#card_transactions "Link direto para card_transactions") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | -------------------------------------- | ----------- | -------- | ---------------------- | -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_card_transactions_list` | read | `read` | `finance/credit_cards` | `credit-cards.show` | `GET /v1/card-transactions` | List card launches (purchases, installments, refunds, fees) filtered by card, statement, group, date or category. | | `finance_card_transactions_aggregates` | read | `read` | `finance/credit_cards` | `credit-cards.show` | `GET /v1/card-transactions/aggregates` | Totals of card launches — count, total, base without IOF and `sum_iof_amount` — optionally by card, statement, category, supplier or month. | | `finance_card_transactions_get` | read | `read` | `finance/credit_cards` | `credit-cards.show` | `GET /v1/card-transactions/{transaction_id}` | Fetch one card launch with its statement, IOF, exchange rate, installment and rateio. | | `finance_card_transactions_create` | write | `write` | `finance/credit_cards` | `card-transactions.create` | `POST /v1/card-transactions` | Launch a purchase, installment purchase, refund or fee on a card. | | `finance_card_transactions_update` | write | `write` | `finance/credit_cards` | `card-transactions.update` | `PATCH /v1/card-transactions/{transaction_id}` | Partially update a card launch; scope extends the change to the next installments or the whole series. | | `finance_card_transactions_delete` | destructive | `delete` | `finance/credit_cards` | `card-transactions.delete` | `DELETE /v1/card-transactions/{transaction_id}` | Delete a card launch and its mirror in the card's account; scope extends it to the next installments or the whole series. | | `finance_card_transactions_move` | write | `write` | `finance/credit_cards` | `card-transactions.update` | `POST /v1/card-transactions/{transaction_id}/move` | Move one card launch to another open or future statement of the same card; it stays there on later cutoff changes. | | `finance_card_transactions_anticipate` | destructive | `write` | `finance/credit_cards` | `card-transactions.update` | `POST /v1/card-transactions/{transaction_id}/anticipate` | Anticipate the remaining installments of a purchase into the open statement, with an optional discount launched as a refund. | ## `card_recurrences`[​](#card_recurrences "Link direto para card_recurrences") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | --------------------------------- | ----------- | -------- | ---------------------- | -------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_card_recurrences_list` | read | `read` | `finance/credit_cards` | `credit-cards.show` | `GET /v1/card-recurrences` | List a card's recurring charges (subscriptions) with the next charge, the last confirmed amount, its deviation and the suggested new amount. | | `finance_card_recurrences_get` | read | `read` | `finance/credit_cards` | `credit-cards.show` | `GET /v1/card-recurrences/{recurrence_id}` | Fetch one card recurrence: amount and currency, charge day, frequency, validity and the deviation of the last occurrence. | | `finance_card_recurrences_create` | write | `write` | `finance/credit_cards` | `card-transactions.create` | `POST /v1/card-recurrences` | Create a recurring charge on a card; it forecasts one expected launch in each open or future statement. | | `finance_card_recurrences_update` | write | `write` | `finance/credit_cards` | `card-transactions.update` | `PATCH /v1/card-recurrences/{recurrence_id}` | Partially update a card recurrence; its untouched forecasts follow. | | `finance_card_recurrences_delete` | destructive | `delete` | `finance/credit_cards` | `card-transactions.delete` | `DELETE /v1/card-recurrences/{recurrence_id}` | Delete a card recurrence and its forecasts. | ## `iof_rates`[​](#iof_rates "Link direto para iof_rates") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ------------------------ | ---- | ------ | ---------------------- | ----------- | ------------------- | ------------------------------------------------------------------------------- | | `finance_iof_rates_list` | read | `read` | `finance/credit_cards` | — (nenhuma) | `GET /v1/iof-rates` | List the IOF rates with their validity (global and this workspace's overrides). | *** Os campos de cada recurso estão na [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/introduction.md) e em `finance_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Contas a pagar e a receber Os títulos: criar, alterar, baixar, cancelar e apagar contas a pagar e a receber, os totais por período, mandar um pagamento ao banco e emitir uma cobrança (boleto ou Pix). ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | -------------------------------- | ----- | ---- | ----- | ----------- | | `payables` — Contas a pagar | 10 | 4 | 1 | 5 | | `receivables` — Contas a receber | 10 | 4 | 1 | 5 | ## `payables`[​](#payables "Link direto para payables") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ---------------------------------- | ------------- | -------- | ---------------------------- | ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `finance_payables_list` | read | `read` | `finance/payables` | `payables.list` | `GET /v1/payables` | List payables (contas a pagar), cursor-paginated. | | `finance_payables_get` | read | `read` | `finance/payables` | `payables.show` | `GET /v1/payables/{id}` | Fetch one payable with its rateio (`cost_center_allocations`), tax charges, custom classifications and reconciliation group. | | `finance_payables_aggregates` | read | `read` | `finance/payables` | `payables.list` | `GET /v1/payables/aggregates` | Totals of payables (pending, paid, overdue…) for a period (`month`+`year` or `start_date`+`end_date`) and optionally one company. | | `finance_payables_ids` | read | `read` | `finance/payables` | `payables.list` | `GET /v1/payables/ids` | The id of every live payable, for reconciling a mirror: an id that stops appearing was deleted. | | `finance_payables_create` | write | `write` | `finance/payables` | `payables.create` | `POST /v1/payables` | Create a payable. | | `finance_payables_update` | destructive\* | `write` | `finance/payables` | `payables.update` | `PATCH /v1/payables/{id}` | Partially update a payable. | | `finance_payables_settle_batch` | destructive | `write` | `finance/payables` | `payables.update` | `POST /v1/payables/settle-batch` | Mark many payables as paid at once (up to 100) with ONE confirmation, instead of one per `finance_payables_update`. | | `finance_payables_delete` | destructive | `delete` | `finance/payables` | `payables.delete` | `DELETE /v1/payables/{id}` | Delete a payable. | | `finance_payables_send_to_bank` | destructive | `write` | `finance/payable_dispatches` | `payables.dispatch` | `POST /v1/payables/{id}/send-to-bank` | MOVES MONEY: dispatch an approved payable to the bank through Kobana. | | `finance_payables_cancel_dispatch` | destructive | `write` | `finance/payable_dispatches` | `payables.dispatch` | `POST /v1/payables/{id}/cancel-dispatch` | Cancel a payable's bank dispatch on the Kobana side. | ## `receivables`[​](#receivables "Link direto para receivables") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ----------------------------------- | ------------- | -------- | ---------------------------- | -------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `finance_receivables_list` | read | `read` | `finance/receivables` | `receivables.list` | `GET /v1/receivables` | List receivables (contas a receber), cursor-paginated. | | `finance_receivables_get` | read | `read` | `finance/receivables` | `receivables.show` | `GET /v1/receivables/{id}` | Fetch one receivable with its rateio, tax charges, custom classifications, charge state and reconciliation group. | | `finance_receivables_aggregates` | read | `read` | `finance/receivables` | `receivables.list` | `GET /v1/receivables/aggregates` | Totals of receivables (pending, received, overdue…) for a period (`month`+`year` or `start_date`+`end_date`) and optionally one company. | | `finance_receivables_ids` | read | `read` | `finance/receivables` | `receivables.list` | `GET /v1/receivables/ids` | The id of every live receivable, for reconciling a mirror. | | `finance_receivables_create` | write | `write` | `finance/receivables` | `receivables.create` | `POST /v1/receivables` | Create a receivable. | | `finance_receivables_update` | destructive\* | `write` | `finance/receivables` | `receivables.update` | `PATCH /v1/receivables/{id}` | Partially update a receivable. | | `finance_receivables_settle_batch` | destructive | `write` | `finance/receivables` | `receivables.update` | `POST /v1/receivables/settle-batch` | Settle many receivables as received at once (up to 100) with ONE confirmation, instead of one per `finance_receivables_update`. | | `finance_receivables_delete` | destructive | `delete` | `finance/receivables` | `receivables.delete` | `DELETE /v1/receivables/{id}` | Delete a receivable. | | `finance_receivables_charge` | destructive | `write` | `finance/receivable_charges` | `receivables.charge` | `POST /v1/receivables/{id}/charge` | ASKS A CUSTOMER FOR MONEY: issue a bank slip or Pix charge for the receivable through Kobana. | | `finance_receivables_charge_cancel` | destructive | `write` | `finance/receivable_charges` | `receivables.charge` | `POST /v1/receivables/{id}/charge/cancel` | Cancel the receivable's charge on the gateway. | *** Os campos de cada recurso estão na [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/introduction.md) e em `finance_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Anexos, notas fiscais, schemas e espaços Os arquivos anexados aos registros, as notas fiscais recebidas, `finance_schemas_get`, o catálogo dos campos que cada tool devolve — o que pedir em `fields` —, e `finance_workspaces_list`, os espaços de onde sai o `workspace_id` das outras tools — e `finance_me`, a identidade por trás do token da conexão — e `finance_organization_get`/`_update`, a organização do token — e `finance_operation_approvals_get`/`_list`, o resultado das operações que você aprovou pelo link. ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | -------------------------------------------- | ----- | ---- | ----- | ----------- | | `attachments` — Anexos | 7 | 3 | 2 | 2 | | `fiscal_documents` — Notas fiscais recebidas | 2 | 2 | 0 | 0 | | `schemas` — Catálogo de campos | 1 | 1 | 0 | 0 | | `workspaces` — Espaços | 1 | 1 | 0 | 0 | | `me` — Identidade | 1 | 1 | 0 | 0 | | `organization` — Organização | 2 | 1 | 1 | 0 | | `operation_approvals` — Aprovações por link | 2 | 2 | 0 | 0 | ## `attachments`[​](#attachments "Link direto para attachments") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ------------------------------ | ----------- | -------- | --------------------- | ---------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `finance_attachments_list` | read | `read` | `finance/attachments` | `attachments.list` | `GET /v1/attachments` | List attachments (metadata only). | | `finance_attachments_get` | read | `read` | `finance/attachments` | `attachments.list` | `GET /v1/attachments/{attachment_id}` | Fetch one attachment's metadata, including `download_url`. | | `finance_attachments_download` | read | `read` | `finance/attachments` | `attachments.download` | `GET /v1/attachments/{attachment_id}/download` | Locate an attachment's bytes. | | `finance_attachments_upload` | write | `write` | `finance/attachments` | `attachments.create` | `POST /v1/attachments` | Upload a file (pdf, png, jpg, xml, ofx, csv, xlsx; max 10 MB) as an attachment. | | `finance_attachments_delete` | destructive | `delete` | `finance/attachments` | `attachments.delete` | `DELETE /v1/attachments/{attachment_id}` | Delete an attachment (file and metadata). | | `finance_attachments_link` | write | `write` | `finance/attachments` | `attachments.update` | `POST /v1/attachments/{attachment_id}/links` | Attach the file to a payable, receivable or transaction: `type` names the kind of record and `id` its id. | | `finance_attachments_unlink` | destructive | `write` | `finance/attachments` | `attachments.update` | `POST /v1/attachments/{attachment_id}/unlink` | Detach the file from a payable, receivable or transaction (`type` + `id` of the record). | ## `fiscal_documents`[​](#fiscal_documents "Link direto para fiscal_documents") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ------------------------------- | ---- | ------ | -------------------------- | ----------------------- | ------------------------------- | ---------------------------------------------------------------------------------- | | `finance_fiscal_documents_list` | read | `read` | `finance/fiscal_documents` | `fiscal-documents.list` | `GET /v1/fiscal-documents` | List received fiscal documents (NF-e / NFS-e issued to the workspace's companies). | | `finance_fiscal_documents_get` | read | `read` | `finance/fiscal_documents` | `fiscal-documents.show` | `GET /v1/fiscal-documents/{id}` | Fetch one received fiscal document. | ## `schemas`[​](#schemas "Link direto para schemas") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | --------------------- | ---- | ------ | ------ | ----------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `finance_schemas_get` | read | `read` | — | — (nenhuma) | — (local) | Describe a schema of the Finance API contract: the fields a tool returns (`PayableDetailV1`, `FinancialTransactionV1`…) or accepts. | ## `workspaces`[​](#workspaces "Link direto para workspaces") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ------------------------- | ---- | ------ | ------ | ----------- | --------- | -------------------------------------------------------- | | `finance_workspaces_list` | read | `read` | — | — (nenhuma) | — (local) | List the workspaces of this organization you can act on. | ## `me`[​](#me "Link direto para me") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ------------ | ---- | ----- | ------ | ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_me` | read | — | — | — (nenhuma) | — (local) | Return the identity behind this connection's access token: the person, the organization, the granted scopes and access levels, and when the token expires. | ## `organization`[​](#organization "Link direto para organization") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ----------------------------- | ----- | ------- | ------------------ | ----------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_organization_get` | read | `read` | `finance/settings` | `settings.show` | `GET /v1/organization` | Return the organization this connection's token belongs to — the customer above every workspace: its public id, registration (name, trade name, CNPJ/CPF), contacts, addresses and `custom_metadata`. | | `finance_organization_update` | write | `write` | `finance/settings` | `settings.update` | `PATCH /v1/organization` | Update the organization profile: `trade_name`, `website`, `addresses` or `custom_metadata` (`null` keeps it). | ## `operation_approvals`[​](#operation_approvals "Link direto para operation_approvals") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ---------------------------------- | ---- | ------ | ------ | ----------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_operation_approvals_get` | read | `read` | — | — (nenhuma) | — (local) | Read one operation approval you asked for (the `approval.id` of an `approval_required` answer): its status (`pending`, `approved` = being processed, `executed`, `failed`, `declined`, `expired`), when it was decided and run, the error code when it failed and the masked result when it ran — those two (and an amount read from the record) only when this token can read the operation's resource (a money operation needs both its money resource and the bill's: `finance/payable_dispatches` with `finance/payables`, `finance/receivable_charges` with `finance/receivables`) and you can still read it in this workspace; otherwise they are null and `result_hidden` is true. | | `finance_operation_approvals_list` | read | `read` | — | — (nenhuma) | — (local) | List the operation approvals you asked for in this workspace, most recent first, with the same fields as finance\_operation\_approvals\_get. | *** Os campos de cada recurso estão na [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/introduction.md) e em `finance_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Tools O servidor expõe **148 tools** sobre **30 famílias de recurso**. Cada uma despacha in-process para o endpoint de `/v1` que já implementa a operação, então filtros, validação, regras de baixa e isolamento por workspace são exatamente os da API REST — a tool *é* o endpoint. As exceções, `finance_schemas_get` (o contrato publicado), `finance_workspaces_list` (os espaços que a pessoa alcança), `finance_me` (a identidade do token) e `finance_operation_approvals_get`/`_list` (as suas aprovações por link), respondem localmente. `finance_organization_get`/`_update` vão ao endpoint, mas são de nível de organização: como `finance_me`, não levam workspace. Toda outra tool aceita `workspace_id`. ## Como ler estas páginas[​](#como-ler-estas-páginas "Link direto para Como ler estas páginas") Cada tool aparece com seis fatos: > `finance_payables_send_to_bank` · **destructive** · verbo `write` · escopo `finance/payable_dispatches` · permissão `payables.dispatch` · `POST /v1/payables/{id}/send-to-bank` | Campo | Significado | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **read** / **write** / **destructive** | A anotação que o cliente MCP lê. Uma `destructive` só roda depois que o servidor pede confirmação à pessoa — num cliente que não pode perguntar, a tool volta um link para você confirmar no app. Veja [Confirmação de tools destrutivas](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md#confirma%C3%A7%C3%A3o-de-tools-destrutivas). | | **destructive\*** | Destrutiva só em algumas chamadas: o `*_update` que baixa ou cancela o título (`status` `paid`/`received`/`cancelled`). Só essa chamada pede confirmação; as outras alterações rodam direto. | | **verbo** | O nível de acesso que o token precisa ter: `read`, `write`, `delete`, `import` ou `export`. Um não substitui o outro — `write` não exclui. `—` quando a tool não exige escopo (só `finance_me`). | | **escopo** | O recurso que o token precisa alcançar: `finance/` ou `finance/all` (ou `all`, que é o mesmo). Vale para o token que carrega escopos `finance/…` (o de um cliente OAuth); um token só com o nível de acesso, sem escopo `finance/…` nem `all`, não alcança nada. Mandar ao banco e cobrar são `write` nos recursos de dinheiro (`finance/payable_dispatches`, `finance/receivable_charges`) — veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). | | **permissão** | A permissão que a pessoa do token precisa ter na organização — a mesma que a ação exige no dashboard. | | **`MÉTODO /caminho`** | O endpoint de `/v1` para onde a tool despacha, para cruzar com a [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/introduction.md). O token precisa do escopo que esse endpoint exige. | ## Argumentos comuns[​](#argumentos-comuns "Link direto para Argumentos comuns") Estes aparecem em muitas tools e significam sempre a mesma coisa. | Argumento | Tipo | Descrição | | ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- | | `limit` | inteiro | Tamanho da página. Padrão `25`, máximo `100` (`10000` nas tools `*_ids`). | | `cursor` | string | O `meta.next_cursor` da página anterior. `null` lá significa a última página. | | `filters` | object | Os filtros que a listagem aceita: escalar é igualdade, array é `in`, objeto escolhe operadores (`{ "gte": …, "lt": … }`). | | `sort_by` | enum | Coluna de ordenação, entre as que a listagem aceita. | | `sort_order` | `asc` \| `desc` | Direção. Padrão `asc`. | | `fields` | string\[] | Colunas a devolver. Omitido, volta o registro inteiro; `id` sempre volta. | | `idempotency_key` | string | Proteção contra repetição, enviada como `X-Idempotency-Key`. Obrigatória nas ações que movem dinheiro. | | `custom_metadata` | object | JSON livre seu, devolvido em toda leitura. | ## O catálogo[​](#o-catálogo "Link direto para O catálogo") | Família | Tools | read | write | destructive | | ------------------------------------------------------------------------------------------------------------------------ | ----- | ---- | ----- | ----------- | | [`payables` — Contas a pagar](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/billings.md) | 10 | 4 | 1 | 5 | | [`receivables` — Contas a receber](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/billings.md) | 10 | 4 | 1 | 5 | | [`financial_transactions` — Lançamentos](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/transactions.md) | 11 | 5 | 2 | 4 | | [`transfers` — Transferências](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/transactions.md) | 2 | 1 | 0 | 1 | | [`reconciliations` — Conciliações](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/transactions.md) | 3 | 1 | 0 | 2 | | [`receipts` — Comprovantes](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/transactions.md) | 2 | 2 | 0 | 0 | | [`financial_accounts` — Contas financeiras e saldos](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/accounts.md) | 10 | 4 | 3 | 3 | | [`banks` — Bancos](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/accounts.md) | 1 | 1 | 0 | 0 | | [`cash_flow` — Fluxo de caixa](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/accounts.md) | 1 | 1 | 0 | 0 | | [`credit_cards` — Cartões de crédito](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/accounts.md) | 5 | 2 | 2 | 1 | | [`card_statements` — Faturas do cartão](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/accounts.md) | 9 | 3 | 2 | 4 | | [`card_transactions` — Lançamentos do cartão](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/accounts.md) | 8 | 3 | 3 | 2 | | [`card_recurrences` — Recorrências do cartão](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/accounts.md) | 5 | 2 | 2 | 1 | | [`iof_rates` — Alíquotas de IOF](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/accounts.md) | 1 | 1 | 0 | 0 | | [`companies` — Empresas](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`people` — Pessoas](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/registers.md) | 6 | 3 | 2 | 1 | | [`categories` — Categorias](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`classification_centers` — Centros de classificação](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`custom_classifiers` — Classificadores personalizados](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/registers.md) | 8 | 2 | 4 | 2 | | [`taxes` — Impostos](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`automatic_rules` — Regras automáticas](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/registers.md) | 6 | 2 | 3 | 1 | | [`ai_agents` — Agentes de IA](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/registers.md) | 9 | 3 | 4 | 2 | | [`ai_skills` — Habilidades de IA](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`attachments` — Anexos](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/documents.md) | 7 | 3 | 2 | 2 | | [`fiscal_documents` — Notas fiscais recebidas](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/documents.md) | 2 | 2 | 0 | 0 | | [`schemas` — Catálogo de campos](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/documents.md) | 1 | 1 | 0 | 0 | | [`workspaces` — Espaços](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/documents.md) | 1 | 1 | 0 | 0 | | [`me` — Identidade](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/documents.md) | 1 | 1 | 0 | 0 | | [`organization` — Organização](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/documents.md) | 2 | 1 | 1 | 0 | | [`operation_approvals` — Aprovações por link](https://docs.finance.kobana.com.br/pt/pt/mcp/tools/documents.md) | 2 | 2 | 0 | 0 | Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Cadastros O que classifica os títulos e lançamentos: empresas, pessoas, categorias, centros de classificação, classificadores personalizados, impostos e as regras de classificação automática — e os agentes de IA, instruções que o assistente roda sozinho num agendamento, e as habilidades de IA, instruções que ele carrega quando a tarefa pede. ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | ----------------------------------------------------- | ----- | ---- | ----- | ----------- | | `companies` — Empresas | 5 | 2 | 2 | 1 | | `people` — Pessoas | 6 | 3 | 2 | 1 | | `categories` — Categorias | 5 | 2 | 2 | 1 | | `classification_centers` — Centros de classificação | 5 | 2 | 2 | 1 | | `custom_classifiers` — Classificadores personalizados | 8 | 2 | 4 | 2 | | `taxes` — Impostos | 5 | 2 | 2 | 1 | | `automatic_rules` — Regras automáticas | 6 | 2 | 3 | 1 | | `ai_agents` — Agentes de IA | 9 | 3 | 4 | 2 | | `ai_skills` — Habilidades de IA | 5 | 2 | 2 | 1 | ## `companies`[​](#companies "Link direto para companies") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | -------------------------- | ----------- | -------- | ------------------- | ------------------ | --------------------------- | -------------------------------------------- | | `finance_companies_list` | read | `read` | `finance/companies` | `companies.list` | `GET /v1/companies` | List the companies (CNPJs) of the workspace. | | `finance_companies_get` | read | `read` | `finance/companies` | `companies.show` | `GET /v1/companies/{id}` | Fetch one company. | | `finance_companies_create` | write | `write` | `finance/companies` | `companies.create` | `POST /v1/companies` | Create a company. | | `finance_companies_update` | write | `write` | `finance/companies` | `companies.update` | `PATCH /v1/companies/{id}` | Update a company's `name` or `active`. | | `finance_companies_delete` | destructive | `delete` | `finance/companies` | `companies.delete` | `DELETE /v1/companies/{id}` | Delete a company. | ## `people`[​](#people "Link direto para people") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ----------------------- | ----------- | -------- | ---------------- | --------------- | ------------------------ | ---------------------------------------------------------------- | | `finance_people_list` | read | `read` | `finance/people` | `people.list` | `GET /v1/people` | List people — customers, suppliers, team members, bank managers. | | `finance_people_get` | read | `read` | `finance/people` | `people.show` | `GET /v1/people/{id}` | Fetch one person. | | `finance_people_ids` | read | `read` | `finance/people` | `people.list` | `GET /v1/people/ids` | The id of every live person, for reconciling a mirror. | | `finance_people_create` | write | `write` | `finance/people` | `people.create` | `POST /v1/people` | Create a person (customer and/or supplier). | | `finance_people_update` | write | `write` | `finance/people` | `people.update` | `PATCH /v1/people/{id}` | Partially update a person. | | `finance_people_delete` | destructive | `delete` | `finance/people` | `people.delete` | `DELETE /v1/people/{id}` | Soft-delete a person. | ## `categories`[​](#categories "Link direto para categories") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | --------------------------- | ----------- | -------- | -------------------- | ------------------- | ---------------------------- | ----------------------------------------------------------------- | | `finance_categories_list` | read | `read` | `finance/categories` | `categories.list` | `GET /v1/categories` | List categories (plano de contas). | | `finance_categories_get` | read | `read` | `finance/categories` | `categories.show` | `GET /v1/categories/{id}` | Fetch one category. | | `finance_categories_create` | write | `write` | `finance/categories` | `categories.create` | `POST /v1/categories` | Create a category. | | `finance_categories_update` | write | `write` | `finance/categories` | `categories.update` | `PATCH /v1/categories/{id}` | Rename a category or change its `type` (cascades to descendants). | | `finance_categories_delete` | destructive | `delete` | `finance/categories` | `categories.delete` | `DELETE /v1/categories/{id}` | Delete a leaf category, clearing it from transactions and titles. | ## `classification_centers`[​](#classification_centers "Link direto para classification_centers") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | --------------------------------------- | ----------- | -------- | ---------------------- | --------------------- | ---------------------------------------- | ----------------------------------------------------------------------- | | `finance_classification_centers_list` | read | `read` | `finance/cost_centers` | `cost-centers.list` | `GET /v1/classification-centers` | List classification centers (centros de custo/receita) used for rateio. | | `finance_classification_centers_get` | read | `read` | `finance/cost_centers` | `cost-centers.show` | `GET /v1/classification-centers/{id}` | Fetch one classification center. | | `finance_classification_centers_create` | write | `write` | `finance/cost_centers` | `cost-centers.create` | `POST /v1/classification-centers` | Create a classification center. | | `finance_classification_centers_update` | write | `write` | `finance/cost_centers` | `cost-centers.update` | `PATCH /v1/classification-centers/{id}` | Partially update a classification center. | | `finance_classification_centers_delete` | destructive | `delete` | `finance/cost_centers` | `cost-centers.delete` | `DELETE /v1/classification-centers/{id}` | Delete a classification center. | ## `custom_classifiers`[​](#custom_classifiers "Link direto para custom_classifiers") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ------------------------------------------ | ----------- | -------- | ---------------------------- | --------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `finance_custom_classifiers_list` | read | `read` | `finance/custom_classifiers` | `custom-classifiers.list` | `GET /v1/custom-classifiers` | List custom classifiers — the workspace's own classification dimensions — with their values. | | `finance_custom_classifiers_get` | read | `read` | `finance/custom_classifiers` | `custom-classifiers.show` | `GET /v1/custom-classifiers/{classifier_id}` | Fetch one custom classifier with its values. | | `finance_custom_classifiers_create` | write | `write` | `finance/custom_classifiers` | `custom-classifiers.create` | `POST /v1/custom-classifiers` | Create a custom classifier (dimension). | | `finance_custom_classifiers_update` | write | `write` | `finance/custom_classifiers` | `custom-classifiers.update` | `PATCH /v1/custom-classifiers/{classifier_id}` | Partially update a custom classifier. | | `finance_custom_classifiers_delete` | destructive | `delete` | `finance/custom_classifiers` | `custom-classifiers.delete` | `DELETE /v1/custom-classifiers/{classifier_id}` | Delete a custom classifier. | | `finance_custom_classifiers_values_create` | write | `write` | `finance/custom_classifiers` | `custom-classifiers.update` | `POST /v1/custom-classifiers/{classifier_id}/values` | Add a value to a custom classifier. | | `finance_custom_classifiers_values_update` | write | `write` | `finance/custom_classifiers` | `custom-classifiers.update` | `PATCH /v1/custom-classifiers/{classifier_id}/values/{value_id}` | Partially update a value of a custom classifier. | | `finance_custom_classifiers_values_delete` | destructive | `delete` | `finance/custom_classifiers` | `custom-classifiers.update` | `DELETE /v1/custom-classifiers/{classifier_id}/values/{value_id}` | Delete a value of a custom classifier. | ## `taxes`[​](#taxes "Link direto para taxes") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ---------------------- | ----------- | -------- | --------------- | -------------- | ----------------------- | --------------------------------------------------------------- | | `finance_taxes_list` | read | `read` | `finance/taxes` | `taxes.list` | `GET /v1/taxes` | List the workspace's taxes and withholdings (ISS, IRRF, INSS…). | | `finance_taxes_get` | read | `read` | `finance/taxes` | `taxes.show` | `GET /v1/taxes/{id}` | Fetch one tax. | | `finance_taxes_create` | write | `write` | `finance/taxes` | `taxes.create` | `POST /v1/taxes` | Create a tax. | | `finance_taxes_update` | write | `write` | `finance/taxes` | `taxes.update` | `PATCH /v1/taxes/{id}` | Partially update a tax. | | `finance_taxes_delete` | destructive | `delete` | `finance/taxes` | `taxes.delete` | `DELETE /v1/taxes/{id}` | Delete a tax. | ## `automatic_rules`[​](#automatic_rules "Link direto para automatic_rules") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | --------------------------------- | ----------- | -------- | ------------------------- | ------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `finance_automatic_rules_list` | read | `read` | `finance/automatic_rules` | `automatic-rules.list` | `GET /v1/automatic-rules` | List the automatic classification rules. | | `finance_automatic_rules_get` | read | `read` | `finance/automatic_rules` | `automatic-rules.show` | `GET /v1/automatic-rules/{id}` | Fetch one automatic rule. | | `finance_automatic_rules_create` | write | `write` | `finance/automatic_rules` | `automatic-rules.create` | `POST /v1/automatic-rules` | Create an automatic rule, appended at the end of its (company, scope) group. | | `finance_automatic_rules_update` | write | `write` | `finance/automatic_rules` | `automatic-rules.update` | `PATCH /v1/automatic-rules/{id}` | Partially update an automatic rule. | | `finance_automatic_rules_delete` | destructive | `delete` | `finance/automatic_rules` | `automatic-rules.delete` | `DELETE /v1/automatic-rules/{id}` | Delete an automatic rule. | | `finance_automatic_rules_reorder` | write | `write` | `finance/automatic_rules` | `automatic-rules.update` | `POST /v1/automatic-rules/reorder` | Rewrite the precedence of one (company, scope) group: `ordered_ids` must be the COMPLETE set of that group, first = position 1. | ## `ai_agents`[​](#ai_agents "Link direto para ai_agents") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ---------------------------------- | ----------- | -------- | ------------------- | ------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_ai_agents_list` | read | `read` | `finance/ai_agents` | `ai-agents.list` | `GET /v1/ai-agents` | List the person's AI agents in the workspace: instructions the assistant runs on its own, each with its triggers (manual, event, api, schedule) and its latest run (every run is a new assistant conversation). | | `finance_ai_agents_get` | read | `read` | `finance/ai_agents` | `ai-agents.show` | `GET /v1/ai-agents/{id}` | Fetch one of the person's AI agents, with its triggers. | | `finance_ai_agents_create` | write | `write` | `finance/ai_agents` | `ai-agents.create` | `POST /v1/ai-agents` | Create an AI agent owned by the person. | | `finance_ai_agents_update` | write | `write` | `finance/ai_agents` | `ai-agents.update` | `PATCH /v1/ai-agents/{id}` | Partially update an AI agent. | | `finance_ai_agents_delete` | destructive | `delete` | `finance/ai_agents` | `ai-agents.delete` | `DELETE /v1/ai-agents/{id}` | Delete an AI agent, its triggers and schedules. | | `finance_ai_agent_triggers_list` | read | `read` | `finance/ai_agents` | `ai-agents.show` | `GET /v1/ai-agents/{id}/triggers` | List the triggers of one of the person's AI agents: manual, event (with `event_type`), api (endpoint and token hint, never the token) and schedule (cron, time zone, next run). | | `finance_ai_agent_triggers_create` | write | `write` | `finance/ai_agents` | `ai-agents.update` | `POST /v1/ai-agents/{id}/triggers` | Add a trigger to an AI agent: `kind: manual` (at most one), `kind: event` with `event_type` (receipt.saved, fiscal\_document.received, payable.created, receivable.created), `kind: schedule` with `cron` (5 fields, at most every 15 minutes) and optional `timezone`, or `kind: api`. | | `finance_ai_agent_triggers_update` | write | `write` | `finance/ai_agents` | `ai-agents.update` | `PATCH /v1/ai-agents/{id}/triggers/{triggerId}` | Update a trigger of an AI agent: `active` pauses or resumes it; `event_type` for event triggers; `cron`/`timezone` for schedule triggers. | | `finance_ai_agent_triggers_delete` | destructive | `delete` | `finance/ai_agents` | `ai-agents.update` | `DELETE /v1/ai-agents/{id}/triggers/{triggerId}` | Remove a trigger from an AI agent (a schedule trigger takes its schedule with it). | ## `ai_skills`[​](#ai_skills "Link direto para ai_skills") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | -------------------------- | ----------- | -------- | ------------------- | ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_ai_skills_list` | read | `read` | `finance/ai_skills` | `ai-skills.list` | `GET /v1/ai-skills` | List the AI skills the person can see in the workspace — their own and the ones shared with them (`is_owner` tells them apart): instruction sets the assistant loads when a task matches their `description`. | | `finance_ai_skills_get` | read | `read` | `finance/ai_skills` | `ai-skills.show` | `GET /v1/ai-skills/{id}` | Fetch one AI skill the person can see, with its instructions and files. | | `finance_ai_skills_create` | write | `write` | `finance/ai_skills` | `ai-skills.create` | `POST /v1/ai-skills` | Create an AI skill owned by the person. | | `finance_ai_skills_update` | write | `write` | `finance/ai_skills` | `ai-skills.update` | `PATCH /v1/ai-skills/{id}` | Partially update one of the person's AI skills — someone else's is read-only (403 `not_owner`). | | `finance_ai_skills_delete` | destructive | `delete` | `finance/ai_skills` | `ai-skills.delete` | `DELETE /v1/ai-skills/{id}` | Delete one of the person's AI skills, for everyone it was shared with. | *** Os campos de cada recurso estão na [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/introduction.md) e em `finance_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Lançamentos e conciliação O lado realizado: os lançamentos de cada conta, as transferências entre contas, a conciliação de títulos com lançamentos e os comprovantes de pagamento. ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | -------------------------------------- | ----- | ---- | ----- | ----------- | | `financial_transactions` — Lançamentos | 11 | 5 | 2 | 4 | | `transfers` — Transferências | 2 | 1 | 0 | 1 | | `reconciliations` — Conciliações | 3 | 1 | 0 | 2 | | `receipts` — Comprovantes | 2 | 2 | 0 | 0 | ## `financial_transactions`[​](#financial_transactions "Link direto para financial_transactions") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ----------------------------------------------------------- | ----------- | -------- | ------------------------- | ------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_financial_transactions_list` | read | `read` | `finance/transactions` | `transactions.list` | `GET /v1/financial-transactions` | List financial transactions (lançamentos — what actually moved in an account), cursor-paginated. | | `finance_financial_transactions_get` | read | `read` | `finance/transactions` | `transactions.show` | `GET /v1/financial-transactions/{id}` | Fetch one financial transaction. | | `finance_financial_transactions_aggregates` | read | `read` | `finance/transactions` | `transactions.list` | `GET /v1/financial-transactions/aggregates` | Credit, debit and net totals of realised transactions (forecasts excluded) for a period (`month`+`year` or `start_date`+`end_date`) and optionally one company. | | `finance_financial_transactions_ids` | read | `read` | `finance/transactions` | `transactions.list` | `GET /v1/financial-transactions/ids` | The id of every live financial transaction, for reconciling a mirror. | | `finance_financial_transactions_create` | write | `write` | `finance/transactions` | `transactions.create` | `POST /v1/financial-transactions` | Record a financial transaction (credit or debit) on an account. | | `finance_financial_transactions_update` | write | `write` | `finance/transactions` | `transactions.update` | `PATCH /v1/financial-transactions/{id}` | Partially update a financial transaction. | | `finance_financial_transactions_delete` | destructive | `delete` | `finance/transactions` | `transactions.delete` | `DELETE /v1/financial-transactions/{id}` | Delete a financial transaction. | | `finance_financial_transactions_reconciliation_suggestions` | read | `read` | `finance/reconciliations` | `reconciliations.list` | `GET /v1/financial-transactions/{id}/reconciliation-suggestions` | For an open statement line: the title of the same amount that closes it (or the other leg of a transfer), the classification to record it with otherwise (with a counterparty to create when the line names one by CNPJ), and its twins. | | `finance_financial_transactions_reconcile_with_new_billing` | destructive | `write` | `finance/reconciliations` | `reconciliations.create` | `POST /v1/financial-transactions/{id}/reconcile-with-new-billing` | Create the payable (outflow) or receivable (inflow) a statement line pays, born settled on it; `twin_transaction_ids` repeats it on the line's twins. | | `finance_financial_transactions_reconcile_as_transfer` | destructive | `write` | `finance/reconciliations` | `reconciliations.create` | `POST /v1/financial-transactions/{id}/reconcile-as-transfer` | Make a statement line one leg of a transfer to another account: paired with that account's open opposite line of the same amount, or the other leg is created in that account. | | `finance_financial_transactions_reconcile_batch` | destructive | `write` | `finance/reconciliations` | `reconciliations.create` | `POST /v1/financial-transactions/reconcile-batch` | Launch many open statement lines at once (up to 100): a settled title or a transfer per line, each on its own; `results` says which went through and why each other did not. | ## `transfers`[​](#transfers "Link direto para transfers") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | -------------------------- | ----------- | ------- | ---------------------- | ------------------- | --------------------------------- | -------------------------------------------------------------------------------------------- | | `finance_transfers_create` | destructive | `write` | `finance/transactions` | `transfers.create` | `POST /v1/transfers` | Transfer between two accounts: creates the linked debit/credit pair under one `transfer_id`. | | `finance_transfers_get` | read | `read` | `finance/transactions` | `transactions.show` | `GET /v1/transfers/{transfer_id}` | Fetch a transfer: the linked debit and credit transactions. | ## `reconciliations`[​](#reconciliations "Link direto para reconciliations") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | -------------------------------- | ----------- | -------- | ------------------------- | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------- | | `finance_reconciliations_create` | destructive | `write` | `finance/reconciliations` | `reconciliations.create` | `POST /v1/reconciliations` | Reconcile payables/receivables against bank transactions (n:m). | | `finance_reconciliations_get` | read | `read` | `finance/reconciliations` | `reconciliations.show` | `GET /v1/reconciliations/{id}` | Fetch a reconciliation: the ids of the titles and transactions it groups. | | `finance_reconciliations_delete` | destructive | `delete` | `finance/reconciliations` | `reconciliations.delete` | `DELETE /v1/reconciliations/{id}` | Dissolve a manual reconciliation, reverting every title in it to pending. | ## `receipts`[​](#receipts "Link direto para receipts") | Tool | Tipo | Verbo | Escopo | Permissão | Endpoint | O que faz | | ----------------------- | ---- | ------ | ------------------ | --------------- | ----------------------- | ------------------------------------------------------- | | `finance_receipts_list` | read | `read` | `finance/receipts` | `receipts.list` | `GET /v1/receipts` | List payment receipts (comprovantes), cursor-paginated. | | `finance_receipts_get` | read | `read` | `finance/receipts` | `receipts.show` | `GET /v1/receipts/{id}` | Fetch one payment receipt. | *** Os campos de cada recurso estão na [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/introduction.md) e em `finance_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Meu perfil **Meu perfil** (`/profile`) mostra as informações da sua conta. É o **único destino interno do menu do usuário** — o avatar no canto superior direito. ![Meu perfil](/pt/assets/images/20-profile-df05c026ecb4de31a971172ab9ee4855.png) ## O que a tela mostra[​](#o-que-a-tela-mostra "Link direto para O que a tela mostra") Os cartões: | Cartão | Conteúdo | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Perfil** | Nome e e-mail, como vieram do login, e o espaço de trabalho ativo. Sem seleção, mostra *"Nenhum espaço de trabalho selecionado"* | | **Preferências** | Tema (claro, escuro ou o do sistema) e idioma — os mesmos controles do cabeçalho, num lugar onde dá para procurá-los | | **Organizações** | Só para quem é membro de duas ou mais organizações: o nome de cada uma no seletor — veja abaixo | | **Notificações** | **Receber a Agenda do dia** por e-mail | | **Primeiros Passos** | Liga e desliga o item **Primeiros Passos** do menu lateral | observação **Quem você é não se edita aqui.** Nome e e-mail vêm do login, e senha não existe — veja abaixo por quê. O que a tela guarda são preferências: tema, idioma, o nome das organizações no seletor, a Agenda do dia e a exibição dos Primeiros Passos. ## O nome das organizações no seletor[​](#o-nome-das-organizações-no-seletor "Link direto para O nome das organizações no seletor") Quem é membro de duas ou mais organizações vê o cartão **Organizações**. Nele você dá a cada organização o nome que quer ver no seletor do cabeçalho e na escolha de organização ao entrar — "Samsung" no lugar da razão social inteira, por exemplo. * **O nome é só seu.** Os outros membros continuam vendo o nome que eles deram, ou o oficial. * **O nome oficial não muda aqui.** Ele vem da sua conta Kobana e aparece como título de cada campo. * **Campo em branco volta ao nome oficial** — apague e clique em **Salvar**. * **O seletor muda na hora**, sem sair e entrar de novo. ## Como você entra[​](#como-você-entra "Link direto para Como você entra") **Este produto não usa senha.** Há dois caminhos, e nenhum deles pede uma — mas eles não são intercambiáveis: * **Entrar com a Kobana** — é a porta de entrada. Sua conta Kobana autentica você, e é por ela que chega quem ainda não tem acesso ao Financeiro Inteligente. * **Link mágico** — você informa o e-mail e recebe um link de acesso único, válido por **15 minutos**. **Só funciona para quem já tem acesso**: um e-mail que ainda não foi liberado não recebe link nenhum. observação **O formulário de e-mail pode não aparecer na tela de login.** Alguns ambientes deixam só **"Entrar com a Kobana"**. O link mágico continua valendo para quem já o usa — apenas deixa de ser oferecido. Por isso não existe cadastro de senha, troca de senha nem "esqueci minha senha": o e-mail **é** a identidade. O fuso horário também não é configurável por aqui. ## Entrar não é o mesmo que ter acesso[​](#entrar-não-é-o-mesmo-que-ter-acesso "Link direto para Entrar não é o mesmo que ter acesso") Autenticar prova **quem você é**; entrar no produto depende de você ter um **espaço de trabalho**. Quando os dois não coincidem, o login funciona e você para numa tela que explica o porquê: | Tela | Quando aparece | O que fazer | | -------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | **Crie o espaço da sua empresa** | Sua conta Kobana ainda não tem um espaço de trabalho aqui | Confira os dados e clique em **Criar espaço de trabalho** | | **Você ainda não foi convidado** | A sua empresa já tem um espaço de trabalho, e o seu e-mail não é membro dele | Peça a um administrador que libere o seu acesso | | **Seu acesso está suspenso** | Você era membro e um administrador pausou o seu acesso | Fale com quem administra a conta — não é o mesmo que nunca ter sido convidado | | **Cadastro indisponível** | A criação de novos espaços de trabalho está desativada no ambiente | Se a sua empresa já usa o Financeiro Inteligente, peça um convite | informação **A tela de criação não é um formulário.** Nome da empresa e CNPJ (ou CPF) vêm do cadastro da sua conta Kobana — você confere e confirma, sem digitar nada. É também por isso que ela só aparece no login com a Kobana: o link mágico autentica um e-mail, não uma conta, e não carrega esses dados. dica **Se você administra a conta na Kobana** e o espaço de trabalho da sua empresa já existe, você entra direto: o login reconhece o seu papel de administrador e libera o acesso sem convite. A exceção é ter tido o acesso pausado — nesse caso vale a pausa. O botão **Voltar**, no canto, retorna à tela anterior. ## Como chegar[​](#como-chegar "Link direto para Como chegar") Clique no seu avatar, no canto superior direito, e escolha **Meu perfil**. O topo do menu mostra o seu e-mail, o seu nome e o espaço de trabalho ativo, com **Gerenciar conta** — que abre a sua conta Kobana em outra aba, e só aparece nos ambientes em que esse endereço está configurado. Abaixo dele, o menu ainda oferece **Política de privacidade**, **Política de segurança**, **Termos de uso** e **Sair** — os três primeiros abrem páginas externas. ## Trocar de espaço de trabalho[​](#trocar-de-espaço-de-trabalho "Link direto para Trocar de espaço de trabalho") Não é aqui. O cartão apenas **mostra** qual está ativo. Para trocar, use o seletor no cabeçalho da aplicação ou a tela de [Espaços de trabalho](https://docs.finance.kobana.com.br/pt/pt/workspaces/.md). --- # Notas fiscais **Documentos > Notas fiscais** (`/fiscal-documents`) reúne as *"Notas recebidas contra as empresas do espaço"* — as NF-e (produto) e NFS-e (serviço) que os seus fornecedores emitiram contra os CNPJs cadastrados. Elas entram sozinhas pelas integrações ou pela mão, e a partir daqui você as concilia e transforma em título. observação **Aqui é a nota que VOCÊ recebe, não a que você emite.** O Financeiro não emite nem cancela nota fiscal — ele guarda, lê e concilia o que chega. Cancelar ou reemitir é sempre do lado de quem emitiu. ## De onde vem cada nota[​](#de-onde-vem-cada-nota "Link direto para De onde vem cada nota") | Origem | Como entra | Como aparece | | --------------------- | ------------------------------------------------- | -------------------------------------- | | **nfe.io** | captura automática das NFS-e de serviço recebidas | notas de **Serviço**, prontas na lista | | **Importação de XML** | você envia os arquivos em **"Importar XML"** | um XML ou um ZIP com o mês inteiro | | **SEFAZ** | busca por chave de acesso | a nota puxada da SEFAZ pela chave | dica **Um ZIP com o mês inteiro funciona.** Em *"Importar XML"* você pode soltar um pacote com vários XMLs de uma vez — o que já existe é ignorado, e só o que é novo entra. ## Encontrar uma nota[​](#encontrar-uma-nota "Link direto para Encontrar uma nota") A busca no topo aceita *"Buscar por chave, número ou emitente"*. As abas separam por tipo — *Todas*, *Serviço* e *Produto* — e os filtros recortam o que importa: | Filtro | O que mostra | | ------------------------- | -------------------------------------------------------- | | **Sem empresa vinculada** | notas cujo CNPJ do tomador não casou com nenhuma empresa | | **Com título gerado** | notas que já viraram conta a pagar | | **Sem título gerado** | notas que ainda não viraram título | | **Data de criação** | quando a nota entrou no espaço | Cada nota mostra a **situação** — *Autorizada*, *Cancelada* ou *Indefinida* — e, quando só o resumo da nota é conhecido, o marcador *Resumo*. informação **Resumo é uma nota sem o detalhe.** A SEFAZ entrega ao destinatário só o cabeçalho da NF-e até você manifestar — sem itens nem duplicatas. Uma nota *Resumo* aparece na lista, mas não tem os itens para conferir nem parcelas para gerar título. ## A empresa vinculada[​](#a-empresa-vinculada "Link direto para A empresa vinculada") A nota é ligada a uma empresa do espaço pelo **CNPJ do tomador**. Quando nenhum CNPJ cadastrado casa, ela fica *Sem empresa vinculada* — previsto, não erro: a nota pode ter sido emitida contra um CNPJ que você ainda não cadastrou, ou contra um CPF. Na tela da nota, quando não há vínculo, o botão **Cadastrar empresa** abre o cadastro já preenchido com o CNPJ do tomador; ao salvar, a nota (e as outras que esperavam esse CNPJ) passa para a empresa nova. Se uma empresa com esse CNPJ já existe, o mesmo botão liga a nota a ela na hora, sem abrir o cadastro. ## Ler a nota[​](#ler-a-nota "Link direto para Ler a nota") Ao abrir uma nota você vê: * **Prestador** e **Tomador** — razão social, CNPJ e endereço de cada lado. * **Valores e impostos** — valor do serviço, base de cálculo, ISS e os impostos retidos (IRRF, PIS, COFINS, CSLL, INSS), com o valor líquido. * **Serviço** (NFS-e) ou **Itens** (NF-e) — a descrição e os códigos fiscais, ou a lista de produtos. * **Duplicatas** e **Contas a pagar** — as parcelas da nota e os títulos já gerados a partir dela. ## Virar conta a pagar[​](#virar-conta-a-pagar "Link direto para Virar conta a pagar") A partir das duplicatas da nota você **gera as contas a pagar** — uma por parcela. Notas sem duplicata usam a data de vencimento que você informar na geração. O que já foi gerado aparece na aba *Contas a pagar* da nota, e o filtro *Com título gerado* separa na lista o que já foi convertido do que ainda falta. ## Baixar os arquivos[​](#baixar-os-arquivos "Link direto para Baixar os arquivos") | Ação | O que faz | | ---------------- | --------------------------------------------------------- | | **Copiar XML** | copia o XML da nota para a área de transferência | | **Baixar XML** | baixa o XML guardado da nota | | **Baixar todas** | gera um ZIP com os XMLs de todas as notas do filtro atual | aviso **Nem toda nota tem XML guardado.** Uma nota *Resumo* pode não ter o XML — nesse caso *"Baixar XML"* fica indisponível e o rótulo mostra *"Sem XML guardado"*. ## Pela API[​](#pela-api "Link direto para Pela API") As notas fiscais também são expostas, **somente leitura**, na API v1 sob o escopo `finance/fiscal_documents` (nível de acesso `read`): * [Listar notas fiscais](https://docs.finance.kobana.com.br/pt/pt/api/v1/list-fiscal-documents) — página paginada, com filtros por empresa, tipo, situação, origem, chave, número e data. * [Obter nota fiscal por ID](https://docs.finance.kobana.com.br/pt/pt/api/v1/get-fiscal-document) — a nota individual. O `xml_download_url` que a API devolve aponta para o recurso de anexos, então baixar os bytes do XML exige também o escopo `finance/attachments`. ## Relacionado[​](#relacionado "Link direto para Relacionado") * [Comprovantes](https://docs.finance.kobana.com.br/pt/pt/comprovantes/.md) — a prova do pagamento que sai * [Anexos](https://docs.finance.kobana.com.br/pt/pt/anexos/.md) — onde os arquivos das notas ficam guardados * [Contas a pagar](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/.md) — para onde a nota vira título * [Integrações](https://docs.finance.kobana.com.br/pt/pt/integracoes/.md) — a captura das NFS-e pela nfe.io --- # Pessoas Pessoas (`/people`) são os clientes, fornecedores e contatos cadastrados no espaço de trabalho. Um mesmo cadastro pode acumular papéis — cliente, fornecedor, os dois ou nenhum — sem virar registro duplicado. ![Listagem de pessoas](/pt/assets/images/09-people-59af507551962f9e0bb475c64247dead.png) ![Detalhe de pessoa](/pt/assets/images/10-person-detail-7535de5efa58c43a314640280be62e48.png) ## A listagem[​](#a-listagem "Link direto para A listagem") Colunas: **foto**, **Nome**, **Papel**, **Documento**, **E-mail** e **Telefone** — mais **Cadastrado em**, que só aparece na visão consolidada. Cada papel vira um selo — **Cliente**, **Fornecedor**, **Gerente de conta**, **Time** — ou aparece o texto **Sem papel**. Acima da tabela, a **busca** (por nome ou documento) e o filtro **Papel**: **Todas**, **Clientes**, **Fornecedores**, **Gerentes**, **Time** e **Sem papel**. Cada linha tem duas ações — **Editar** e **Excluir**. O botão de criação é **"Nova pessoa"**. ## O formulário[​](#o-formulário "Link direto para O formulário") Quatro abas: **Identificação**, **Contato**, **Endereço** e **Dados bancários**. ### Identificação[​](#identificação "Link direto para Identificação") | Campo | Observações | | ---------------------- | ------------------------------------------------------------------------------------------------------------- | | **Nome** | Obrigatório | | **Apelido** | Opcional | | **Razão social** | *"Para PJ — razão social oficial"* | | **Cadastrar em** | **Obrigatório** — a empresa onde a pessoa é cadastrada | | **Papel** | Os checkboxes **Cliente**, **Fornecedor**, **Gerente de conta** e **Time**. Deixar todos desmarcados é válido | | **Natureza** | **Detectar automaticamente** (padrão), **Pessoa física** ou **Pessoa jurídica** | | **CPF** / **CNPJ** | O rótulo e a máscara seguem a Natureza — CPF por padrão, CNPJ quando pessoa jurídica | | **Data de nascimento** | Opcional | **A Natureza não precisa ser escolhida.** No padrão, o sistema deduz pelo documento que você digitar. ### Contato[​](#contato "Link direto para Contato") **E-mails** e **Telefones**, ambos em lista — dá para adicionar quantos precisar. **Só o e-mail tem rótulo.** Cada e-mail aceita um rótulo livre (financeiro, comercial…). Telefone não tem esse campo. E **"e-mail principal" não é um conceito do sistema** — nenhum e-mail é eleito o principal. ### Endereço e Dados bancários[​](#endereço-e-dados-bancários "Link direto para Endereço e Dados bancários") Duas abas próprias. **Dados bancários** cobre banco, agência e conta (com dígitos), chave PIX e tipo da chave. ## Papéis[​](#papéis "Link direto para Papéis") | Combinação | Uso típico | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Cliente** | Quem paga à empresa | | **Fornecedor** | Quem recebe da empresa | | **Cliente + Fornecedor** | Parceiro que compra e vende | | **Gerente de conta** | Gerente do banco que atende uma conta da empresa — veja [Gerentes](https://docs.finance.kobana.com.br/pt/pt/contas-financeiras/.md#gerentes) | | **Time** | Gente da própria empresa: sócios, equipe do financeiro — veja [Acessos](https://docs.finance.kobana.com.br/pt/pt/contas-financeiras/.md#acessos) | | Nenhum | Contato sem relação financeira ativa | O papel decide onde a pessoa aparece: o campo **Cliente** das contas a receber busca só quem é cliente; o **Fornecedor** das contas a pagar, só quem é fornecedor. Para quem é ou foi gerente, o detalhe da pessoa mostra **Contas que atende**, com o período de cada uma; para quem tem acesso a contas, **Acessos a contas**, com o nível de cada uma. ## Busca e criação automática[​](#busca-e-criação-automática "Link direto para Busca e criação automática") Ao digitar um nome nos formulários de contas a pagar ou receber, o sistema busca os cadastros existentes e, não achando, oferece **cadastrar pelo nome** — a pessoa é criada junto no salvamento. A importação CSV faz o mesmo. ## Foto de perfil[​](#foto-de-perfil "Link direto para Foto de perfil") O sistema busca a foto em **duas** fontes, nesta ordem: 1. **Gravatar** — pelo e-mail cadastrado. É a fonte primária. 2. **WhatsApp** — pelo telefone, e só se a integração estiver configurada para a empresa. É o **fallback**, usado quando o Gravatar não devolve nada. observação **Nenhuma foto aparece sozinha.** A busca não roda em segundo plano nem ao salvar a pessoa: é uma ferramenta manual, em **Manutenção → Buscar fotos**. Cada execução percorre **apenas pessoas ainda sem foto**, no teto de **100 por vez**, e espera **30 dias** antes de tentar de novo quem falhou. A foto encontrada é **guardada** no cadastro — não é buscada de novo a cada visita. A foto aparece na listagem e no topo do detalhe da pessoa. ## Transferências e a Segurança[​](#transferências-e-a-segurança "Link direto para Transferências e a Segurança") A aba **Beneficiários** da [Segurança](https://docs.finance.kobana.com.br/pt/pt/seguranca/.md#benefici%C3%A1rios) decide para quais favorecidos as **transferências (Pix e TED)** podem ser enviadas ao banco. A regra olha o **CPF/CNPJ**, não o cadastro: * **Uma regra por documento.** A mesma pessoa cadastrada em várias empresas aparece uma vez só em Segurança, e liberar, bloquear ou limitar vale para todos os cadastros com aquele CPF/CNPJ — com os limites diário e mensal somados entre as empresas. * **Cadastrar não é bloqueado.** No modo *Bloquear todos e liberar alguns*, uma pessoa nova pode ser cadastrada e usada em títulos normalmente; só o **envio** das transferências para ela fica barrado (*"Favorecido não liberado"*) até que alguém peça a liberação do documento e a Kobana aprove. No modo *Liberar todos e bloquear alguns*, ela entra liberada. * **Boleto, tributo e concessionária não passam por essa regra** — para eles o dinheiro vai para quem o código de barras indica, e o controle fica em Tipos de operações. * **Excluir ou juntar cadastros não muda a regra.** Um documento bloqueado continua bloqueado mesmo sem cadastro ativo (aparece em Segurança como *"Sem cadastro ativo"*), e um liberado continua liberado. ## Exclusão[​](#exclusão "Link direto para Exclusão") Um único bloqueio: **[regra automática](https://docs.finance.kobana.com.br/pt/pt/regras-automaticas/.md) apontando para a pessoa**. Enquanto existir uma, a exclusão falha — a regra ficaria classificando contra alguém invisível, e não há para quem repontar. Edite ou remova a regra antes. **Contas a pagar, a receber e lançamentos não bloqueiam.** O diálogo mostra o que está vinculado, mas deixa excluir. perigo **A exclusão não pode ser desfeita — e isso é intencional.** A pessoa sai das telas mas o histórico financeiro dela permanece intacto, apontando para o cadastro apagado. Não há "restaurar": ao apagar, o **CPF/CNPJ é liberado**, e nada impede que outro cadastro passe a usá-lo. Por isso a volta não é oferecida — ela poderia colidir com quem ocupou o lugar. --- # Regras automáticas Regras automáticas (`/automatic-rules`) classificam lançamentos automaticamente conforme critérios cadastrados, dispensando a categorização manual de documentos recorrentes. ![Listagem de regras automáticas](/pt/assets/images/14-automatic-rules-37053c0ded2e99ac15a5a8e7f05eb275.png) ## Escopo da regra[​](#escopo-da-regra "Link direto para Escopo da regra") Cada regra tem um **escopo fixo** (definido na criação, **imutável**) e pertence a uma **entidade**. O escopo é um par de abas no topo do formulário, sem rótulo — as duas opções são: * **Contas financeiras** — dispara em lançamentos recém-criados. * **Contas a pagar / receber** — dispara em títulos recém-criados. ## Como funciona[​](#como-funciona "Link direto para Como funciona") Avaliado um documento, o sistema percorre as regras **da mesma entidade e do mesmo escopo**, em ordem de precedência. A **primeira** regra ativa cujos critérios batam todos é aplicada — e só ela. Os campos definidos na regra **sobrescrevem** os valores do documento, mesmo já preenchidos. ## Critérios[​](#critérios "Link direto para Critérios") A regra combina critérios com lógica **E** — todos precisam bater. O montador tem dois lados, **SE** (critérios) e **ENTÃO** (ações), com uma pré-visualização em linguagem corrente. | Critério | Como compara | | ----------------------------- | ------------------------------------------- | | **Entidade** | Obrigatório — a empresa da regra | | **Conta** | Igualdade (só no escopo Contas financeiras) | | **Tipo de lançamento** | **Pagamentos** ou **Recebimentos** | | **Cliente/Fornecedor** | Igualdade | | **Descrição original contém** | Trecho do texto, ignorando maiúsculas | | **Observação contém** | Trecho do texto, ignorando maiúsculas | aviso **Maiúsculas são ignoradas; acentos não.** A comparação baixa a caixa das duas pontas, mas **não** remove acento: uma regra com **"Pao"** não pega uma descrição escrita **"Pão"**. Escreva o critério como o texto realmente chega. Não existe critério de **valor ou faixa**, nem operadores "igual a / começa com / termina com" — texto é sempre "contém". dica O link **"Exibir lançamentos afetados por esse critério"** abre a pré-visualização com o que a regra pegaria hoje — vale conferir antes de salvar. ## Ações[​](#ações "Link direto para Ações") | Ação | Descrição | | --------------------------- | --------------------------------------------------------------- | | **Descrição** | Reescreve a descrição | | **Cliente/Fornecedor** | Atribui a pessoa | | **Categoria** | Atribui a categoria | | **Centro de classificação** | Atribui **um** centro | | **Pagar/Receber via** | Define a conta prevista (só no escopo Contas a pagar / receber) | observação **A ação de centro de classificação não rateia.** Ela atribui um único centro — o seletor é de escolha única. Para dividir entre centros, use o **Rateio** no formulário do título. Ver [Centros de classificação](https://docs.finance.kobana.com.br/pt/pt/centros-de-classificacao/.md). **A regra não desfaz rateio.** Num título já rateado entre duas ou mais categorias, a regra não mexe na categoria; o mesmo vale para o centro de classificação. As demais ações da regra se aplicam normalmente, e a prévia mostra *"rateado — a regra mantém"* no campo preservado. Para trocar o rateio por uma classificação só, use **Classificar selecionados**. ## Precedência[​](#precedência "Link direto para Precedência") Regras só competem **dentro do próprio grupo: entidade × escopo**. Cada card traz as setas **"Mover para cima"** e **"Mover para baixo"**, e a regra de menor posição vence primeiro. **As setas param na borda do grupo.** Mesmo havendo um card logo acima na tela, a seta não passa por cima dele se for de outro grupo — a listagem mostra todos os grupos em uma coluna só, mas a ordenação é por grupo. Não é travamento: mover para lá não faria sentido, porque regras de grupos diferentes nunca disputam o mesmo documento. * Num grupo de **uma regra só**, as setas **não aparecem** — não há contra quem ordenar. * Na primeira do grupo, a seta para cima fica desabilitada; na última, a de baixo. * **Não há aviso ao mover**: o card mudando de lugar é a confirmação. **A ordem dos grupos entre si não significa nada.** Os grupos são listados por identificador interno da entidade, não por nome nem por relevância. Um grupo aparecer acima de outro não lhe dá precedência — a disputa nunca cruza grupos. ## Ativar e pausar[​](#ativar-e-pausar "Link direto para Ativar e pausar") A pílula no rodapé do card mostra o **estado** — **"Regra ativa"** ou **"Regra desativada"** — e o clique faz a **ação oposta**, que o tooltip anuncia: **"Pausar"** ou **"Retomar"**. Os avisos são **"Regra ativada"** e **"Regra desativada"**. **Regra pausada nunca dispara.** Ela não é apenas ignorada na listagem: a avaliação só considera regras ativas. Pausar é a forma de desligar uma regra sem perdê-la. ## Onde as regras disparam[​](#onde-as-regras-disparam "Link direto para Onde as regras disparam") * **Criação** de lançamentos e títulos (formulário e API). * **Importação CSV** — lançamentos, contas a pagar e contas a receber. * **Extratos bancários**, ao confirmar a importação do extrato. * **Parcelas geradas** — cada parcela do grupo é avaliada por conta própria, porque um critério de descrição pode depender do sufixo ("1/12"). * **Importação do Fintera** — nos três importadores: contas a pagar, contas a receber e lançamentos. * **Sincronização de extrato do Gateway Bancário**. ## Aplicar às já existentes[​](#aplicar-às-já-existentes "Link direto para Aplicar às já existentes") observação **Não é uma ação da listagem.** É o checkbox **"Aplicar regra aos lançamentos já existentes?"**, no **rodapé do formulário**. Marcado, salvar pede confirmação e enfileira a aplicação retroativa — que roda em segundo plano (*"Aplicação retroativa enfileirada"*). Diferente do diálogo **"Classificar"** em massa, que define categoria e centro manualmente sobre uma seleção, sem criar regra. ## Criar uma regra[​](#criar-uma-regra "Link direto para Criar uma regra") 1. Em `/automatic-rules`, use **"Nova regra"**. 2. Escolha a **Entidade** e, nas abas do topo, o escopo — **"Contas financeiras"** ou **"Contas a pagar / receber"**. Só dá para escolher agora: depois de salva, a regra não muda de escopo. 3. Monte os critérios (**SE**) e as ações (**ENTÃO**), conferindo a pré-visualização. 4. Salve — a regra vale imediatamente para os **novos** documentos. ## Excluir[​](#excluir "Link direto para Excluir") O diálogo é **"Excluir regra automática"**: *"A regra será removida permanentemente. Lançamentos já classificados não são afetados."* --- # SDKs do Financeiro Inteligente Os SDKs são as bibliotecas oficiais para chamar a API REST do Financeiro Inteligente em **Node.js / TypeScript**, **Python**, **Ruby** e **PHP**, sem montar requisições HTTP, autenticação, paginação e tratamento de erros à mão. ## Linguagens[​](#linguagens "Link direto para Linguagens") | Linguagem | Pacote | Registro | Status | | -------------------- | ------ | --------- | -------- | | Node.js / TypeScript | — | npm | Em breve | | Python | — | PyPI | Em breve | | Ruby | — | RubyGems | Em breve | | PHP | — | Packagist | Em breve | :::info Em breve Os SDKs do Financeiro Inteligente ainda não foram publicados. Quando forem, esta página passa a listar o nome do pacote e o comando de instalação de cada linguagem. ::: ## O que esperar[​](#o-que-esperar "Link direto para O que esperar") * Clientes gerados a partir da especificação OpenAPI da API, com os mesmos recursos e nomes da [referência da API](https://docs.finance.kobana.com.br/pt/pt/api/overview/introduction.md). * Autenticação, paginação, repetição de chamadas e erros tratados pela biblioteca. * Um pacote por linguagem, publicado no registro oficial: npm, PyPI, RubyGems e Packagist. ## Enquanto isso[​](#enquanto-isso "Link direto para Enquanto isso") Você já integra o Financeiro Inteligente por outros caminhos: * [API REST](https://docs.finance.kobana.com.br/pt/pt/api/overview/introduction.md): a referência completa dos endpoints. * [MCP](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/introduction.md): para agentes de IA operarem o produto. * [CLI](https://docs.finance.kobana.com.br/pt/pt/cli/overview/introduction.md): o comando `kobana finance` no terminal. Os SDKs de todos os produtos Kobana estão no [catálogo de SDKs](https://www.kobana.com.br/desenvolvedores/sdks). --- # Segurança **Segurança** (`/settings/security`) reúne as regras que protegem o dinheiro que sai pelo banco: **o que pode ser enviado, de quais contas, para quais favorecidos, por quais canais e com quais limites**. Vale só para **pagamentos e transferências** — cobranças ficam de fora. As regras são do **espaço de trabalho**: valem para todas as empresas dele ao mesmo tempo, e a tela avisa isso no topo (*"Vale para todas as empresas do espaço de trabalho…"*). Sem um espaço selecionado, ela pede que você escolha um. ## Onde fica[​](#onde-fica "Link direto para Onde fica") ![Aba Limites da tela Segurança](/pt/assets/images/21-security-limits-bcf4d6e4f61cefb05907454773ed9c81.png) Menu **Sistema** → **Segurança**. ## O que as regras travam[​](#o-que-as-regras-travam "Link direto para O que as regras travam") Quase tudo aqui age **no envio ao banco**. Criar e aprovar títulos continua livre: um título de um tipo desligado, de uma conta bloqueada ou para um favorecido não liberado pode ser cadastrado e aprovado normalmente — ele só não sai para o banco. Há três exceções, que agem antes do envio: * a aba **Canais**, que tem interruptores próprios para **Criar** e **Aprovar**; * o interruptor **Permitir aprovações no período noturno**, na aba Limites; * as [Configurações de Aprovação](https://docs.finance.kobana.com.br/pt/pt/aprovar-pagamentos/.md#ligar-ou-desligar), que também passam pela Kobana (ver [Quem pode pedir mudanças](#quem-pode-pedir-mudan%C3%A7as)). observação Um limite **não se libera editando ou excluindo um título**. O que já foi enviado ao banco fica registrado à parte, com o valor do envio: excluir o título, trocar o valor ou o favorecido depois não devolve nada ao limite. Só um pagamento **cancelado, rejeitado, reprovado ou que falhou** no banco deixa de contar. ## Nada vale na hora[​](#nada-vale-na-hora "Link direto para Nada vale na hora") ![Barra de alterações com uma mudança pronta para enviar](/pt/assets/images/27-security-changes-f9d9f75ef007b6d987eb10a881660064.png) **Nenhuma alteração desta tela tem efeito imediato.** Toda mudança vira uma **solicitação**, que a **Kobana analisa e aprova ou nega**. Uma regra de segurança que qualquer pessoa pudesse afrouxar na hora não protegeria nada. Na prática: 1. Você muda o que quiser, em quantas abas quiser. As mudanças ficam num rascunho até o envio; depois de enviadas, a tela volta a mostrar os valores **em vigor**. 2. Cada mudança aparece na **barra lateral Alterações**, à direita, com o valor de antes e o de depois e um botão **Desfazer** por item. 3. O campo **Justificativa (opcional)** explica o pedido para quem vai analisar. 4. **Enviar para Aprovação** manda tudo numa solicitação só. O botão fica sempre visível — fixo no topo da barra e, em telas estreitas, numa barra presa ao rodapé. aviso **O rascunho fica só no navegador.** Se você sair da página sem enviar, as alterações se perdem — o navegador avisa antes de sair. Enquanto houver pedidos em análise, a tela mostra o aviso *"1 solicitação aguarda a aprovação da Kobana. Os valores na tela são os que estão valendo agora."* A regra nova só começa a valer quando a Kobana aprova. ### Solicitações[​](#solicitações "Link direto para Solicitações") ![Tela de solicitações](/pt/assets/images/28-security-requests-ad458f8fa71f0b3e0a27aebd60e5ea21.png) O botão **Solicitações**, no topo da página, mostra quantas estão pendentes e abre a lista de todos os pedidos do espaço de trabalho, com busca por solicitante ou justificativa e filtro por situação. | Coluna | O que mostra | | ----------------- | ----------------------------------------------------------------------------------------------------- | | **Data e hora** | Quando o pedido foi enviado | | **Solicitante** | Quem pediu | | **Alterações** | O que muda, item a item | | **Justificativa** | O texto enviado junto | | **Situação** | **Pendente**, **Aprovado**, **Negado** ou **Cancelado** — e, quando houver, o motivo dado pela Kobana | | **Ações** | **Cancelar**, nas pendentes | **Cancelar** retira o pedido da análise (*"A Kobana não vai mais analisar estas alterações."*). Para pedir de novo, refaça as alterações na tela. Pode cancelar quem pode criar aquele pedido — não só o autor. Pedidos cancelados continuam na lista, como histórico. Os pedidos feitos pela tela de Configurações de Aprovação aparecem aqui também. Mais de um pedido pode estar pendente ao mesmo tempo. Se dois mexem no mesmo valor, o segundo a ser analisado é negado por conflito — o valor que ele esperava mudar já não é o mesmo. ## As abas[​](#as-abas "Link direto para As abas") ### Limites[​](#limites "Link direto para Limites") Define **quando é dia e quando é noite** e **quanto pode ser enviado ao banco** em cada período. * **Fuso horário** — o relógio de todas as regras: o que é dia, noite, "hoje" e "este mês". A busca aceita cidade, região ou UTC; primeiro vêm os fusos do **Brasil**, depois os **Outros fusos**. Padrão: São Paulo. * **Horário diurno e noturno** — arraste os dois marcadores para definir quando começam o dia e a noite, em passos de 30 minutos. **O dia começa às 05:00, no mínimo, e termina às 22:00, no máximo.** Padrão: diurno das 06:00 às 20:00, que é também o padrão do Banco Central para o Pix. * **Período noturno**, com dois interruptores: | Interruptor | Ligado (padrão) | Desligado | | ---------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------- | | **Permitir aprovações no período noturno** | Aprova-se a qualquer hora | Os botões de aprovar ficam bloqueados entre o início da noite e o início do dia | | **Permitir envio ao banco no período noturno** | O envio segue normalmente, respeitando os limites noturnos | **Nada vai ao banco à noite** — ver [Envio noturno desligado](#envio-noturno-desligado) | * **Limites de valor** — uma matriz com **Pagamentos** (boletos, tributos e concessionárias) e **Transferências** (Pix e TED) nas linhas, e **Limite diurno** e **Limite noturno** nas colunas, cada um com: * **Por operação** — o valor máximo de um único envio; * **Total por dia** — a soma de tudo o que foi enviado ao banco no período, **somando todas as empresas do espaço de trabalho**. Campo em branco é **Sem limite**. O limite por operação não pode passar do total por dia. Com o envio noturno desligado, os limites noturnos não têm efeito. ### Contas[​](#contas "Link direto para Contas") ![Aba Contas](/pt/assets/images/22-security-accounts-e5b35555062266faa8484156306c4823.png) Escolhe **de quais contas** pagamentos e transferências podem sair, e **quanto cada uma pode enviar por dia**. As contas aparecem agrupadas por empresa; cada uma tem um interruptor para **Pagamentos** e outro para **Transferências**, cada um com o seu **Limite de envio por dia**. * **Novas contas** — a primeira linha é o modelo: a configuração que **cada conta recebe ao ser integrada ao banco**. Depois ela pode ser ajustada na própria linha. Mudar o modelo não altera as contas que já existem. * Contas **Sem integração com o banco** aparecem travadas — não há o que enviar por elas. * **Todas as contas habilitadas** aplica o mesmo limite a todas as contas ligadas, de todas as empresas, com **Aplicar para todos**. Um campo em branco nessa linha **mantém** o limite atual de cada conta. O limite da conta vale junto com os da aba Limites: quando os dois se aplicam, vale o menor. ### Beneficiários[​](#beneficiários "Link direto para Beneficiários") ![Aba Beneficiários](/pt/assets/images/23-security-beneficiaries-2035f4e695652995373b08262b5e05f1.png) Escolhe **para quais favorecidos as transferências podem ser enviadas** e quanto cada um pode receber. observação **Só transferências — Pix e TED.** Boleto, tributo e concessionária não passam por esta regra: nesses casos o dinheiro vai para quem o código de barras indica, e uma lista de fornecedores não protegeria nada. Eles são controlados em [Tipos de operações](#tipos-de-opera%C3%A7%C3%B5es). **Regra geral**, com dois modos: | Modo | Quem recebe | Favorecidos novos | | -------------------------------------------- | --------------------------------- | ----------------- | | **Liberar todos e bloquear alguns** (padrão) | Todos, menos os que você bloquear | Entram liberados | | **Bloquear todos e liberar alguns** | Só os que você liberar | Entram bloqueados | Cada modo guarda a sua lista: trocar de um para o outro não apaga as marcações do outro. **O favorecido é identificado pelo CPF/CNPJ**, não pelo cadastro. Por isso o mesmo fornecedor cadastrado em várias empresas aparece **uma vez só** (*"Cadastrado em 3 empresas"*), e os limites dele valem somados entre as empresas. O documento comparado no envio é: * o da **chave Pix**, quando a chave é CPF ou CNPJ; * o **CPF/CNPJ do favorecido informado no título**, nos demais casos. aviso Em Pix por chave **e-mail, telefone ou aleatória**, o sistema não sabe de quem é a chave: vale o documento informado no título. Quem quiser rigor total desliga esses tipos de chave em Tipos de operações. Por favorecido, a lista mostra o interruptor **Liberado**, o **Limite diário**, o **Limite mensal** e o **Transferido no mês**. O mês é o do calendário, no fuso da aba Limites. A busca aceita nome ou CPF/CNPJ, e o filtro separa **Liberados** e **Bloqueados**. Documentos que a regra cita mas que não têm mais cadastro aparecem como **Sem cadastro ativo**. **Todos os liberados** aplica os mesmos limites a todos os liberados — de todas as páginas, ou só aos encontrados pela busca. Um campo em branco nessa linha mantém o limite atual de cada um. ### Tipos de operações[​](#tipos-de-operações "Link direto para Tipos de operações") ![Aba Tipos de operações](/pt/assets/images/24-security-operation-types-3420bc14d16c2726f3c3cf06e082e49f.png) Uma árvore com tudo o que pode ser enviado ao banco, com interruptores que ligam e desligam cada tipo: * **Pagamentos** — Boleto bancário; Concessionárias; Tributos (Federais: DARF, GPS, GRU e FGTS; Estaduais: ICMS e DARE; Municipais: ISS, IPTU e ITBI); Pix copia e cola. * **Transferências** — Pix por tipo de chave (CPF, CNPJ, e-mail, telefone, aleatória); TED para conta de favorecido ou depósito judicial. Desligar um grupo desliga tudo o que está dentro; um grupo com parte ligada e parte desligada aparece em amarelo. Os tipos só ligam e desligam — não há limite por tipo. Tipos desligados podem ser cadastrados e aprovados normalmente, mas **não são enviados ao banco**. ### Canais[​](#canais "Link direto para Canais") ![Aba Canais](/pt/assets/images/25-security-channels-e12bfe00f7fdbd461ccafa89b2116442.png) Uma matriz com o que pode ser feito em cada canal: **Criar**, **Aprovar**, **Pagar** (*"Enviar para o Banco"*) e **Cobrar** (*"Emitir boleto ou Pix para o cliente"*). **Canais de acesso** — por onde uma pessoa ou um sistema entra: | Canal | Observação | | ---------------------------------------------- | ------------------------------------------------------------------------------------------ | | **Dashboard** | Esta interface web | | **Aplicativo Desktop** e **Aplicativo Mobile** | **Em desenvolvimento** — aparecem travados | | **API** | Integrações com o seu sistema | | **MCP - Inteligência Artificial** | Agentes de IA: **Kadu**, **Kia** e **Outros**. Ligar ou desligar o MCP muda os três juntos | | **CLI - Linha de comando** | | **Canais de origem** — de onde um título vem sem que alguém o digite. **Só criam títulos**: Aprovar, Pagar e Cobrar aparecem como *"Não se aplica"*. | Canal | O que cobre | | ----------------- | ----------------------------------------- | | **Importação** | Planilhas CSV | | **Inbox** | Documentos recebidos por e-mail ou upload | | **Notas Fiscais** | Títulos gerados a partir de notas | | **Integrações** | Nibo, Fintera e as próximas | Quando uma pessoa gera um título de um canal de origem — por exemplo, a partir de uma nota fiscal, no Dashboard —, **os dois canais precisam permitir Criar**. Títulos de recorrência seguem o canal em que a série foi criada. **Todos os canais** liga ou desliga uma ação em todos de uma vez, menos os em desenvolvimento. Consultas continuam liberadas em todos os canais. aviso **Padrão: Pagar ligado só no Dashboard.** Criar e Aprovar vêm ligados em todos os canais de acesso, e Criar nos de origem — mas enviar ao banco pela API, pela CLI ou por agentes de IA **exige uma solicitação aprovada**. São os caminhos que dá para automatizar, e por isso começam fechados. **Cobrar** vem ligado no Dashboard, na API e na CLI, e desligado para agentes de IA: um agente só emite boleto ou Pix em nome da organização se alguém ligar isso. O envio automático depois da aprovação (ver [Configurações de Aprovação](https://docs.finance.kobana.com.br/pt/pt/aprovar-pagamentos/.md#ligar-ou-desligar)) usa o canal de quem deu a última aprovação. ### Usuários[​](#usuários "Link direto para Usuários") ![Aba Usuários](/pt/assets/images/26-security-users-8140ae5dff71ee1d58f34c8d8a6f7309.png) **Somente leitura.** Lista quem tem acesso ao espaço de trabalho, as funções de cada pessoa e o que essas funções permitem: **Criar**, **Aprovar**, **Pagar** e **Forçar reenvio**. Passe o mouse sobre uma marcação para ver qual função concede a permissão. A mesma permissão vale para pagamentos e transferências. Para mudar, use **Alterar**, que leva às funções da pessoa em Membros — o link só aparece para quem pode ver membros. Convites pendentes e usuários suspensos não operam até ficarem ativos. ## Quando uma regra bloqueia[​](#quando-uma-regra-bloqueia "Link direto para Quando uma regra bloqueia") Ao enviar ao banco, as regras são conferidas nesta ordem, e a primeira que falha decide: canal, tipo de operação, conta, favorecido (só transferências), horário noturno, limite por operação, total do período, limite diário da conta e limites do favorecido. **Nada é reagendado.** Um título bloqueado fica onde está, com o motivo à vista, e precisa ser enviado de novo quando a regra permitir. ### Na lista de envio[​](#na-lista-de-envio "Link direto para Na lista de envio") No diálogo **Enviar pagamentos para o banco** — a lista "Enviar ao banco" de Contas a pagar —, um título barrado por uma regra que só depende dele aparece **desabilitado**, com o motivo: | Motivo na lista | O que fazer | | -------------------------------------- | ----------------------------------------------- | | **Canal sem permissão de envio** | Pedir Pagar para o canal, na aba Canais | | **Tipo de operação desligado** | Pedir o tipo, em Tipos de operações | | **Conta bloqueada para esta operação** | Pedir a operação para a conta, em Contas | | **Favorecido não liberado** | Pedir a liberação do CPF/CNPJ, em Beneficiários | | **Envio noturno bloqueado** | Esperar o início do período diurno | | **Acima do limite por operação** | Pedir um limite maior, em Limites | Os limites que dependem do que **já foi enviado** — total do período, limite diário da conta, limites diário e mensal do favorecido — aparecem como **aviso**, e a linha continua selecionável: *"Passaria do limite do período"*, *"Passaria do limite diário da conta"*, *"Passaria do limite diário do favorecido"*, *"Passaria do limite mensal do favorecido"*. Passe o mouse para ver o limite, quanto já foi enviado e quanto resta. Num envio em lote, os títulos vão em ordem de vencimento; quando um limite é atingido, os seguintes que passariam dele **não são enviados**, e o resultado lista cada um com o motivo. Se o envio automático foi recusado por uma regra, a linha traz o selo **Envio automático bloqueado**. ### Envio noturno desligado[​](#envio-noturno-desligado "Link direto para Envio noturno desligado") Com **Permitir envio ao banco no período noturno** desligado: * **nada vai ao banco** entre o início da noite e o início do dia — nem pelo botão, nem pelo envio automático depois da aprovação; * a lista mostra o aviso **"Envio ao banco bloqueado até 06:00"** (com o seu horário); * o que foi aprovado à noite **não é enviado sozinho de manhã**: fica na lista e precisa ser enviado de novo no período diurno. ### Lote retido no banco[​](#lote-retido-no-banco "Link direto para Lote retido no banco") Pode acontecer de um pagamento ser criado no banco no fim do dia e a aprovação automática do lote cair já no período noturno. Nesse caso o lote **não é aprovado**: ele fica **retido no banco**. * No título, o card do pagamento mostra o selo **"Retido no banco: envio noturno bloqueado"**. * Na lista de envio, esses títulos aparecem na seção **Retidos no banco**. * O botão **Aprovar no banco** — no card e na seção — só funciona no período diurno. Ele confere as regras de novo, aprova o lote e retoma o acompanhamento do pagamento. O "Atualizar status" e o acompanhamento automático **não** aprovam um lote retido. ### Na aprovação[​](#na-aprovação "Link direto para Na aprovação") Com a aprovação noturna desligada ou com **Aprovar** desligado no canal, a tela de [Aprovação](https://docs.finance.kobana.com.br/pt/pt/aprovar-pagamentos/.md) mostra um aviso e desabilita os botões de aprovar. **Recusar nunca é bloqueado.** A mesma tela avisa, em cada título, quando ele **não vai poder ser enviado** do jeito que está (*"Envio bloqueado pela Segurança"*) — para quem aprova saber que precisa pedir a liberação. ### Na criação[​](#na-criação "Link direto para Na criação") Com **Criar** desligado num canal, o título não é criado: *"O canal … não pode criar títulos. Peça a liberação em Segurança."* Nas importações e integrações, o motivo fica registrado no relatório da execução, e uma recorrência criada por um canal desligado para de gerar ocorrências enquanto ele estiver desligado. ## Quem pode pedir mudanças[​](#quem-pode-pedir-mudanças "Link direto para Quem pode pedir mudanças") | Quem | O que pode pedir | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Proprietário** | Qualquer mudança, em todas as abas | | Quem tem a permissão **Configurações de aprovação** | Só mudanças das configurações de aprovação, pela tela [Configurações de Aprovação](https://docs.finance.kobana.com.br/pt/pt/aprovar-pagamentos/.md#ligar-ou-desligar) | | Demais funções (Administrador, Visualizador…) | Nenhuma: veem as regras, e a barra lateral avisa *"Só quem pode pedir mudanças de segurança envia solicitações."* | Por padrão, **só o Proprietário** pede mudanças de segurança — nem o Administrador. Quem decide é sempre a **Kobana**. --- # Transferências Uma transferência move dinheiro entre duas contas financeiras do mesmo espaço de trabalho, gerando **dois lançamentos espelhados**: uma saída na origem e uma entrada no destino. ## Onde fica[​](#onde-fica "Link direto para Onde fica") observação **Transferência não é um item de menu.** Não existe tela de transferências: é o diálogo **"Nova transferência"**, aberto de dois lugares, ambos em **Contas financeiras**: * No **cabeçalho da listagem** de contas. * No **detalhe de uma conta** — e aí a **origem já vem preenchida** com a conta que você está vendo. ## Campos[​](#campos "Link direto para Campos") Seis campos, e **cinco são obrigatórios**: | Campo | Observações | | -------------- | ------------------------------------------------------------------------------------- | | **De** | Obrigatório — a conta que envia | | **Para** | Obrigatório — a conta que recebe | | **Valor** | Obrigatório — precisa ser **maior que zero** | | **Data** | Obrigatório — vem preenchida com hoje | | **Descrição** | **Obrigatório** — diferente de um lançamento comum, aqui não dá para deixar em branco | | **Observação** | Opcional. *"Informações adicionais — visíveis nos dois lançamentos."* | O botão é **"Criar transferência"**. **"De" e "Para" são os rótulos.** "Conta de origem" e "Conta de destino" aparecem como texto de apoio dentro dos campos, não como nome deles. **Não existem "Mês de competência" nem "Provisório" numa transferência.** Os dois campos existem na API, mas a tela não os oferece — uma transferência criada por aqui é sempre efetivada, e a competência acompanha a data. ### O que o sistema recusa[​](#o-que-o-sistema-recusa "Link direto para O que o sistema recusa") * **Valor zero ou negativo** — *"O valor precisa ser maior que zero"*. * **Origem igual ao destino** — *"A origem e o destino precisam ser contas diferentes"*. * **Descrição vazia** — *"Informe uma descrição"*. ## Os dois lançamentos[​](#os-dois-lançamentos "Link direto para Os dois lançamentos") Confirmada a transferência, nascem dois registros: | Registro | Conta | | ----------- | ---------------- | | **Saída** | Conta de origem | | **Entrada** | Conta de destino | Os dois carregam o mesmo identificador de transferência, o que os marca como as duas pernas do mesmo movimento e evita que a conciliação os trate como dinheiro novo. ## Como aparecem depois[​](#como-aparecem-depois "Link direto para Como aparecem depois") Na listagem de [Lançamentos](https://docs.finance.kobana.com.br/pt/pt/lancamentos/.md), cada perna ganha o selo de **transferência** ao lado da descrição, e o filtro rápido **Transferências** isola todas elas. Abrindo uma perna, o card do topo diz **"Transferência enviada para outra conta"** ou **"Transferência recebida de outra conta"**, mostra a conta do outro lado, a data e o valor, e traz o atalho **"Abrir lado oposto →"**. ## Excluir[​](#excluir "Link direto para Excluir") perigo **Não há edição de transferência, e a exclusão não é em cascata.** As duas pernas são lançamentos independentes depois de criadas: apagar uma remove só aquela e **deixa a outra órfã**, com o saldo distorcido dos dois lados. Para desfazer por inteiro, exclua **as duas** — o "Abrir lado oposto →" é o caminho para achar a segunda. ## Diferença para um lançamento comum[​](#diferença-para-um-lançamento-comum "Link direto para Diferença para um lançamento comum") Um lançamento de entrada ou saída afeta **uma** conta e mexe no saldo total do espaço de trabalho. A transferência afeta **duas** e mantém o total intacto — é o mecanismo correto para mover saldo entre contas sem inventar receita nem despesa. --- # Espaços de trabalho Um espaço de trabalho é a caixa que guarda tudo o que você cadastra no Financeiro Inteligente. Cada usuário pode pertencer a vários espaços de trabalho, e os dados de um nunca aparecem no outro. ![Listagem de espaços de trabalho](/pt/assets/images/18-workspaces-b27888d83d97a2a535c9204eccceb09e.png) ## Modelo de isolamento[​](#modelo-de-isolamento "Link direto para Modelo de isolamento") ``` Usuário (e-mail) ├── Espaço de trabalho A │ ├── Empresa 1 (CNPJ) │ ├── Empresa 2 (CNPJ) │ ├── Pessoas (clientes e fornecedores) │ ├── Contas financeiras │ ├── Categorias │ ├── Centros de classificação │ ├── Contas a pagar │ ├── Contas a receber │ └── Lançamentos └── Espaço de trabalho B └── ... ``` Nenhum dado cruza a fronteira entre espaços de trabalho. Um espaço de trabalho equivale a uma organização ou a um grupo de empresas administradas pela mesma pessoa. ## A tela[​](#a-tela "Link direto para A tela") Em `/workspaces` você vê **um cartão por espaço de trabalho**, não uma tabela. Cada cartão traz o nome no topo e, abaixo, a lista das empresas que ele contém, sob o rótulo **Empresas (N)**. O cartão do espaço de trabalho ativo aparece destacado por uma borda colorida. **Clicar no cartão troca para aquele espaço de trabalho e leva você para a Visão geral** — o mesmo efeito do seletor no topo da aplicação. ## Criar[​](#criar "Link direto para Criar") Clique em **Novo espaço de trabalho** e informe o **Nome**. É o único campo. O espaço de trabalho é criado na hora, passa a ser o ativo e fica disponível no seletor do topo. observação **O seu primeiro espaço de trabalho não nasce aqui.** Ele é criado logo depois do primeiro login com a Kobana, numa tela de confirmação que já vem com o nome e o documento da sua empresa — veja [Entrar não é o mesmo que ter acesso](https://docs.finance.kobana.com.br/pt/pt/meus-dados/.md#entrar-n%C3%A3o-%C3%A9-o-mesmo-que-ter-acesso). Esta tela serve para os **demais**: um segundo espaço de trabalho, criado só com o nome. ## Renomear[​](#renomear "Link direto para Renomear") No menu de ações do cartão (ícone de três pontos), escolha **Editar**. Só o nome muda — não há como mover empresas de um espaço de trabalho para outro. ## Alternar[​](#alternar "Link direto para Alternar") O seletor no cabeçalho lista todos os seus espaços de trabalho. Ao alternar, todas as telas recarregam com os dados do espaço de trabalho escolhido. Quem é membro de mais de uma organização vê as duas escolhas no mesmo seletor, rotulado **Org / Espaço**: as organizações numa coluna, os espaços da organização atual na outra. Trocar de organização recarrega a aplicação na **Visão geral**. ## Exclusão[​](#exclusão "Link direto para Exclusão") perigo **Não existe trava. Excluir um espaço de trabalho apaga tudo o que está dentro dele, para sempre.** Não importa quantas empresas, contas ou lançamentos ele contenha: a exclusão é aceita, o conteúdo vai junto, e não há lixeira nem como desfazer. Isso contraria o que acontece um nível abaixo, e vale saber: uma **empresa** com um único lançamento, conta a pagar ou conta a receber **não pode ser excluída** — o sistema recusa e pede que você remova os registros antes. Mas excluir o **espaço de trabalho** que contém essa empresa **funciona**, e leva a empresa e todos os registros dela junto. O caminho mais curto é também o mais destrutivo. Por isso o diálogo existe para você **conferir antes de assinar**. No menu de ações do cartão, escolha **Excluir**: 1. O diálogo **conta o que será destruído** e cita apenas o que existe de fato — empresas, contas a pagar, contas a receber, lançamentos, pessoas, contas financeiras, conciliações e registros de auditoria: > Serão apagados junto, para sempre: 2 empresas, 1 conta a pagar, 14 lançamentos. Se não houver nada vinculado, ele diz isso: *"Ele está vazio — não há nada vinculado a ele."* 2. Logo abaixo, o lembrete do que vai junto sem ser contado: **configurações, anexos, agendamentos e histórico de importação**. 3. **Para liberar o botão, você digita o nome do espaço de trabalho.** O texto precisa bater **exatamente**, inclusive maiúsculas e minúsculas. Só então **Excluir espaço de trabalho** fica clicável. Se a contagem não puder ser carregada, o diálogo avisa — *"Não conseguimos verificar o que será removido. Confira antes de continuar."* — e mantém a exigência de digitar o nome. Excluir o espaço de trabalho ativo limpa a seleção; escolha outro no seletor do topo. --- # Financeiro Inteligente — Documentação Bem-vindo! O Financeiro Inteligente é a plataforma de back-office financeiro multi-empresa para o mercado brasileiro: contas a pagar e a receber, lançamentos, conciliação, importações e envio de pagamentos ao banco — várias empresas, em um só lugar. Esta documentação descreve o que você vê e consegue fazer nas telas do produto. Para integrar seus sistemas via REST, veja a [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api.md). ## O que tem nesta documentação[​](#o-que-tem-nesta-documentação "Link direto para O que tem nesta documentação") | Seção | Para quem | O que você encontra | | ---------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Documentação** (esta seção) | quem usa o painel | contas financeiras, lançamentos, contas a pagar e a receber, conciliação, documentos, classificação e cadastros | | [API](https://docs.finance.kobana.com.br/pt/pt/api/overview/introduction.md) | quem integra outro sistema | a API v1: autenticação, paginação, filtros, idempotência, erros e a referência de cada endpoint | | [MCP](https://docs.finance.kobana.com.br/pt/pt/mcp/overview/introduction.md) | quem usa o produto de um cliente de IA (Claude, ChatGPT…) | o servidor MCP remoto: autenticação, transporte e a referência de cada tool | | [CLI](https://docs.finance.kobana.com.br/pt/pt/cli/overview/introduction.md) | quem opera pelo terminal ou por script | o `kobana`, a linha de comando de todos os produtos Kobana: instalação, autenticação e uso | ## Primeiros passos[​](#primeiros-passos "Link direto para Primeiros passos") Se você está chegando agora, este é o caminho natural: 1. [Crie um espaço de trabalho](https://docs.finance.kobana.com.br/pt/pt/workspaces/.md) — a caixa que isola os dados de cada organização. 2. [Cadastre as empresas](https://docs.finance.kobana.com.br/pt/pt/empresas/.md) — as entidades jurídicas (CNPJ) administradas nele. 3. [Crie as contas financeiras](https://docs.finance.kobana.com.br/pt/pt/contas-financeiras/.md) — corrente, poupança, caixa, investimento e crédito. 4. [Registre contas a pagar](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/.md) e [a receber](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/.md) — à vista, parceladas ou recorrentes — ou importe em lote via CSV. 5. [Importe o extrato](https://docs.finance.kobana.com.br/pt/pt/extratos-bancarios/.md) e [concilie](https://docs.finance.kobana.com.br/pt/pt/conciliacao/.md) — case o que aconteceu no banco com o que estava previsto. ## As seções[​](#as-seções "Link direto para As seções") As seções abaixo seguem os **seis grupos do menu** do produto — você navega aqui a mesma árvore que vê na tela. Só **Meu perfil** chega por outro caminho no produto: o menu do avatar. ### Principal[​](#principal "Link direto para Principal") * [Visão geral](https://docs.finance.kobana.com.br/pt/pt/dashboard/.md) — indicadores, fluxo de caixa realizado e projetado, próximos vencimentos. * [Espaços de trabalho](https://docs.finance.kobana.com.br/pt/pt/workspaces/.md) — o isolamento entre organizações: criação, troca e exclusão. * [Empresas](https://docs.finance.kobana.com.br/pt/pt/empresas/.md) — cadastro multi-empresa (CNPJ), matriz e filiais, consulta à Receita. ### Financeiro[​](#financeiro "Link direto para Financeiro") * [Contas financeiras](https://docs.finance.kobana.com.br/pt/pt/contas-financeiras/.md) — contas correntes, poupança, caixa, investimento e crédito, com saldo calculado pelos lançamentos. * [Extratos bancários](https://docs.finance.kobana.com.br/pt/pt/extratos-bancarios/.md) — importação de OFX e QIF na conta. * [Transferências](https://docs.finance.kobana.com.br/pt/pt/transferencias/.md) — movimentação entre contas do mesmo espaço de trabalho. * [Cartões](https://docs.finance.kobana.com.br/pt/pt/cartoes/.md) — cartões de crédito, pré-pagos e de benefício: faturas, limite, parcelas, compras internacionais com IOF, recorrências e o pagamento da fatura. * [Lançamentos](https://docs.finance.kobana.com.br/pt/pt/lancamentos/.md) — as movimentações das contas financeiras; a base da conciliação. * [Contas a pagar](https://docs.finance.kobana.com.br/pt/pt/contas-a-pagar/.md) — compromissos de saída: parcelas, recorrência, tributos e envio ao banco. * [Aprovar pagamentos](https://docs.finance.kobana.com.br/pt/pt/aprovar-pagamentos/.md) — o portão que exige o ok de uma pessoa antes de um título entrar na lista. * [Contas a receber](https://docs.finance.kobana.com.br/pt/pt/contas-a-receber/.md) — compromissos de entrada, com parcelas e recorrência, e a cobrança por boleto ou Pix. * [Conciliação](https://docs.finance.kobana.com.br/pt/pt/conciliacao/.md) — casamento entre títulos e lançamentos vindos do extrato. ### Documentos[​](#documentos "Link direto para Documentos") * [Comprovantes](https://docs.finance.kobana.com.br/pt/pt/comprovantes/.md) — a prova de cada pagamento: capturada sozinha quando o banco confirma, ou enviada por você. * [Anexos](https://docs.finance.kobana.com.br/pt/pt/anexos/.md) — a biblioteca de arquivos do espaço de trabalho, vinculável a qualquer registro. ### Eixos[​](#eixos "Link direto para Eixos") * [Categorias](https://docs.finance.kobana.com.br/pt/pt/categorias/.md) — classificação em até três níveis, por receita e despesa. * [Centros de classificação](https://docs.finance.kobana.com.br/pt/pt/centros-de-classificacao/.md) — alocação por departamento ou projeto, com rateio. * [Classificadores personalizados](https://docs.finance.kobana.com.br/pt/pt/classificadores-personalizados/.md) — dimensões de classificação que você cria, com valores próprios, além de categorias e centros. * [Regras automáticas](https://docs.finance.kobana.com.br/pt/pt/regras-automaticas/.md) — classificação automática por critérios que você define. ### Cadastros[​](#cadastros "Link direto para Cadastros") * [Pessoas](https://docs.finance.kobana.com.br/pt/pt/pessoas/.md) — clientes e fornecedores (PF e PJ), com papéis acumuláveis. * [Impostos](https://docs.finance.kobana.com.br/pt/pt/impostos/.md) — o catálogo de tributos vinculáveis aos títulos. ### Sistema[​](#sistema "Link direto para Sistema") * [Integrações](https://docs.finance.kobana.com.br/pt/pt/integracoes/.md) — Gateway Bancário (pagamentos, contas, extrato e pessoas), Fintera (importação de dados) e WhatsApp (fotos de perfil). * [Manutenção](https://docs.finance.kobana.com.br/pt/pt/manutencao/.md) — ferramentas de higiene dos cadastros de pessoas. * [Meu perfil](https://docs.finance.kobana.com.br/pt/pt/meus-dados/.md) — suas informações de conta e como o login funciona. ### API[​](#api "Link direto para API") * [Referência da API](https://docs.finance.kobana.com.br/pt/pt/api.md) — REST com autenticação Bearer JWT: endpoints, paginação, filtros, idempotência e erros. ---