# Financeiro Inteligente — Documentação > Documentação do Financeiro Inteligente: contas a pagar, contas a receber, transações, conciliações e API. ## en Welcome! Smart Finance is the multi-company financial back-office platform for the Brazilian market: payables and receivables, transactions, reconciliation, imports, and payment dispatch to the bank — several companies, in one place. - [Smart Finance — Documentation](https://docs.finance.kobana.com.br/en/index.md): Welcome! Smart Finance is the multi-company financial back-office platform for the Brazilian market: payables and receivables, transactions, reconciliation, imports, and payment dispatch to the bank — several companies, in one place. ### search - [Search the documentation](https://docs.finance.kobana.com.br/en/search.md) ### anexos The workspace file library — a many-to-many link with bills and transactions. - [Attachments](https://docs.finance.kobana.com.br/en/anexos.md): The workspace file library — a many-to-many link with bills and transactions. ### api - [API Reference](https://docs.finance.kobana.com.br/en/api.md) #### overview - [Overview](https://docs.finance.kobana.com.br/en/api/overview.md) - [Authentication](https://docs.finance.kobana.com.br/en/api/overview/authentication.md): The Smart Finance API uses a Kobana Account access token to authenticate every request. - [Data retention](https://docs.finance.kobana.com.br/en/api/overview/data-retention.md): This page describes how long each type of data is kept in Smart Finance. - [Endpoints](https://docs.finance.kobana.com.br/en/api/overview/endpoints.md): | Environment | Platform (web access) | API (v1) | - [Errors](https://docs.finance.kobana.com.br/en/api/overview/errors.md): Every error response uses a stable JSON envelope. - [Field selection](https://docs.finance.kobana.com.br/en/api/overview/fields.md): Record reads — the listings and the single-item GETs — accept ?fields= to return only the columns you will use: - [Filtering and sorting](https://docs.finance.kobana.com.br/en/api/overview/filtering.md): Collection GET endpoints accept filtering and sorting via query string, on top of cursor pagination. Which fields are filterable and sortable varies by resource — check each endpoint's OpenAPI specification. Here is the common grammar. - [Idempotency](https://docs.finance.kobana.com.br/en/api/overview/idempotency.md): The API supports idempotency so requests can be safely retried without executing the same operation twice. Useful when a call is interrupted in transit and you don't get a response — for example, a request to create a payable that drops on a network error can be retried with the same key, guaranteeing that only one record is created. - [Introduction](https://docs.finance.kobana.com.br/en/api/overview/introduction.md): You're a dev — have fun! ✨ - [OpenAPI](https://docs.finance.kobana.com.br/en/api/overview/openapi.md): The Smart Finance API specification is available in OpenAPI 3.1 format to import into the tool of your choice. - [Listing and pagination](https://docs.finance.kobana.com.br/en/api/overview/pagination.md): Every GET endpoint that returns collections uses cursor-based pagination. - [Postman](https://docs.finance.kobana.com.br/en/api/overview/postman.md): Download the collection in the language of your choice and import it into Postman, or open the online version straight from Kobana's public workspace. - [Rate limiting](https://docs.finance.kobana.com.br/en/api/overview/rate-limit.md): Limits run over a 1-hour sliding window — each request counts against the limit for the next 60 minutes; there is no fixed-time reset — and split into three bands: read (GET), write (POST, PUT, PATCH, DELETE), and money-moving actions, which get their own, tighter bucket. - [User-Agent](https://docs.finance.kobana.com.br/en/api/overview/user-agent.md): The User-Agent header identifies your integration. Include your name and a valid email address so the Kobana team can reach you if: ### aprovar-pagamentos The gate that requires a person's approval before a bill enters the official payables list. - [Approve payments](https://docs.finance.kobana.com.br/en/aprovar-pagamentos.md): The gate that requires a person's approval before a bill enters the official payables list. ### cartoes Credit, prepaid and benefit cards — statements, limit, installments, international purchases, subscriptions and paying the statement. - [Cards](https://docs.finance.kobana.com.br/en/cartoes.md): Credit, prepaid and benefit cards — statements, limit, installments, international purchases, subscriptions and paying the statement. #### cadastrar-e-converter Register a card with a new account, convert an existing credit account, and the statement preview the form works out as you type. - [Register and convert](https://docs.finance.kobana.com.br/en/cartoes/cadastrar-e-converter.md): Register a card with a new account, convert an existing credit account, and the statement preview the form works out as you type. #### fatura-e-corte The card screen — statements by month, the statement header, the entries, the predicted and the confirmed closing date, and the history. - [Statement and closing](https://docs.finance.kobana.com.br/en/cartoes/fatura-e-corte.md): The card screen — statements by month, the statement header, the entries, the predicted and the confirmed closing date, and the history. #### fechar-conferir-pagar The automatic closing and the statement's payable, the review against the bank's total, paying in full or in part, undoing, reopening, the prepaid top-up and the card in the cash flow. - [Close, review and pay](https://docs.finance.kobana.com.br/en/cartoes/fechar-conferir-pagar.md): The automatic closing and the statement's payable, the review against the bank's total, paying in full or in part, undoing, reopening, the prepaid top-up and the card in the cash flow. #### lancamentos-e-iof Enter one-off, installment and international purchases, refunds and interest and fees — which statement each falls on, the IOF and the exchange rate, editing a series, moving and anticipating. - [Entries and IOF](https://docs.finance.kobana.com.br/en/cartoes/lancamentos-e-iof.md): Enter one-off, installment and international purchases, refunds and interest and fees — which statement each falls on, the IOF and the exchange rate, editing a series, moving and anticipating. #### recorrencias Subscriptions charged to the card — the expected charges on each statement, confirming the real amount, not charged, the suggestion to update the amount, editing and ending. - [Recurrences](https://docs.finance.kobana.com.br/en/cartoes/recorrencias.md): Subscriptions charged to the card — the expected charges on each statement, confirming the real amount, not charged, the suggestion to update the amount, editing and ending. #### relatorios IOF paid on international purchases, by month, card, category or supplier, and the recurrences' forecast vs. actual — exported as CSV or XLSX. - [Reports](https://docs.finance.kobana.com.br/en/cartoes/relatorios.md): IOF paid on international purchases, by month, card, category or supplier, and the recurrences' forecast vs. actual — exported as CSV or XLSX. ### categorias Hierarchical classification up to three levels, by revenue and expense. - [Categories](https://docs.finance.kobana.com.br/en/categorias.md): Hierarchical classification up to three levels, by revenue and expense. ### centros-de-classificacao Allocating costs and revenues to departments and projects — with splits across centers. - [Classification centers](https://docs.finance.kobana.com.br/en/centros-de-classificacao.md): Allocating costs and revenues to departments and projects — with splits across centers. ### classificadores-personalizados Classification dimensions you create — like "Region" or "Product" — each with its own values. - [Custom classifiers](https://docs.finance.kobana.com.br/en/classificadores-personalizados.md): Classification dimensions you create — like "Region" or "Product" — each with its own values. ### cli #### overview - [Authentication](https://docs.finance.kobana.com.br/en/cli/overview/authentication.md): KOBANA_TOKEN holds one product's credential at a time. A Smart Finance token does not authenticate against any other Kobana product, and vice versa. - [Environment variables](https://docs.finance.kobana.com.br/en/cli/overview/environment-variables.md): Every variable can also be set in a .env file (loaded via dotenvy). - [Exit codes](https://docs.finance.kobana.com.br/en/cli/overview/exit-codes.md): Every kobana invocation exits with one of these codes, so a script can branch on failure class without parsing the JSON error body. - [Installation](https://docs.finance.kobana.com.br/en/cli/overview/installation.md): Homebrew (macOS and Linux) - [Introduction](https://docs.finance.kobana.com.br/en/cli/overview/introduction.md): kobana is a single command-line tool for every Kobana product's API — Smart Finance included. It is built and maintained in its own repository (kobana-cli), not by this product, and it does not hardcode endpoints: at startup it parses the OpenAPI 3.1 specs embedded in the binary and builds its command tree from them. Updating the API surface is a matter of refreshing the embedded spec and shipping a new build — no per-endpoint code. #### resources - [AI agents](https://docs.finance.kobana.com.br/en/cli/resources/ai-agents.md): Instructions the assistant runs on its own, with the permissions of the person who owns the token — say, a daily digest of the payables that became overdue. The list returns only the token person's agents in the workspace, never another member's. Every run spends AI credit and becomes a new assistant conversation (lastrun.conversationid); a destructive action waits for the person's confirmation in the assistant. - [AI skills](https://docs.finance.kobana.com.br/en/cli/resources/ai-skills.md): Instruction sets, in the Agent Skills format, that the assistant loads when a task matches the skill's description — that is all it reads to decide. The list returns the skills the token person can see in the workspace: their own and the ones other members shared with them (is_owner tells them apart; mine=true keeps only their own). - [Attachments](https://docs.finance.kobana.com.br/en/cli/resources/attachments.md): Files — invoice, contract, receipt — uploaded once and linked to one or more bills. links creates that link and unlink undoes it. - [Automatic rules](https://docs.finance.kobana.com.br/en/cli/resources/automatic-rules.md): The rules that classify transactions on their own, evaluated in the order they sit in. reorder is what changes that order. - [Banks](https://docs.finance.kobana.com.br/en/cli/resources/banks.md): The table of supported banks, for filling in an account's or person's bank details. Read-only. - [Cash flow](https://docs.finance.kobana.com.br/en/cli/resources/cash-flow.md): The consolidated projection: realised and forecast income and expenses per bucket, running balance and today's seam. Read-only — it is the result of everything else, not an editable collection. - [Categories](https://docs.finance.kobana.com.br/en/cli/resources/categories.md): The chart of accounts: the income and expense tree every transaction is classified against. - [Classification centers](https://docs.finance.kobana.com.br/en/cli/resources/classification-centers.md): The second classification dimension — cost center, project, branch — used to split one bill across areas. - [Companies](https://docs.finance.kobana.com.br/en/cli/resources/companies.md): The companies in the group. Every account, bill and transaction belongs to one of them, and nearly every filter accepts company_id. - [Custom classifiers](https://docs.finance.kobana.com.br/en/cli/resources/custom-classifiers.md): Classification dimensions the company defines itself — project, contract, branch — next to category and classification center. Each classifier belongs to a company (filter with company_id) and carries its values[] inline; the values are what gets assigned to payables, receivables and transactions. - [Financial accounts](https://docs.finance.kobana.com.br/en/cli/resources/financial-accounts.md): The accounts money moves through — checking, cash, card. Every transaction, payable and receivable points at a financial account, and it is that balance the cash flow projects. - [Transactions](https://docs.finance.kobana.com.br/en/cli/resources/financial-transactions.md): The statement itself: every credit and debit that hit a financial account, classified by category and classification center. The aggregates endpoint returns totals instead of the full list. - [Fiscal documents](https://docs.finance.kobana.com.br/en/cli/resources/fiscal-documents.md): The fiscal documents (NF-e and NFS-e) received against the workspace's companies — through NFE.io, XML upload or SEFAZ. They are read-only: the product never issues notes, so there is no create and no cancellation. The list is sorted by most recent issue date. - [Token identity](https://docs.finance.kobana.com.br/en/cli/resources/me.md): Who is behind the token: the person (user, null on an integration token), the organization and the token's own details. Use it to test that the configured token is valid — it is the first command to run after setting KOBANA_TOKEN. The token itself never comes back in the response. - [Organization](https://docs.finance.kobana.com.br/en/cli/resources/organization.md): The profile of the token's organization, at the top of the hierarchy: it holds for every workspace. The resource is singular — there is no list and no id, because a token always reaches exactly one organization, its own. - [Resources](https://docs.finance.kobana.com.br/en/cli/resources/overview.md): Every finance resource below is generated from the same OpenAPI spec documented in the API Reference — the CLI dispatches to the exact same endpoints, so filters, validation and delete behaviour are identical. Reach for schema introspection whenever a command's exact parameters aren't obvious from the examples here. - [Payables](https://docs.finance.kobana.com.br/en/cli/resources/payables.md): Bills due and already paid, with payment approval, dispatch to the bank and allocation across classification centers. Bills awaiting approval only show up in the listing if you filter by paymentapproval=pendingapproval. - [People](https://docs.finance.kobana.com.br/en/cli/resources/people.md): Customers and suppliers — the counterparty of any bill. ids returns identifiers only, handy to keep an agent's context window small. - [Receipts](https://docs.finance.kobana.com.br/en/cli/resources/receipts.md): The payment receipts the platform generates. Read-only. - [Receivables](https://docs.finance.kobana.com.br/en/cli/resources/receivables.md): What you have coming in, with charge issuing and cancellation through the Banking Gateway straight from the receivable. Moving the money is the charge command — the record itself lives here. - [Reconciliations](https://docs.finance.kobana.com.br/en/cli/resources/reconciliations.md): The link between a statement transaction and the bill it settles. Creating the reconciliation settles the bill; deleting it undoes the settlement. - [Taxes](https://docs.finance.kobana.com.br/en/cli/resources/taxes.md): The taxes withheld or payable attached to a bill. - [Transfers](https://docs.finance.kobana.com.br/en/cli/resources/transfers.md): Moves between two of your own financial accounts. Produces both transactions — out and in — in a single call. #### usage - [Global flags](https://docs.finance.kobana.com.br/en/cli/usage/global-flags.md): | Flag | Description | - [Helpers](https://docs.finance.kobana.com.br/en/cli/usage/helpers.md): Helpers are commands prefixed with + that provide multi-step workflows the dynamic commands alone cannot: simplified interfaces, batch operations, or calls composed across multiple endpoints. They do not wrap a single API call already available through the dynamic commands — every helper flag controls orchestration logic, not a reshaped version of --params/--json. - [Usage](https://docs.finance.kobana.com.br/en/cli/usage/overview.md): Syntax - [Schema introspection](https://docs.finance.kobana.com.br/en/cli/usage/schema.md): Returns parameters, required fields, types and responses — all derived from the embedded OpenAPI spec, so it is always in sync with what a command actually accepts. The path has the same shape as the command: ... ### comprovantes Where payment receipts live — the ones captured on their own and the ones you upload. - [Receipts](https://docs.finance.kobana.com.br/en/comprovantes.md): Where payment receipts live — the ones captured on their own and the ones you upload. ### conciliacao Close each statement line with the bill it pays, or record what is missing — one at a time (Manual) or many at once (Batch). - [Reconciliation](https://docs.finance.kobana.com.br/en/conciliacao.md): Close each statement line with the bill it pays, or record what is missing — one at a time (Manual) or many at once (Batch). ### contas-a-pagar The organization's outgoing commitments — installments, recurrence, taxes and sending to the bank. - [Payables](https://docs.finance.kobana.com.br/en/contas-a-pagar.md): The organization's outgoing commitments — installments, recurrence, taxes and sending to the bank. #### ciclo-de-vida States, transitions and the approval gate — Draft → Pending → Paid. - [Payables lifecycle](https://docs.finance.kobana.com.br/en/contas-a-pagar/ciclo-de-vida.md): States, transitions and the approval gate — Draft → Pending → Paid. #### disparo-kobana Send approved payables to the bank through the Banking Gateway — prerequisites, status and automatic settlement. - [Sending payments to the bank](https://docs.finance.kobana.com.br/en/contas-a-pagar/disparo-kobana.md): Send approved payables to the bank through the Banking Gateway — prerequisites, status and automatic settlement. #### importacao-csv Import batches of payables from a spreadsheet — accepted columns, the forgiving format and the approval gate. - [CSV import — Payables](https://docs.finance.kobana.com.br/en/contas-a-pagar/importacao-csv.md): Import batches of payables from a spreadsheet — accepted columns, the forgiving format and the approval gate. #### operacao-e-pagamento Operation type, document (bank slip, utility bill, tax, PIX), transfer (TED, PIX) or direct debit, and the payment coordinates. - [Operation and payment](https://docs.finance.kobana.com.br/en/contas-a-pagar/operacao-e-pagamento.md): Operation type, document (bank slip, utility bill, tax, PIX), transfer (TED, PIX) or direct debit, and the payment coordinates. #### parcelas-e-recorrencia Split into installments or repeat periodically — the three bill types and how series behave. - [Installments and recurrence](https://docs.finance.kobana.com.br/en/contas-a-pagar/parcelas-e-recorrencia.md): Split into installments or repeat periodically — the three bill types and how series behave. #### tributos DARF, DARE, GRU, GPS, FGTS, ICMS, ISS, IPTU and ITBI — how to enter the tax form and what goes to the bank. - [Tax / tribute](https://docs.finance.kobana.com.br/en/contas-a-pagar/tributos.md): DARF, DARE, GRU, GPS, FGTS, ICMS, ISS, IPTU and ITBI — how to enter the tax form and what goes to the bank. ### contas-a-receber The organization's incoming commitments — installments, recurrence and receiving. - [Receivables](https://docs.finance.kobana.com.br/en/contas-a-receber.md): The organization's incoming commitments — installments, recurrence and receiving. #### ciclo-de-vida States, transitions and receipt — Draft → Pending → Received. - [Receivables lifecycle](https://docs.finance.kobana.com.br/en/contas-a-receber/ciclo-de-vida.md): States, transitions and receipt — Draft → Pending → Received. #### cobranca-kobana Create a bank slip or a Pix charge from a receivable through the Banking Gateway — prerequisites, states and cancellation. - [Bank slip and Pix charges](https://docs.finance.kobana.com.br/en/contas-a-receber/cobranca-kobana.md): Create a bank slip or a Pix charge from a receivable through the Banking Gateway — prerequisites, states and cancellation. #### importacao-csv Import batches of receivables from a spreadsheet — accepted columns and a forgiving format. - [CSV import — Receivables](https://docs.finance.kobana.com.br/en/contas-a-receber/importacao-csv.md): Import batches of receivables from a spreadsheet — accepted columns and a forgiving format. #### parcelas-e-recorrencia Split into installments or repeat periodically — same behavior as payables. - [Installments and recurrence — Receivables](https://docs.finance.kobana.com.br/en/contas-a-receber/parcelas-e-recorrencia.md): Split into installments or repeat periodically — same behavior as payables. ### contas-financeiras The bank and cash accounts of the companies — balance calculated from the transactions. - [Financial accounts](https://docs.finance.kobana.com.br/en/contas-financeiras.md): The bank and cash accounts of the companies — balance calculated from the transactions. ### dashboard The home screen — performance metrics and the cash flow projection. - [Dashboard](https://docs.finance.kobana.com.br/en/dashboard.md): The home screen — performance metrics and the cash flow projection. ### docs-mcp This documentation has its own MCP server. It lets an AI assistant (Claude, - [Docs MCP](https://docs.finance.kobana.com.br/en/docs-mcp.md): This documentation has its own MCP server. It lets an AI assistant (Claude, ### empresas The legal entities (CNPJ) of the workspace — Receita lookup, headquarters and branch. - [Companies](https://docs.finance.kobana.com.br/en/empresas.md): The legal entities (CNPJ) of the workspace — Receita lookup, headquarters and branch. ### extratos-bancarios Import OFX and QIF into the financial account — deduplication, history and undo. - [Bank statements](https://docs.finance.kobana.com.br/en/extratos-bancarios.md): Import OFX and QIF into the financial account — deduplication, history and undo. ### impostos The registry of rates and levies you can link to payables and receivables. - [Taxes](https://docs.finance.kobana.com.br/en/impostos.md): The registry of rates and levies you can link to payables and receivables. ### integracoes Connections to external services — Banking Gateway, Open Finance, Fintera and WhatsApp. - [Integrations](https://docs.finance.kobana.com.br/en/integracoes.md): Connections to external services — Banking Gateway, Open Finance, Fintera and WhatsApp. #### fintera Importing financial data from Fintera — eleven resources, company binding and schedules. - [Fintera integration](https://docs.finance.kobana.com.br/en/integracoes/fintera.md): Importing financial data from Fintera — eleven resources, company binding and schedules. #### kobana Sending payments to the bank and syncing accounts, statements and people via Kobana. - [Banking Gateway integration (Kobana)](https://docs.finance.kobana.com.br/en/integracoes/kobana.md): Sending payments to the bank and syncing accounts, statements and people via Kobana. #### open-finance Connect the company's bank accounts through Open Finance and receive balances and statements automatically. - [Open Finance](https://docs.finance.kobana.com.br/en/integracoes/open-finance.md): Connect the company's bank accounts through Open Finance and receive balances and statements automatically. #### whatsapp Profile pictures for customers and suppliers via the Evolution API — per-company setup. - [WhatsApp integration (Evolution API)](https://docs.finance.kobana.com.br/en/integracoes/whatsapp.md): Profile pictures for customers and suppliers via the Evolution API — per-company setup. ### lancamentos The movements of the financial accounts — money in and money out; the basis for reconciliation. - [Transactions](https://docs.finance.kobana.com.br/en/lancamentos.md): The movements of the financial accounts — money in and money out; the basis for reconciliation. #### importacao-csv Import transactions in bulk from a spreadsheet — inside the financial account, with a Portuguese header. - [CSV import — Transactions](https://docs.finance.kobana.com.br/en/lancamentos/importacao-csv.md): Import transactions in bulk from a spreadsheet — inside the financial account, with a Portuguese header. ### manutencao Data hygiene tools — people (phones, names, duplicates, empty records, and photos) and duplicate transactions. - [Maintenance](https://docs.finance.kobana.com.br/en/manutencao.md): Data hygiene tools — people (phones, names, duplicates, empty records, and photos) and duplicate transactions. ### mcp #### overview - [Authentication](https://docs.finance.kobana.com.br/en/mcp/overview/authentication.md): The MCP server accepts a Bearer token in the Authorization header, and nothing else — no cookie, no client certificate, no token in the URL. A request carrying ?accesstoken= (or ?token=, ?apikey= and the like) is refused with 401 and error="invalid_request", even alongside a valid header: in the URL the token leaks into logs, browser history and intermediaries. - [Clients](https://docs.finance.kobana.com.br/en/mcp/overview/clients.md): Any client that speaks Streamable HTTP MCP and can run the MCP OAuth 2.1 flow can connect. You only provide the URL and the client discovers on its own where to authenticate, opens the Kobana login in the browser and stores the token. See Authentication. - [Endpoints](https://docs.finance.kobana.com.br/en/mcp/overview/endpoints.md): MCP server - [Errors](https://docs.finance.kobana.com.br/en/mcp/overview/errors.md): Failures arrive through two different channels, and the distinction matters: one is a broken request, the other is something the model should read and react to. - [Idempotency](https://docs.finance.kobana.com.br/en/mcp/overview/idempotency.md): The create and update tools accept an idempotency_key argument. It is sent to the endpoint as the X-Idempotency-Key header the REST API already honours — see Idempotency in the API. - [Introduction](https://docs.finance.kobana.com.br/en/mcp/overview/introduction.md): The Smart Finance MCP server is a remote Model Context Protocol server that exposes the public API's operations — payables and receivables, transactions, reconciliations, financial accounts, cash flow and registers — as tools an AI client can call. You connect it by URL; there is nothing to install. - [Listing, Filters and Fields](https://docs.finance.kobana.com.br/en/mcp/overview/pagination.md): The _list tools use the same pagination as the REST API: by cursor*. - [Rate Limit](https://docs.finance.kobana.com.br/en/mcp/overview/rate-limit.md): The MCP server spends the same limits as the REST API, counted per person in the organization — not per token —, plus a limit of its own for the protocol. Minting a new token, or re-authorizing the client, does not reset the budget. - [Resources and prompts](https://docs.finance.kobana.com.br/en/mcp/overview/resources-and-prompts.md): Besides the tools, the server offers three things the client uses on its own: resources (documents you attach to the conversation), prompts (ready-made scripts you pick) and completions (autocomplete for the arguments of both). On 2026-07-28, it also asks for confirmation before running a destructive tool — including the ones that move money. - [Transport](https://docs.finance.kobana.com.br/en/mcp/overview/transport.md): Streamable HTTP, stateless. One JSON-RPC 2.0 message per POST, one JSON response. There is no Mcp-Session-Id, no resumability and no server→client stream: the application runs several replicas, and no operation needs to push messages to the client. #### tools - [Financial accounts and cash flow](https://docs.finance.kobana.com.br/en/mcp/tools/accounts.md): {/ Generated from the tool registry. The names, permissions and endpoints below are the ones tools/list returns. /} - [Payables and receivables](https://docs.finance.kobana.com.br/en/mcp/tools/billings.md): {/ Generated from the tool registry. The names, permissions and endpoints below are the ones tools/list returns. /} - [Attachments, fiscal documents, schemas and workspaces](https://docs.finance.kobana.com.br/en/mcp/tools/documents.md): {/ Generated from the tool registry. The names, permissions and endpoints below are the ones tools/list returns. /} - [Tools](https://docs.finance.kobana.com.br/en/mcp/tools/overview.md): {/ Generated from the tool registry. The names, permissions and endpoints below are the ones tools/list returns. /} - [Registers](https://docs.finance.kobana.com.br/en/mcp/tools/registers.md): {/ Generated from the tool registry. The names, permissions and endpoints below are the ones tools/list returns. /} - [Transactions and reconciliation](https://docs.finance.kobana.com.br/en/mcp/tools/transactions.md): {/ Generated from the tool registry. The names, permissions and endpoints below are the ones tools/list returns. /} ### meus-dados Your account information and how passwordless sign-in works. - [My profile](https://docs.finance.kobana.com.br/en/meus-dados.md): Your account information and how passwordless sign-in works. ### notas-fiscais The fiscal documents (NF-e and NFS-e) received against the workspace's companies — where they come from, how they link to a company, and how they become payables. - [Fiscal documents](https://docs.finance.kobana.com.br/en/notas-fiscais.md): The fiscal documents (NF-e and NFS-e) received against the workspace's companies — where they come from, how they link to a company, and how they become payables. ### pessoas Customers, suppliers and contacts — stackable roles, photos and deletion. - [People](https://docs.finance.kobana.com.br/en/pessoas.md): Customers, suppliers and contacts — stackable roles, photos and deletion. ### regras-automaticas Automatic classification of transactions and bills by criteria you define. - [Automatic rules](https://docs.finance.kobana.com.br/en/regras-automaticas.md): Automatic classification of transactions and bills by criteria you define. ### sdk The SDKs are the official libraries for calling the Smart Finance REST API from Node.js / TypeScript, Python, Ruby and PHP, without building HTTP requests, authentication, pagination and error handling by hand. - [Smart Finance SDKs](https://docs.finance.kobana.com.br/en/sdk.md): The SDKs are the official libraries for calling the Smart Finance REST API from Node.js / TypeScript, Python, Ruby and PHP, without building HTTP requests, authentication, pagination and error handling by hand. ### seguranca Anti-fraud rules for payments and transfers — limits, accounts, payees, operation types and channels, with every change approved by Kobana. - [Security](https://docs.finance.kobana.com.br/en/seguranca.md): Anti-fraud rules for payments and transfers — limits, accounts, payees, operation types and channels, with every change approved by Kobana. ### transferencias Move money between accounts of the workspace — two mirrored transactions. - [Transfers](https://docs.finance.kobana.com.br/en/transferencias.md): Move money between accounts of the workspace — two mirrored transactions. ### workspaces The box that isolates each organization's data — creation, switching and deletion. - [Workspaces](https://docs.finance.kobana.com.br/en/workspaces.md): The box that isolates each organization's data — creation, switching and deletion. --- # Full Documentation Content [Skip to main content](#__docusaurus_skipToContent_fallback) [![Kobana](/en/img/kobana-logo-hor-positivo.png)![Kobana](/en/img/kobana-logo-hor-negativo.png)](https://docs.finance.kobana.com.br/en/en/.md) [**Smart Finance**](https://docs.finance.kobana.com.br/en/en/.md) Documentation [Documentation](https://docs.finance.kobana.com.br/en/en/.md)[API](https://docs.finance.kobana.com.br/en/en/api/overview.md)[MCP](https://docs.finance.kobana.com.br/en/en/mcp/overview/introduction.md)[CLI](https://docs.finance.kobana.com.br/en/en/cli/overview/introduction.md)[SDK](https://docs.finance.kobana.com.br/en/en/sdk.md) Ask AI [](#) * [🇧🇷 Português](https://docs.finance.kobana.com.br/en/pt/search) * [🇺🇸 English](https://docs.finance.kobana.com.br/en/en/search.md) * [🇪🇸 Español](https://docs.finance.kobana.com.br/en/es/search) Search # Search the documentation ![Empresa Neutra em Carbono](/en/img/badge-neutra-carbono.webp)![Empresa Parceira da Natureza](/en/img/badge-parceira-natureza.webp) Comercial[3003-0386](tel:+551130030386) [](https://wa.me/551130030386)[](mailto:comercial@kobana.com.br) ![Kobana](/en/img/kobana-logo-site.webp)![](/en/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 --- # Attachments The **Attachments library** (`/attachments`) holds every file in the workspace — whether or not it is linked to payables, receivables, and transactions. ![Attachments library](/en/assets/images/15-attachments-6f13729d149486183e59e49ca3a0ec28.png) ## Two doors into the same collection[​](#two-doors-into-the-same-collection "Direct link to Two doors into the same collection") Attachments show up in two places, and the difference is the direction you come from: * **The library** (`/attachments`) starts **from the file**: you upload a document and choose which records it belongs to. * **The Attachments section** — inside a payable, a receivable, or a transaction — starts **from the record**: you are on a bill and choose which files to link to it. note **It is the same collection.** Every file you upload lands in the library, including the ones you upload from inside a form. There is no such thing as an attachment private to a record. The link is **many to many**: one file can serve several records, and one record can hold several files. ## Scope[​](#scope "Direct link to Scope") The library covers the **entire workspace**, not a single company. It works with the header selector set to all companies, and a file linked to one company's bill stays visible to the whole workspace. ## Uploading[​](#uploading "Direct link to Uploading") Click **Attach files** and choose a file — drag it onto the drop area or click the area. | | | | ----------- | ---------------------------------------- | | **Formats** | pdf, png, jpg, jpeg, xml, ofx, csv, xlsx | | **Size** | up to 10 MB | A file over the limit is rejected right there: *"File exceeds the 10 MB limit"*. **It is one file at a time**, despite the plural on the button. The system also checks that the **content matches the extension** — a renamed file is rejected. ## The listing[​](#the-listing "Direct link to The listing") Columns: **Name** (the title, when there is one, with the file name below it), **Usage**, **Size**, **Uploaded at**, and **Uploaded by**. A file already linked to a record shows the **Already attached** mark in the Usage column. * **Search** covers **file name or title** — it looks at both, so the file turns up under its original name as well as under the name you gave it. * **Tabs**: **All** and **Already attached**. There is no inverse filter (unlinked only), and none by type, date, or author. * The listing always runs **from the most recent upload to the oldest**, 25 per page. > **Clicking a column header re-sorts only the page on screen**, not the whole library. The icon at the right of each row opens a panel with **the records linked to that file**, each one with a link to open it. It is not a preview of the file. ## Row actions[​](#row-actions "Direct link to Row actions") | Action | What it does | | ---------- | ------------------------------------------------------------------------------------------------------- | | **View** | Opens the file in a new tab. PDFs and images open in the browser; xml, ofx, csv, and xlsx **download**. | | **Edit** | Changes the **Title** — the only editable field | | **Link** | Links (and unlinks) the file to records | | **Delete** | Removes the file from the library | ### Title[​](#title "Direct link to Title") The only field you edit. When set, it appears in place of the file name in the listings; leave it blank and the file name takes over again. There is no description, category, folder, or version, and **you cannot swap the file out** — only the title. ## Linking[​](#linking "Direct link to Linking") **Link** opens a dialog with three tabs — **Payable**, **Receivable**, and **Transaction**. Search by description, tick the records, and confirm. Worth knowing beforehand: * **The selection does not survive a tab change.** Switching tabs clears the ticks, so linking the same file to a bill and to a transaction is two operations. * **The dialog shows the first 25** of each tab, with no pagination. Beyond that, use the search. * **Already linked** records move to the top, ticked and locked. **Unlinking lives here too**: every linked row has a button to undo it. There is no confirmation on this path — the action is immediate. ## Deleting[​](#deleting "Direct link to Deleting") note **A linked file cannot be deleted.** The system refuses and tells you how many records it is tied to: *"Attachment linked to 2 payables, 1 receivable, and 0 transactions."* Unlink it from all of them first. **A payment receipt holds on to its file too.** There is no unlinking there: the receipt owns the file, and the message is a different one — *"This attachment is a receipt's document — delete the receipt to remove the file"*. See [Receipts](https://docs.finance.kobana.com.br/en/en/comprovantes/.md). There is no cascade: deleting never removes the records, and never undoes links on its own. The dialog warns you: *"The file will be permanently removed. If it is linked to any record, unlink it first."* The action shows on every row, including linked ones — in those cases you only find out about the block after you confirm. ## Attaching from inside a record[​](#attaching-from-inside-a-record "Direct link to Attaching from inside a record") In the **Attachments** section of a bill or transaction, the **Attach file** button opens a dialog with two paths side by side: * **Pick from computer** — uploads now. Here the upload fires **as soon as you choose the file**, with no confirm button. * **Pick from library** — grabs a file that already exists. Shows 5 per page, with no search; the ones already attached appear ticked. The footer carries **Go to attachments library**, which takes you to `/attachments`. In this section, **Unlink** asks for confirmation and explains: *"The file stays in the library and on any other records it is linked to."* note **On a bill you haven't saved yet, it depends on how the file got there.** If you **uploaded the file right there** and changed your mind, Unlink deletes it from the library as well — the whole upload is undone, which is what you'd expect from an abandoned creation. If you **took it from the library**, Unlink only releases it from the draft: the file was in the library before you started, and it stays there. --- # API Reference --- # Overview --- # Authentication The Smart Finance API uses a **Kobana Account access token** to authenticate every request. ## The token[​](#the-token "Direct link to The token") The token is an `RS256` JWT issued by the **Kobana authorization server** (`account.kobana.com.br`). This API only **verifies** it, against the public key that server publishes — it holds no signing key and cannot mint a token at all. Checked on every request: | Claim | Requirement | | ----- | ------------------------------------------------------------------------------------------------------------------- | | `iss` | The authorization server's identifier, as a URL: `https://account[.{env}].kobana.com.br` | | `aud` | This API's URL: `https://api.finance[.{env}].kobana.com.br`. May be a **list** — the rule is *contains*, not equals | | `exp` | **Required.** A token without an expiry is refused | | `org` | **The Kobana account** the token acts for. It is what resolves the organization here, and it is **required** | | `sub` | **The person** (`users.public_id`). Carried for audit and attribution; it scopes nothing | | `jti` | Unique token id — the basis for revocation and audit | The **workspace** comes from the `X-Workspace-Id` header: `org` names the organization, and an organization may have several workspaces. It is a **selector, not a grant** — a workspace belonging to another organization is not reachable by guessing its id. Without the header, when there is more than one workspace, the answer is `400 WORKSPACE_REQUIRED`. The exceptions are `GET /v1/me` and `GET`/`PATCH /v1/organization`: they are **organization-level** — they answer for the token's organization and hold for every workspace — and take no such header. :::caution Change from the dashboard-generated token The credential used to be a token generated in the platform, with a secret shown only once. The same value signed and verified it, so a leak on either side was a leak of **issuance** itself. Now the authorization server issues, and this API only verifies. ::: If the authorization server is unreachable, the answer is **`5xx`, never `401`** — a `401` there would send you debugging a perfectly good credential during an outage of ours. ## How to send the token[​](#how-to-send-the-token "Direct link to How to send the token") Include the `Authorization: Bearer ` header on every request. ``` export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx curl -i \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'Content-Type: application/json' \ -H 'User-Agent: My System (contact@mycompany.com)' \ -X GET 'https://api.finance.kobana.com.br/v1/financial-accounts' ``` ## Scopes[​](#scopes "Direct link to Scopes") Scopes have **two axes**: the **resource**, always prefixed by the app (`finance/payables`), and the **access level**, a global scope with no prefix — `read`, `write`, `delete`, `import` or `export`. Every request needs **one** level, given by its HTTP method, on **the resource** the endpoint names; every operation in the reference states the pair as "Requires scope `finance/` with access level ``". | Method | Level needed | | ---------------------- | --------------------------------------------------------------------- | | `GET` | none — the resource scope alone reads | | `POST`, `PUT`, `PATCH` | `write` — sending a payment to the bank and issuing a charge included | | `DELETE` | `delete` — **`write` does not delete** | No level stands in for another: `write` does not delete, and `delete` neither reads nor writes. A level can also apply to one resource only, as `finance/:` (`finance/payables:delete`); only scopes with the `finance/` prefix count. `import` and `export` are for bulk import and export endpoints — this API has none today. Every deletion is a `DELETE`, and every `DELETE` is a deletion. | Resource | Scope | What the read covers | | ------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Financial accounts | `finance/accounts` | accounts and balances | | Bank catalog | `finance/banks` | read-only, there is no write | | Payables | `finance/payables` | payable bills | | Receivables | `finance/receivables` | receivable bills | | Sending to the bank | `finance/payable_dispatches` | the payment dispatches and their state | | Issuing a charge | `finance/receivable_charges` | the charges (bank slip/Pix) issued | | Payment receipts | `finance/receipts` | read-only | | Received fiscal documents | `finance/fiscal_documents` | read-only | | Transactions | `finance/transactions` | entries and transfers | | Reconciliations | `finance/reconciliations` | reconciliations (the write covers create and dissolve) | | Projected cash flow | `finance/cash_flow` | read-only | | Companies | `finance/companies` | | | People | `finance/people` | | | Categories | `finance/categories` | | | Classification centers | `finance/cost_centers` | the scope names the grant, hence `cost_centers` and not `classification-centers` as in the URL | | Automatic rules | `finance/automatic_rules` | the write includes reordering | | Taxes | `finance/taxes` | | | Attachments | `finance/attachments` | the write covers upload and management | | Organization | `finance/settings` | the profile of the token's organization (`/organization`); the write takes the organization owner or access to every workspace | | **Resource catch-all** | `finance/all` | reads **every** resource above — and grants **no verb at all** | Two examples: `finance/payables read` reads payables and cannot write; `finance/payables read write delete` also creates, updates and deletes them, and still cannot reach receivables. The granular form `finance/payables:write` is an **exception** of the grammar, not the default shape: it satisfies both axes for that one resource, and exists for "read one resource, write another". `finance/*` is a **registration-time** wildcard and is never issued in a token — comparison here is always literal. In the per-resource grammar, reading is the resource without a verb; the `read` that does exist is the Kobana Account's **access level**, below. Resolution rules: * `finance/all` reaches **every** resource but grants no level. `finance/all read` reads everything; writing needs the level: `finance/all write`. * `finance/receipts` lists receipts but **does not download the document**: `download_url` points at the attachments resource, so fetching the bytes also requires `finance/attachments`. * `finance/fiscal_documents` lists received notes but **does not download the XML**: `xml_download_url` points at the attachments resource, so fetching the bytes also requires `finance/attachments`. warning **Moving money is a resource of its own, not a level of its own.** Sending a payment to the bank (and cancelling it) and issuing a charge (and cancelling it) are `write` on separate resources: `finance/payable_dispatches` and `finance/receivable_charges`. A token with `finance/payables write` records bills and does **not** dispatch payments. `finance/all write` (or `all write`) reaches both, because the catch-all covers every resource. A token with only the `write` level, with no per-resource scope, reaches nothing. ### Access level[​](#access-level "Direct link to Access level") The scope **is enforced on every route** (only `GET /me` is exempt, so you can test a token). The per-resource scopes above are registered on the Kobana Account, and a personal token carries them according to the resources you checked. Every token also carries the **access level** you granted when authorizing, and it only counts inside the reach of the resource scopes (`finance/…` or `all`). **A token with no resource scope of this app — only levels (`read write`) or only another app's resources (`billing/invoices write`) — reaches nothing**; only `GET /me` answers it. Inside the reach: | Level | What it reaches | | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `read` | reads (`GET`) — the resource scope alone already reads | | `write` | every write (`POST`, `PUT`, `PATCH`), sending payments to the bank and issuing charges included — **it does not delete** | | `delete` | `DELETE`, and only that | | `import` / `export` | bulk import / export (no endpoint today) | **`all` is not an access level.** It is the resource catch-all, the same as `finance/all`: it reaches every resource and grants no verb. `all` alone reads everything; `all write` reads and writes everything; deleting, importing and exporting need the explicit verb (`all delete`). **When the token carries per-resource scopes** — the personal token you create on the Kobana Account, for instance —, **they define the reach**, and the levels apply only inside those resources: `finance/payables read write` reads and writes payables and nothing else; `finance/all read` (or just `all`) reads everything and writes nothing. If either axis is missing, the answer is `403 INSUFFICIENT_SCOPE`, with `required` (the minimal set of scopes to add — the resource first, then the verb: `["finance/payables", "delete"]`), `access` (the request's verb) and `granted` in `details`. A token with no resource scope this API recognizes reaches nothing. :::caution Breaking changes * The old scopes `finance.`, `finance..write`, `finance.all`, `finance.all.write` and the `.dispatch` / `.charge` suffixes **are no longer accepted**: use `finance/` and the access levels. * A `DELETE` requires `delete`: `write` no longer deletes. * A token with only access levels, no `finance/…` scope and no `all`, no longer reaches anything (it used to reach every resource). Ask for the resources too, or `all`. * `all` no longer grants any verb: it is the resource catch-all, like `finance/all`. A token with only `all` now only reads; to write, delete, import or export, ask for the verb too (`all write delete`). * Sending to the bank and issuing a charge require `write` (on the money resource, when the token carries per-resource scopes); `all` is no longer required. * Unlinking an attachment moved from `DELETE /v1/attachments/{id}/links` to `POST /v1/attachments/{id}/unlink`, with the same `{ type, id }` body. * The `details` of `403 INSUFFICIENT_SCOPE` carries `required` as a list: the minimal set of missing scopes (e.g. `["finance/payables", "delete"]`), never empty; `accepted_levels` is gone. ::: ## Best practices[​](#best-practices "Direct link to Best practices") * **Never** commit tokens to git. Use environment variables or secret vaults (AWS Secrets Manager, Vault, etc.). * Use distinct tokens per integration — this makes it easy to rotate/revoke without taking everything down. * Ask for the minimum scopes required (principle of least privilege) — `read` when the integration only reads, `delete` only for whoever deletes, and the money resource (`finance/payable_dispatches`, `finance/receivable_charges`) only for whoever sends to the bank or charges. * Revoke any leaked token immediately. * Always point at `https://` — calls on port 80 are redirected to 443, but clients do not resend the body on a redirect. --- # Data retention This page describes how long each type of data is kept in Smart Finance. ## Active workspaces[​](#active-workspaces "Direct link to Active workspaces") | Data type | Retention | | ------------------------------------- | ------------ | | API Request Logs | 30 days | | Transactions | Indefinitely | | Payables | Indefinitely | | Receivables | Indefinitely | | Financial Accounts | Indefinitely | | Companies and People | Indefinitely | | Categories and Classification Centers | Indefinitely | | Attachments | Indefinitely | | Any data not listed | Indefinitely | ## Inactive workspaces[​](#inactive-workspaces "Direct link to Inactive workspaces") Workspaces without access for an extended period may have their data archived. Contact support for restoration. The times above may change at any time. --- # Endpoints | Environment | Platform (web access) | API (v1) | | -------------- | ------------------------------------------------------------------------------ | ---------------------------------------------- | | **Production** | [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` | This documentation is published at [docs.finance.kobana.com.br](https://docs.finance.kobana.com.br). tip Develop against the **sandbox** and switch to production by changing only the base URL — the contracts are the same. --- # Errors Every error response uses a stable JSON envelope. warning **Branch your logic on `code`, never on the `message` text** — the message is human-readable and may change; the `code` is the contract. ## Envelope[​](#envelope "Direct link to Envelope") ``` { "error": { "code": "VALIDATION_ERROR", "message": "Request body validation failed.", "details": { "issues": [ { "path": "amount", "code": "invalid_type", "message": "Expected number, received string" } ] } } } ``` | Field | Description | | --------------- | ------------------------------------------------------------------------------------------------------------- | | `error.code` | Stable code (table below). Branch on it. | | `error.message` | Human-readable text, in English. **Do not parse.** | | `error.details` | Present on some errors — useful structured data (offending field, reason, missing scope). See examples below. | ## Codes[​](#codes "Direct link to Codes") | `code` | HTTP | When | | ------------------------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BAD_REQUEST` | 400 | Malformed query/body — invalid JSON, unknown filter/operator, invalid cursor, empty filter value, invalid `limit`. | | `INVALID_TOKEN` | 401 | Token missing, malformed, invalid signature, or expired. | | `INVALID_AUDIENCE` | 401 | The token's `aud` is not accepted. | | `TOKEN_REVOKED` | 401 | Token revoked. | | `INSUFFICIENT_SCOPE` | 403 | Valid token, but missing the required scope. `details.required` is the minimal set of scopes to add to the token for the request to pass — the resource scope first (`finance/`, or `finance/all` outside the catalogue), then the verb; never empty, never `all`. `details` also carries `access` and `granted`. | | `UNKNOWN_ORGANIZATION` | 403 | The token's `sub` does not match any workspace. | | `NOT_FOUND` | 404 | Resource does not exist **or is outside your workspace** — due to isolation, a resource from another tenant reads as `404`. | | `CONFLICT` | 409 | State conflict: an identical request still in progress, or a race on a unique constraint. | | `IDEMPOTENCY_KEY_REUSED` | 409 | `X-Idempotency-Key` reused with a different body. Resend the original parameters or generate a new key. | | `VALIDATION_ERROR` | 422 | The body does not satisfy the schema — missing field, wrong type, unknown key. `details.issues` says where. Resending the same body will not help. | | `UNPROCESSABLE_ENTITY` | 422 | Well-formed body that the domain refused — FK outside the tenant, invalid state transition. It may pass once the state changes. | | `RATE_LIMITED` | 429 | Rate limit reached. See [Rate Limiting](https://docs.finance.kobana.com.br/en/en/api/overview/rate-limit.md). | | `INTERNAL_ERROR` | 500 | Unexpected server failure. **Never** carries `details`. Resend with backoff. | ## `details` examples[​](#details-examples "Direct link to details-examples") **Schema validation (422):** ``` { "error": { "code": "VALIDATION_ERROR", "message": "Request body validation failed.", "details": { "issues": [ { "path": "amount", "code": "invalid_type", "message": "Expected number, received string" } ] } } } ``` **Insufficient scope (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 reused with a different body (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." } } ``` --- # Field selection Record reads — the listings and the single-item `GET`s — accept `?fields=` to return only the columns you will use: ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: My System (contact@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": "Rent", "amount": 1500.5, "due_date": "2026-11-10T00:00:00.000Z" } ], "meta": { "next_cursor": null } } ``` Rules: * Comma-separated names, in snake\_case — the same ones the full response carries. * Without the parameter (or with it empty), **every** field comes back. * **`id` always comes back**, even when not requested. * **Top level only**: asking for an object field (`reconciliation`, `classification_centers`) returns the whole object. There is no `object.field` syntax. * A name the resource does not have → `400 BAD_REQUEST`, with `details.unknown` (what was not recognised) and `details.available` (what exists). A wrong name is never silently ignored. * A listing's `meta` is untouched — `next_cursor` is still there. * Combines with [filtering, sorting](https://docs.finance.kobana.com.br/en/en/api/overview/filtering.md) and [pagination](https://docs.finance.kobana.com.br/en/en/api/overview/pagination.md). It does not apply to writes (which return the whole record), to totals (`/aggregates`, `/cash-flow`), to the id sweep (`/ids`) or to the attachment download — there the parameter is refused with `400`. --- # Filtering and sorting Collection `GET` endpoints accept filtering and sorting via query string, on top of [cursor pagination](https://docs.finance.kobana.com.br/en/en/api/overview/pagination.md). **Which fields are filterable and sortable varies by resource** — check each endpoint's [OpenAPI specification](https://docs.finance.kobana.com.br/en/en/api/overview/openapi.md). Here is the common **grammar**. ## Filters[​](#filters "Direct link to Filters") Syntax: `?field=value` (equality) or `?field[operator]=value`. | Operator | Syntax | Meaning | | --------------- | ------------------------------------ | ---------------------------- | | `eq` (implicit) | `?status=paid` or `?status[eq]=paid` | Equal to | | `in` | `?status[in]=pending,paid` | Is in (comma-separated list) | | `gte` | `?due_date[gte]=2026-01-01` | Greater than or equal | | `lte` | `?due_date[lte]=2026-01-31` | Less than or equal | | `gt` | `?amount[gt]=100.00` | Greater than | | `lt` | `?amount[lt]=100.00` | Less than | | `not` | `?status[not]=cancelled` | Not equal to | Rules: * Each resource allows a **subset** of fields and operators; a field or operator outside the allowlist → `400 bad_request`. * `eq` is always allowed when the field is filterable. * An empty value (`?field=` or `?field[in]=`) → `400`. Omit the parameter to not filter. * Multiple filters combine with logical **AND**. ## Sorting[​](#sorting "Direct link to Sorting") `?sort_by=field` picks the field and `?sort_order=asc|desc` the direction (default `asc`). One field at a time; a field outside the allowlist → `400`, and so is `sort_order` without `sort_by`. ## Example[​](#example "Direct link to Example") ``` # Payables of a company, due in January, most recent first curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: My System (contact@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' ``` ## Combining with pagination[​](#combining-with-pagination "Direct link to Combining with pagination") Filters and sorting carry across pages — pass the `cursor` from the previous response together with the **same** filters. See [Listing and Pagination](https://docs.finance.kobana.com.br/en/en/api/overview/pagination.md). --- # Idempotency The API supports idempotency so requests can be safely retried without executing the same operation twice. Useful when a call is interrupted in transit and you don't get a response — for example, a request to create a payable that drops on a network error can be retried with the same key, guaranteeing that only one record is created. ## How to use it[​](#how-to-use-it "Direct link to How to use it") Send the `X-Idempotency-Key: ` header on any `POST`, `PUT`, or `PATCH` request. The key is free-form, generated on your side. We recommend `UUID v4` or any random string with enough entropy to avoid collisions. On **money-moving actions** the header is **required**: sending to the bank, canceling a dispatch, issuing a charge and canceling a charge respond `400 bad_request` (`details.reason = "idempotency_key_required"`) without it. ``` curl -i \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: 8c0f5d6e-3f8b-4cb5-9a47-d8f5b15e9b21' \ -H 'User-Agent: My System (contact@example.com)' \ -d '{ "account_id": "00000000-0000-0000-0000-000000000001", "description": "Rent January/2026", "amount": 3500.0, "due_date": "2026-01-10" }' \ -X POST 'https://api.finance.kobana.com.br/v1/payables' ``` ## How it works[​](#how-it-works "Direct link to How it works") When the server receives a request carrying `X-Idempotency-Key`: 1. **Reserves the key** atomically, scoped to the **workspace**. Two different workspaces can use the same key without conflict. 2. **Computes a request fingerprint** — SHA-256 of `method + path + raw body`. That hash is stored alongside the key. 3. **Runs the handler**. If it returns a response, the server records `status_code`, body, and relevant headers tied to the key. 4. **Marks the key as completed**. Any new request with the same key within **24 hours** receives the original response verbatim — same `status_code`, same body, same headers — plus an `X-Idempotent-Replay: true` header to indicate that it is a replay. warning The layer records the result **regardless of whether it succeeded or failed**. Retries with the same key return the same result, **including `5xx` errors** — to genuinely try again after a server error, generate a new key. ### Limits[​](#limits "Direct link to Limits") * Maximum key length: **255 characters**. * Retention: keys expire automatically **24 hours** after creation. * Scope: per workspace. A key used in one workspace does not interfere with another. * Accepted characters: any printable UTF-8 string. ## Conflicts[​](#conflicts "Direct link to Conflicts") If the same key is reused with a different request (any change in method, path, or body), the API responds `409` with the code `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." } } ``` ## Accepted methods[​](#accepted-methods "Direct link to Accepted methods") | Method | Accepts `X-Idempotency-Key`? | | -------- | ---------------------------------------- | | `POST` | ✅ Yes | | `PUT` | ✅ Yes | | `PATCH` | ✅ Yes | | `GET` | ❌ No (already idempotent by definition) | | `DELETE` | ❌ No (already idempotent by definition) | ## Best practices[​](#best-practices "Direct link to Best practices") * **One key per logical operation.** Don't reuse the same key to create two different resources — you will get `409 IDEMPOTENCY_KEY_REUSED`. * **Persist the key alongside the operation state** on your side, so a retry after a crash or restart uses the same key. * **Pair it with exponential backoff** on `5xx` or timeout responses. * **Clean up the key after 24 hours.** There is no benefit to keeping it on your side beyond that. --- # Introduction You're a dev — have fun! ✨ The Smart Finance API is **REST over HTTPS, with JSON and Bearer authentication**. Everything the screens do with payables, receivables, transactions, records, and reconciliations is available to your systems — under the same per-workspace isolation as the product. ## Getting started[​](#getting-started "Direct link to Getting started") 1. **Generate a token** in the platform, under **Integrations → API Token** — see [Authentication](https://docs.finance.kobana.com.br/en/en/api/overview/authentication.md). 2. **Make your first call**: ``` export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: My System (contact@mycompany.com)' \ 'https://api.finance.kobana.com.br/v1/financial-accounts' ``` 3. **Explore the resources** — the **Resources** category in the sidebar documents every endpoint with examples. Or import the [OpenAPI specification](https://docs.finance.kobana.com.br/en/en/api/overview/openapi.md) / the [Postman collection](https://docs.finance.kobana.com.br/en/en/api/overview/postman.md). tip Prefer the **sandbox** (`https://api.finance.sandbox.kobana.com.br/v1`) for development — see [Endpoints](https://docs.finance.kobana.com.br/en/en/api/overview/endpoints.md). ## Format[​](#format "Direct link to Format") The API accepts only the `JSON` format. All requests must use `Content-Type: application/json`. All responses use `snake_case`. | Field type | Format | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **DateTime** | [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format. Examples — Date: `2026-01-24`. Date and Time: `2026-01-24T10:07Z` | | **Money** | **Decimal string** with 2 places and a dot as the separator, in BRL. e.g.: `"100.00"`. Always sent/received as a string (never a number), to preserve cent precision; up to 13 integer digits. Transactions and bills are always positive — the direction (debit/credit, cost/revenue) goes in `type`/polarity, never in the sign. Account balances may be negative | | **UUID** | Resource identifiers in UUID v4 format | ## Conventions[​](#conventions "Direct link to Conventions") Conventions used in this documentation: | Convention | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`:variable`** | Variable name that must be replaced in a URL. | | **`#{variable}`** | Variable name that must be replaced with values from your account. | | **`...`** | Response content truncated for readability. | | **`$KOBANA_TOKEN`** | Access token. For command-line testing, export it: `export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx` and paste the documentation commands into your terminal. | ## HTTP status codes[​](#http-status-codes "Direct link to HTTP status codes") The API returns standard HTTP codes: | | Code | Description | | -- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | ✅ | **200 OK** | Successful request. Every success response carries a body, including `DELETE`: `{ "data": { "id": "…", "deleted": true } }`. | | ✅ | **201 Created** | Resource created successfully. | | ❌ | **400 Bad Request** | Invalid request, generally malformed content. | | ❌ | **401 Unauthorized** | Missing or invalid access token. | | ❌ | **403 Forbidden** | API access blocked or user lacks permission. | | ❌ | **404 Not Found** | The requested address does not exist. | | ❌ | **409 Conflict** | Conflict with the current state of the resource — e.g. reusing an `X-Idempotency-Key` with a different body. | | ❌ | **422 Unprocessable Entity** | Valid request, but the submitted data is not. | | ❌ | **429 Too Many Requests** | Rate limit reached. | | ❌ | **500 Internal Server Error** | Internal processing error. Check the [server status](https://status.kobana.com.br). | The envelope and the stable vocabulary of error codes are in [Errors](https://docs.finance.kobana.com.br/en/en/api/overview/errors.md). ## Request IDs (Request-Id)[​](#request-ids-request-id "Direct link to Request IDs (Request-Id)") Each request has an associated identifier, available in the `Request-Id` response header. This value helps with debugging and auditing — requests and their IDs can be looked up in the system panel. The request log is available for **30 days**. When opening a support ticket about a specific request, provide the `Request-Id` to speed up the investigation. ## Security[​](#security "Direct link to Security") The Smart Finance API uses **2048-bit SSL** certificates. Every request must be made over **HTTPS** — calls on port 80 are redirected to 443. Clients must support `TLSv1.2` or `TLSv1.3` with one of the following ciphers: `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` and `TLSv1.1` are not supported. ## HTTP Cache[​](#http-cache "Direct link to HTTP Cache") Use HTTP cache headers to reduce load and gain speed. Most responses include `ETag` and/or `Last-Modified` — store these values and resend them in subsequent requests via `If-None-Match` and `If-Modified-Since`. If the resource has not changed, the response will be `304 Not Modified`, with no body and no reprocessing. More information: [HTTP Cache Docs](http://www.mnot.net/cache_docs/). ## Error handling[​](#error-handling "Direct link to Error handling") 5xx errors indicate server failures: **500 Internal Server Error** (application unavailable), **502 Bad Gateway**, **503 Service Unavailable**, and **504 Gateway Timeout** (transient infrastructure failures). Your application should identify these codes and reschedule the request after a few minutes with backoff. Server status: . ## Next steps[​](#next-steps "Direct link to Next steps") * [Specifications](https://docs.finance.kobana.com.br/en/en/api/overview/openapi.md) — OpenAPI 3.1 in YAML for download. * [Endpoints](https://docs.finance.kobana.com.br/en/en/api/overview/endpoints.md) — production and sandbox URLs. * [User-Agent](https://docs.finance.kobana.com.br/en/en/api/overview/user-agent.md) — header to identify your application. * [Rate limiting](https://docs.finance.kobana.com.br/en/en/api/overview/rate-limit.md) — throttling and response headers. * [Listing and pagination](https://docs.finance.kobana.com.br/en/en/api/overview/pagination.md) — cursor and collection envelope. * [Filtering and sorting](https://docs.finance.kobana.com.br/en/en/api/overview/filtering.md) — grammar for `?field[operator]=`, `?sort_by=` and `?sort_order=`. * [Field selection](https://docs.finance.kobana.com.br/en/en/api/overview/fields.md) — `?fields=` to return only the columns you use. * [Idempotency](https://docs.finance.kobana.com.br/en/en/api/overview/idempotency.md) — `X-Idempotency-Key` for safe retries. * [Errors](https://docs.finance.kobana.com.br/en/en/api/overview/errors.md) — envelope and vocabulary of error codes. * [Data retention](https://docs.finance.kobana.com.br/en/en/api/overview/data-retention.md) — retention policy by resource type. --- # OpenAPI The Smart Finance API specification is available in OpenAPI 3.1 format to import into the tool of your choice. ## OpenAPI 3.1[​](#openapi-31 "Direct link to OpenAPI 3.1") | Version | Language | File | | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | v1 | Português | [openapi-v1-pt.yaml](https://docs.finance.kobana.com.br/en/en/assets/files/openapi-v1-pt-9a63c71c25a9b0816c435bf01a39950f.yaml) | | v1 | English | [openapi-v1-en.yaml](https://docs.finance.kobana.com.br/en/en/assets/files/openapi-v1-en-152fe871601f9ff86730d43fa9d0f068.yaml) | | v1 | Español | [openapi-v1-es.yaml](https://docs.finance.kobana.com.br/en/en/assets/files/openapi-v1-es-e15db594e818543214dbd31b2ba92c0b.yaml) | Also available through the API itself in real time, on the production or sandbox host (includes the current server URL): | Format | Endpoint | | ------ | ---------------------- | | YAML | `GET /v1/openapi.yaml` | | JSON | `GET /v1/openapi.json` | ## Postman Collection[​](#postman-collection "Direct link to Postman Collection") Also available as a collection ready to import into Postman. Details and files at [Postman](https://docs.finance.kobana.com.br/en/en/api/overview/postman.md). --- # Listing and pagination Every `GET` endpoint that returns collections uses **cursor**-based pagination. ## Parameters[​](#parameters "Direct link to Parameters") Sent via query string: | Parameter | Type | Default | Description | | --------- | ------------- | ------- | ------------------------------------------------------------------ | | `limit` | integer 1–100 | `25` | Number of items per page. Maximum **100**. | | `cursor` | string | — | Opaque cursor returned in `meta.next_cursor` of the previous page. | ## Response[​](#response "Direct link to Response") Every successful API response comes in `{ data }`. In a listing, `data` is the page's array and `meta` carries the cursor: ``` { "data": [ { "id": "00000000-0000-0000-0000-000000000001", "name": "Conta Corrente" } ], "meta": { "next_cursor": "eyJpZCI6Mn0" } } ``` | Field | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | Array with the items of the current page. On a single resource (`GET /{id}`, `POST`, `PATCH`, `DELETE`) it is the object instead of the array. | | `meta.next_cursor` | Cursor for the next page. `null` when there are no more items. | ## Examples[​](#examples "Direct link to Examples") ### First page[​](#first-page "Direct link to First page") ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: My System (contact@example.com)' \ 'https://api.finance.kobana.com.br/v1/financial-accounts?limit=25' ``` ### Next page[​](#next-page "Direct link to Next page") ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: My System (contact@example.com)' \ 'https://api.finance.kobana.com.br/v1/financial-accounts?limit=25&cursor=eyJpZCI6Mn0' ``` ## Iterating over all pages[​](#iterating-over-all-pages "Direct link to Iterating over all pages") Recommended pattern in pseudocode: ``` 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; } ``` ## Best practices[​](#best-practices "Direct link to Best practices") * `limit=100` minimizes the number of requests and consumes less of the [rate limit](https://docs.finance.kobana.com.br/en/en/api/overview/rate-limit.md). * Apply [filters](https://docs.finance.kobana.com.br/en/en/api/overview/filtering.md) (e.g.: `?company_id=`, `?occurred_at[gte]=2026-01-01`) to reduce the volume before paginating. warning **The cursor is opaque** — don't try to decode it or build it manually. Store it exactly as it came in `meta.next_cursor` and send it back in `?cursor=`. --- # Postman Download the collection in the language of your choice and import it into Postman, or open the online version straight from Kobana's public workspace. ## Public workspace[​](#public-workspace "Direct link to Public workspace") The Smart Finance API v1 collections are published in the [**universokobana/kobana-finance-api**](https://www.postman.com/universokobana/kobana-finance-api/overview) workspace, with one collection per language. ## Online collection[​](#online-collection "Direct link to Online collection") Open it directly in Postman (web or app): [**Smart Finance API (v1.0.0) — Português**](https://www.postman.com/universokobana/kobana-finance-api/collection/46791755-98450bf6-afcd-4de0-8072-7632cad6445b) ## Downloadable collections[​](#downloadable-collections "Direct link to Downloadable collections") Import the `.json` file directly into Postman (**File → Import**): | Version | Language | File | | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | v1 | Português | [postman-v1-pt.json](https://docs.finance.kobana.com.br/en/en/assets/files/postman-v1-pt-2805a6b38f13dd4bdf8c3b8ab53636a5.json) | | v1 | English | [postman-v1-en.json](https://docs.finance.kobana.com.br/en/en/assets/files/postman-v1-en-9bce9f42b878da0bc64550a5d2670a02.json) | | v1 | Español | [postman-v1-es.json](https://docs.finance.kobana.com.br/en/en/assets/files/postman-v1-es-5df4535af8486782d042bb3326191e79.json) | ## Using it[​](#using-it "Direct link to Using it") 1. Download and import the `.json` file into Postman (**File → Import**) — or open the [online collection](#online-collection) directly. 2. Open the collection's **Variables** tab and fill in: * `baseUrl` — production (`https://api.finance.kobana.com.br/v1`) or sandbox (`https://api.finance.sandbox.kobana.com.br/v1`). * `bearerToken` — your JWT, generated in the platform settings under **Integrations → API Token**. 3. `Bearer` authentication comes preconfigured at the collection level, pointing to `{{bearerToken}}`. 4. Open any request, adjust parameters if needed, and click **Send**. --- # Rate limiting Limits run over a **1-hour sliding window** — each request counts against the limit for the next 60 minutes; there is no fixed-time reset — and split into three bands: **read** (`GET`), **write** (`POST`, `PUT`, `PATCH`, `DELETE`), and **money-moving actions**, which get their own, tighter bucket. | Type | Limit | | ---------------------------------------------------------------- | ---------------------- | | Read (`GET`) | **60 requests/hour** | | Write (`POST`, `PUT`, `PATCH`, `DELETE`) | **1000 requests/hour** | | Money-moving (issue/cancel a charge, send/cancel a bank payment) | **60 requests/hour** | Money-moving actions count only against their own band (`throttle_v1_money`), not the write band. If your operation needs a higher limit, talk to support or sales. ## Response headers[​](#response-headers "Direct link to Response headers") On every request, the server attaches to the response headers the limits used and when the count frees up: | Header | Example | Description | | ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `X-RateLimit-Limit` | `60` | Request limit for the client. | | `X-RateLimit-Name` | `throttle_v1_write` | Name of the throttle used. | | `X-RateLimit-Remaining` | `0` | Number of requests still available. | | `X-RateLimit-Reset` | `1782648000000` | [Unix time](https://en.wikipedia.org/wiki/Unix_time) in **milliseconds** — when the count resets. | | `Retry-After` | `30` | Seconds until the count resets. See [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). | ### Example of a successful response[​](#example-of-a-successful-response "Direct link to Example of a successful response") ``` Date: Fri, 17 Jul 2026 12:00:00 GMT Content-Type: application/json; charset=utf-8 X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 486 ``` ### Example of a blocked response[​](#example-of-a-blocked-response "Direct link to Example of a blocked response") When the limit is reached, the server returns `HTTP 429 Too Many Requests`. Wait the number of seconds from the `Retry-After` header before the next request. ``` 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." } } ``` tip Use `limit=100` on [listings](https://docs.finance.kobana.com.br/en/en/api/overview/pagination.md) and the [filters](https://docs.finance.kobana.com.br/en/en/api/overview/filtering.md) to reduce the number of requests — and handle `429` with backoff based on `Retry-After`, never with an immediate retry. Reference: [RateLimit header fields for HTTP](https://ietf-wg-httpapi.github.io/ratelimit-headers/draft-ietf-httpapi-ratelimit-headers.html) --- # User-Agent The `User-Agent` header identifies your integration. Include your name and a valid email address so the Kobana team can reach you if: 1. You're doing something wrong, and we can warn you before blocking; 2. You're doing something really cool, and we can congratulate you 🙂 Example: ``` User-Agent: My Name (myname@example.com) ``` Example of how to pass this header using cURL: ``` curl -i \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'Content-Type: application/json' \ -H 'User-Agent: My Name (myname@example.com)' \ -X GET 'https://api.finance.kobana.com.br/v1/financial-accounts' ``` warning Send this header on **every** request — it is recorded in the API access log and is what identifies your integration when you contact support. --- # Approve payments **Approve payments** (`/payables/approvals`) is the gate into payables: a new bill — created via form, CSV or API — **does not enter the official list** until someone approves it. It is the guard against an improper entry — nothing a person (or the API) creates as a new obligation turns into money going out without a second pair of eyes. It ships **on by default** and can be turned off per workspace (see [Turn it on or off](#turn-it-on-or-off)). ## Where it lives[​](#where-it-lives "Direct link to Where it lives") **Financial** menu → **Approve payments**, right below Payables. The item carries a **badge with the number of bills that still need approval** — the waiting and the partially approved ones, not those already approved or rejected. The number respects the company selected in the header. ## Turn it on or off[​](#turn-it-on-or-off "Direct link to Turn it on or off") Approval is a **workspace setting**, and it ships **on by default**. The control sits on the **Approval Settings** screen, opened by the **gear icon in the top-right corner of this screen** — the **"Require approval"** switch, with the explanation of the two states right below it. | State | What happens when a bill is created | | ---------------- | ----------------------------------------------------------------------------------------------------------------- | | **On** (default) | It enters the queue and only becomes official after someone approves it — everything this page describes applies. | | **Off** | It goes **straight to the official** payables list, skipping this screen. | note The switch governs **new bills only**. Turning it off doesn't release what's already waiting, and turning it on doesn't pull already-official bills into the queue; rejected bills stay blocked. ### Changes go through Kobana[​](#changes-go-through-kobana "Direct link to Changes go through Kobana") ![Approval settings](/en/assets/images/31-payment-approval-settings-1667507d6bcc0e168c74768255ac2883.png) **Nothing on that screen changes right away.** Turning approval on or off, changing the number of approvals, letting the creator approve, sending to the bank after approval and auto-approving batches on the gateway — all of it becomes a **request** that Kobana approves or denies, just like the [Security](https://docs.finance.kobana.com.br/en/en/seguranca/.md#nothing-takes-effect-right-away) rules. * When you confirm the change, the button is **Send for approval**, and the notice says: *"The change takes effect once Kobana approves it."* * The screen always shows the values **in effect**. While a request is under review, it shows *"There is 1 pending request to change these settings"*, with the **View requests** link, which opens the [Requests](https://docs.finance.kobana.com.br/en/en/seguranca/.md#requests) list — where you can follow or cancel the request. * Requesting these changes takes the **Approval settings** permission, which by default only the Owner has. ## How many approvals[​](#how-many-approvals "Direct link to How many approvals") On the same screen, **Approvals required** sets how many **different people** must approve each bill — from 1 (default) to 10. The number can't exceed how many people **with access to the workspace and permission to approve payments** there are: the screen shows that count and blocks the values above it. If someone loses the permission later, the screen warns in red that new bills will be stuck in the queue. With more than one, each approval is recorded and the bill stays **Partially approved** until the last one: it remains **off the official list** and shows up in the tab of the same name, with its progress (*"1 of 2 approvals"*). When the last person approves, it enters the list. If someone **edits the payment** of a bill still awaiting approval — amount, dates, supplier, barcode, Pix or bank details —, the approvals already given are discarded and it goes back to **Waiting**: everyone approves again what changed. Editing the category, classification center or notes leaves the approvals alone. note The number is **frozen when the bill enters the queue**: raising the setting applies to new bills only. **Lowering** it also applies to the ones already waiting — it is the way out when someone loses the permission and the queue asks for more people than are left. Once Kobana approves the reduction, a bill that already has the approvals of the new number enters the list right away. ## What the gate blocks[​](#what-the-gate-blocks "Direct link to What the gate blocks") While it waits for approval, the bill **exists** but sits outside everything: * **Does not appear** in the Payables list * **Does not count** toward totals, overdue amounts, cash flow, reports, or the Dashboard * **Cannot** be sent to the bank * **Takes no** manual settlement — "Mark as paid" does not appear In other words: as far as the rest of the system is concerned, it is not an obligation yet. ## What goes through the gate[​](#what-goes-through-the-gate "Direct link to What goes through the gate") | Origin | Goes through? | | ----------------------------------------------- | ------------------------------------------------------- | | Form (`/payables/new`) | **Yes** | | CSV import | **Yes** | | API | **Yes** | | Publishing a draft | **Yes** — saving as a draft is not a shortcut around it | | Recurrence installments generated automatically | Only while the series still awaits approval | | Bills imported from Fintera | No | | Bills that predate the gate | No | The rule in one sentence: **anything someone creates as a new obligation goes through; anything derived, synced, or legacy is born official.** ## The screen[​](#the-screen "Direct link to The screen") ![Payment approval screen](/en/assets/images/30-payment-approvals-5c5c505e332ca8189388e69fe641f044.png) Four tabs, each with its own counter: | Tab | Lists | | ---------------------- | --------------------------------------------------------------- | | **Waiting** | The queue that needs your ok, ordered by due date | | **Partially approved** | Bills that already got approvals but still wait on other people | | **Approved** | History, most recent first | | **Rejected** | History, most recent first, with the reason | Columns: **Description** (with the supplier below it, and the rejection reason on the Rejected tab), **Origin**, **Due date**, **Status**, and **Amount**. With all companies selected, a **Company** column joins them. The search covers **description and supplier name**. ### Origin[​](#origin "Direct link to Origin") Tells you where the bill came from, and it is the field the decision rests on: * **Manual** — created in the form or through the API * **CSV import** — came from a file ## Approving[​](#approving "Direct link to Approving") On the **Waiting** and **Partially approved** tabs, by three paths: * **The Approve button** on the row itself * **The row's action menu** * **In bulk** — tick the rows and use **Approve selected** (up to 25 at a time) The **Approve payment?** dialog confirms: *"1 payment will be approved and enters the accounts payable list."* When approvals are still missing, it tells you yours will be recorded and that the bill only enters the list once all of them are given. After you approve a bill that still waits on other people, its row shows **"You approved"** instead of the button. note **Approving does not send anything to the bank.** The bill becomes official and enters the list — sending is a separate step, done in Payables. See [Bank dispatch](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md). In a bulk approval, one isolated failure does not take the others down. ## Rejecting[​](#rejecting "Direct link to Rejecting") Through the **row's action menu** — there is no inline rejection and no bulk rejection. A partially approved bill can be rejected too: one person rejecting is enough. The **Reject payment?** dialog warns you: *"The bill is blocked forever and never enters the accounts payable list. Record the reason (optional)."* The **reason is optional** (up to 500 characters), but it is what the Rejected tab will show later — without it, the history does not explain the decision. danger **Rejecting cannot be undone through the interface.** A rejected bill cannot be approved afterwards and cannot go to the bank. It stays on the Rejected tab as a record, and nothing more. The **Approved** and **Rejected** tabs have no actions — they are an audit trail. Clicking the description opens the bill. ## Who can approve[​](#who-can-approve "Direct link to Who can approve") **Anyone with access to the workspace and permission to approve**, with two locks: * **Whoever created the bill cannot approve it** — unless they are the workspace's **only member**. Alone, there is nobody to ask for the approval, so the screen says *"You are the only member of this workspace, so you can approve the payments you created yourself. Once someone else joins, approval will again require someone other than the payment's creator."* and lets you approve. The lock comes back by itself once someone else gains access to the workspace. A member who is suspended or whose access is paused still counts; only removing the member frees the approval. * **Each person counts once.** When the workspace requires more than one approval, they must come from different people. Approving is also **not exposed in the API** — it is a screen-only action. ### Night and per-channel approval[​](#night-and-per-channel-approval "Direct link to Night and per-channel approval") The workspace's [Security](https://docs.finance.kobana.com.br/en/en/seguranca/.md) can restrict **when** and **through where** approvals happen: * **Night period** — with **Allow approvals at night** off, the screen shows *"Approvals are blocked during the night period. They are allowed again at 06:00."* (with your workspace's hour) and disables the approve buttons, on the row and in bulk. * **Channel** — with **Approve** off for the channel in use, it shows *"This workspace's Security settings don't allow approving payments through this channel."* **Rejecting is never blocked** — not at night, not by channel. The night rule applies only to approvals made by people: recurrences, ERP imports and the gateway batch approval are not approvals of this gate. ### Sending blocked by Security[​](#sending-blocked-by-security "Direct link to Sending blocked by Security") When a bill, as it stands, **won't be able to go to the bank** — operation type off, account blocked, payee not allowed, amount above the per-transaction limit —, the row shows the **"Sending blocked by Security"** badge: *"As it is, this bill won't be sent to the bank. Ask for it to be allowed in Security."* Approving is still possible; the badge only warns that dispatch will be held back. ## Editing an approved bill[​](#editing-an-approved-bill "Direct link to Editing an approved bill") An approval covers the payment **as it was seen**. With approval on, if someone changes any of these fields on a bill that is **approved and not yet sent** to the bank, it **goes back to the queue** (**Waiting**), with its approvals reset, and leaves the Payables list until it is approved again: * amount; * supplier; * payee — name, CPF/CNPJ, Pix key, key type and bank details; * barcode or typeable line; * source account ("Pay from"); * operation type and payment method; * tax data. This also applies to edits made through the API. Dates, interest, discounts, category, classification center and notes don't send the bill back to the queue. Once the bill is **sent to the bank**, those fields are **locked** — see [Editing after dispatch](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md#editing-after-dispatch). ## How the state shows up in Payables[​](#how-the-state-shows-up-in-payables "Direct link to How the state shows up in Payables") In the Payables listing, an approved bill shows a **round badge with a shield**; hover it to read **"Creation approved"**, followed by who approved it and when — that is where the audit trail is at hand, without opening the bill. The other states do not appear there — by the gate's own rule, they never reach the list. Once the bill is sent to the bank, the badge gives way to the gateway status. --- # Cards Cards (`/credit-cards`, menu **Movements › Cards**) follows the cards of the workspace's companies: which statement each purchase falls on, how much of the limit is used, the installments and subscriptions still to come, the IOF on international purchases, the review against the bank's statement and the payment. ![Card list with each card\'s statement, the limit used and the closed statement to pay](/en/assets/images/36-credit-cards-c2007cf4bbd137bc2988f881ba20d535.png) ## In this section[​](#in-this-section "Direct link to In this section") ## [📄️Register and convert](https://docs.finance.kobana.com.br/en/en/cartoes/cadastrar-e-converter.md) [Register a card with a new account, convert an existing credit account, and the statement preview the form works out as you type.](https://docs.finance.kobana.com.br/en/en/cartoes/cadastrar-e-converter.md) ## [📄️Statement and closing](https://docs.finance.kobana.com.br/en/en/cartoes/fatura-e-corte.md) [The card screen — statements by month, the statement header, the entries, the predicted and the confirmed closing date, and the history.](https://docs.finance.kobana.com.br/en/en/cartoes/fatura-e-corte.md) ## [📄️Entries and IOF](https://docs.finance.kobana.com.br/en/en/cartoes/lancamentos-e-iof.md) [Enter one-off, installment and international purchases, refunds and interest and fees — which statement each falls on, the IOF and the exchange rate, editing a series, moving and anticipating.](https://docs.finance.kobana.com.br/en/en/cartoes/lancamentos-e-iof.md) ## [📄️Recurrences](https://docs.finance.kobana.com.br/en/en/cartoes/recorrencias.md) [Subscriptions charged to the card — the expected charges on each statement, confirming the real amount, not charged, the suggestion to update the amount, editing and ending.](https://docs.finance.kobana.com.br/en/en/cartoes/recorrencias.md) ## [📄️Close, review and pay](https://docs.finance.kobana.com.br/en/en/cartoes/fechar-conferir-pagar.md) [The automatic closing and the statement's payable, the review against the bank's total, paying in full or in part, undoing, reopening, the prepaid top-up and the card in the cash flow.](https://docs.finance.kobana.com.br/en/en/cartoes/fechar-conferir-pagar.md) ## [📄️Reports](https://docs.finance.kobana.com.br/en/en/cartoes/relatorios.md) [IOF paid on international purchases, by month, card, category or supplier, and the recurrences' forecast vs. actual — exported as CSV or XLSX.](https://docs.finance.kobana.com.br/en/en/cartoes/relatorios.md) ## The three types[​](#the-three-types "Direct link to The three types") | Type | How it works | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Credit** | One statement a month. On closing, the statement becomes a [payable](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/.md) and the payment leaves the account that pays the statement. It has a limit. | | **Prepaid** | Topped up from a bank account; purchases come out of the balance. The limit is the balance itself. The statement closes with no payable. | | **Benefit** | Works like the prepaid card (meal or food vouchers). | ## The card and your accounts[​](#the-card-and-your-accounts "Direct link to The card and your accounts") Every card has a **Credit** account in [My accounts](https://docs.finance.kobana.com.br/en/en/contas-financeiras/.md): created with the card, or an existing credit account that was converted (see [Register and convert](https://docs.finance.kobana.com.br/en/en/cartoes/cadastrar-e-converter.md)). Each purchase entered on the card shows up **once** in the rest of the system: | Where | What shows up | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Transactions** | The purchase, on its date and in its category, with the **Card** badge. The statement payment is a transfer, with the **Statement payment** badge; a prepaid top-up, with the **Top-up** badge. | | **My accounts** | The card account's balance is the debt: purchases lower it, the payment brings it back. | | **Dashboard** | Purchases count as expenses on their purchase date; the statement payment, being a transfer, does not count again. | | **Cash flow** | The card is not cash. The outflow is the statement payment, on the due date, from the account that pays the statement. See [Close, review and pay](https://docs.finance.kobana.com.br/en/en/cartoes/fechar-conferir-pagar.md#in-the-cash-flow). | | **Payables** | The closed statement becomes a payable, with the **Card statement** source. | note **What came from the card is changed through the card.** On [Transactions](https://docs.finance.kobana.com.br/en/en/lancamentos/.md), the purchase shows its edit, classify, reconcile and delete actions disabled, with the reason at the foot of the menu: *"Card entry: change it through the card."* **"Open in the card"** goes straight to its statement. The same goes for the two legs of the payment (*"Statement payment: undo it from the card's statement."*) and of a top-up (*"Card top-up: delete it through the card."*). ## The list[​](#the-list "Direct link to The list") Each card is a tile, in the order of the next due date: * **Nickname**, brand and, on prepaid and benefit cards, the type. Below, the issuing bank, the product and the last digits (`···· 4821`). * **The closed statement still to pay**, highlighted: the amount, the due date (*"due 11/09 · in 4 days"*) and the **Pay** button, which opens the payment on the statement itself. * **The current statement** — *"Dec/26 statement"*, its status, the expected total and *"closes 12/02 · due 12/09"*. * **The limit bar** — *"Used R$ 22.007,75 of R$ 60.000,00"* and the percentage. The bar turns yellow from the **Limit alert** set on the card and red above 100%. * On prepaid and benefit cards, instead of the statement and the limit: **Balance**, how much was used and the **Top up** button. * At the foot, where the money comes from: *"Paid from Itaú — Conta Corrente · Direct debit"*, or *"Topped up from …"*. The **⋯** menu of each tile has **Edit card** and **View the account in My accounts**. At the top: the search (*"Search by nickname or last digits"*), the **Active**, **Blocked**, **Cancelled** and **All** tabs with their counts, the **Report** pill (see [Reports](https://docs.finance.kobana.com.br/en/en/cartoes/relatorios.md)) and **New card**. If the workspace has Credit accounts that are not cards yet, a notice at the top of the list offers **Convert into a card**. ## Card status[​](#card-status "Direct link to Card status") **Active**, **Blocked** or **Cancelled**, on the card itself. The field's (i) icon explains: *"A cancelled card stops generating new statements. Cards are not deleted, because their statements stay as history."* ## Permissions[​](#permissions "Direct link to Permissions") In the role editor, the module has three groups: **Credit cards**, **Card transactions** and **Card statements**. | To | You need | | ------------------------------------------------------------------ | ------------------------------------------------------ | | See the list | Credit cards › **List** | | Open a card, its statements, history and reports | Credit cards › **View details** | | Register, convert and edit a card | Credit cards › **Create** / **Edit** | | Enter, edit, move, anticipate and delete purchases and recurrences | Card transactions › **Create** / **Edit** / **Delete** | | Change the closing date and review the statement | Card statements › **Edit** | | Close and reopen the statement | Card statements › **Close and reopen** | | Pay, undo the payment and top up | Card statements › **Pay** | As everywhere in the product, the screen does not hide a button from someone without the permission: the system refuses the action on save. ## Through the API and MCP[​](#through-the-api-and-mcp "Direct link to Through the API and MCP") Everything in this section is also on API v1 — [cards](https://docs.finance.kobana.com.br/en/en/api/v1/list-credit-cards), [statements](https://docs.finance.kobana.com.br/en/en/api/v1/get-card-statement), [entries](https://docs.finance.kobana.com.br/en/en/api/v1/list-card-transactions), [recurrences](https://docs.finance.kobana.com.br/en/en/api/v1/list-card-recurrences) and [IOF rates](https://docs.finance.kobana.com.br/en/en/api/v1/list-iof-rates) — and in the [MCP server tools](https://docs.finance.kobana.com.br/en/en/mcp/tools/accounts.md#credit_cards). None of them ever takes the full card number: only the last 4 digits. --- # Register and convert **New card** (`/credit-cards/new`) opens the form as a page. On the right, the **Statement preview** panel shows, as you type, the best purchase day and the next statements with their closing and due dates. ![Card form with the statement preview beside it](/en/assets/images/38-credit-card-form-35e43a8ef7a247a48dcc54211fbbd897.png) **The (i) icon next to a field's name explains the field.** Hover over it, or reach it with Tab, to read the explanation. In the tables below, the texts marked (i) are those. ## New account or conversion[​](#new-account-or-conversion "Direct link to New account or conversion") The first block, **Card account**, decides which account in My accounts holds the card's entries: | Option | What it does | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Create a new account** | *"We create a credit-type account for this card in My accounts, with its nickname and bank."* A card has no branch or account number, so the account is created without them. | | **Convert a credit account** | *"A credit-type account you already have gets statements and stays in My accounts. The company is the account's, and the issuing bank comes filled in from it."* Only Credit accounts that are not cards yet are offered. | The notice on the card list, *"… is a credit account that is not a card yet"*, goes straight to the conversion with the account already picked. A converted account cannot be converted again into another card. warning **A purchase entered in both places counts twice.** *"Transactions already in … stay there. To avoid counting a purchase twice, pick a start date after the last transaction made in that account."* Converting neither moves nor deletes the account's history: it stays in the account as it was, and the statements start with the one that includes the **Start date**. ## Identification[​](#identification "Direct link to Identification") | Field | Notes | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Type** | **Credit**, **Prepaid** or **Benefit**. It does not change after registering. | | **Nickname** | Required, up to 60 characters. The card's name across the product. | | **Issuing bank** | Required, from the bank list. | | **Brand** | Required: Visa, Mastercard, Elo, American Express, Hipercard or Other. | | **Product name** | Optional (*"E.g. Black, Infinite"*). | | **Last 4 digits** | Required. (i) *"For security, we keep only the last 4 digits. The full card number is never saved."* | | **Status** | Active, Blocked or Cancelled. (i) *"A cancelled card stops generating new statements. Cards are not deleted, because their statements stay as history."* | danger **A full card number is refused in every text field.** Nickname, product, description and notes reject a digit run that looks like a card number — so a number pasted by mistake is never stored. CVV and expiry date do not exist on the form. ## Statement dates[​](#statement-dates "Direct link to Statement dates") | Field | Notes | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Closing day** | 1 to 31. In a shorter month, the last day. (i) *"The day the bank closes the statement. Purchases up to that day go on that month's statement; from the next day on, on the following one."* | | **Early closing (days)** | 0 to 15. (i) *"Some banks close the statement a few days before the closing day. If yours does, enter how many days. E.g. closing day 10 and 2 days early: purchases up to the 8th go on this statement. If unsure, leave 0."* | | **Due day** | 1 to 31. (i) *"The day the statement is due. If it falls on a weekend or holiday, the Due date on a non-business day rule applies."* | | **Due date on a non-business day** | Next business day, previous business day, or keep the date. | | **Start date** | (i) *"Statements start with the one that includes this date. Earlier purchases are not added to the card."* A past date creates the statements from it on. | **How the dates come out.** A statement is named after the **month of its due date**. The closing falls in the same month when the closing day comes before the due day (closes on the 2nd, due on the 9th: both in December); when it comes after, it falls in the previous month (closes on the 25th, due on the 5th: closing in November, due in December). The closing is **inclusive**: a purchase made on the closing day itself still goes into the statement. With **Early closing (days)**, each statement's closing date is the closing day minus those days. **Business days** follow the banking calendar: Saturdays, Sundays, the national holidays and the movable ones around Easter — Carnival Monday and Tuesday, Good Friday and Corpus Christi. On the panel, an adjusted due date carries the warning *"01/09 is not a business day"*. ### The Statement preview panel[​](#the-statement-preview-panel "Direct link to The Statement preview panel") * **Best purchase day** — the day after the closing: *"Purchases from 12/03 go into the Jan/27 statement, due on 01/11: the longest time to pay."* * **The next three statements**, with closing date, due date and the weekday of each. * On registering, *"First statement in the system: … (purchases from … to …)."* and, at the foot, *"On saving, we create the current statement and the next 12."* The panel runs the same rules as the server: the dates it shows are the dates the statements will have. ### Changing the dates later[​](#changing-the-dates-later "Direct link to Changing the dates later") *"Changing the closing or due day recalculates the upcoming statements whose closing date is not confirmed yet, and the entries move to the right statement."* Open, closed and paid statements do not change, and neither do future ones whose closing date someone already confirmed. To fix the closing date of a single statement, use **Change closing date** on it — see [Statement and closing](https://docs.finance.kobana.com.br/en/en/cartoes/fatura-e-corte.md#change-the-closing-date). ## Limit and payment[​](#limit-and-payment "Direct link to Limit and payment") | Field | Notes | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Limit** | Credit cards only. With no limit, the tile shows no bar. | | **Limit alert** | (i) *"The limit bar turns yellow when usage goes past this percentage. E.g. 80%."* | | **Account that pays the statement** | (i) *"The bank account, of the same company, the statement payment leaves from. Each statement's payable comes with it."* On a prepaid card the field is called **Account for top-ups**. | | **Payment method** | Direct debit, Boleto or Pix. (i) *"How the statement is usually paid. It goes on each statement's payable."* | | **Statement supplier** | (i) *"Who shows as the supplier on each statement's payable. Left blank, we use the issuing bank."* | | **Default category** · **Default classification center** | (i) *"Comes filled in on each new card entry. You can change it on the entry."* | On prepaid and benefit cards the limit is not typed: *"On prepaid and benefit cards, the limit is the loaded balance: each top-up raises it."* ## International purchases[​](#international-purchases "Direct link to International purchases") | Field | Notes | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **IOF rate** | (i) *"Left blank, each purchase uses the official rate in force on its date. Fill it in only if your bank charges a different rate."* | | **Bank spread** | In percentage points (4 = 4%). (i) *"The percentage the bank adds to the official exchange rate (Central Bank PTAX) on international purchases. We use it to estimate the rate until the statement arrives."* | See [Entries and IOF](https://docs.finance.kobana.com.br/en/en/cartoes/lancamentos-e-iof.md#international-purchase). ## After saving[​](#after-saving "Direct link to After saving") **Register card** (or **Convert into a card**) creates the open statement and the next 12 and opens the card. From then on, every night, the system closes the statement whose closing date has passed and opens the next one — see [Close, review and pay](https://docs.finance.kobana.com.br/en/en/cartoes/fechar-conferir-pagar.md). To edit, use the pencil next to the card's name or **Edit card** on the tile's menu. When editing, **Type** and company do not change, and the **Start date** only moves back. ### Adding an earlier statement[​](#adding-an-earlier-statement "Direct link to Adding an earlier statement") To add the purchases of a statement from before the card was registered (the PDF of a statement already due, for instance), edit the card and move the **Start date** back to the start of that statement's period — at most 24 months back. (i) *"Move the date back to add purchases from earlier statements: the statements from it on are created, and the ones past their closing close in the daily routine."* The oldest one stays open to take the entries; the next night, the system closes the ones past their closing date, each with its payable on its own due date, and opens the current statement again. Without this, an entry dated before the first statement is refused: *"The date is before the card's first statement in the system. To add it, move the card's start date back."* --- # Statement and closing Clicking a card opens its screen (`/credit-cards/`), with two tabs at the top: **Statements** and **Recurrences** (see [Recurrences](https://docs.finance.kobana.com.br/en/en/cartoes/recorrencias.md)). The **Report** pill, to the right of the tabs, opens the [reports](https://docs.finance.kobana.com.br/en/en/cartoes/relatorios.md) already filtered by this card. ![Open statement with installments, an international purchase with IOF and expected recurring charges](/en/assets/images/37-credit-card-statement-23e11291ebb61bc2169a506a5b36a32e.png) ## The card header[​](#the-card-header "Direct link to The card header") The nickname, the brand and the edit pencil; below, the type, the issuing bank, the product, the last digits and the account that pays the statement. On the right, the **Available limit** with the *"Used … of …"* bar — on prepaid and benefit cards, the **Balance** and the **Top up** button. And the **New entry** button (see [Entries and IOF](https://docs.finance.kobana.com.br/en/en/cartoes/lancamentos-e-iof.md)). ## Statements, month by month[​](#statements-month-by-month "Direct link to Statements, month by month") A strip of tabs shows six statements at a time, each with its month and a coloured dot for its status; the arrows bring the earlier and the later ones. The screen opens on the **Open** statement, and the one you pick stays in the address (`?statement=2026-12`), so you can send a link to a specific statement. | Status | What it means | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- | | **Future** | Not started yet. It already receives installments and expected recurring charges, and its closing date can already be confirmed. | | **Open** | The current cycle: it receives the purchases. There is only one per card. | | **Closed** | The closing date has passed. On a credit card, it already has a payable. | | **Reviewed** | The total matched the bank statement's. | | **Paid** | The payment covered the total. The entries become **Reconciled**. | | **Partially paid** | Less than the total was paid; the rest went to the next statement. | ## The statement header[​](#the-statement-header "Direct link to The statement header") *"December 2026 statement"* and its status, with a row of figures. The fields with the (i) icon explain the figure on hover: | Field | What it shows | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Period** | From the day after the previous closing to this statement's closing date. (i) *"Purchases made in this period go on this statement."* | | **Closing** | The date, with the **Predicted** or **Confirmed** badge and, on an open or future statement, the pencil to change it. (i) *"The last day of purchases on this statement. It stays predicted until you confirm the date shown in your bank's app."* | | **Due date** | Already moved to a business day. | | **Expected total** | What is on the statement: realized, expected and IOF, minus refunds, plus the previous balance. Not charged and cancelled entries are left out. (i) *"The sum of this statement's entries, with IOF and net of refunds."* | | **Bank total** · **Difference** | After the review: the bank statement's total and how far it is from matching. (i) on **Bank total**: *"The total shown on the bank's statement, entered when reviewing the statement."* | Below, a line says what comes next: * Open: *"Closes automatically overnight on 12/03/2026 and creates a R$ 6.348,80 payable due 12/09."* * Future: *"Future statement: it already receives installments and expected recurring charges. Its closing date can already be confirmed."* * Closed or reviewed: the payable, with its status and due date — and, if the total did not match, *"The bank total does not match: check the entries and add what is missing."* * Paid: *"Paid on 10/08/2026: R$ 10.142,65 from Itaú — Conta Corrente. The entries are reconciled."* ### Statement actions[​](#statement-actions "Direct link to Statement actions") The buttons change with the status: | Action | Shows on | | --------------------------------- | ------------------------------------------------------------------ | | **Change closing date** | Open and future (also through the closing pencil) | | **Confirm recurring charges (n)** | Future, open and closed, when there are expected recurring charges | | **Close statement now** | Open | | **Review against the bank** | Closed (highlighted) and reviewed | | **Pay statement** | Closed and reviewed, on a credit card | | **Undo payment** | Paid and partially paid | | **Reopen** | Closed, reviewed, paid and partially paid | | History (clock icon) | Always | Closing, reviewing, paying, undoing and reopening are in [Close, review and pay](https://docs.finance.kobana.com.br/en/en/cartoes/fechar-conferir-pagar.md). ## The statement's entries[​](#the-statements-entries "Direct link to The statement's entries") The table lists what is on the statement, with the **Date**, **Description** (with the supplier below), **Category**, **Installment**, **Expected**, **Realized**, **IOF**, **Total** and **Status** columns. The first row adds up the statement: the number of entries and the total of each amount column, without the not charged and the cancelled ones. * A recurrence's **expected** charge shows in grey italics, with the **Recurring** badge, until it is confirmed. * An international purchase carries the currency badge (**USD**) and, below the amount, the calculation: *"$135.00 × 5.4700 estimated"*. The IOF has its own column, with the rate. * A refund shows the **Refund** badge and a negative amount. * Not charged and cancelled entries are struck through. * An entry moved here manually shows a padlock: *"Moved here manually: it stays on this statement even if the closing date changes."* The search (*"Search by description or supplier"*), the **Type** and **Category** filters and the **All**, **Expected** and **International** tabs, each with its count. Each row's menu is in [Entries and IOF](https://docs.finance.kobana.com.br/en/en/cartoes/lancamentos-e-iof.md#the-entry-menu). ## Change the closing date[​](#change-the-closing-date "Direct link to Change the closing date") Banks do not always close the statement on the same day. Each statement keeps **its own** closing: it starts **Predicted**, worked out from the card's dates, and becomes **Confirmed** when someone checks the date in the bank's app or statement. **Change closing date** (or the closing pencil) opens *"Closing date · … statement"*, with the current date (**Predicted closing** or **Confirmed closing**) and the **Closing date at the bank** field. *"Purchases made up to the closing date, inclusive, stay on this statement. From the next day on, they go to the following one."* Once you pick the date, the dialog shows **before applying** what will happen: * *"3 entries change statement"*, each one with where it goes; * *"The Jan/27 statement starts on …"*; * or, when nothing changes, *"No entry changes statement."* Keeping the same date as the predicted closing moves nothing: *"No entry changes statement: the closing just becomes Confirmed."* — and the button reads **Confirm date**. With another date, **Apply new date**. *"The change goes into the statement history, with who made it."* note **What follows the change and what does not.** Installments follow the first one: if installment 1 changes statement, the next ones move with it, one statement after the other. An entry **moved manually** stays where it is, and so does the **previous balance** of a partial payment. A closed statement never gains or loses an entry through a closing date change. **The limits.** The new closing date cannot come before the start of the statement's period nor reach the next statement's closing date. A closed, reviewed or paid statement does not accept a change: reopen it first (see [Reopen](https://docs.finance.kobana.com.br/en/en/cartoes/fechar-conferir-pagar.md#reopen)). warning **The statement closes on the predicted date if nobody confirms it.** The overnight automatic closing does not wait for the confirmation. If the bank closed after the predicted date, the purchases of those days fall on the next statement; to fix it, reopen the statement and change the closing date. ## Statement history[​](#statement-history "Direct link to Statement history") The clock icon opens the statement's **History**: *"Everything that happened on this statement, newest first, with who did it and from where."* | Event | How it shows | | ---------------------- | -------------------------------------------------------------------------- | | Closing date confirmed | *"Closing date confirmed: 12/02"* | | Closing date changed | *"Closing date changed from 12/02 to 12/04 · 3 entries changed statement"* | | Closed | *"Closed · total R$ 8.908,95 · payable created"* | | Reviewed | *"Reviewed: bank total R$ 8.908,95"* | | Reopened | *"Reopened (was Paid)"* | | Paid | *"Paid: R$ 8.908,95 from Itaú — Conta Corrente"* | | Payment undone | *"Payment undone: R$ 8.908,95"* | What the automatic closing did shows as **System**; the rest, with the e-mail of who did it and the channel (screen, API or MCP). --- # Close, review and pay ## Close[​](#close "Direct link to Close") **The statement closes automatically.** Every night the system closes the open statement whose closing date has passed and opens the next one. The open statement's line says when: *"Closes automatically overnight on 12/03/2026 and creates a R$ 6.348,80 payable due 12/09."* **Close statement now** does it earlier: *"Creates the … payable due … now. If you don't close it, it closes automatically overnight on …. Purchases for this statement entered after closing go to the next open statement."* ### The statement's payable[​](#the-statements-payable "Direct link to The statement's payable") On a credit card, closing creates a [payable](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/.md): | Field | Value | | ----------------------- | ----------------------------------------------------------------- | | Description | *"Fatura Itaú Empresas Visa — 11/2026"* | | Supplier | The card's **Statement supplier**, or the issuing bank | | Amount | The statement total | | Due date and competence | The statement's due date | | Pay via | The **Account that pays the statement**, from the card's settings | | Payment method | The card's | | Category | None: each purchase is already in its own category | It shows up on Payables with the **Card statement** source. With [payment approval](https://docs.finance.kobana.com.br/en/en/aprovar-pagamentos/.md) on, it enters the approval queue like any payable. warning **The amount of that payable is the statement's.** It changes through the review (it becomes the bank's total) and through a partial payment — never by editing the payable, which refuses an amount change. It cannot be deleted while the statement exists either. Description, due date and the rest stay editable. Prepaid and benefit cards close **without** a payable, and so does a statement whose total is zero or negative. ## Review against the bank[​](#review-against-the-bank "Direct link to Review against the bank") With the bank statement at hand, **Review against the bank** opens *"Review against the bank statement"*: the **System total**, the live **Difference**, the **Bank statement total** and the **Minimum payment** (optional). | Result | What happens | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | It matches | *"It matches: the statement becomes Reviewed and the payable changes to …."* | | It does not match | *"It does not match: the figures are saved and the statement stays Closed, showing the difference, until what is missing is entered."* | To make it match: enter what was missing (a purchase that came late, interest and fees, a refund), confirm the recurring charges with the real amount, or adjust the rate of the international purchases. Then review again. ## Pay[​](#pay "Direct link to Pay") **Pay statement** — on a closed or reviewed statement, or through **Pay** on the list tile — opens the payment: ![Pay the closed statement, in full or another amount](/en/assets/images/40-card-pay-statement-dcc839eaddd7447f4e902571856d0d59.png) | Option | What it does | | ---------------- | ------------------------------------------------------------------------------------------------- | | **Full** | *"Settles the statement."* | | **Minimum** | Only when the minimum payment was entered in the review. *"The rest goes to the next statement."* | | **Other amount** | Any amount up to the statement total. | **Paid from** is the account that pays the statement (you can change it) and **Payment date** the day the money left. **Record payment** records a **transfer** from that account to the card account, settles the payable and turns the statement's entries **Reconciled**. tip **Paying through any door gives the same result.** Settling the statement's payable on Payables, through the API, or through the bank's confirmation when the payment was sent through [Kobana](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md) produces exactly the same outcome: the transfer, the statement paid and the entries reconciled. *"Paying through the bank? Send the payable through Kobana: when the bank confirms, the payment is recorded here automatically."* ### Partial payment[​](#partial-payment "Direct link to Partial payment") Paying less than the total leaves the statement **Partially paid**, and the difference goes to the next statement as **Previous balance** — the *"Saldo da fatura 11/2026"* entry. The dialog warns: *"The remaining … goes to the next statement as previous balance. When interest and late fees show up on the statement, enter them as Interest and fees."* The system does not compute interest. ### Undo the payment[​](#undo-the-payment "Direct link to Undo the payment") **Undo payment** asks first: *"Deletes the … payment (the transfer to the card's account) and the balance that went to the next statement. The statement goes back to Reviewed or Closed."* The payable goes back to pending, with the statement total. If the statement that received the previous balance has already closed, the undo is refused: reopen it first. ## Reopen[​](#reopen "Direct link to Reopen") **Reopen** takes the statement back to **Open** — to enter a missing purchase, fix an amount or a date, or change the closing date. *"The statement goes back to Open, and the history records who reopened it and when. The payable stays; the total is recalculated when it closes again."* On a paid statement: *"The payment stays recorded, the balance that went to the next statement is removed and the entries go back to Realized. The total is recalculated when it closes again."* When it closes again, the statement goes back to **Paid** if the payment covers the new total, or stays **Partially paid** with the difference on the next one. There is only one open statement per card: the one that was open goes back to future while the reopened one has not closed. If the reopened statement's closing date has already passed, it closes again the following night — close it earlier with **Close statement now** once you are done. ## Prepaid and benefit[​](#prepaid-and-benefit "Direct link to Prepaid and benefit") **Top up** (on the list tile or in the card header) records a top-up: the amount, the date and the account it leaves from (**Paid from**, the card's account for top-ups). *"It enters as a credit in the open statement (…). The balance becomes …."* The top-up is a transfer from the bank account to the card account; deleting it on the statement deletes the transfer. A prepaid card's statement has the same cycle and the same review, but closes without a payable: once reviewed, it ends as **Reviewed**. ## In the cash flow[​](#in-the-cash-flow "Direct link to In the cash flow") **The card is not cash.** In the [cash flow](https://docs.finance.kobana.com.br/en/en/dashboard/.md#cash-flow-tab): * **What already happened** — the outflow is the statement **payment**, on the payment day, from the account that pays the statement. Purchases do not come in one by one. * **What lies ahead** — the open and future statements come in through their **expected total**, on the **due date**, in the account that pays the statement. Once closed, the statement comes in through its payable (without counting twice). * **Prepaid** — the cash outflow is the top-up; the statement never enters the projection. Picking the card's account on the **Account** selector, the projection and cash-flow tabs show a notice instead of the chart — *"Itaú Empresas Visa is a card: it is not part of the cash flow"* — with a **View** shortcut to the account that pays the statement. Balances add up cash accounts only; cards come after, in grey. The **Dashboard** (the month's performance, largest expenses) still sees each purchase on its date: it is the expense view, not the cash view. --- # Entries and IOF **New entry**, in the card header, opens the entry dialog. The type picked at the top changes the fields: | Type | For | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **One-off** | A purchase on a single statement. | | **Installments** | A purchase split into installments, one per statement. | | **Recurring** | A subscription charged every month, quarter or year. *"Creates a recurring charge: the expected amount shows on each statement, and you confirm the real amount when the statement arrives."* See [Recurrences](https://docs.finance.kobana.com.br/en/en/cartoes/recorrencias.md). | | **Refund** | The bank returned the amount of a purchase. *"Reduces the statement total."* | | **Interest and fees** | *"Interest, late fee, annual fee and financing IOF. It enters the statement as an expense, in the chosen category."* | The common fields are **Purchase date**, **Amount**, **Description**, **Supplier**, **Category** and **Classification center** — the last two already carry the card's defaults. **Split** divides the classification center across several, as on payables. A **realized** entry goes straight into the card's account, in My accounts — and that is what shows up on Transactions, on the Dashboard and in the category reports, on the purchase date. ## Which statement it falls on[​](#which-statement-it-falls-on "Direct link to Which statement it falls on") Before you save, the dialog says where the entry will end up: | Situation | The dialog says | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | The date is in the period of an open or future statement | *"Falls in the Dec/26 statement, due 12/09."* | | The date's statement already closed | *"The Nov/26 statement already closed: the entry goes to Dec/26, which is open. The closed statement does not change."* | | The date is beyond the statements created so far | *"Falls in the … statement, which will be created."* | | The date is before the card's first statement | *"The date is before the card's first statement in the system (…)."* — a one-off entry is refused. | note **A closed statement does not change.** A purchase that arrives after the closing — the bank was slow to post it, or someone forgot — goes to the open statement, with the warning *"The date's statement already closed: the entry went to the open statement."* The closed statement's total, its payable and its review stay as they were. To put the purchase on the closed statement, reopen it first (see [Reopen](https://docs.finance.kobana.com.br/en/en/cartoes/fechar-conferir-pagar.md#reopen)). ## Installments[​](#installments "Direct link to Installments") Enter the **Total amount** and the **Number of installments**. The dialog shows the split — *"6 × R$ 1.500,00"*, or *"1st of R$ 33,34 + 2 × R$ 33,33"* when the cents do not divide evenly: **the cents left by the division go in the first installment**. And where each one falls: *"One installment per statement, from Sep/26 to Feb/27."* * Installment **k** falls **k − 1** statements after the purchase. * A purchase made before the card's **Start date** adds only the installments that fall from the first statement on, with their original numbers (**4/10** to **10/10**): *"Installments before the card's first statement in the system will not be added."* * **An international purchase cannot be split into installments here.** On the statement table, each installment shows its number in the **Installment** column (**4/6**) and the original purchase date. ## International purchase[​](#international-purchase "Direct link to International purchase") Tick **International purchase** and enter the **Currency** and the **Amount in USD** (or in the chosen currency). The dialog works out the rest live: | Field | Where it comes from | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Exchange rate** | Estimated: the Central Bank's PTAX selling rate of the business day before the purchase, plus the **Bank spread** set on the card — *"Estimate: official rate (PTAX) of 11/03, 5.2600, plus the bank's 4% spread. Replace it with the real rate when the statement arrives."* | | **IOF rate** | Read-only. (i) *"The official rate on the purchase date, or the card's own rate if it has one. It is stored on the entry, even if the rate changes later."* | | **IOF charged by the bank** | Optional. (i) *"If the IOF on the bank's statement differs from the calculated one, type its amount here."* | | **Statement total** | *"$135.00 × 5.4700 = R$ 738,45 + IOF R$ 25,85"* | **The IOF is part of the entry.** It goes into the statement total, the card's account and the reports in the same category and classification center as the purchase — and, with a split, each slice takes its share. The [IOF paid report](https://docs.finance.kobana.com.br/en/en/cartoes/relatorios.md#iof-paid) separates it as a tax. **Estimated until the bank statement arrives.** While the rate is the estimated one, the table shows *"estimated"* below the amount. When the bank statement arrives, edit the entry with the rate (or the IOF) it shows. tip **The Central Bank being down does not block the entry.** If PTAX does not answer, the rate stays blank with the warning *"The Central Bank did not answer just now. Type the rate to add the entry."* **A new rate does not change the past.** The rate is stored on each purchase: when the table changes, earlier purchases keep the rate that applied on their date. ## Refund[​](#refund "Direct link to Refund") Pick the **Refunded purchase** and the amount. The refund goes negative into the open statement and lowers its total. On a refund of an international purchase, currency, rate and IOF rate come from the original; tick **IOF refunded** only if the bank statement refunded the IOF too. The field's (i) icon reminds you: *"Tick it only if the bank's statement also refunded the IOF. It varies from bank to bank."* **Refund**, on the menu of a realized purchase, opens the dialog with the original already picked. ## The entry menu[​](#the-entry-menu "Direct link to The entry menu") | Action | Shows when | | ----------------------- | -------------------------------------------------------- | | **Edit** | Always, except on the previous balance | | **Move** | On an open or future statement | | **Anticipate** | On installments | | **Refund** | On realized purchases | | **Mark as not charged** | On a recurring charge still expected | | **Delete** | On an open or future statement, except recurring charges | ### Edit[​](#edit "Direct link to Edit") *"Amount and date change only in an open or future statement."* On a closed statement, the dialog warns: *"The … statement already closed: amount and date are locked. Description, supplier and classification can still change."* **On a series** — installments or charges of a recurrence —, saving asks for the reach: | Option | Installments | Recurrence | | -------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Only this one** | Changes only this installment | Changes only this month's charge | | **This and the next ones** | From this one to the last | Changes the recurrence and the expected charges from then on, except those already edited | | **All of them** | The whole purchase | Changes the recurrence and all expected charges, except those already edited. *"What was already confirmed does not change."* | An option whose reach takes in an installment on a closed statement shows disabled, with the reason: *"Installment 2/6 is in the Oct/26 statement, which already closed: reopen it to change its amount or date."* An installment purchase's date changes only with **All of them**; on a recurrence, the date, the split, the rate, the IOF and the notes apply to that charge only. ### Move[​](#move "Direct link to Move") Takes the entry to another open or future statement. *"The entry stays pinned to the chosen statement, even if the closing date changes."* — hence the padlock it gets on the table. ### Anticipate[​](#anticipate "Direct link to Anticipate") When the bank brings installments forward (with or without a discount), **Anticipate** takes the last installments sitting on future statements to the open statement, and they stay pinned there. The **Bank discount**, if any, comes in as the refund *"Desconto por antecipação"*. ### Delete[​](#delete "Direct link to Delete") *"The entry leaves the statement and the card's account."* On an installment purchase, the reach asks which installments go. The charges of a recurrence are not deleted: use **Mark as not charged** or end the recurrence. --- # Recurrences Subscriptions and services charged every month on the card — software, hosting, e-mail — become **recurrences**. Each recurrence puts an **expected** charge on every open and future statement; when the bank statement arrives, you confirm the real amount. ![The card\'s recurrences, with the suggestion to update the amount](/en/assets/images/39-card-recurrences-71a50758257fd736cb16540df0f4a551.png) ## Create[​](#create "Direct link to Create") On the card's **Recurrences** tab, **New recurrence** — or **New entry** with the **Recurring** type. The fields: | Field | Notes | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **First charge** | When the subscription starts being charged. | | **Amount** | The expected amount of each charge. On a subscription in a foreign currency, the amount in that currency. | | **Charge day** | The day of the month the subscription is charged to the card (capped to the month's last day). | | **Frequency** | **Monthly**, **Quarterly** or **Yearly**. | | **End date** | (i) *"Left blank, the charge has no end date. If you end it later, the expected charges from then on are cancelled."* | | **Description** · **Supplier** · **Category** · **Classification center** | Copied to each expected charge. | *"One expected charge on each statement, from Dec/26 on."* A closed statement never gets a new expected charge. note **An expected charge is not an expense yet.** It counts in the statement's **Expected total** and in the limit used, but not in the card's account, on Transactions or on the Dashboard. It becomes an expense when it is confirmed. On a subscription in a foreign currency, the expected charge is converted at the PTAX of the previous business day plus the card's **Bank spread**. If the Central Bank does not answer and there is no stored rate, the expected charges wait: *"No USD rate right now: the expected charges come in when the Central Bank answers."* ## Confirm the real amount[​](#confirm-the-real-amount "Direct link to Confirm the real amount") On the statement, **Confirm recurring charges (3)** opens the list of that statement's expected charges: *"Type the amount shown on the bank's statement. Enter confirms and moves to the next one. Left blank, it confirms the expected amount."* * A variation of more than 5% over the expected amount shows in amber. * On an international subscription, enter the **Real rate** too. * **Not charged** takes the charge out of the statement total: the bank did not charge it this month. Confirming also works with the statement **closed** — that is how you review it against the bank statement. A reviewed or paid statement no longer takes confirmations: reopen it first. Each charge also has actions on the statement row menu: **Edit** (to confirm a single one) and **Mark as not charged**. ## The Recurrences tab[​](#the-recurrences-tab "Direct link to The Recurrences tab") | Column | What it shows | | -------------------- | --------------------------------------------------------- | | **Description** | With the supplier and the category below | | **Amount** | The expected amount, in the recurrence's currency | | **Charge** | *"day 4 · monthly"* | | **Next charge** | The date of the next charge and the statement it falls on | | **Last real amount** | The last confirmed amount and its month | | **Variance** | Of the last real amount over the expected one | | **Status** | **Active** or **Ended** | The search, the **Active** and **Ended** tabs and the **New recurrence** button. The **Recurrences** tab at the top shows how many are active. ### The suggestion to update the amount[​](#the-suggestion-to-update-the-amount "Direct link to The suggestion to update the amount") When the **last three** confirmed charges all came more than 5% above (or below) the expected amount, a notice at the top of the tab suggests their average: > *"Hospedagem dos sites came more than 5% above the forecast in the last 3 months (average R$ 947,90). Update the recurrence amount?"* **Update to R$ 947,90** changes the amount of the recurrence and of the expected charges not edited yet. **Not now** hides the notice until the suggestion changes. A **not charged** month in between breaks the run, and there is no suggestion when the average is within 5% of the current amount — the case of a subscription stable in dollars while the exchange rate moves. ## Edit, end, delete[​](#edit-end-delete "Direct link to Edit, end, delete") | Action | What it does | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Edit** | *"Expected charges not edited yet follow the recurrence. What was already confirmed does not change."* | | **End** | Asks for the end date. *"Expected charges after this date are cancelled. What was already confirmed does not change."* | | **Delete** | *"… and its expected charges leave the statements. It can only be deleted while no charge was confirmed; after that, end the recurrence."* | Editing a charge on the statement with the **This and the next ones** or **All of them** reach also updates the recurrence — see [Entries and IOF](https://docs.finance.kobana.com.br/en/en/cartoes/lancamentos-e-iof.md#edit). ## In the report[​](#in-the-report "Direct link to In the report") The [Forecast vs. actual](https://docs.finance.kobana.com.br/en/en/cartoes/relatorios.md#forecast-vs-actual) report compares, month by month, what each recurrence expected and what was charged. --- # Reports The **Report** pill — on the card list or on a card's screen — opens **Generate report** with two types: **IOF paid** and **Forecast vs. actual**. Opened from a card's screen, it already comes with that card in the filter and the type of the tab you were on. | Step | Options | | ---------------- | ----------------------------------------------------------------------------------------- | | **Type** | **IOF paid** or **Forecast vs. actual** | | **Detail level** | **Summary** (the groups) or **Detail** (the groups and, below each one, its entries) | | **Group by** | IOF only: **Month**, **Card**, **Category** or **Supplier** | | **Period** | Required. For the IOF, by **purchase date**; for forecast vs. actual, by **charge month** | | **Filters** | **Cards**, **Category** and **Supplier** (optional) | **Include chart** adds the chart above the table. **Generate report** opens the report on a page of its own, ready to print. ![IOF paid on international purchases, by supplier](/en/assets/images/41-card-iof-report-12ffd3d70191fa6643c79e40349f1fc0.png) ## IOF paid[​](#iof-paid "Direct link to IOF paid") The IOF on international purchases treated as a tax: for each group, the **Purchase amount** (in reais, without the IOF), the **IOF**, the **Rate** and the number of purchases, with the total at the end. * Only **realized** or **reconciled** entries with IOF count. An expected charge has not paid any tax yet. * A refund with the IOF returned **subtracts** from the group. * **By category**, a purchase split across categories shares out its IOF in the same proportion. Filtering by category counts only the purchase's share in the chosen categories. * In **Detail**, each purchase shows the currency, the amount in that currency, the exchange rate, the purchase amount, the rate stored on it and the IOF. note **The group's rate is the effective one: the IOF divided by the purchase amount.** Since each purchase's IOF is rounded to the cent, it may show as *3.4999%* for a group of purchases at 3.5%. Each purchase's rate, in the detail, is the one stored on it. ## Forecast vs. actual[​](#forecast-vs-actual "Direct link to Forecast vs. actual") For each recurrence, month by month: the **Forecast** (the expected amount), the **Actual** (what was confirmed; not charged counts as zero), the **Difference** and the **Difference (%)**, always in reais and without IOF — the same calculation as the **Variance** column on the Recurrences tab. A month still forecast counts in the forecast and has no actual nor difference. The **Months** column shows how many are confirmed: *"6 (2 to confirm)"*. *"The difference compares the confirmed months only; the forecast adds them all."* ## Export as CSV or XLSX[​](#export-as-csv-or-xlsx "Direct link to Export as CSV or XLSX") On the report page, **Export to Excel** opens the export with the choice of **Format**: CSV or XLSX. The columns are the same as on screen, in both formats: * **CSV** in the Brazilian layout (semicolons, decimal comma), like the product's other reports; * **XLSX** with real numbers — currency, percentage and date formatted, frozen header —, ready to add up and filter in a spreadsheet. ## Through the API and MCP[​](#through-the-api-and-mcp "Direct link to Through the API and MCP") The same figures come from [`GET /card-transactions/aggregates`](https://docs.finance.kobana.com.br/en/en/api/v1/aggregate-card-transactions), grouping by `card`, `statement`, `category`, `person` or `month`, with `sum_iof_amount` and `sum_base_amount` in each group, and from the `finance_card_transactions_aggregates` tool of the [MCP server](https://docs.finance.kobana.com.br/en/en/mcp/tools/accounts.md#card_transactions). --- # Categories Categories (`/categories`) classify payables, receivables and transactions. The structure is hierarchical, up to **three levels**. ![Categories list](/en/assets/images/11-categories-5d09a7ee01fc507eabe1b865d29bd5c1.png) ## Fields[​](#fields "Direct link to Fields") | Field | Required | Description | | ------------------- | -------- | -------------------------------------- | | **Name** | Yes | Category name | | **Type** | Yes | **Revenue** or **Expense** | | **Company** | Yes | The company that owns the category | | **Parent category** | No | The category above it in the hierarchy | **On a subcategory, Type and Company don't appear** — they are inherited from the parent. You only pick those two when creating a root category. ## Type: revenue or expense[​](#type-revenue-or-expense "Direct link to Type: revenue or expense") * **Expense** — appears in the picker for payables and outgoing transactions. * **Revenue** — appears in the picker for receivables and incoming transactions. **A subcategory is always the same type as its parent.** There is no mixing: the system refuses to save, with *"A subcategory must have the same type as its parent category"*. Changing the type of a **root** category is allowed, and the change **cascades through the whole subtree** — children and grandchildren follow. ## Hierarchy[​](#hierarchy "Direct link to Hierarchy") ``` Operating Expenses (Expense) ├── Rent ├── Power and Water │ ├── Electricity │ └── Water and Sewage └── Payroll ├── Salaries └── Payroll Taxes Revenue (Revenue) ├── Subscriptions └── Services ├── Consulting └── Support ``` note **The limit is three levels.** At the third level the **Add subcategory** button stops appearing, and an attempt by any other route is refused with *"Limit of 3 hierarchy levels reached."* ## The screen[​](#the-screen "Direct link to The screen") Categories are shown as **cards**, not a table. Each card is a root category, with its subcategories listed inside. * **Search** by name. A hit at level 2 or 3 pulls the ancestor's whole card onto the screen, so you can see where it sits. * **Tabs** with counters: **All** · **Expenses** · **Revenue**. The counters count root categories only — it's the number of cards. * **Double-click the name** to edit it in place, with no dialog. * **Badges:** **Revenue** or **Expense** on the root card, and **Unused** when neither the category nor any of its subcategories has links. * A card's transaction count **sums the subtree** — the number on the parent includes what's on the children. With the company selector on "All", the cards are grouped into collapsible sections per company. Pick a specific company and it becomes a single grid. ## Filtering by category on other screens[​](#filtering-by-category-on-other-screens "Direct link to Filtering by category on other screens") When you filter transactions or bills by a parent category, **the subcategories don't come along automatically**. Inside the Category filter there is an **Include subcategories** option — tick it for the filter to reach the whole subtree. The **Uncategorized** option, in the same filter, is mutually exclusive: ticking it disables **Include subcategories**. ## Split[​](#split "Direct link to Split") A bill can be divided across **several categories** — say 60% to **Rent** and 40% to **Utilities**. The **Split** shortcut, beside the **Category** field on the **payable**, **receivable** and **transaction** forms, opens the **"Category split"** dialog. The dialog works exactly like the classification-center one — **"Split mode"** by percentage or amount, a **"Remaining total"** that has to close, no category twice. See [Split in Classification centers](https://docs.finance.kobana.com.br/en/en/centros-de-classificacao/.md#split). The two splits are **independent**: a bill can be split by category, by center, by both or by neither. What changes with a split bill: * **Reports and the overview** count each category by its share: a R$ 1,000 bill split 60/40 adds R$ 600 to Rent and R$ 400 to Utilities — future occurrences of a recurring series included. * **The category filter** finds the bill by **any** of its categories. **Uncategorized** never returns a split bill. * **Reports filtered by category** add up only the bill's share in the filtered categories: filtering **Utilities** brings R$ 400 of the bill above, not R$ 1,000. The classification center filter works the same way. * **Listings** show the split's first category, with a **+N** for the others. * **Installments, recurrence and settlement** inherit the split — the settlement transaction comes out split the same way. * **Automatic rules don't undo the split**: a rule keeps the categories of an already-split bill. **Classify selected**, being an explicit action, replaces the split with a single category. Picking a single category for a bill that was split removes the split. ## CSV import[​](#csv-import "Direct link to CSV import") The import takes **one category per row** — the category split is set up on the form. In the import preview, each category in the file shows what will happen to it: one that already exists is linked; one that doesn't exist yet comes marked to **create** (if you have permission to create categories); and a name almost equal to an existing one — only accents, case or spacing differ — comes marked to **use the existing one**. You can change each choice, including to **leave blank**. A category created by the import is a **root** category, of the file's side: **Expense** for payables, **Revenue** for receivables and, for transactions, each row's type. The lookup is by the category's name, not its path in the tree. Details on the import pages for [transactions](https://docs.finance.kobana.com.br/en/en/lancamentos/importacao-csv.md), [payables](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/importacao-csv.md) and [receivables](https://docs.finance.kobana.com.br/en/en/contas-a-receber/importacao-csv.md). ## Delete[​](#delete "Direct link to Delete") danger **Deletion takes the subcategories with it.** Deleting a category removes it **and its entire subtree**. The linked transactions, payables and receivables **are not deleted**: they are left **without a category**. **The only thing that blocks deletion is a split.** If the category — or one of its subcategories — is a slice of a split bill, deletion is refused with *"This category is used in a split and cannot be deleted. Change the split first."* Taking the category out of the split would leave the slices not adding up, so you decide where that share goes. The dialog says exactly that before you confirm: *"This will delete this category and all subcategories. This action cannot be undone."*, followed by what it found — *"This category is linked to 12 transactions, 3 payables (15 in total). These transactions will be uncategorized after deletion."* If there are no links, it says so too. The warning is **informative, not blocking**. If you want to preserve the classification, reclassify the records first: on the Transactions, Payables and Receivables screens, select the rows and use **Classify selected**. --- # Classification centers Classification centers (`/classification-centers`) let you allocate expenses and revenues to departments, projects or areas of the company. A single bill can be split across several centers — the **split**. ![Classification centers list](/en/assets/images/12-classification-centers-ef153d81f64f208670b68b56dfa2f43a.png) ## Fields[​](#fields "Direct link to Fields") | Field | Description | | --------------- | ----------------------------------------------------------------- | | **Name** | Required | | **Type** | Required. **Cost**, **Revenue** or **Both** | | **Company** | Required. The center belongs to one company | | **Description** | Optional | | **Active** | On/off. *"Inactive classification centers don't appear in forms"* | A **Both** center serves both polarities — useful for projects or areas that concentrate costs and revenues alike. **In the listing, "Both" has no badge of its own.** A center of that type shows **two** badges side by side, **Cost** and **Revenue**, each in the color of its polarity. It reads as "serves both", not as a third type. ## Active and Inactive[​](#active-and-inactive "Direct link to Active and Inactive") The status column shows **Active** or **Inactive**. **Deactivating doesn't remove it from the listing.** The center stays there, with the **Inactive** badge. The promise *"will not show up on new transactions"* is about the **pickers**: it drops out of the payable, receivable and transaction forms, but the history that already references it stays intact. ## Deletion[​](#deletion "Direct link to Deletion") The path depends on whether the center is in use, and the screen decides for you: **Not linked** — dialog **"Delete classification center?"**: *"This will delete this classification center. This action cannot be undone."* **In use** — there is no deletion. The dialog is **"Classification center in use"**: > *"This classification center is in use by transactions and cannot be deleted. Do you want to deactivate it? It stays in the history but will not show up on new transactions."* The button is **"Deactivate"**. In other words: the product **converts the deletion into a deactivation** — there is no forced-delete path that would leave transactions without a center. ## Split[​](#split "Direct link to Split") The split **is not configured on this screen**. It lives in the **"Classification-center split"** dialog, opened from the **Split** shortcut on the **payable**, **receivable** and **transaction** forms. ### Split mode[​](#split-mode "Direct link to Split mode") The **"Split mode"** field picks which column you fill in: | Mode | You fill in | The system computes | | ------------------------------ | --------------------- | ------------------- | | **Percentage (%)** *(default)* | Each row's percentage | The amount | | **Amount (R$)** | Each row's amount | The percentage | The inactive mode's column is **disabled** — both are always visible, but only one is editable. ### Making the total add up[​](#making-the-total-add-up "Direct link to Making the total add up") The footer shows the **"Remaining total"**, as a percentage and as an amount, and stays red until it closes. **"Save split"** only unlocks when all three conditions hold: * The total closes (remainder zero, with a one-cent tolerance). * **Every row has a center picked** — *"All rows need a selected classification center."* * **No center is repeated** — *"Duplicate classification center — each row needs a distinct center."* note **Editing one row doesn't redistribute the others.** Taking a center down from 60% to 50% does **not** hand the 10% to anyone: the "Remaining total" starts flagging 10%, and it's on you to close the books. The same goes for **adding** a row (it enters at zero) and for **removing** one (its slice becomes surplus). The system **validates**; you redistribute. ### What the system rebalances on its own[​](#what-the-system-rebalances-on-its-own "Direct link to What the system rebalances on its own") One thing, and only it: **changing the bill's total amount**. Percentages are preserved and amounts recalculated — the last row absorbs the cent-level remainder so the sum matches exactly. That's why fixing the amount of an already-split bill doesn't dismantle the split. In **Amount (R$)** mode the effect inverts: the amounts are preserved and the **percentages** are the ones recalculated. An **automatic rule** doesn't undo this split — see [Automatic rules](https://docs.finance.kobana.com.br/en/en/regras-automaticas/.md). The category can be split too, independently: see [Categories](https://docs.finance.kobana.com.br/en/en/categorias/.md#split). ## Split across installments[​](#split-across-installments "Direct link to Split across installments") When you **create** an installment bill, the split is propagated to **all** the installments in the group, automatically. When you **edit** an installment that already exists, it isn't: the system **asks**. If you change the split on one installment of a group, the propagation dialog shows what changed and lets you choose which sibling installments inherit the change. See [Installments and recurrence](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/parcelas-e-recorrencia.md). ## CSV import[​](#csv-import "Direct link to CSV import") The import accepts **a single center per line**. The column name changes depending on the file: | Import | Column | Also accepts | | ---------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | Payables / receivables | `cost_center_name` | `centro_custo`, `centro_de_custo`, `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` | | Transactions | `centro_custo` | `centro_de_custo`, `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` | Besides these names, a column with the word **centro** in its header is also read as the classification center. In the preview, each center in the file shows what will happen to it: one that already exists is linked — case-insensitively, and ignoring surrounding whitespace; one that doesn't exist yet comes marked to **create** (if you have permission to create classification centers); and a name almost equal to an existing one — only accents, case or spacing differ — comes marked to **use the existing one**. You can change each choice, including to **leave blank**. The file's side decides **which** centers count: a payables import only sees **Cost** centers, and a receivables import only **Revenue** ones. A **Both** center serves either. If two centers share a name, the one on the exact side beats the **Both**. A center that only exists on the other side comes marked to leave blank; choosing create makes another center, on the file's side. A center created by the import is on the file's side — for transactions, a new center used for both credits and debits is created only once, as **Both**. Details on the import pages for [transactions](https://docs.finance.kobana.com.br/en/en/lancamentos/importacao-csv.md), [payables](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/importacao-csv.md) and [receivables](https://docs.finance.kobana.com.br/en/en/contas-a-receber/importacao-csv.md). To split across several centers, edit the bill after importing. --- # Custom classifiers Custom classifiers (`/custom-classifiers`) are **classification dimensions you create** — like "Region", "Product" or "Channel" — beyond the fixed axes (category and classification center). Each dimension has its own **values**, and a single bill can carry **several** dimensions at once. *"Create your own dimensions (e.g. Region, Product) and their values to classify your records."* ## Two levels: dimension and value[​](#two-levels-dimension-and-value "Direct link to Two levels: dimension and value") The catalog has two levels: * **Dimension** — the axis. It has only a **name** (e.g. "Region"). * **Value** — each option within the dimension (e.g. "South", "Southeast"). It lives **inside** the dimension. A dimension with no values shows up in the list marked **"No values"** — it exists, but classifies nothing until you add at least one value. ## Fields[​](#fields "Direct link to Fields") | Field | Level | Description | | ------------------ | --------- | ------------------------------------------------------ | | **Dimension name** | Dimension | Required. E.g. "Region" | | **Company** | Dimension | The dimension belongs to a company | | **Active** | Dimension | On/off. *"Inactive dimensions don't appear in forms."* | | **Value** | Value | Required. E.g. "Southeast" | | **Active** | Value | Toggles the value individually | ## The screen[​](#the-screen "Direct link to The screen") Management lives under **Axes → Custom classifiers**, in a table where each row is a **dimension** with its values shown as chips beside it. * **Search** by dimension name. * **New dimension** creates the axis; the values dialog adds, renames, activates/deactivates and deletes each value **live**. * A value can be **activated or deactivated** individually without leaving the dimension. When no dimension exists yet, the screen shows the empty state: *"No classifiers registered — Create dimensions like 'Region' or 'Product' and their values to classify your records."* ## Active and inactive[​](#active-and-inactive "Direct link to Active and inactive") The **Active** flag exists at both levels, and the effect matches classification centers: **deactivating does not delete**. * An inactive **dimension** leaves the forms, but the history that already references it stays. * An inactive **value** disappears from the selector **for new choices** — but if a bill already uses it, it stays visible there as the selected value, so it never drops from the record. ## Deleting[​](#deleting "Direct link to Deleting") As with classification centers, the product **turns deletion into deactivation** when there is usage — there is no path that leaves records unclassified. **Value in use** — no deletion: *"Value is in use by records. Deactivate it instead of deleting."* **Dimension in use** — the dialog is **"Classifier in use"**: > *"This classifier is in use by records and cannot be deleted. Do you want to deactivate it?"* The button is **"Deactivate"**. Deleting the dimension is only possible when **none** of its values is assigned to a bill. ## Classifying a record[​](#classifying-a-record "Direct link to Classifying a record") The **"Custom classifiers"** block appears in the **payable**, **receivable** and **transaction** forms — all **three** screens, and in each one's detail view too. * There is **one selector per active dimension**. Every active dimension is always visible. * The selection is **one value per dimension** (single-select) — unlike the classification-center split, here a bill is not divided across values. * The selector does **"pick or create"**: type a value that doesn't exist yet and it offers to register it, creating the value in the dimension when you save the bill. note **Classification does not automatically spread to installments 2 onward.** When you publish an installment bill, the dimension stays on the anchor installment — the same behavior as the classification center. To apply it to several rows at once, use **Classify selected** in the Transactions, Payables and Receivables lists. ## Advanced search[​](#advanced-search "Direct link to Advanced search") The advanced search for Transactions, Payables and Receivables has a single **"Classifier"** facet that gathers the values of **any** dimension. Check one or more values and the search returns the bills that carry them. The same facet offers **"No classifier"**, to find bills with no dimension at all. The facet only appears when at least one dimension exists. ## Reports[​](#reports "Direct link to Reports") Reports (normal and fiscal) support **grouping by classifier**: pick a dimension and each report row is one of its values, while bills without that dimension fall into **"(no classifier)"** — they never drop from the total. ## CSV import[​](#csv-import "Direct link to CSV import") Unlike categories and classification centers, the CSV import **creates the missing values**. * Each active dimension becomes a **column** in the file, with the **dimension name** in the header. * On import, each row's value is **looked up and created if it doesn't exist** in that dimension. The dimensions themselves are **not** created by the import — register them beforehand; the values, however, are born from the file. ## In the API[​](#in-the-api "Direct link to In the API") The public API v1 exposes the catalog at `/api/v1/custom-classifiers` (dimensions, with their values under nested `/{id}/values` routes) under the `finance/custom_classifiers` scope, with the `read` access level to read, `write` to create and update, and `delete` to delete. On bills, the `custom_classifications` field rides **payables**, **receivables** and **transactions**: a count on the list, the full array on the detail, and, on write, you supply the value by id **or** by name (pick-or-create). See the **API reference** for details. ## Fintera source[​](#fintera-source "Direct link to Fintera source") When the Fintera integration is active, classifiers and their values are **imported** from there (read-only). A bill's link names the value by **text**, resolved to the matching value in Smart Finance at import time. See [Fintera integration](https://docs.finance.kobana.com.br/en/en/integracoes/fintera.md). --- # Authentication :::caution Products do not share credentials `KOBANA_TOKEN` holds **one product's credential at a time**. A Smart Finance token does not authenticate against any other Kobana product, and vice versa. ::: ## The token[​](#the-token "Direct link to The token") Smart Finance authenticates with a **JWT signed in RS256** by the Kobana authorization server, sent as `Authorization: Bearer `. See [API Authentication](https://docs.finance.kobana.com.br/en/en/api/overview/authentication.md) for how that token is issued and which scopes it carries — `kobana auth login`, which belongs to the Banking Gateway, does **not** produce it. :::caution The token alone is not enough The JWT identifies the **organization** (`org` claim). Since an organization can own several workspaces, the API also requires the `X-Workspace-Id` header naming which one to act on — without it the answer is `400 WORKSPACE_REQUIRED`. The exceptions are `me` and [`organization`](https://docs.finance.kobana.com.br/en/en/cli/resources/organization.md), which are organization-level and take no such header. See [API Authentication](https://docs.finance.kobana.com.br/en/en/api/overview/authentication.md). ::: Put the JWT in `KOBANA_TOKEN` before calling the product: ``` export KOBANA_TOKEN=$JWT_FINANCE kobana finance financial-accounts list --fields "id,name,balance" ``` Since the variable is the same for every product, export it per command (or use a per-project `.env`) if you switch products in the same session: ``` KOBANA_TOKEN=$JWT_FINANCE kobana finance financial-accounts list --fields "id,name,balance" ``` ## Resolution priority[​](#resolution-priority "Direct link to Resolution priority") | Priority | Method | Configuration | | -------- | ----------------- | ------------------------------------------ | | 1 | Direct token | `KOBANA_TOKEN` | | 2 | Credentials file | `KOBANA_CREDENTIALS_FILE` | | 3 | Saved credentials | `kobana auth login` (Banking Gateway only) | ## Environments[​](#environments "Direct link to Environments") The CLI operates in three environments, and each product has its own hosts. **Production is the default.** | Environment | API | `--env` | | ----------- | ----------------------------------- | ---------------------- | | Production | `api.finance.kobana.com.br` | `production` (default) | | Sandbox | `api.finance.sandbox.kobana.com.br` | `sandbox` | Smart Finance has no development host of its own: with `--env development` the CLI falls back to production. ``` # Production (default — no flag needed) kobana finance financial-accounts list # Sandbox kobana finance financial-accounts list --env sandbox # Via environment variable export KOBANA_ENVIRONMENT=sandbox kobana finance financial-accounts list ``` Tokens are **different across environments** — a sandbox token does not work in production and vice versa. ## Next steps[​](#next-steps "Direct link to Next steps") * [Usage](https://docs.finance.kobana.com.br/en/en/cli/usage/overview.md) — syntax, resources, examples. * [Environment variables](https://docs.finance.kobana.com.br/en/en/cli/overview/environment-variables.md) — the full reference, including config and logging. --- # Environment variables Every variable can also be set in a `.env` file (loaded via `dotenvy`). ## Authentication[​](#authentication "Direct link to Authentication") | Variable | Description | | ------------------------- | ------------------------------------------------------------------------ | | `KOBANA_TOKEN` | Bearer token for the product you are calling. Not shared across products | | `KOBANA_CREDENTIALS_FILE` | Path to an OAuth credentials JSON file | | `KOBANA_CLIENT_ID` | OAuth client ID (Banking Gateway) | | `KOBANA_CLIENT_SECRET` | OAuth client secret (Banking Gateway) | ## Configuration[​](#configuration "Direct link to Configuration") | Variable | Description | | -------------------- | ----------------------------------------------------------- | | `KOBANA_CONFIG_DIR` | Override the config directory (default: `~/.config/kobana`) | | `KOBANA_ENVIRONMENT` | `production` (default), `sandbox` or `development` | ## Logging[​](#logging "Direct link to Logging") | Variable | Description | | ----------------- | ------------------------------------------------------------------ | | `KOBANA_LOG` | Log level filter for stderr (e.g. `kobana=debug`). Off by default. | | `KOBANA_LOG_FILE` | Directory for JSON log files with daily rotation. Off by default. | ## Next steps[​](#next-steps "Direct link to Next steps") * [Authentication](https://docs.finance.kobana.com.br/en/en/cli/overview/authentication.md) — resolution priority and per-product credentials. * [Exit codes](https://docs.finance.kobana.com.br/en/en/cli/overview/exit-codes.md) — process exit codes for scripting. --- # Exit codes Every `kobana` invocation exits with one of these codes, so a script can branch on failure class without parsing the JSON error body. | Code | Meaning | | ---- | -------------------- | | `0` | Success | | `1` | API error (4xx/5xx) | | `2` | Authentication error | | `3` | Validation error | | `4` | Schema error | | `5` | Internal error | ## Next steps[​](#next-steps "Direct link to Next steps") * [Usage](https://docs.finance.kobana.com.br/en/en/cli/usage/overview.md) — syntax, resources, examples. * [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) — `--dry-run`, `--output-format` and the rest. --- # Installation ### Homebrew (macOS and Linux)[​](#homebrew-macos-and-linux "Direct link to Homebrew (macOS and Linux)") ``` brew tap universokobana/tap brew install kobana ``` To update: ``` brew update && brew upgrade kobana ``` ### Prebuilt binaries[​](#prebuilt-binaries "Direct link to Prebuilt binaries") Download the binary for your platform from the [Releases page](https://github.com/universokobana/kobana-cli/releases/latest) and put it on your `PATH`. | Platform | File | | ------------------- | -------------------------- | | 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 "Direct link to Nix") ``` # Run straight from GitHub nix run github:universokobana/kobana-cli # Install into the profile nix profile install github:universokobana/kobana-cli ``` ### Build from source[​](#build-from-source "Direct link to Build from source") ``` git clone https://github.com/universokobana/kobana-cli.git cd kobana-cli cargo install --path crates/kobana-cli ``` Requires [Rust](https://rustup.rs/) 1.70+. ## Shell completions[​](#shell-completions "Direct link to Shell completions") ``` # 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 ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Authentication](https://docs.finance.kobana.com.br/en/en/cli/overview/authentication.md) — tokens and environments. * [Usage](https://docs.finance.kobana.com.br/en/en/cli/usage/overview.md) — syntax, resources, examples. --- # Introduction **`kobana`** is a single command-line tool for every Kobana product's API — Smart Finance included. It is built and maintained in its own repository ([`kobana-cli`](https://github.com/universokobana/kobana-cli)), not by this product, and it does not hardcode endpoints: at startup it parses the OpenAPI 3.1 specs embedded in the binary and builds its command tree from them. Updating the API surface is a matter of refreshing the embedded spec and shipping a new build — no per-endpoint code. ``` kobana [flags] ``` Designed for both humans and AI agents: structured JSON output by default, schema introspection, `--dry-run` and automatic pagination. ## Products[​](#products "Direct link to Products") | Product | Description | | ------------ | -------------------------------------------------------------------------------- | | `banking` | Banking Gateway — charges, payments, transfers (API v1 and v2) | | `finance` | Smart Finance — payables and receivables, transactions, cash flow | | `billing` | Automatic Billing — subscriptions, plans, invoices, tax documents | | `inbox` | Autonomous Inbox — inboxes, agents, e-mails, webhooks | | `dunning` | Dunning — debtors, charges, collection rules, agreements, credit bureau listings | | `dashboards` | Magic Dashboard — data sources, entities, portal, workspaces | The `finance` product talks to the same API documented on this site. Its resources — see the [full catalogue](https://docs.finance.kobana.com.br/en/en/cli/resources/overview.md) — point at the same endpoints as the [API Reference](https://docs.finance.kobana.com.br/en/en/api/v1); the CLI is just another way to call it. It does not share credentials with the other products: see [Authentication](https://docs.finance.kobana.com.br/en/en/cli/overview/authentication.md). ## Getting started[​](#getting-started "Direct link to Getting started") 1. **Install** it — see [Installation](https://docs.finance.kobana.com.br/en/en/cli/overview/installation.md). 2. **Authenticate** for the product you are going to use. See [Authentication](https://docs.finance.kobana.com.br/en/en/cli/overview/authentication.md). 3. **Make your first call**: ``` kobana finance financial-accounts list --fields "id,name,balance" ``` 4. **Explore the surface** — every command supports `--help`, and `kobana schema` introspects any endpoint's parameters and body without leaving the terminal. ## Next steps[​](#next-steps "Direct link to Next steps") * [Installation](https://docs.finance.kobana.com.br/en/en/cli/overview/installation.md) — Homebrew, prebuilt binaries, Nix, building from source. * [Authentication](https://docs.finance.kobana.com.br/en/en/cli/overview/authentication.md) — tokens, environments and the `finance` product's own credentials. * [Usage](https://docs.finance.kobana.com.br/en/en/cli/usage/overview.md) — syntax, resources, examples. * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — `kobana schema` for parameters and request/response shapes. * [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) — the flags every command accepts. * [Helpers](https://docs.finance.kobana.com.br/en/en/cli/usage/helpers.md) — `+verb` shortcuts for common workflows. * [Environment variables](https://docs.finance.kobana.com.br/en/en/cli/overview/environment-variables.md) — auth, config and logging. * [Exit codes](https://docs.finance.kobana.com.br/en/en/cli/overview/exit-codes.md) — process exit codes for scripting. --- # AI agents Instructions the assistant runs on its own, with the permissions of the person who owns the token — say, a daily digest of the payables that became overdue. The list returns only the token person's agents in the workspace, never another member's. Every run spends AI credit and becomes a new assistant conversation (`last_run.conversation_id`); a destructive action waits for the person's confirmation in the assistant. | Command | HTTP | Description | | --------------------------- | ---------------------------------------------------- | ---------------------------------- | | `ai-agents list` | `GET /v1/ai-agents` | List AI agents | | `ai-agents create` | `POST /v1/ai-agents` | Create an AI agent | | `ai-agents get` | `GET /v1/ai-agents/{id}` | Get an AI agent by id | | `ai-agents update` | `PATCH /v1/ai-agents/{id}` | Update an AI agent | | `ai-agents delete` | `DELETE /v1/ai-agents/{id}` | Delete an AI agent | | `ai-agents triggers get` | `GET /v1/ai-agents/{id}/triggers` | List the triggers of an AI agent | | `ai-agents triggers create` | `POST /v1/ai-agents/{id}/triggers` | Add a trigger to an AI agent | | `ai-agents triggers update` | `PATCH /v1/ai-agents/{id}/triggers/{triggerId}` | Update a trigger of an AI agent | | `ai-agents triggers delete` | `DELETE /v1/ai-agents/{id}/triggers/{triggerId}` | Remove a trigger from an AI agent | | `ai-agents triggers token` | `POST /v1/ai-agents/{id}/triggers/{triggerId}/token` | Rotate the token of an API trigger | An agent is born active with a `manual` trigger; the others come in through `triggers create`: `event` (with `event_type`: `receipt.saved`, `fiscal_document.received`, `payable.created` or `receivable.created`), `schedule` (with a 5-field `cron`, at most every 15 minutes, and an optional `timezone` — default `America/Sao_Paulo`) and `api`. An `api` trigger's token only appears in the response of `triggers create` and `triggers token` — store it; `triggers token` invalidates the previous one at once. That is why those two routes take no `--idempotency-key`. `update` with `active: false` pauses every automatic trigger and `active: true` resumes them. Deleting the agent removes its triggers; past runs stay in the assistant. The scopes are `finance/ai_agents` (read, write and delete). ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List AI agents kobana finance ai-agents list \ --params '{"active": true}' \ --fields "id,title,active,next_run_at,last_run" # Get an AI agent by id kobana finance ai-agents get \ --params '{"id": "AI_AGENT_ID"}' # Create an AI agent kobana finance ai-agents create \ --json '{"title": "Overdue payables digest", "instructions": "List the payables that became overdue yesterday, grouped by supplier, with the total."}' # Pause every automatic trigger kobana finance ai-agents update \ --params '{"id": "AI_AGENT_ID"}' \ --json '{"active": false}' # List the triggers of an AI agent kobana finance ai-agents triggers get \ --params '{"id": "AI_AGENT_ID"}' # Schedule the agent on weekdays at 6am kobana finance ai-agents triggers create \ --params '{"id": "AI_AGENT_ID"}' \ --json '{"kind": "schedule", "cron": "0 6 * * 1-5", "timezone": "America/Sao_Paulo"}' # Update a trigger of an AI agent kobana finance ai-agents triggers update \ --params '{"id": "AI_AGENT_ID", "triggerId": "TRIGGER_ID"}' \ --json '{"cron": "0 7 * * 1-5"}' # Rotate the token of an API trigger kobana finance ai-agents triggers token \ --params '{"id": "AI_AGENT_ID", "triggerId": "TRIGGER_ID"}' # Remove a trigger from an AI agent kobana finance ai-agents triggers delete \ --params '{"id": "AI_AGENT_ID", "triggerId": "TRIGGER_ID"}' \ --dry-run # Delete an AI agent kobana finance ai-agents delete \ --params '{"id": "AI_AGENT_ID"}' \ --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [AI skills](https://docs.finance.kobana.com.br/en/en/cli/resources/ai-skills.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # AI skills Instruction sets, in the Agent Skills format, that the assistant loads when a task matches the skill's `description` — that is all it reads to decide. The list returns the skills the token person can see in the workspace: their own and the ones other members shared with them (`is_owner` tells them apart; `mine=true` keeps only their own). | Command | HTTP | Description | | ------------------ | --------------------------- | --------------------- | | `ai-skills list` | `GET /v1/ai-skills` | List AI skills | | `ai-skills create` | `POST /v1/ai-skills` | Create an AI skill | | `ai-skills get` | `GET /v1/ai-skills/{id}` | Get an AI skill by id | | `ai-skills update` | `PATCH /v1/ai-skills/{id}` | Update an AI skill | | `ai-skills delete` | `DELETE /v1/ai-skills/{id}` | Delete an AI skill | `create` needs `name`, `description` and `instructions` (the SKILL.md body, in Markdown); `slug` is made from `name` when omitted and is unique among the person's skills (`409 slug_taken`). `files` carries text files besides SKILL.md, up to 200,000 characters in total. A skill is born active and `private`; `visibility` (`restricted` with `member_ids`, or `workspace`) shares it, and needs the person's `ai-skills.share` permission. A person has at most 100 skills per workspace. Only the owner changes or deletes it (`403`, `details.reason: not_owner`); on `update`, `files` and `member_ids` replace the whole list and `active: false` hides the skill from the assistant. The scopes are `finance/ai_skills`. ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List AI skills kobana finance ai-skills list \ --params '{"mine": true}' \ --fields "id,slug,name,visibility,active,is_owner" # Get an AI skill by id kobana finance ai-skills get \ --params '{"id": "AI_SKILL_ID"}' # Create an AI skill kobana finance ai-skills create \ --json '{"name": "Month-End Close", "description": "Use when closing the month: checks pending reconciliations and overdue bills.", "instructions": "1. List the unreconciled transactions of the month.\n2. List the overdue payables."}' # Share it with the workspace kobana finance ai-skills update \ --params '{"id": "AI_SKILL_ID"}' \ --json '{"visibility": "workspace"}' # Delete an AI skill kobana finance ai-skills delete \ --params '{"id": "AI_SKILL_ID"}' \ --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [AI agents](https://docs.finance.kobana.com.br/en/en/cli/resources/ai-agents.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Attachments Files — invoice, contract, receipt — uploaded once and linked to one or more bills. `links` creates that link and `unlink` undoes it. | Command | HTTP | Description | | ---------------------- | ----------------------------------- | ---------------------------------- | | `attachments list` | `GET /v1/attachments` | List attachments | | `attachments create` | `POST /v1/attachments` | Upload an attachment | | `attachments get` | `GET /v1/attachments/{id}` | Get an attachment's metadata by ID | | `attachments delete` | `DELETE /v1/attachments/{id}` | Delete an attachment | | `attachments download` | `GET /v1/attachments/{id}/download` | Download the attachment's bytes | | `attachments links` | `POST /v1/attachments/{id}/links` | Link an attachment to a record | | `attachments unlink` | `POST /v1/attachments/{id}/unlink` | Unlink an attachment from a record | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List attachments kobana finance attachments list \ --fields "id,file_name,title,mime_type,file_size" # Get an attachment's metadata by ID kobana finance attachments get --params '{"id": "ATTACHMENT_ID"}' # Upload an attachment, with a title kobana finance attachments create \ --file file=invoice-june.pdf \ --json '{"title": "June invoice"}' # Delete an attachment kobana finance attachments delete --params '{"id": "ATTACHMENT_ID"}' --dry-run ``` `attachments create` goes as `multipart/form-data`: the file goes in `--file file=…` (pdf, png, jpg/jpeg, xml, ofx, csv or xlsx, up to 10 MB), and `title` goes in `--json`, as a text part. Then `attachments links` ties the attachment to a record. See [Sending files](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md#sending-files). ## Next steps[​](#next-steps "Direct link to Next steps") * [Receipts](https://docs.finance.kobana.com.br/en/en/cli/resources/receipts.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Automatic rules The rules that classify transactions on their own, evaluated in the order they sit in. `reorder` is what changes that order. | Command | HTTP | Description | | ------------------------- | ---------------------------------- | --------------------------- | | `automatic-rules list` | `GET /v1/automatic-rules` | List automatic rules | | `automatic-rules create` | `POST /v1/automatic-rules` | Create an automatic rule | | `automatic-rules get` | `GET /v1/automatic-rules/{id}` | Get an automatic rule by ID | | `automatic-rules update` | `PATCH /v1/automatic-rules/{id}` | Update an automatic rule | | `automatic-rules delete` | `DELETE /v1/automatic-rules/{id}` | Delete an automatic rule | | `automatic-rules reorder` | `POST /v1/automatic-rules/reorder` | Reorder automatic rules | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List automatic rules kobana finance automatic-rules list \ --fields "id,company_id,scope,position,active" # Get an automatic rule by ID kobana finance automatic-rules get --params '{"id": "AUTOMATIC_RULE_ID"}' # Create an automatic rule kobana finance automatic-rules create \ --json '{"company_id": "COMPANY_ID", "scope": "transactions"}' # Update an automatic rule kobana finance automatic-rules update \ --params '{"id": "AUTOMATIC_RULE_ID"}' \ --json '{"active": true, "account_id": "ACCOUNT_ID", "transaction_type": "debit"}' # Delete an automatic rule kobana finance automatic-rules delete \ --params '{"id": "AUTOMATIC_RULE_ID"}' \ --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [People](https://docs.finance.kobana.com.br/en/en/cli/resources/people.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Banks The table of supported banks, for filling in an account's or person's bank details. Read-only. | Command | HTTP | Description | | ------------ | --------------- | ----------- | | `banks list` | `GET /v1/banks` | List banks | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List banks kobana finance banks list --fields "id,code,name" ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Organization](https://docs.finance.kobana.com.br/en/en/cli/resources/organization.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Cash flow The consolidated projection: realised and forecast income and expenses per bucket, running balance and today's seam. Read-only — it is the result of everything else, not an editable collection. | Command | HTTP | Description | | --------------- | ------------------- | ---------------------------- | | `cash-flow get` | `GET /v1/cash-flow` | Get the cash-flow projection | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # Get the cash-flow projection kobana finance cash-flow get \ --fields "granularity,current_balance,today_bucket,truncated,retroactive_overdue" ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Reconciliations](https://docs.finance.kobana.com.br/en/en/cli/resources/reconciliations.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Categories The chart of accounts: the income and expense tree every transaction is classified against. | Command | HTTP | Description | | ------------------- | ---------------------------- | -------------------- | | `categories list` | `GET /v1/categories` | List categories | | `categories create` | `POST /v1/categories` | Create a category | | `categories get` | `GET /v1/categories/{id}` | Get a category by ID | | `categories update` | `PATCH /v1/categories/{id}` | Update a category | | `categories delete` | `DELETE /v1/categories/{id}` | Delete a category | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List categories kobana finance categories list --fields "id,company_id,name,parent_id,level" # Get a category by ID kobana finance categories get --params '{"id": "CATEGORIE_ID"}' # Create a category kobana finance categories create \ --json '{"company_id": "COMPANY_ID", "name": "NAME", "type": "debit"}' # Update a category kobana finance categories update \ --params '{"id": "CATEGORIE_ID"}' \ --json '{"name": "NAME", "type": "debit"}' # Delete a category kobana finance categories delete --params '{"id": "CATEGORIE_ID"}' --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Classification centers](https://docs.finance.kobana.com.br/en/en/cli/resources/classification-centers.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Classification centers The second classification dimension — cost center, project, branch — used to split one bill across areas. | Command | HTTP | Description | | ------------------------------- | ---------------------------------------- | --------------------------------- | | `classification-centers list` | `GET /v1/classification_centers` | List classification centers | | `classification-centers create` | `POST /v1/classification_centers` | Create a classification center | | `classification-centers get` | `GET /v1/classification_centers/{id}` | Get a classification center by ID | | `classification-centers update` | `PATCH /v1/classification_centers/{id}` | Update a classification center | | `classification-centers delete` | `DELETE /v1/classification_centers/{id}` | Delete a classification center | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List classification centers kobana finance classification-centers list \ --fields "id,company_id,name,type,description" # Get a classification center by ID kobana finance classification-centers get \ --params '{"id": "CLASSIFICATION_CENTER_ID"}' # Create a classification center kobana finance classification-centers create \ --json '{"company_id": "COMPANY_ID", "name": "NAME", "type": "cost"}' # Update a classification center kobana finance classification-centers update \ --params '{"id": "CLASSIFICATION_CENTER_ID"}' \ --json '{"name": "NAME", "type": "cost", "description": "DESCRIPTION"}' # Delete a classification center kobana finance classification-centers delete \ --params '{"id": "CLASSIFICATION_CENTER_ID"}' \ --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Automatic rules](https://docs.finance.kobana.com.br/en/en/cli/resources/automatic-rules.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Companies The companies in the group. Every account, bill and transaction belongs to one of them, and nearly every filter accepts `company_id`. | Command | HTTP | Description | | ------------------ | --------------------------- | ------------------- | | `companies list` | `GET /v1/companies` | List companies | | `companies create` | `POST /v1/companies` | Create a company | | `companies get` | `GET /v1/companies/{id}` | Get a company by ID | | `companies update` | `PATCH /v1/companies/{id}` | Update a company | | `companies delete` | `DELETE /v1/companies/{id}` | Delete a company | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List companies kobana finance companies list --fields "id,name,cnpj,type,active" # Get a company by ID kobana finance companies get --params '{"id": "COMPANIE_ID"}' # Create a company kobana finance companies create \ --json '{"name": "ACME Comércio Ltda", "cnpj": "12345678000190"}' # Update a company kobana finance companies update \ --params '{"id": "COMPANIE_ID"}' \ --json '{"name": "NAME", "active": true, "trade_name": "TRADE_NAME"}' # Delete a company kobana finance companies delete --params '{"id": "COMPANIE_ID"}' --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Taxes](https://docs.finance.kobana.com.br/en/en/cli/resources/taxes.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Custom classifiers Classification dimensions the company defines itself — project, contract, branch — next to category and classification center. Each classifier belongs to a company (filter with `company_id`) and carries its `values[]` inline; the values are what gets assigned to payables, receivables and transactions. | Command | HTTP | Description | | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- | | `custom-classifiers list` | `GET /v1/custom-classifiers` | List custom classifiers | | `custom-classifiers create` | `POST /v1/custom-classifiers` | Create a custom classifier | | `custom-classifiers get` | `GET /v1/custom-classifiers/{id}` | Get a custom classifier by id | | `custom-classifiers update` | `PATCH /v1/custom-classifiers/{id}` | Update a custom classifier | | `custom-classifiers delete` | `DELETE /v1/custom-classifiers/{id}` | Delete a custom classifier | | `custom-classifiers values create` | `POST /v1/custom-classifiers/{id}/values` | Add a value to a custom classifier | | `custom-classifiers values update` | `PATCH /v1/custom-classifiers/{id}/values/{valueId}` | Update a custom classifier value | | `custom-classifiers values delete` | `DELETE /v1/custom-classifiers/{id}/values/{valueId}` | Delete a custom classifier value | `field_type` sets the field (`dropdown`, the default, `radio`, `multi_select`, `number`, `text`, `phone`, `url`, `date`, `datetime`); `number_format` only applies to `number` and `option_style` only to the list types. A value takes a hex `color` (`#rrggbb`), or a palette color when omitted; `color: null` on `values update` goes back to the palette. Deleting a classifier, or a value, already assigned to a bill or transaction answers `422` (`reason: in_use`) — deactivate it with `active: false` instead, which keeps the assignments. The scopes are `finance/custom_classifiers`. ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List custom classifiers kobana finance custom-classifiers list \ --params '{"company_id": "COMPANY_ID", "active": true}' \ --fields "id,company_id,name,field_type,active,values" # Get a custom classifier by id kobana finance custom-classifiers get \ --params '{"id": "CUSTOM_CLASSIFIER_ID"}' # Create a custom classifier kobana finance custom-classifiers create \ --json '{"company_id": "COMPANY_ID", "name": "Project", "field_type": "dropdown"}' # Update a custom classifier kobana finance custom-classifiers update \ --params '{"id": "CUSTOM_CLASSIFIER_ID"}' \ --json '{"name": "Project (2026)"}' # Add a value to a custom classifier kobana finance custom-classifiers values create \ --params '{"id": "CUSTOM_CLASSIFIER_ID"}' \ --json '{"value": "Downtown site", "color": "#2a78d6"}' # Deactivate a value in use kobana finance custom-classifiers values update \ --params '{"id": "CUSTOM_CLASSIFIER_ID", "valueId": "VALUE_ID"}' \ --json '{"active": false}' # Delete a custom classifier value kobana finance custom-classifiers values delete \ --params '{"id": "CUSTOM_CLASSIFIER_ID", "valueId": "VALUE_ID"}' \ --dry-run # Delete a custom classifier kobana finance custom-classifiers delete \ --params '{"id": "CUSTOM_CLASSIFIER_ID"}' \ --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Classification centers](https://docs.finance.kobana.com.br/en/en/cli/resources/classification-centers.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Financial accounts The accounts money moves through — checking, cash, card. Every transaction, payable and receivable points at a financial account, and it is that balance the cash flow projects. | Command | HTTP | Description | | ---------------------------------------- | --------------------------------------------------------- | ------------------------------------ | | `financial-accounts list` | `GET /v1/financial-accounts` | List financial accounts | | `financial-accounts create` | `POST /v1/financial-accounts` | Create a financial account | | `financial-accounts get` | `GET /v1/financial-accounts/{id}` | Get a financial account by ID | | `financial-accounts update` | `PATCH /v1/financial-accounts/{id}` | Update a financial account | | `financial-accounts delete` | `DELETE /v1/financial-accounts/{id}` | Delete a financial account | | `financial-accounts adjust-balance` | `POST /v1/financial-accounts/{id}/adjust-balance` | Adjust the account balance | | `financial-accounts balances list` | `GET /v1/financial-accounts/{id}/balances` | List recorded balances of an account | | `financial-accounts balances create` | `POST /v1/financial-accounts/{id}/balances` | Record a balance | | `financial-accounts balances latest get` | `GET /v1/financial-accounts/{id}/balances/latest` | Latest balance of every source | | `financial-accounts balances delete` | `DELETE /v1/financial-accounts/{id}/balances/{balanceId}` | Delete a recorded balance | `balances` are **observed balances**, not the account's computed balance (that is `balance` on `get`): each row keeps the `source` that produced it, so a balance the bank reported and one a person typed stay apart. `balances create` only records the observation — it moves no money and creates no transaction; to correct the ledger use `adjust-balance`. `source` defaults to `api`; send `cli` so the audit trail names the real channel (`manual`, `banking`, `open_finance`, `calculated` and `imported` belong to the product itself and answer `422`). `balances latest get` returns the most recent observation of each source in one call — a source that never reported comes back with `amount: null`. A `banking` or `calculated` balance cannot be deleted (`422`): its producer would recreate it. ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List financial accounts kobana finance financial-accounts list \ --fields "id,company_id,name,type,bank_id" # Get a financial account by ID kobana finance financial-accounts get \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' # Create a financial account kobana finance financial-accounts create \ --json '{"company_id": "COMPANY_ID", "name": "NAME", "type": "checking"}' # Update a financial account kobana finance financial-accounts update \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --json '{"company_id": "COMPANY_ID", "name": "NAME", "type": "checking"}' # Adjust the account balance kobana finance financial-accounts adjust-balance \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --json '{"target_balance": "1500.00", "category_id": "CATEGORY_ID"}' # Delete a financial account kobana finance financial-accounts delete \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --dry-run # List recorded balances of an account kobana finance financial-accounts balances list \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --fields "id,source,capture_date,amount,external_id" # Record a balance 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"}' # Latest balance of every source kobana finance financial-accounts balances latest get \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' # Delete a recorded balance kobana finance financial-accounts balances delete \ --params '{"id": "FINANCIAL_ACCOUNT_ID", "balanceId": "BALANCE_ID"}' \ --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Transactions](https://docs.finance.kobana.com.br/en/en/cli/resources/financial-transactions.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Transactions The statement itself: every credit and debit that hit a financial account, classified by category and classification center. The `aggregates` endpoint returns totals instead of the full list. | Command | HTTP | Description | | --------------------------------------- | ------------------------------------------- | ---------------------------- | | `financial-transactions list` | `GET /v1/financial-transactions` | List transactions | | `financial-transactions create` | `POST /v1/financial-transactions` | Create a transaction | | `financial-transactions get` | `GET /v1/financial-transactions/{id}` | Get a transaction by ID | | `financial-transactions update` | `PATCH /v1/financial-transactions/{id}` | Update a transaction | | `financial-transactions delete` | `DELETE /v1/financial-transactions/{id}` | Delete a transaction | | `financial-transactions aggregates get` | `GET /v1/financial-transactions/aggregates` | Aggregate transaction totals | | `financial-transactions ids list` | `GET /v1/financial-transactions/ids` | List transaction IDs | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List transactions kobana finance financial-transactions list \ --fields "id,company_id,financial_account_id,description,bank_description" # Get a transaction by ID kobana finance financial-transactions get \ --params '{"id": "FINANCIAL_TRANSACTION_ID"}' # Create a transaction 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"}' # Update a transaction kobana finance financial-transactions update \ --params '{"id": "FINANCIAL_TRANSACTION_ID"}' \ --json '{"description": "DESCRIPTION", "bank_description": "BANK_DESCRIPTION", "document": "DOCUMENT"}' # Aggregate transaction totals for a month kobana finance financial-transactions aggregates get \ --params '{"company_id": "COMPANY_ID", "month": 1, "year": 2026}' # Delete a transaction kobana finance financial-transactions delete \ --params '{"id": "FINANCIAL_TRANSACTION_ID"}' \ --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Payables](https://docs.finance.kobana.com.br/en/en/cli/resources/payables.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Fiscal documents The fiscal documents (NF-e and NFS-e) **received** against the workspace's companies — through NFE.io, XML upload or SEFAZ. They are read-only: the product never issues notes, so there is no `create` and no cancellation. The list is sorted by most recent issue date. | Command | HTTP | Description | | ----------------------- | ------------------------------- | --------------------------- | | `fiscal-documents list` | `GET /v1/fiscal-documents` | List fiscal documents | | `fiscal-documents get` | `GET /v1/fiscal-documents/{id}` | Get a fiscal document by id | Filters include `kind` (`service` for NFS-e, `product` for NF-e), `situation` (`authorized`, `cancelled`, `unknown`), `source` (`nfe_io`, `xml_upload`, `sefaz`), `access_key`, `number`, `issuer_document` (issuer CNPJ/CPF, digits only) and ranges on `issued_at`, `created_at` and `updated_at` (`[gte]`, `[lte]`…) — `updated_at` is the incremental-sync window. The XML is not served here: follow `xml_download_url`, which belongs to the [Attachments](https://docs.finance.kobana.com.br/en/en/cli/resources/attachments.md) resource and needs the `finance/attachments` scope. This resource's scope is `finance/fiscal_documents` with read access. ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List authorized service notes kobana finance fiscal-documents list \ --params '{"kind": "service", "situation": "authorized"}' \ --fields "id,number,issued_at,issuer_name,issuer_document,total_amount" # A supplier's notes issued in January kobana finance fiscal-documents list \ --params '{"issuer_document": "12345678000190", "issued_at[gte]": "2026-01-01", "issued_at[lte]": "2026-01-31"}' # Get a fiscal document by id kobana finance fiscal-documents get \ --params '{"id": "FISCAL_DOCUMENT_ID"}' \ --fields "id,access_key,number,situation,total_amount,payable_count,xml_download_url" ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Attachments](https://docs.finance.kobana.com.br/en/en/cli/resources/attachments.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Token identity Who is behind the token: the person (`user`, null on an integration token), the organization and the token's own details. Use it to test that the configured token is valid — it is the first command to run after setting `KOBANA_TOKEN`. The token itself never comes back in the response. | Command | HTTP | Description | | -------- | ------------ | --------------------------------- | | `me get` | `GET /v1/me` | Get the identity behind the token | The route is **organization-level**: it takes no `X-Workspace-Id`, so `KOBANA_WORKSPACE_ID` is not needed here. Any valid token works — no scope is required. ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # Get the identity behind the token kobana finance me get # Only the organization and the token kobana finance me get \ --fields "organization,token" ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Authentication](https://docs.finance.kobana.com.br/en/en/cli/overview/authentication.md) — how to get the token and pick the workspace. * [Organization](https://docs.finance.kobana.com.br/en/en/cli/resources/organization.md) --- # Organization The profile of the token's organization, at the top of the hierarchy: it holds for every workspace. The resource is **singular** — there is no `list` and no `id`, because a token always reaches exactly one organization, its own. | Command | HTTP | Description | | --------------------- | ------------------------ | --------------------------------- | | `organization get` | `GET /v1/organization` | Get the organization of the token | | `organization update` | `PATCH /v1/organization` | Update the organization profile | Both routes are **organization-level**: they take no `X-Workspace-Id`, so `KOBANA_WORKSPACE_ID` is not needed here. `get` needs the `finance/settings` scope with read access; `update` needs write access and, since the profile holds for every workspace, the organization owner or access to all of them. `update` only changes `trade_name`, `website`, `addresses` and `custom_metadata`. Name, e-mail and phone come from the Kobana Account and the fiscal identity (`document_type`, `document_number`) does not change through the API: sending any of them — or any unknown key — is a `422`, and a commercial field (`courtesy`, `entitlements`…) is a `403`. `custom_metadata: null` keeps the stored value. ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # Get the organization of the token kobana finance organization get \ --fields "id,name,trade_name,document_number,website,created_at" # Update the organization profile kobana finance organization update \ --json '{"trade_name": "Acme", "website": "https://acme.com.br", "custom_metadata": {"crm_id": "CRM_ID"}}' ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Authentication](https://docs.finance.kobana.com.br/en/en/cli/overview/authentication.md) — the `finance/settings` scope and the workspace of the other routes. * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Resources Every `finance` resource below is generated from the same OpenAPI spec documented in the [API Reference](https://docs.finance.kobana.com.br/en/en/api/v1) — the CLI dispatches to the exact same endpoints, so filters, validation and delete behaviour are identical. Reach for [schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) whenever a command's exact parameters aren't obvious from the examples here. ``` kobana finance [flags] ``` ## How to read these pages[​](#how-to-read-these-pages "Direct link to How to read these pages") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. See [Authentication](https://docs.finance.kobana.com.br/en/en/cli/overview/authentication.md) for the `finance` product's own credentials. A subpath that only takes `POST` is an action of its resource, named by its last segment — `kobana finance automatic-rules reorder` and `kobana finance receivables charge cancel`. The older form ending in `create` still works. ## The catalogue[​](#the-catalogue "Direct link to The catalogue") | Resource | Command | Methods | | ---------------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | [Financial accounts](https://docs.finance.kobana.com.br/en/en/cli/resources/financial-accounts.md) | `financial-accounts` | list, create, get, update, delete, adjust-balance, balances list, balances create, balances latest get, balances delete | | [Transactions](https://docs.finance.kobana.com.br/en/en/cli/resources/financial-transactions.md) | `financial-transactions` | list, create, get, update, delete, aggregates get, ids list | | [Payables](https://docs.finance.kobana.com.br/en/en/cli/resources/payables.md) | `payables` | list, create, get, update, delete, cancel-dispatch, send-to-bank, aggregates get, ids list | | [Receivables](https://docs.finance.kobana.com.br/en/en/cli/resources/receivables.md) | `receivables` | list, create, get, update, delete, aggregates get, charge create, charge cancel, ids list | | [Cash flow](https://docs.finance.kobana.com.br/en/en/cli/resources/cash-flow.md) | `cash-flow` | get | | [Reconciliations](https://docs.finance.kobana.com.br/en/en/cli/resources/reconciliations.md) | `reconciliations` | create, get, delete | | [Categories](https://docs.finance.kobana.com.br/en/en/cli/resources/categories.md) | `categories` | list, create, get, update, delete | | [Classification centers](https://docs.finance.kobana.com.br/en/en/cli/resources/classification-centers.md) | `classification-centers` | list, create, get, update, delete | | [Custom classifiers](https://docs.finance.kobana.com.br/en/en/cli/resources/custom-classifiers.md) | `custom-classifiers` | list, create, get, update, delete, values create, values update, values delete | | [Automatic rules](https://docs.finance.kobana.com.br/en/en/cli/resources/automatic-rules.md) | `automatic-rules` | list, create, get, update, delete, reorder | | [People](https://docs.finance.kobana.com.br/en/en/cli/resources/people.md) | `people` | list, create, get, update, delete, ids list | | [Companies](https://docs.finance.kobana.com.br/en/en/cli/resources/companies.md) | `companies` | list, create, get, update, delete | | [Taxes](https://docs.finance.kobana.com.br/en/en/cli/resources/taxes.md) | `taxes` | list, create, get, update, delete | | [Attachments](https://docs.finance.kobana.com.br/en/en/cli/resources/attachments.md) | `attachments` | list, create, get, delete, download, links, unlink | | [Receipts](https://docs.finance.kobana.com.br/en/en/cli/resources/receipts.md) | `receipts` | list, get | | [Fiscal documents](https://docs.finance.kobana.com.br/en/en/cli/resources/fiscal-documents.md) | `fiscal-documents` | list, get | | [Transfers](https://docs.finance.kobana.com.br/en/en/cli/resources/transfers.md) | `transfers` | create, get | | [Banks](https://docs.finance.kobana.com.br/en/en/cli/resources/banks.md) | `banks` | list | | [AI agents](https://docs.finance.kobana.com.br/en/en/cli/resources/ai-agents.md) | `ai-agents` | list, create, get, update, delete, triggers get, triggers create, triggers update, triggers delete, triggers token | | [AI skills](https://docs.finance.kobana.com.br/en/en/cli/resources/ai-skills.md) | `ai-skills` | list, create, get, update, delete | | [Organization](https://docs.finance.kobana.com.br/en/en/cli/resources/organization.md) | `organization` | get, update | | [Token identity](https://docs.finance.kobana.com.br/en/en/cli/resources/me.md) | `me` | get | --- # Payables Bills due and already paid, with payment approval, dispatch to the bank and allocation across classification centers. Bills awaiting approval only show up in the listing if you filter by `payment_approval=pending_approval`. | Command | HTTP | Description | | -------------------------- | ---------------------------------------- | ------------------------------- | | `payables list` | `GET /v1/payables` | List payables | | `payables create` | `POST /v1/payables` | Create a payable | | `payables get` | `GET /v1/payables/{id}` | Get a payable by ID | | `payables update` | `PATCH /v1/payables/{id}` | Update or settle a payable | | `payables delete` | `DELETE /v1/payables/{id}` | Delete a payable | | `payables cancel-dispatch` | `POST /v1/payables/{id}/cancel-dispatch` | Cancel the dispatch to the bank | | `payables send-to-bank` | `POST /v1/payables/{id}/send-to-bank` | Send a payable to the bank | | `payables aggregates get` | `GET /v1/payables/aggregates` | Aggregate payable totals | | `payables ids list` | `GET /v1/payables/ids` | List payable IDs | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List payables kobana finance payables list \ --fields "id,company_id,description,amount,interest_amount" # Get a payable by ID kobana finance payables get --params '{"id": "PAYABLE_ID"}' # Create a payable kobana finance payables create \ --json '{"company_id": "COMPANY_ID", "description": "DESCRIPTION", "amount": "1500.00", "due_date": "2026-01-31T12:00:00Z"}' # Update or settle a payable kobana finance payables update \ --params '{"id": "PAYABLE_ID"}' \ --json '{"description": "DESCRIPTION", "amount": "1500.00", "due_date": "2026-01-31T12:00:00Z"}' # Cancel the dispatch to the bank kobana finance payables cancel-dispatch --params '{"id": "PAYABLE_ID"}' # Aggregate payable totals for a month kobana finance payables aggregates get \ --params '{"company_id": "COMPANY_ID", "month": 1, "year": 2026}' # Delete a payable kobana finance payables delete --params '{"id": "PAYABLE_ID"}' --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Receivables](https://docs.finance.kobana.com.br/en/en/cli/resources/receivables.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # People Customers and suppliers — the counterparty of any bill. `ids` returns identifiers only, handy to keep an agent's context window small. | Command | HTTP | Description | | ----------------- | ------------------------ | ------------------------------------- | | `people list` | `GET /v1/people` | List people (customers / suppliers) | | `people create` | `POST /v1/people` | Create a person (customer / supplier) | | `people get` | `GET /v1/people/{id}` | Get a person by ID | | `people update` | `PATCH /v1/people/{id}` | Update a person | | `people delete` | `DELETE /v1/people/{id}` | Delete a person | | `people ids list` | `GET /v1/people/ids` | List person IDs | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List people (customers / suppliers) kobana finance people list --fields "id,company_id,name,legal_name,nickname" # Get a person by ID kobana finance people get --params '{"id": "PEOPLE_ID"}' # Create a person (customer / supplier) kobana finance people create \ --json '{"company_id": "COMPANY_ID", "name": "NAME"}' # Update a person kobana finance people update \ --params '{"id": "PEOPLE_ID"}' \ --json '{"name": "NAME", "legal_name": "LEGAL_NAME", "nickname": "NICKNAME"}' # Delete a person kobana finance people delete --params '{"id": "PEOPLE_ID"}' --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Companies](https://docs.finance.kobana.com.br/en/en/cli/resources/companies.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Receipts The payment receipts the platform generates. Read-only. | Command | HTTP | Description | | --------------- | ----------------------- | --------------------------- | | `receipts list` | `GET /v1/receipts` | List payment receipts | | `receipts get` | `GET /v1/receipts/{id}` | Get a payment receipt by ID | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List payment receipts kobana finance receipts list \ --fields "id,company_id,payable_id,payable_status,financial_account_id" # Get a payment receipt by ID kobana finance receipts get --params '{"id": "RECEIPT_ID"}' ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Transfers](https://docs.finance.kobana.com.br/en/en/cli/resources/transfers.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Receivables What you have coming in, with charge issuing and cancellation through the Banking Gateway straight from the receivable. Moving the money is the `charge` command — the record itself lives here. | Command | HTTP | Description | | ---------------------------- | ----------------------------------------- | ------------------------------- | | `receivables list` | `GET /v1/receivables` | List receivables | | `receivables create` | `POST /v1/receivables` | Create a receivable | | `receivables get` | `GET /v1/receivables/{id}` | Get a receivable by ID | | `receivables update` | `PATCH /v1/receivables/{id}` | Update or settle a receivable | | `receivables delete` | `DELETE /v1/receivables/{id}` | Delete a receivable | | `receivables aggregates get` | `GET /v1/receivables/aggregates` | Aggregate receivable totals | | `receivables charge create` | `POST /v1/receivables/{id}/charge` | Issue a charge for a receivable | | `receivables charge cancel` | `POST /v1/receivables/{id}/charge/cancel` | Cancel a receivable's charge | | `receivables ids list` | `GET /v1/receivables/ids` | List receivable IDs | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List receivables kobana finance receivables list \ --fields "id,company_id,description,amount,interest_amount" # Get a receivable by ID kobana finance receivables get --params '{"id": "RECEIVABLE_ID"}' # Create a receivable kobana finance receivables create \ --json '{"company_id": "COMPANY_ID", "description": "DESCRIPTION", "amount": "1500.00", "due_date": "2026-01-31T12:00:00Z"}' # Update or settle a receivable kobana finance receivables update \ --params '{"id": "RECEIVABLE_ID"}' \ --json '{"description": "DESCRIPTION", "amount": "1500.00", "due_date": "2026-01-31T12:00:00Z"}' # Aggregate receivable totals for a month kobana finance receivables aggregates get \ --params '{"company_id": "COMPANY_ID", "month": 1, "year": 2026}' # Delete a receivable kobana finance receivables delete --params '{"id": "RECEIVABLE_ID"}' --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Cash flow](https://docs.finance.kobana.com.br/en/en/cli/resources/cash-flow.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Reconciliations The link between a statement transaction and the bill it settles. Creating the reconciliation settles the bill; deleting it undoes the settlement. | Command | HTTP | Description | | ------------------------ | --------------------------------- | -------------------------- | | `reconciliations create` | `POST /v1/reconciliations` | Create a reconciliation | | `reconciliations get` | `GET /v1/reconciliations/{id}` | Get a reconciliation by ID | | `reconciliations delete` | `DELETE /v1/reconciliations/{id}` | Delete a reconciliation | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # Get a reconciliation by ID kobana finance reconciliations get --params '{"id": "RECONCILIATION_ID"}' # Create a reconciliation kobana finance reconciliations create \ --json '{"billings": [], "transaction_ids": []}' # Delete a reconciliation kobana finance reconciliations delete \ --params '{"id": "RECONCILIATION_ID"}' \ --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Categories](https://docs.finance.kobana.com.br/en/en/cli/resources/categories.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Taxes The taxes withheld or payable attached to a bill. | Command | HTTP | Description | | -------------- | ----------------------- | --------------- | | `taxes list` | `GET /v1/taxes` | List taxes | | `taxes create` | `POST /v1/taxes` | Create a tax | | `taxes get` | `GET /v1/taxes/{id}` | Get a tax by ID | | `taxes update` | `PATCH /v1/taxes/{id}` | Update a tax | | `taxes delete` | `DELETE /v1/taxes/{id}` | Delete a tax | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # List taxes kobana finance taxes list \ --fields "id,name,default_rate,default_withholding,active" # Get a tax by ID kobana finance taxes get --params '{"id": "TAXE_ID"}' # Create a tax kobana finance taxes create --json '{"name": "IRRF"}' # Update a tax kobana finance taxes update \ --params '{"id": "TAXE_ID"}' \ --json '{"name": "IRRF", "default_rate": "1.50", "default_withholding": true}' # Delete a tax kobana finance taxes delete --params '{"id": "TAXE_ID"}' --dry-run ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Attachments](https://docs.finance.kobana.com.br/en/en/cli/resources/attachments.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Transfers Moves between two of your own financial accounts. Produces both transactions — out and in — in a single call. | Command | HTTP | Description | | ------------------ | ------------------------ | -------------------- | | `transfers create` | `POST /v1/transfers` | Create a transfer | | `transfers get` | `GET /v1/transfers/{id}` | Get a transfer by ID | ## Examples[​](#examples "Direct link to Examples") `--params` carries query and path parameters (id, page, filters); `--json` carries the request body; `--fields` limits which fields come back — worth using on every `list`/`get` to save context. See [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) for the full reference. ``` # Get a transfer by ID kobana finance transfers get --params '{"id": "TRANSFER_ID"}' # Create a transfer 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"}' ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Banks](https://docs.finance.kobana.com.br/en/en/cli/resources/banks.md) * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — every parameter this resource accepts. --- # Global flags | Flag | Description | | ------------------------- | ---------------------------------------------------------------------------------------------------------- | | `--params ''` | Query/URL parameters (id, page, filters) | | `--json ''` | Request body (POST/PUT/PATCH) | | `--file ` | Sends a file as a part of a `multipart/form-data` body (repeatable; the `--json` fields become text parts) | | `--fields ''` | Limits which fields come back in the response | | `--dry-run` | Shows the request without executing it | | `--page-all` | Auto-pagination with NDJSON output | | `--page-limit ` | Maximum number of pages (default: 10) | | `--page-delay ` | Delay between pages (default: 100ms) | | `--env ` | Environment: `production` (default), `sandbox`, `development` | | `--verbose` | Request details on stderr | | `--output ` | Saves the response to a file | | `--output-format ` | Format: `json`, `table`, `csv` | | `--idempotency-key ` | Custom idempotency key | | `--lang ` | Language of the messages: `pt`, `en` or `es` (default: the system's) | ## Sending files[​](#sending-files "Direct link to Sending files") `--file field=path` swaps the JSON body for `multipart/form-data`: each `--file` becomes a file part named after the field, and the `--json` fields go along as text parts. Repeat the flag to send more than one file. Each part's type comes from the extension (an `.eml` goes as `message/rfc822`), and `--dry-run` shows the `content_type` and the `files` list before sending. The field names are those of the endpoint's `multipart/form-data` body in the [API Reference](https://docs.finance.kobana.com.br/en/en/api/v1). ``` kobana finance attachments create \ --file file=nota-junho.pdf \ --json '{"title": "Nota fiscal de junho"}' \ --dry-run ``` ## Language[​](#language "Direct link to Language") The CLI speaks Portuguese, English or Spanish: help, messages, errors and command descriptions. The language comes, in this order, from `--lang`, the `KOBANA_LANG` variable, the terminal's locale variables (`LC_ALL`, `LC_MESSAGES`, `LANG`) and, last, the system language. ``` kobana --lang pt finance --help export KOBANA_LANG=es ``` Command and flag names, JSON keys and exit codes never change with the language. Available since version 0.6.0. ## Next steps[​](#next-steps "Direct link to Next steps") * [Usage](https://docs.finance.kobana.com.br/en/en/cli/usage/overview.md) — syntax, resources, examples. * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — parameters, required fields, types and responses. --- # Helpers Helpers are commands prefixed with `+` that provide multi-step workflows the dynamic commands alone cannot: simplified interfaces, batch operations, or calls composed across multiple endpoints. They do not wrap a single API call already available through the dynamic commands — every helper flag controls orchestration logic, not a reshaped version of `--params`/`--json`. Today's helpers belong to the **Banking Gateway**, and are available from the same binary whichever product you use: | Helper | Description | | ---------------- | ------------------------------------------------ | | `+emitir` | Simplified bank billet creation with named flags | | `+cancelar-lote` | Batch-cancel multiple bank billets by id | | `+cobrar` | Simplified Pix charge creation with named flags | ``` # Issue a bank billet kobana +emitir --valor 150.50 --vencimento 2026-05-01 \ --nome "Maria Silva" --cpf-cnpj "012.345.678-90" --carteira 1 # Create a Pix charge kobana +cobrar --valor 99.90 --conta-pix "UID" \ --nome "João" --cpf-cnpj "012.345.678-90" # Batch-cancel bank billets kobana +cancelar-lote --ids "123,456,789" ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Usage](https://docs.finance.kobana.com.br/en/en/cli/usage/overview.md) — the dynamic commands these helpers sit alongside. * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — inspect the underlying endpoints a helper calls. --- # Usage ## Syntax[​](#syntax "Direct link to Syntax") ``` kobana [flags] ``` * **``** — `banking`, `finance`, `billing` or `inbox`. * **``** — can be nested: `payables`, `receivables`, `attachments links`. * **``** — the action: `list`, `get`, `create`, `update`, `delete`, or an action specific to the resource. The API version never appears in the command — the CLI resolves the URL from the embedded OpenAPI spec. URL and query parameters go in `--params`; the request body goes in `--json`. The whole surface is discoverable through `--help`, at every level: ``` kobana --help # products kobana finance --help # Smart Finance resources kobana finance financial-accounts --help # a resource's methods ``` ## `finance` resources[​](#finance-resources "Direct link to finance-resources") | Resource | Description | | ------------------------ | ---------------------- | | `financial-accounts` | Financial accounts | | `financial-transactions` | Transactions | | `payables` | Payables | | `receivables` | Receivables | | `cash-flow` | Cash flow | | `reconciliations` | Reconciliations | | `categories` | Categories | | `classification-centers` | Classification centers | | `automatic-rules` | Automatic rules | | `people` | People | | `companies` | Companies | | `taxes` | Taxes | | `attachments` | Attachments | | `receipts` | Receipts | | `transfers` | Transfers | | `banks` | Banks | Each resource has a page of its own, with the full command table and examples — see the [catalogue](https://docs.finance.kobana.com.br/en/en/cli/resources/overview.md). ## Examples[​](#examples "Direct link to Examples") ``` # Open payables kobana finance payables list \ --params '{"status": "pending"}' \ --fields "id,description,amount,due_date" # Aggregate totals instead of the whole list kobana finance payables aggregates get --params '{"month": 1, "year": 2026}' # Send a bill to the bank for payment kobana finance payables send-to-bank --dry-run --params '{"id": "PAYABLE_ID"}' # The month's cash flow kobana finance cash-flow get \ --params '{"from": "2026-01-01", "to": "2026-01-31"}' # Reconcile a transaction against a bill kobana finance reconciliations create \ --json '{"financial_transaction_id": "TRANSACTION_ID", "payable_id": "PAYABLE_ID"}' # List with automatic pagination (NDJSON) kobana finance financial-transactions list --page-all --fields "id,amount,date" # Table output kobana finance financial-accounts list --output-format table # Save the response to a file kobana finance payables get --params '{"id": "PAYABLE_ID"}' --output conta.json ``` ## Next steps[​](#next-steps "Direct link to Next steps") * [Schema introspection](https://docs.finance.kobana.com.br/en/en/cli/usage/schema.md) — inspect any endpoint's parameters and body. * [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) — every flag a command accepts. * [Helpers](https://docs.finance.kobana.com.br/en/en/cli/usage/helpers.md) — `+verb` shortcuts for common workflows. * [Resources](https://docs.finance.kobana.com.br/en/en/cli/resources/overview.md) — the full catalogue, resource by resource. --- # Schema introspection ``` # List every product and its resources kobana schema --list # View the schema of a specific endpoint kobana schema finance.payables.list kobana schema finance.payables.create kobana schema finance.cash-flow.list ``` Returns parameters, required fields, types and responses — all derived from the embedded OpenAPI spec, so it is always in sync with what a command actually accepts. The path has the same shape as the command: `..`. This is the recommended first step for an AI agent that does not already know the exact shape of a payload: inspect the schema before issuing a mutating call, rather than guessing. ## Next steps[​](#next-steps "Direct link to Next steps") * [Global flags](https://docs.finance.kobana.com.br/en/en/cli/usage/global-flags.md) — `--params`, `--json`, `--dry-run` and the rest. * [Usage](https://docs.finance.kobana.com.br/en/en/cli/usage/overview.md) — syntax, resources, examples. --- # Receipts **Financial > Receipts** (`/receipts`) gathers the payment receipts of the workspace. Every payment sent to the bank and confirmed produces a receipt here **automatically** — and whatever was paid outside the system (bank app, direct debit) you upload by hand. Either way, whoever needs the receipt is [notified by email](#who-is-emailed). note **A receipt is about money going OUT.** This screen belongs to the payables side. On the receivables side the equivalent is the charge your customer pays — see [Bank slip and Pix charges](https://docs.finance.kobana.com.br/en/en/contas-a-receber/cobranca-kobana.md). ## Where each receipt comes from[​](#where-each-receipt-comes-from "Direct link to Where each receipt comes from") | Source | How it shows up | Deletable? | | ----------------- | ------------------------------------------------------------ | ---------- | | **Bank** | on its own, when a payment sent to the bank is **confirmed** | ❌ no | | **Manual upload** | you upload the file through **"Upload receipt"** | ✅ yes | info **A captured receipt cannot be deleted.** It is the proof of a payment that really happened, and the next capture would bring it back — deleting it would be a promise the bank undoes. What you uploaded, on the other hand, is your own file, and it leaves along with its attachment. ## The numbers strip[​](#the-numbers-strip "Direct link to The numbers strip") Above the table, five numbers for the filtered period: | Number | What it counts | | ---------------- | ----------------------------------------------------------------------------------------------------- | | **Receipts** | how many exist in the current slice | | **Available** | the document is already stored — the happy ending | | **No link** | no payable attached | | **Failed** | the capture could not fetch the document | | **Total amount** | the sum of their amounts — set apart by a rule, since it is the only one that does not count receipts | note **These numbers ignore the search box and the active tab.** They answer *"how many exist over there?"*, not *"how many are left of what I'm looking at"* — otherwise the tab counter would shrink while you type. ## The four tabs[​](#the-four-tabs "Direct link to The four tabs") * **All** — everything in the period. * **No link** — receipts that don't point at a payable yet. Only manual uploads produce these: through the bank the bill is always known. * **Bill still open** — the receipt points at a payable nobody settled. See [A receipt does not settle the bill](#a-receipt-does-not-settle-the-bill). * **Failed** — the capture could not fetch the document. Each row shows why. ## A receipt's status[​](#a-receipts-status "Direct link to A receipt's status") | Status | What it means | | --------------- | ------------------------------------------------------------ | | **Downloading** | the receipt was identified and the document is being fetched | | **Available** | ready to open and download | | **Failed** | the document could not be fetched; use **"Try again"** | info **A few moments in "Downloading" is normal.** Fetching the document runs in the background and is done sparingly — the bank caps how many lookups fit in an hour, and those lookups are shared with the syncs and with the payment status tracking. ## Filters and search[​](#filters-and-search "Direct link to Filters and search") The search box at the top looks at the **payee** (name or document) and at the **bill's description**. **Advanced search** narrows by: * **Payment date** (period) * **Company** — only in the consolidated view; with one company picked at the top, it is the scope of the whole screen * **Financial account** — where the money came from * **Settlement** — bank slip, Pix, tax, transfer… * **Source** — bank or manual upload ## What you can do on each row[​](#what-you-can-do-on-each-row "Direct link to What you can do on each row") | Action | When it appears | | ------------------------ | ----------------------------------------------- | | **Download receipt** | the document is available | | **Open the bill** | there is a payable linked | | **Link to a bill** | there isn't, and only on manually uploaded ones | | **Unlink from the bill** | there is, and only on manually uploaded ones | | **Mark as paid** | the linked bill is still open | | **Try again** | only on captured receipts that failed | | **Delete** | only on manually uploaded ones | Clicking the document opens the **preview**. **Images** render right there; a **PDF opens in a new tab** — the system's security policy doesn't allow displaying it inside the screen, and the preview says so instead of showing an empty frame. note **Some banks only hand the receipt over as a web page, not as a file.** There is nothing to store in that case: the receipt stays reachable through **"Open at the origin"**, and the row remains **Available** — it is not a failure. ## Linking to a payable[​](#linking-to-a-payable "Direct link to Linking to a payable") **"Link to a bill"** attaches the receipt to a payable. **The attachment goes with it**: the receipt then also shows up on the bill's own screen, with no need to attach it again. Unlinking removes that association. This is the path for a payment you made through your bank's app: upload the receipt and link it to the matching bill — either as you upload it, or later from the row's own menu. tip **Can't find the bill in the list? Type.** With nothing typed the list shows bills due **around the payment date**, which is where the matching one almost always is — and flags the ones matching the receipt with **"Same amount"** and **"Same date"**. As soon as you type, the search covers **every period**: that is how you find the bill for a payment made two months late. The line under the field always says which slice is in force and how many bills were left out. note **Link and unlink exist only on manual uploads.** On a captured receipt the bill comes from the payment itself, and the next capture would bring it back — touching it there would be a promise the bank undoes. ## A receipt does not settle the bill[​](#a-receipt-does-not-settle-the-bill "Direct link to A receipt does not settle the bill") **Linking a receipt does not mark the payable as paid.** They are two different facts: the receipt is the *evidence* that the money left; the settlement is the payment recorded in the system, which creates the entry in the financial account. When the payment goes out through the bank, the settlement already happens on its own at confirmation. On a manual upload it does not — which is why a bill can read **Overdue** with the receipt attached to it. The screen tells you instead of deciding for you: the linked bill gets a **"Bill still open"** mark under its description, the tab of the same name gathers all of them, and the **"Mark as paid"** action opens the usual payment confirmation — already filled in with the receipt's date and account. info **Why not automatic?** The receipt's amount is not always the bill's: interest, discounts and partial payments make the two differ. Settling on its own would record the wrong amount in exactly the cases that matter most — so the confirmation stays with you, who knows what happened. ## Uploading a receipt by hand[​](#uploading-a-receipt-by-hand "Direct link to Uploading a receipt by hand") **"Upload receipt"** opens the form. Required: the **file**, the **payment date** and the **amount**. Optional: **payable**, payee, financial account and settlement kind — you can link the bill now or later. The company is not chosen here: whichever one is selected at the top of the screen applies. note **The file must be a PDF or an image** (`pdf`, `png`, `jpg`). Spreadsheets and statements — `xlsx`, `csv`, `xml`, `ofx` — are accepted under **[Attachments](https://docs.finance.kobana.com.br/en/en/anexos/.md)**, because they serve other purposes, but none of them proves a payment. The size limit is the same as for attachments. ## Who is emailed[​](#who-is-emailed "Direct link to Who is emailed") The notice goes out to **two lists**, which coexist: | List | Where you set it | Who can be on it | What they get | | ------------------- | --------------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------- | | **The workspace's** | **"Configure delivery"**, on this screen | workspace members only | a notice, with a link to the bill and the [attached files](#what-is-attached) | | **The bill's** | on the payable's form, under **"Receipt delivery"** | any email address | **the [attached files](#what-is-attached)**, no link | ### The workspace list[​](#the-workspace-list "Direct link to The workspace list") **"Configure delivery"** opens the list of who is notified about **every** receipt in the workspace. info **Only workspace members appear here.** This list has no free email field: a loose address covering the whole workspace would be a parallel registry, with no owner and no way to revoke it. Removing someone from the workspace already takes them off the delivery list; there is no need to uncheck them here too. ### The bill's list[​](#the-bills-list "Direct link to The bill's list") On the payable's form, **"Receipt delivery"** takes **any address** — the supplier's accountant, the payee themselves. They receive **the receipt and the bill's other attachments** in the email, and no link into the system: they are outsiders, and a button to a screen they cannot enter would be a locked door. info **Why a free email address here but not on the other list?** A receipt is a document you send *out* — requiring the supplier's accountant to become a member of your workspace to receive one is not governance, it is a wall. What keeps this list in check is its reach: it belongs to **that one bill**, is edited on that bill's form, and leaves with it, so there is no inherited address nobody remembers to remove. The list **repeats down a series**: when you create an installment plan or a recurrence, every installment and every occurrence is born with the same recipients, because each one produces its own receipt. Changing it afterwards affects only the bill you edited. ### When the email goes out[​](#when-the-email-goes-out "Direct link to When the email goes out") On any of the three ways a receipt reaches a bill: * the **automatic capture**, when the bank confirms the payment; * a **manual upload already linked** to a payable; * **"Link to a bill"**, on a receipt that had no link yet. With nobody on either list, no email is sent — and nothing fails because of it. The **bell** notification happens either way. Anyone on both lists receives it **only once**. note **The email always goes out in the product's default language.** The bell notification, on the other hand, shows up in each person's own language. ### What is attached[​](#what-is-attached "Direct link to What is attached") The email carries the **receipt** and, with it, **all of the bill's attachments** — the invoice, the boleto, the contract — because whoever needs the receipt almost always needs those too. The receipt comes first; the rest follow in the order they were attached to the bill. **The bill's other receipts are left out.** A bill can hold more than one (installments, a re-upload), and each email is about a single payment — the earlier ones already had their own notice. note **Emails have a size limit.** If the files add up to more than **25 MB**, the ones that don't fit are left out, and the email itself says which — better for the rest to arrive than nothing at all. note **A receipt the bank only serves as a web page has no file to attach.** The email still goes out, with just the bill's other attachments. ## Receipts of older payments[​](#receipts-of-older-payments "Direct link to Receipts of older payments") The capture is triggered by the payment's confirmation, so it cannot reach the past: payments confirmed **before** the feature existed have no receipt here. Whoever administers the environment can run a one-off sweep to fetch them — it is deliberately slow, so it doesn't eat the bank's lookup budget. ## Related[​](#related "Direct link to Related") * [Payables — sending to the bank](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md) — what produces the confirmation that generates the receipt * [Attachments](https://docs.finance.kobana.com.br/en/en/anexos/.md) — the library where the captured document is stored * [Banking Gateway integration](https://docs.finance.kobana.com.br/en/en/integracoes/kobana.md) — the connection that makes the capture possible * [Payables — the form](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/.md#receipt-delivery) — where a bill's recipients are registered * [API — Receipts](https://docs.finance.kobana.com.br/en/en/api/v1/list-receipts) — to read receipts from outside the system (read-only) * [API — Update payable](https://docs.finance.kobana.com.br/en/en/api/v1/update-payable) — the `receipt_emails` field, to register recipients from outside the system --- # Reconciliation The **Reconciliation** screen (`/conciliacao`) closes the bank statement lines of one account. Each line is money that already left or came in; reconciling is saying which **bill** it belongs to — a payable or a receivable — or, when there is no bill (a fee, rent nobody registered, money that only moved between accounts), recording what is missing right there. ## Concept[​](#concept "Direct link to Concept") * **Transaction** — the statement line, as the bank sent it (Open Finance, the Kobana Banking Gateway, an OFX/QIF file or the Fintera or Nibo import). It already is a transaction of the account, usually classified by the [automatic rules](https://docs.finance.kobana.com.br/en/en/regras-automaticas/.md) when it arrives. * **Bill** — the payable or receivable. A line is **open** while it has no bill, is not part of a reconciliation group and is not a leg of a transfer. Only open lines show on the screen; a reconciled line leaves it. What is not a bank movement never shows: a zero line, a **balance adjustment** made on the account and the opening balance the Nibo import writes. When Nibo settled a schedule across several statement lines, the import already reconciles all of them with the bill: those lines do not show here, and the bill lists them all in its reconciliation. When a bill is settled from the bill itself (**"Mark as paid"** / **"Mark as received"**), the system creates a transaction linked to it. If the statement line arrives later, reconciling swaps that automatic transaction for the bank's line. ## Prerequisites[​](#prerequisites "Direct link to Prerequisites") * **One account chosen.** Reconciliation works account by account: with **All accounts** at the top of the screen, it asks you to *"Choose an account"*. * **An account that reconciles.** The account must be active with reconciliation enabled; otherwise the screen shows *"Reconciliation is off for this account"* (or *"No accounts available"* when none reconciles). * **An account with a company.** Bills belong to a company: an account without one shows *"Account has no company"*. ## The top[​](#the-top "Direct link to The top") * **Manual** / **Batch** — the two modes. The choice is remembered. * **Back to statement** — the account's statement, where a reconciliation is also undone. * **Automatic rules** — the [rules](https://docs.finance.kobana.com.br/en/en/regras-automaticas/.md) screen. * **Import** — **OFX or QIF file**, **Spreadsheet** or **Imported statements**, on the account page. * **The account block** — bank, branch and account, the **Connected via Open Finance** badge when it applies, **Change account** and when the statement was last read: the last Open Finance or Banking Gateway read, or the last file import on a manual account. ### Filters and order[​](#filters-and-order "Direct link to Filters and order") Both modes filter by **Period**, **Description or name**, **Amount** (Min and Max) and **Type** (Inflows or Outflows). Filters apply on **Filter** and are remembered. The period starts empty: every open line of the account. The order can be **by date** (the default, oldest first), **by description**, **by amount** or **by relevance**. A line's **relevance** is how many open lines of the account have the same bank text: sorting by it brings first what repeats the most — fees, rent, payroll. ## Manual[​](#manual "Direct link to Manual") One card per line. On the left, what the bank sent: date, amount (arrow left and green for an inflow, right and red for an outflow, as in Transactions), the bank text and the counterparty, when known. Below, **Create rule** and the trash can. On the right, three tabs and the **OK** button. The card opens on **Suggestion** when there is one; otherwise on **New transaction**. ### Suggestion[​](#suggestion "Direct link to Suggestion") The bill that closes the line: * **same amount**, always; * of the **same company** and the right direction (an outflow with a payable, an inflow with a receivable); * **pending or overdue**, or already **settled by the automatic transaction** and not reconciled yet; * picked by the **counterparty** — the document of the bill's person written on the line, the person a rule already put on the line, the name — and by **how close the date is**, up to 45 days. With no counterparty signal at all, a suggestion only shows for a lone bill up to 7 days away. When two bills tie, there is no suggestion: the choice is yours, in **Search / Create several**. The suggestion can also be the **other end of a transfer**: the only open line of another account of the workspace, in the opposite direction, with the same amount and up to 3 days apart — *"Transfer to (account)"* on an outflow, *"Transfer from (account)"* on an inflow. **OK** reconciles: the bill becomes paid or received with the statement line. The same suggestion can show on several identical lines; after the OK, the other line moves on to the next suggestion. ### New transaction[​](#new-transaction "Direct link to New transaction") When nothing closes the line, it becomes a new bill, **already settled** with the line's amount, date and account: * **Type** — **Payable** on an outflow, **Receivable** on an inflow, or **Transfer**. * **Supplier** or **Customer**, **Description**, **Category** and **Classification center**. The description starts with the bank text. * The **paperclip** attaches a file to the bill created. * **Open full form** opens the full payable or receivable form, filled with what is on the card (a **New** contact and the attachment do not carry over). Saving it comes back reconciled. A bill created here goes through neither payment approval nor the bank: it is born paid. Its classification also goes to the statement line; what the bill leaves empty, the line keeps. The supplier or customer, category and center must belong to the account's company. #### Guesses[​](#guesses "Direct link to Guesses") With **Show guesses** on (next to *"Statement in Smart Finance"*), the form comes filled in, with the **guess** ribbon: 1. what the line already carries — the person, category and center an automatic rule put on it; 2. otherwise, the last classification used for the **same bank text**, in the same company and direction, in the last year; 3. otherwise, the person whose CPF/CNPJ is written on the line and the category of their last bill. When the line names a **CNPJ that belongs to no one registered** (the Open Finance payer or payee, or the document in the bank text), the supplier or customer comes with the **New** badge and the legal name registered at the Receita Federal. The OK creates the person together with the bill. Turning **Show guesses** off leaves contact, category and center blank. The choice is remembered. #### Transfer[​](#transfer "Direct link to Transfer") With **Type** = **Transfer**, the form asks for the **Destination account** and the description. The line becomes one leg of the transfer: * if the destination account has an open line in the opposite direction, with the same amount and up to 3 days apart, the two are paired; * otherwise, the other leg is written in the destination account. Two new legs are never born. Credit card accounts do not show as a destination. #### Reconcile all[​](#reconcile-all "Direct link to Reconcile all") On the OK of a new transaction, if there are other open lines of the account with **the same amount, direction and bank text**, the screen asks *"Reconcile all at once?"*: * **Only this one** — reconciles only the card's line; * **Reconcile all** — creates the same bill for every line, in one action. A line that could not follow (someone reconciled it meanwhile, for example) stays open, and the notice says how many. ### Search / Create several[​](#search--create-several "Direct link to Search / Create several") For a line that closes with **more than one bill** — a wire that paid three invoices — or with a bill the suggestion did not find: Opening the tab, the search shows **below the card, across its whole width**; the form's place holds what was already picked. 1. **Payables** (or **Receivables**, on an inflow) and **Transfers**. 2. Filters **Name**, **Period**, **Description or reference**, **Amount** (exact) and **Category**, then **Filter**. Without a filter, the list comes by amount, up to 100 at a time. 3. Check the bills. The selection **adds up across searches** and rises to the card, with each one's paperclip and X — and the pencil, when there is a single pending bill. 4. The card shows *"(amount) left to reconcile"* until the sum closes — or *"(amount) over this transaction's amount"* when it goes past. 5. **Create new transaction** (or the *"create a new payable"* link, before picking any) opens *"New payable"* or *"New receivable"* with the amount left: **Description**, **Supplier** or **Customer**, **Category** and **Classification center**. **Save** puts it on the card; **OK** reconciles everything together. **OK** only enables with the exact sum. With a single bill, the pencil opens **Interest and discount**: the bill's amount plus interest, minus discount, must equal the line's. Under **Transfers**, the list brings the open lines of other accounts of the workspace; pairing needs the same amount. Bills and a transfer do not mix in one reconciliation. ### Create rule and delete[​](#create-rule-and-delete "Direct link to Create rule and delete") * **Create rule** opens a new [automatic rule](https://docs.finance.kobana.com.br/en/en/regras-automaticas/.md), prefilled with the account, the direction, the bank text and the card's classification. Once saved, it comes back to the reconciliation. * The trash can deletes the imported transaction, after confirming: *"It leaves the account's statement and the next sync or import does not bring it back."* ## Batch[​](#batch "Direct link to Batch") A table with one row per open transaction, to record **many new lines at once** — fees, transfers between your own accounts, what repeats every month: | Side | Columns | | ------------------------- | --------------------------------------------------------- | | **What was imported** | Date, Description, Payer/payee, Amount, Relevance | | **What will be recorded** | Type, Description, Supplier/Customer or account, Category | The Date, Description, Amount and Relevance columns sort the table; clicking again reverses it. The right side comes prefilled by the guess, and the description with the bank text. * **Ready** — a row turns **green** when it has a description, a contact and a category; on a transfer, a description and a destination account. Checking rows brings up the bulk-actions bar right above the table, as on the other listings: how many are selected, how many are ready to reconcile, **Edit** and **Reconcile**. * **Edit** — opens *"Edit N transactions"*: the fields filled in apply to every checked row (**Apply**), and the empty ones stay as they are. The category can only be changed when the checked rows are all inflows or all outflows. * **⋮ → Create rule** — the same prefilled rule as in Manual. * **Reconcile** — reconciles the checked rows that are ready; the others stay. Each row goes on its own: one that fails (because someone reconciled it first, for example) does not stop the others, and the reason shows below its description. The **Known transactions** filter keeps only the lines the guess knows: those that already have a person or category, or whose bank text was classified in the last year. note **Batch always creates a new bill** (or a transfer) per line, without a classification center. A line that closes with a bill that already exists is reconciled in **Manual**. ## Undoing a reconciliation[​](#undoing-a-reconciliation "Direct link to Undoing a reconciliation") The screen has no undo: the reconciled line leaves it. You undo from the account's statement (**Back to statement**), on the transaction's detail: * **Unlink** — the bill goes back to pending and the line becomes open again. On a bill the reconciliation created, deleting the bill also frees the line. * **Undo reconciliation** — on the transfer card of a line that came from the bank: the leg the reconciliation wrote is deleted; a paired line becomes open again. It only applies to the transfer of a statement line: a transfer entered by hand is deleted on its own screen. note **An imported reconciliation cannot be unlinked.** A reconciliation mirrored from Fintera is read-only: it reflects the source system, and the next import would bring it back. ## Counts on other screens[​](#counts-on-other-screens "Direct link to Counts on other screens") The [transactions](https://docs.finance.kobana.com.br/en/en/lancamentos/.md) listing has the **Reconciled** filter, which looks only at the link with bills. Reconciliation also treats as done a line that became a transfer leg — so a line can be off the Reconciliation screen and still show as not reconciled in the transactions listing. ## Empty states[​](#empty-states "Direct link to Empty states") * **"Nothing to reconcile"** — every line of the account, with the filters applied, is reconciled. A different period or amount may bring others. ## Through the API and MCP[​](#through-the-api-and-mcp "Direct link to Through the API and MCP") The same actions exist in the API v1, under the `finance/reconciliations` scope: * [a line's suggestions](https://docs.finance.kobana.com.br/en/en/api/v1/get-reconciliation-suggestions) — the bill or transfer that closes it, the guess and the twin lines; * [the new bill, already settled](https://docs.finance.kobana.com.br/en/en/api/v1/reconcile-with-new-billing), with reconcile all; * [the transfer](https://docs.finance.kobana.com.br/en/en/api/v1/reconcile-as-transfer); * [the batch](https://docs.finance.kobana.com.br/en/en/api/v1/reconcile-transactions-batch). Reconciling bills that already exist, including many with many transactions, is [creating a reconciliation](https://docs.finance.kobana.com.br/en/en/api/v1/create-reconciliation). In the MCP, the same actions are the [transactions](https://docs.finance.kobana.com.br/en/en/mcp/tools/transactions.md) tools. --- # Payables Payables (`/payables`) record the organization's outgoing commitments: supplier invoices, operating expenses, taxes, payroll, and any past or future disbursement obligation. ![Payables list](/en/assets/images/01-payables-90d34244427b0f7a3513942d00ed78fd.png) ![Payable detail](/en/assets/images/02-payable-detail-0fca950b18499b2ecfd589a601804600.png) ## In this section[​](#in-this-section "Direct link to In this section") ## [📄️Lifecycle](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/ciclo-de-vida.md) [States, transitions and the approval gate — Draft → Pending → Paid.](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/ciclo-de-vida.md) ## [📄️Installments and recurrence](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/parcelas-e-recorrencia.md) [Split into installments or repeat periodically — the three bill types and how series behave.](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/parcelas-e-recorrencia.md) ## [📄️Operation and payment](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/operacao-e-pagamento.md) [Operation type, document (bank slip, utility bill, tax, PIX), transfer (TED, PIX) or direct debit, and the payment coordinates.](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/operacao-e-pagamento.md) ## [📄️Tax / tribute](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/tributos.md) [DARF, DARE, GRU, GPS, FGTS, ICMS, ISS, IPTU and ITBI — how to enter the tax form and what goes to the bank.](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/tributos.md) ## [📄️Sending to the bank (Banking Gateway)](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md) [Send approved payables to the bank through the Banking Gateway — prerequisites, status and automatic settlement.](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md) ## [📄️CSV import](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/importacao-csv.md) [Import batches of payables from a spreadsheet — accepted columns, the forgiving format and the approval gate.](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/importacao-csv.md) ## The list[​](#the-list "Direct link to The list") The header opens with three totals for the period — **To pay**, **Paid** and **Total** — and an actionable subtitle: if anything is late, *"You have 3 overdue bills"* renders the red fragment as a button that applies the overdue filter; if nothing is late, *"You're all caught up on your bills."* The header also holds the **period** button, **"New payable"** and — **only with the gateway connected** — **"Send payments"**, which opens the batch dispatch inbox. The red counter beside it counts everything the inbox will list: bills **overdue and due in the next 7 days**, ready or blocked. That's where the batch goes out from; the list has no per-row shortcut to the bank. To the right of the totals sit the **"Import"** (opens the panel below and clears search and filters) and **"Report"** (opens in a dialog) pills. Import requires a **specific company** to be selected. ### Filters[​](#filters "Direct link to Filters") * **Search** — by description or document number. * **Quick filters** — **All**, **With attachments**, **Paid**, **Reconciled**, **Drafts**. * **Advanced filters** — a panel with the combined criteria, an active-filter counter and a summary you can clear or edit. ### Columns[​](#columns "Direct link to Columns") Description, Due date, Category, **General status**, **Status at the bank**, Amount and **Settlement** — plus **Company**, only in the consolidated view. **Tax** and **Notes** are hidden by default; so is **Settlement**. Turn them on from the column menu. note **General status and Status at the bank are two columns, both sortable, side by side** — not one status with a chip stuck to it. One says what Smart Finance knows; the other, what the bank reports. See [Lifecycle](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/ciclo-de-vida.md). ### Row actions[​](#row-actions "Direct link to Row actions") The same nine as on the receivables side, with the payables labels: | Action | When it shows | | ---------------- | ----------------------------------------------------------------- | | **Mark as paid** | While manual settlement is still possible | | **Reconcile** | Already paid and not yet reconciled | | **Installments** | Installment type | | **Recurrences** | Recurring type, inside a series | | **Classify** | Always | | **Edit** | Always | | **Undo** | Already paid | | **Cancel** | Pending only, and **off** the gateway track | | **Delete** | Off the bank: never sent, or the payment was rejected or canceled | warning **A bill already dispatched to the bank offers neither "Mark as paid", "Cancel" nor "Delete".** Voiding or deleting it here would leave the payment alive on the gateway, without the bill that explains it. Once paid it stays too: it is the record of what left the account. The way out is **"Cancel dispatch"**, on the gateway card in the detail screen. Canceling the dispatch **does not undo it**: the bill stays on the gateway track, now carrying the **Canceled** badge. The only thing that comes back is **"Mark as paid"** — the dispatch never went through, so the bill is still pending and someone has to close it outside the system. **"Cancel" does not come back:** once sent to the bank, a bill can never again be canceled from the list. See [Sending to the bank](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md). ### Bulk actions[​](#bulk-actions "Direct link to Bulk actions") **"Classify selected"** (only with a specific company), **"Mark as paid"** and **"Delete"**, with the selection's **To pay**, **Paid** and **Total** updating live. **"Mark as paid"** opens a dialog with the **Payment date** (today, by default). Each bill is paid at its own amount, from the **source account** it expects; if any selected bill has none, the dialog asks for the account for those. Interest and discounts are left out — for those, settle one at a time. What the row would not let you mark as paid (already paid, sent to the bank, awaiting approval) is left out, and the dialog says how many. ## The form[​](#the-form "Direct link to The form") **Company is not a field** — it comes from the header selector. ### ESSENTIALS[​](#essentials "Direct link to ESSENTIALS") | Field | Notes | | ----------------- | ------------------------------------------------------------------------------ | | **Amount (R$)** | Required. Currency field with a mask | | **Due date** | Required. On creation, relative-date shortcuts are available | | **Pay from** | The financial account expected to fund the payment | | **Description** | Required | | **Supplier** | Required. Picking an existing supplier **pre-fills their payment information** | | **Accrual month** | Required. Month picker | note **"Pay from" is the expected account, and it is the form's only account field.** The account that **actually** paid isn't typed here: you choose it at settlement, in the **"Source account"** field of the "Confirm payment" dialog. ### CLASSIFICATION[​](#classification "Direct link to CLASSIFICATION") **Type** (required: **One-time**, **Recurring**, **Installment**, revealing **Recurrence** or **Installments**), **Category** and **Classification center**, each with the **Split** shortcut. ### OPERATION & DOCUMENT[​](#operation--document "Direct link to OPERATION & DOCUMENT") The axis that sets payables apart from receivables: * **Operation type** — **Document payment** or **Transfer**. * The next field **only appears after** that choice, and its name changes with it: **"Document"** (Bank slip, Utility bill, Tax / tribute, PIX…) or **"Transfer type"** (**Bank transfer (TED)**, PIX). Switching the operation clears an incompatible method. * **Document number** and **Document date**. The choice unlocks the payment coordinates — barcode, PIX, bank details, tax form data. See [Operation and payment](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/operacao-e-pagamento.md) and [Tax / tribute](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/tributos.md). ### RECEIPT DELIVERY[​](#receipt-delivery "Direct link to RECEIPT DELIVERY") Who receives this payment's **receipt** by email, **with the file attached** — together with the [bill's other attachments](https://docs.finance.kobana.com.br/en/en/comprovantes/.md#what-is-attached) —, as soon as a receipt is attached to the bill. Takes **any address** — the supplier's accountant, the payee — with an optional **label** to tell them apart. The list applies to **this bill**. When you create an installment plan or a recurrence, every installment and every occurrence **is born with the same recipients**, because each one produces its own receipt — but changing the list afterwards affects **only the bill you are editing**. It does **not** replace the members selected under [Receipts](https://docs.finance.kobana.com.br/en/en/comprovantes/.md#who-is-emailed): they keep getting their own notices. note **This block does not depend on the operation you picked.** Unlike the payment coordinates, it neither changes nor clears when you switch the document or the transfer type — and it stays editable even after the bank confirms the payment, because it says who to notify, not what the bank did. ### Withheld taxes · Notes and IR[​](#withheld-taxes--notes-and-ir "Direct link to Withheld taxes · Notes and IR") **Withheld taxes** (pills for taxes withheld at source), the **"Tax-relevant"** pill and **"Add note"**. ### Attachments[​](#attachments "Direct link to Attachments") When creating, you can attach files before saving. ## Confirm payment[​](#confirm-payment "Direct link to Confirm payment") Two tabs: * **Pay** — **Payment date** and **Source account**. Marks the bill as paid and creates the debit transaction. * **Pay & reconcile** — *"Pay this bill by linking it to a transaction that already exists in the statement — no duplicates."* On both tabs, the **"Payment adjustments"** section (optional) accepts **Interest** and **Discount**. Below it, **Amount paid** shows what leaves the account. On **Pay**, that figure, not the bill's own value, is what the debit transaction is booked at; on **Pay & reconcile**, it is what the chosen transaction is compared with, and the interest and discount are recorded on the bill. warning **A payment confirmed by the bank locks part of the form.** *"What describes the payment — amount, due date, supplier and the payment information — can no longer be changed. Internal classification (category, center, attachments, notes) stays editable."* See [Lifecycle](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/ciclo-de-vida.md). --- # Payables lifecycle A payable is described by **three independent layers**. They don't replace one another — they coexist, and the screen shows all of them: | Layer | What it answers | Where it shows | | --------------------- | ----------------------------------------------------------------- | -------------------------------- | | **1. Bill status** | Where the bill sits inside Smart Finance (Draft → Pending → Paid) | **"General status"** column | | **2. Approval** | Has a person released this payment? (the entry gate) | Badge next to the general status | | **3. Gateway status** | If it was sent to the bank, where it stands **there** | **"Status at the bank"** column | note Layer 3 only exists if the bill was sent to the bank. In the list it has a **column of its own**: **"General status"** and **"Status at the bank"** sit side by side, both sortable — the gateway is never a chip hanging off the bill status. They are two distinct signals: one says what Smart Finance knows, the other what the bank reports. Off the gateway track, the column shows "-". What appears **next to** the general status is **layer 2**: the approval badge. And on the detail screen the gateway status isn't in the header — it lives inside the **gateway card**. ## Layer 1 — Bill status[​](#layer-1--bill-status "Direct link to Layer 1 — Bill status") | State | Description | | ------------- | ----------------------------------------------------------- | | **Draft** | Created but not published. Doesn't count toward the totals. | | **Pending** | Confirmed, awaiting payment. | | **Paid** | Linked to a transaction. | | **Cancelled** | Voided, generates no movement. | The column also shows a fifth badge that **is not a state**: **Overdue** — any **Pending** bill whose due date has passed. It is derived from the date, not stored: nothing "becomes" overdue, and paying or rescheduling makes it disappear on its own. * **Publish** (Draft → Pending): confirms the bill — but it still goes through layer 2. * **Mark as paid** (Pending → Paid): there are two routes — see "How a bill becomes Paid", below. * **Cancel** (Pending → Cancelled): voids it. It only shows on a pending bill, and it **is not irreversible** — the dialog says *"You can reopen it later by editing the status."* ## Layer 2 — Payment approval[​](#layer-2--payment-approval "Direct link to Layer 2 — Payment approval") An anti-fraud gate: a bill created through the form, CSV or API **does not enter the official list** until a person approves it in [Approve payments](https://docs.finance.kobana.com.br/en/en/aprovar-pagamentos/.md) (`/payables/approvals`). The gate is a workspace setting, **on by default**; turned off, created bills are born official and skip the queue. | State | Meaning | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Awaiting approval** | Waiting for someone to approve it. **Outside the official list** — it counts toward neither the totals nor the cash flow, and it can't go to the bank. | | **Approved** | Released — it enters the official list and becomes eligible to be sent to the bank. | | **Rejected** | Blocked for good. | | *(no badge)* | Born official, without going through the queue. | The gate applies to whatever **comes in the front door**: the form, CSV import and the API. Born **official, without approval** are the bills the system itself generates from something already decided earlier — the occurrences of an already-approved recurrence and whatever comes in from Fintera. The occurrences of a recurrence still awaiting approval are born awaiting it too, with the same author — whoever created it approves none of them. warning **Saving as a draft doesn't dodge the gate.** A draft carries no badge because it isn't an obligation yet — but **publishing** is the moment it becomes one, and that's when it joins the queue, like any bill created directly. A draft is not a shortcut. While it awaits approval, **the manual "Mark as paid" disappears too** — the bill isn't official yet. ## Layer 3 — Gateway status[​](#layer-3--gateway-status "Direct link to Layer 3 — Gateway status") This only comes into existence after the bill is sent to the bank. It mirrors the payment's **real** state on the gateway — from **Pending** and **Awaiting bank approval** through to **Confirmed**, by way of **Scheduled**, **Awaiting funds** and the like. The full list, with what each one means, is in [Sending to the bank](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md). note **Two approvals, unrelated to each other.** The layer 2 one comes from a person in your workspace, and it releases **entry into the list**. The bank's is the institution's own, and it only happens after dispatch. A bill can be approved here and refused there. warning **"Approved" on the gateway is not the end.** It means the batch was approved by the bank — the institution **has not confirmed yet**. What closes the cycle is **Confirmed**. The final states are Confirmed, Canceled, Rejected, Reproved and Failed. **"Send to the bank" is not a row action in the list.** It exists in two places, both on the **detail** screen: the header and the gateway card. From the list, the route is **"Send payments"**, in the header — the inbox that dispatches in **batch**. ## How a bill becomes Paid — two routes[​](#how-a-bill-becomes-paid--two-routes "Direct link to How a bill becomes Paid — two routes") There are **two routes** to a paid bill, and they are mutually exclusive. ### Manual route — the payment happened outside[​](#manual-route--the-payment-happened-outside "Direct link to Manual route — the payment happened outside") You paid the bill **outside the system** (internet banking, cash, petty cash…). Use **"Mark as paid"**: * Enter the payment date and the financial account used. * The system marks it **Paid** and creates the outgoing transaction in that account. * Interest and discounts can be recorded at settlement. ### Gateway route — the system did the sending[​](#gateway-route--the-system-did-the-sending "Direct link to Gateway route — the system did the sending") You clicked **"Send to the bank"**. From there on **you don't settle it** — the system does it on its own: * When the gateway reaches **Confirmed**, the bill is marked **Paid** **automatically** and the outgoing transaction is created in the source account. * That's why, on the gateway route, the **"Mark as paid"** button **disappears** — it's what prevents a double settlement. warning **Requirement for automatic settlement:** the source account (**"Pay from"**) must be set. Without it the system has nowhere to post the outflow and **does not** settle — the bill stays Confirmed and open (see below). ### When "Mark as paid" comes back[​](#when-mark-as-paid-comes-back "Direct link to When \"Mark as paid\" comes back") If the dispatch **finished** and the bill was still left open, the manual button is re-exposed so you can close it outside: * **Confirmed with no source account** — the bank confirmed, but the system had nowhere to post it. * **Canceled, Rejected, Reproved or Failed** — the payment never went through; it has to happen outside. ## The full flow[​](#the-full-flow "Direct link to The full flow") **Draft is an optional detour, not the front door.** Creating through the form, through CSV or through the API writes the bill straight to Pending and awaiting approval. Only clicking **"Save draft"** routes you through there — and publishing from there lands on the same gate, it doesn't skirt it. ## Create a payable[​](#create-a-payable "Direct link to Create a payable") 1. Go to `/payables/new`. 2. Fill in the required fields: **Amount (R$)**, **Due date**, **Description**, **Supplier**, **Accrual month** and **Type**. 3. Set the operation type and the document — see [Operation and payment](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/operacao-e-pagamento.md). Category and classification center are optional. 4. Finish with **Add bill**, **Add and create another** or **Save draft**. **The supplier is not optional.** Without it the form won't submit: *"Selecione ou crie um fornecedor"*. You can pick an existing supplier **or type a new name** — in which case it gets registered along with the bill. **Company** is required too, but it isn't a form field: it comes from the header selector. note **"Publish" does not exist on the create screen.** The buttons there are the three above. **Publish** shows up only on the **detail** screen, and only while the bill is a draft. Either way, the bill enters under approval (layer 2) before it counts toward the numbers. ## Edit[​](#edit "Direct link to Edit") **A paid bill is not read-only.** There is no lock by state: the form opens normally in any status, including Paid. The real lock is a different one, and it comes from the bank — not from the bill's state. **When the gateway reaches Confirmed**, part of the form closes, and the screen warns you: > *"Payment confirmed by the bank. What describes the payment — amount, due date, supplier and the payment information — can no longer be changed. Internal classification (category, center, attachments, notes) stays editable."* In other words: **the lock is partial, and it has a reason**. It freezes what describes a bank transaction that has **already executed** — amount, due date, supplier, "Pay from", operation type, document and the payment coordinates. What stays open is what describes **how you classify** it: category, center, accrual month, description, attachments, notes, and the **receipt delivery** recipients — that last one because it says who to notify, not what the bank did. Classifying is accounting work that carries on after the money leaves. warning **The lock isn't just cosmetic.** The server refuses changes to those fields even over the API — the screen disabling the fields is the courtesy; the rule holds from any door. This lock **does not exist on receivables** — they never go through a dispatch to the bank. When editing a bill that belongs to a group, the system offers **"Apply to other installments"**, showing you exactly what will change first. That means **all** the installments in the group — including the ones **before** the one you're editing, not just the ones after. Only the already-settled ones and the edited installment itself are left out. The selection comes fully checked; uncheck whatever shouldn't inherit — or save on the open installment alone, with **"Only this installment"** (in a recurrence, **"Only this occurrence"**). note **The receipt recipients are not part of that "apply to the others".** They are copied to every installment **when the series is created**; changing them later applies only to the installment you are editing. To change them everywhere, edit them one by one. ## Delete[​](#delete "Direct link to Delete") On a bill that belongs to a group — **installment or recurring** — deleting asks about the scope: * **Delete only this one** * **Delete this and future ones** The same selector covers both cases: what it looks at is the group, not the type. On a standalone bill it doesn't appear. note The selector shows up **both in the list and in the bill's detail**. --- # Sending payments to the bank Smart Finance sends payables to the bank through the **Banking Gateway**. Sending is a **manual** action — done by a person, one bill at a time or in batch from the inbox — **never** by an automatic trigger, unless automatic dispatch after approval is on in the [Approval Settings](https://docs.finance.kobana.com.br/en/en/aprovar-pagamentos/.md#turn-it-on-or-off). The status tracking runs in the background. Before any dispatch, the workspace's [Security](https://docs.finance.kobana.com.br/en/en/seguranca/.md) rules apply — limits, accounts, payees, operation types, channels and night hours. See [Security blocks](#security-blocks). ## Prerequisites[​](#prerequisites "Direct link to Prerequisites") 1. [Banking Gateway](https://docs.finance.kobana.com.br/en/en/integracoes/kobana.md) connected and active, with the source account already synced. 2. An **official** bill: it is only sendable after passing through [payment approval](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/ciclo-de-vida.md) — or if it was born official, like the occurrences of an approved recurrence and the bills imported from Fintera. A bill awaiting that approval or rejected is blocked. Don't confuse it with the **bank's** approval, which only exists after dispatch. 3. **Operation type** set and the payment coordinates filled in — barcode, PIX key, bank details. See [Operation and payment](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/operacao-e-pagamento.md). 4. **"Pay from"** set — that's the account the money leaves from. 5. Allowed by [Security](https://docs.finance.kobana.com.br/en/en/seguranca/.md): channel, operation type, account, payee, time of day and limits. ## Dispatch flow[​](#dispatch-flow "Direct link to Dispatch flow") note **There is no "schedule" on the screen.** Sending is always your click — nothing goes out on its own, on any date. What the system sends to the bank, along with the payment, is the date it should settle: the bill's **due date**. If the bill is already past due, it goes out **today** — the gateway doesn't pay with a backdated date. ## Security blocks[​](#security-blocks "Direct link to Security blocks") The [Security](https://docs.finance.kobana.com.br/en/en/seguranca/.md) rules are checked on every dispatch — through the button, in batch or by automatic dispatch. **Nothing is rescheduled**: a held-back bill keeps its reason in sight and must be sent again once the rule allows it. ### Reasons on the dispatch list[​](#reasons-on-the-dispatch-list "Direct link to Reasons on the dispatch list") ![Send list with Security blocks and a limit warning](/en/assets/images/29-dispatch-inbox-184188cee7e224b5b8c9e6173066d15a.png) In the **Send payments to the bank** dialog, a bill held back by a rule that depends only on the bill itself shows **disabled**, with the reason — hover it to read the full message: | Reason | Where it is solved | | -------------------------------------- | ---------------------------------- | | **Channel not allowed to dispatch** | Security → Channels (Pay) | | **Operation type turned off** | Security → Operation types | | **Account blocked for this operation** | Security → Accounts | | **Beneficiary not allowed** | Security → Payees (transfers only) | | **Night dispatch blocked** | Wait for the day period | | **Above the per-transaction limit** | Security → Limits | The limits that depend on what **has already been sent** show as a **warning**, and the row stays selectable: * *Would exceed the period limit* * *Would exceed the account's daily limit* * *Would exceed the beneficiary's daily limit* * *Would exceed the beneficiary's monthly limit* The warning is a forecast: the final count happens at dispatch time. In a batch send, bills go in due-date order, and once a limit is reached the following ones that would exceed it **are not sent**. The result lists each bill that wasn't sent, with its reason. If automatic dispatch after approval was refused by a rule, the row carries the **Automatic dispatch blocked** badge — the bill goes back to the list and waits for a manual send. note **Forcing a resend does not escape the rules.** Resending and resending a canceled payment go through the same checks, and the previous dispatch keeps counting toward the limit as long as there is no proof it doesn't exist at the bank. ### Night sending off[​](#night-sending-off "Direct link to Night sending off") With **Allow sending to the bank at night** off in Security, nothing goes to the bank between the start of the night and the start of the day. The list shows the notice **"Bank dispatch blocked until 06:00"** (with your workspace's hour). **Nothing is rescheduled for the morning.** What was approved at night — even with automatic dispatch on — stays on the list and must be sent again during the day period. ### Held at the bank[​](#held-at-the-bank "Direct link to Held at the bank") A payment created at the end of the day may have its batch's automatic approval fall in the night period. With night sending off, the batch **is not approved** and stays **held at the bank**: * the payment card, on the bill, shows the **"Held at the bank: night dispatch blocked"** badge; * the dispatch list gets a **Held at the bank** section; * the **Approve at the bank** button (on the card and in the section) only works during the day period: it checks the rules again, approves the batch and resumes tracking. **"Refresh status"** and the automatic tracking do not approve a held batch. ## Gateway status[​](#gateway-status "Direct link to Gateway status") The status mirrors the payment's **real** state on the gateway: | Status | What it means | | ------------------------------------------- | ----------------------------------------- | | **Pending** | Created on the gateway, not processed yet | | **Awaiting bank approval** | In the institution's approval queue | | **Approved** | Approved — but **not settled yet** | | **Scheduled** · **Awaiting scheduled date** | Set for a future date | | **Awaiting funds** | Not enough money in the account to settle | | **Overdue** | Past the date and never settled | | **Finishing** | In final processing | | **Confirmed** | Settled — the money left | | **Reproved** · **Rejected** | Refused by the institution | | **Failed** | Processing error | | **Canceled** | Dispatch canceled | warning **"Approved" is not the end.** It's the state that misleads the most: the batch was approved, but the institution **has not settled yet**. What closes the cycle is **Confirmed**. The final states are Confirmed, Canceled, Rejected, Reproved and Failed. ## Automatic settlement[​](#automatic-settlement "Direct link to Automatic settlement") Settlement happens when the gateway reaches **Confirmed** — not at Approved, which is still an intermediate step. Once there, the system marks the bill as paid and creates the outgoing transaction in the source account. warning **With no "Pay from" set, there is no automatic settlement.** The system would have nowhere to post the outflow: the bill stays Confirmed and open. See [Lifecycle](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/ciclo-de-vida.md). The **"Refresh status"** button fetches the current state on demand, without waiting for the automatic tracking. ## Receipt[​](#receipt "Direct link to Receipt") Once it reaches **Confirmed**, the payment receipt is **captured automatically**: it is stored in the bill's [Attachments](https://docs.finance.kobana.com.br/en/en/anexos/.md) and listed under [Receipts](https://docs.finance.kobana.com.br/en/en/comprovantes/.md). Whoever is set to receive them gets an email, and the addresses registered under **"Receipt delivery"** on the bill's form get the **file attached**; the bell notifies either way. See [Who is emailed](https://docs.finance.kobana.com.br/en/en/comprovantes/.md#who-is-emailed). While it is being fetched the status reads **Downloading** — normal, and it takes a few moments. ## Cancel dispatch[​](#cancel-dispatch "Direct link to Cancel dispatch") **"Cancel dispatch"** undoes the dispatch while the payment **hasn't reached a final state**. The bill stays on the gateway track, now carrying the **"Canceled"** badge, and **"Mark as paid"** comes back — so you can close the bill outside, if the payment ends up happening some other way. That's why a bill already sent does **not** offer "Cancel": voiding it here would leave the payment alive on the gateway. The route is to cancel the dispatch first. ## Editing after dispatch[​](#editing-after-dispatch "Direct link to Editing after dispatch") Once dispatch starts, **amount, payee, account and payment details are locked**: *"Bill already sent to the bank — amount, payee, account and payment details can no longer be changed."* The bill must keep matching what was paid. Before dispatch, changing those fields on an approved bill sends it back to [approval](https://docs.finance.kobana.com.br/en/en/aprovar-pagamentos/.md#editing-an-approved-bill). --- # CSV import — Payables Import batches of payables from a CSV file. ## Where it lives[​](#where-it-lives "Direct link to Where it lives") **There is no "Import" in the menu**, and no import screen. The way in is: **Payables** → the **Import** pill, on the listing itself. With no payable yet, the listing shows the empty state with an **Import** button next to **New payable**, which opens the same panel. You need a **specific company** selected in the header. Under "all companies", the panel only warns: *"Select a specific company to import payables."* The **Download template** button hands you a sample CSV with the right header — the safest place to start, because it already comes in the right encoding. ## CSV columns[​](#csv-columns "Direct link to CSV columns") | Column | Required | Description | | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `description` | ✅ | Payable description | | `amount` | ✅ | Amount in reais (e.g. `3500,00`) | | `due_date` | ✅ | Due date (`dd/MM/yyyy`) | | `competence_date` | — | Competence date (`dd/MM/yyyy`) | | `document` | — | Document identifier | | `document_date` | — | Issue date (`dd/MM/yyyy`) | | `document_number` | — | Invoice number | | `person_name` | — | Supplier name (if it doesn't exist yet, the preview asks whether to create it) | | `category_name` | — | Category name (if it doesn't exist yet, the preview asks whether to create it) | | `cost_center_name` | — | Classification center name (if it doesn't exist yet, the preview asks whether to create it) | | `payment_method` | — | Method: `bank_billet`, `utility`, `tribute`, `ted`, `pix`, `credit_card`, `debit_card`, `cash`, `check`, `direct_debit`, `other` or `none` (the Portuguese aliases — `boleto`, `dinheiro`, … — are also accepted) | | `notes` | — | Notes | | `ir_relevant` | — | `true` or `false` | | `operation_kind` | — | `pagamento` or `transferencia` | | `barcode` | — | Barcode (boleto or utility bill) | | `pix_copia_e_cola` | — | PIX Copia e Cola payload | | `pix_key` | — | PIX key | | `pix_key_type` | — | Key type: `cpf`, `cnpj`, `email`, `phone`, `random` | | `bank_code` | — | Bank COMPE code (TED) | | `bank_ispb` | — | Bank ISPB (TED) | | `agency` | — | Bank branch | | `agency_digit` | — | Branch check digit | | `account_number` | — | Account number | | `account_digit` | — | Account check digit | | `transfer_purpose` | — | Transfer purpose (TED) | | `tax_kind` | — | Tax type: `darf`, `gru`, `gps`, `fgts`, `icms`, `iss`, `iptu`, `itbi` or `dare` | | `beneficiary_name` | — | Beneficiary name (sending to the bank) | | `beneficiary_document` | — | Beneficiary CPF or CNPJ | | `scheduled_to` | — | Date/time to schedule the send to the bank | The names above are the canonical ones, but **every header also accepts its Portuguese equivalent** — `descricao`, `valor`, `vencimento`, `fornecedor`, `categoria`, `observacao` and so on. Spreadsheets from other systems work for supplier, classification center and category too: `contraparte` counts as `person_name`; `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` count as `cost_center_name`, and `plano_de_contas`, `categoria_financeira`, `category` as `category_name`. If the workspace has a classifier with the same name as one of these columns (e.g. *Centro de Resultado*), the column goes to the classifier. If the file has more than one column for the same field (e.g. `Centro de Custo` and `Centro de Receita`), each row uses the first one that is filled in. Beyond those names, a header with the word **centro** is read as the classification center; one with **categoria** or **plano de contas** as the category (e.g. `Centro de Lucro`, `Categoria DRE`); and one with **pessoa**, **cliente** or **fornecedor** next to nothing but name words as the person (e.g. `Nome do Fornecedor`, `Cliente / Fornecedor` — but not `CNPJ do Fornecedor`). Columns the system doesn't know are **ignored silently**. ## Format[​](#format "Direct link to Format") The parser is more forgiving than it looks. You don't have to normalize the file first: * **Header** — case, accents and spaces don't matter: `Descrição`, `DESCRICAO` and `descricao` are the same column. * **Separator** — `,` or `;`, detected **from the header line**. On a tie, `;`. * **Dates** — `31/12/2026`, `31-12-2026` or `2026-12-31`. * **Amounts** — `1234.56`, `1.234,56`, `1234,56`, with or without `R$`. The amount has to be **greater than zero**. * **`ir_relevant`** — `true`/`false`, `sim`/`nao`, `yes`/`no`, `1`/`0`, `s`/`y`/`n`. Accents and case don't matter. Empty leaves the field blank. warning **The encoding has to be UTF-8, and this is where most files trip up.** Excel in Portuguese saves CSV as Windows-1252 by default, and the system refuses it with a message that stays in Portuguese: *"Arquivo não está em UTF-8. Salve novamente em UTF-8 e tente novamente."* ("The file is not UTF-8. Save it again as UTF-8 and try once more.") In Excel, use **Save As → CSV UTF-8**; or start from the downloaded template. Other whole-file rejections: an extension other than `.csv`, a size above **5 MB**, an empty file, and a **missing required column** — *"Colunas obrigatórias ausentes: amount"* ("Missing required columns: amount"). In those cases there is no preview: the problem is the file, not a row. ## Importing[​](#importing "Direct link to Importing") 1. Upload the file. The system reads it and shows the preview. 2. **Valid rows come pre-selected.** Click a row to deselect it. 3. Click **Import N lines**. ### Rows with errors[​](#rows-with-errors "Direct link to Rows with errors") Invalid rows show up in the preview with a red marker, **and can't be selected or edited there**. There is no fixing them inside the system. The screen itself tells you the way out: *"Uncheck the rows with errors or fix them in the file and upload again."* The number in **Row N** is the line number **in the file**, counting the header — the first data line is 2. ### Writing happens in the background[​](#writing-happens-in-the-background "Direct link to Writing happens in the background") On confirmation you get *"Import started in the background"* and a progress dialog. **You can close the dialog** — the import keeps going, and progress stays visible in the lower-right corner. ### Links to other records[​](#links-to-other-records "Direct link to Links to other records") **Suppliers, categories and classification centers show up in the preview**, each with what the import will do: existing ones are linked; new ones come marked to **create** (or to **leave blank** if you can't create them); a name that only differs from an existing one in accents, case or spacing comes marked to **use the existing one**; and a classification center that only exists for the other side (e.g. one of type Revenue on a payable) comes marked to leave blank. The supplier is looked up by name alone: a person already registered as a customer works too, and becomes a supplier as well. Spellings of the same name that only differ in accents, case or spacing (e.g. *Água e Luz* and *agua e luz*) count as one name. You can change any choice before importing. [Automatic rules](https://docs.finance.kobana.com.br/en/en/regras-automaticas/.md) are applied to the imported records. ## History[​](#history "Direct link to History") Below the panel, the **History** section lists the imports with date, file, status (**Queued**, **Running**, **Completed**, **Failed**, **Cancelled**), how many rows went in out of the total, and who asked for it. ## Approval[​](#approval "Direct link to Approval") Imported payables fall under the **payment approval gate**: they are born **awaiting approval** and **do not show up in the official list** (nor in totals/cash flow) until someone approves them at [Approve payments](https://docs.finance.kobana.com.br/en/en/aprovar-pagamentos/.md). Only once approved can they be sent to the bank. This applies when the gate is **on** (the default); off, imported rows are born official. See [Lifecycle](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/ciclo-de-vida.md). --- # Operation and payment The payable form separates **two different things**, into two blocks: | Block | Answers | | ------------------------ | -------------------------------------------------------------------- | | **OPERATION & DOCUMENT** | What this obligation is and which document represents it | | **PAYMENT INFORMATION** | The coordinates to execute it (barcode, Pix, bank details, tax form) | note **There is no generic "Payment method" field on a payable.** The second field is **labeled by the operation** you pick — and the list of options changes along with it. ## OPERATION & DOCUMENT[​](#operation--document "Direct link to OPERATION & DOCUMENT") ### Operation type[​](#operation-type "Direct link to Operation type") The primary axis. Three options: | Option | What it means | | -------------------- | ---------------------------------------------------------------------------------------------- | | **Document payment** | Settle a document that already exists: a bank slip, a utility bill, a tax form or a Pix charge | | **Transfer** | Send money to a beneficiary | | **Direct debit** | The bank debits the bill on its own on the date, with nothing to send | Until the operation type is chosen, **the second field doesn't even appear**. ### Direct debit[​](#direct-debit "Direct link to Direct debit") For the bill the bank debits by itself: a loan, a fee, a utility bill on direct debit. **There is no second field and no payment panel**, and the bill is **never sent to the bank** — it doesn't show in the dispatch inbox nor offer "Send to bank". When the debit happens, settle it: on the row or in bulk, with **"Mark as paid"** (see [Bulk actions](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/.md#bulk-actions)). ### The second field changes its name with the operation[​](#the-second-field-changes-its-name-with-the-operation "Direct link to The second field changes its name with the operation") | Operation type | Field label | Options | | -------------------- | ----------------- | ---------------------------------------------- | | **Document payment** | **Document** | Bank slip · Utility bill · Tax / tribute · PIX | | **Transfer** | **Transfer type** | Bank transfer (TED) · PIX | * Switching the operation type **resets** the second field when the chosen option doesn't belong to the new operation. * **A tax is a document, not a "payment method"** — that's why it shows up under *Document*, and never in a list of methods. * **PIX appears on both axes**, with different meanings: under *Document payment* it's the **copy-and-paste** code of a charge; under *Transfer* it's a **key or bank details** for a beneficiary. ### Document[​](#document "Direct link to Document") Also in this block: **Document number** and **Document date** — the invoice/bank slip identification. ## PAYMENT INFORMATION[​](#payment-information "Direct link to PAYMENT INFORMATION") This panel only appears when the *operation × document* combination has coordinates to enter. Its title is **"PAYMENT INFORMATION"** — or **"TAX FORM DATA"** when the document is a tax. | Operation → Document | What the panel asks for | | --------------------------- | ---------------------------------------------------------------- | | Payment → **Bank slip** | Barcode | | Payment → **Utility bill** | Barcode | | Payment → **Tax / tribute** | **Tax type** + **How to enter**: **Barcode** or **Guide fields** | | Payment → **PIX** | **Pix code** (copy-and-paste) | | Transfer → **PIX** | **Pix key** or **Bank details** tabs — you pick one path | | Transfer → **TED** | **Bank details**: bank, branch + digit, account + digit | ### Beneficiary (transfers only)[​](#beneficiary-transfers-only "Direct link to Beneficiary (transfers only)") Both transfers — TED and PIX — also carry **who receives**: | Field | Required to send to the bank | | ---------------------- | ---------------------------- | | **Beneficiary name** | Yes | | **Beneficiary tax ID** | Yes | | **Transfer purpose** | No | warning **Without those two fields, [sending to the bank](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md) won't go out.** The institution requires the name and tax ID of whoever receives on any transfer, and the dispatch inbox blocks the row until they're filled in. **On PIX, the beneficiary is always the supplier.** By key or by bank details, both fields show **read-only**, with the name and tax ID from the supplier's record, and the note *"On Pix, the beneficiary is always the payable's supplier. To change it, pick another supplier or fix their record."* Sending to the bank uses that record, even if the bill stores another beneficiary from before. A supplier without a tax ID blocks the send until their record is completed. Through the API, a PIX naming someone else's tax ID as beneficiary is refused. **On TED, picking a supplier fills the beneficiary in for you** — name and tax ID come from the person, along with the bank details of their primary account. This happens the moment you select the person in the Supplier field, and it **overwrites whatever is already there**. The fields stay editable: on a TED the beneficiary can legitimately be someone else (an employee of the supplier, an authorized third party). note **This panel doesn't pay anything.** It only stores the coordinates on the record. Payment happens in one of two ways — outside (and you settle it) or through [sending to the bank](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md). See [Lifecycle](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/ciclo-de-vida.md). ### PIX — copy-and-paste[​](#pix--copy-and-paste "Direct link to PIX — copy-and-paste") When you paste the code, the system **draws the QR code** right away — you can scan it in your bank app and pay outside. **"Look up QR data"** goes further: it fetches the charge and shows the **Payee**, the **QR amount**, the **Due date** and whether it **can be paid**. It's read-only — it's there so you can check before sending. With the data on screen, **"Fill form with this data"** brings it into the form: | From the QR | Goes to | | ----------- | --------------------------------------------------------------------------- | | Amount | **Amount (R$)** | | Due date | **Due date** | | Description | **Description** — only if it's empty; whatever you wrote is not overwritten | | Payee | **Supplier** | **The QR's payee becomes the Supplier.** There is no "Beneficiary" field here — that only exists on a transfer. The system looks for an existing supplier **by the payee's tax ID** (CPF or CNPJ); if it finds one, it selects it. If not, it leaves the **name** filled in as a new supplier, which gets registered on save. ### PIX — key[​](#pix--key "Direct link to PIX — key") The **Key type** (CPF, CNPJ, email, phone, random) is **detected automatically** from the key you type — it's a read-only field; you don't select it. ### Tax — barcode or data[​](#tax--barcode-or-data "Direct link to Tax — barcode or data") There are **nine** types: DARF, GRU, GPS, FGTS, DARE, ICMS, ISS, IPTU and ITBI. note **Only four accept the structured tax form.** **DARF, GRU, GPS and FGTS** get the **"How to enter"** field, to choose between **Barcode** (the default) and **Guide fields** — and from there the fields vary by type. The other five accept **the barcode only**; for them, "How to enter" doesn't even appear. This does **not** limit sending to the bank: all nine are sendable. See [Tax / tribute](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/tributos.md). ### Post-confirmation lock[​](#post-confirmation-lock "Direct link to Post-confirmation lock") Once the bank confirms the payment, the whole panel goes **read-only**: the coordinates now describe a bank transaction that has already executed and can no longer change. ## What about cash, card, check?[​](#what-about-cash-card-check "Direct link to What about cash, card, check?") Cash, credit card, debit card, check and "other" exist in the system and can arrive through **CSV import** or through the **API** — but **no form offers them**. There is no such field on payables, on receivables, or on transactions. **Direct debit** is the exception: it has its own option in **Operation type** (see above). Where they do show up is **on the reading side**: the payables list has the **Settlement** column and the transactions list has **Payment method**, both hidden by default and switchable from the column selector. A bill imported with "cash" shows "cash" there — you just can't type it in. If the obligation is neither a document nor a transfer, **leave the operation type blank**: how the money actually left is recorded at settlement (financial account + date), not here. The select opens empty on a new bill — but it only has the three options, with no "None": once an operation is chosen, there's no going back to blank from the screen. --- # Installments and recurrence Payables support two modes beyond a plain one-off payment: installments and recurrence. ## The three types[​](#the-three-types "Direct link to The three types") The **Type** field, required, offers: | Type | What it is | | --------------- | --------------------------------------------------- | | **One-time** | A single bill, no repetition | | **Installment** | Split into N installments with sequential due dates | | **Recurring** | Repeats on its own at a fixed interval | ## Installment[​](#installment "Direct link to Installment") Pick the type and the **Installments** field appears, for the number of installments: from **2** to **120**. warning **The amount is per installment, not the total.** In **Amount (R$)** you enter what **each** installment is worth — 12 × R$ 100 is entered as amount 100 and 12 installments, not as 1,200. The summary next to the form shows both: **Each installment** and **Total over 12 installments**. On save, the system creates all N bills at once, with **monthly due dates starting from the first due date** (one month per installment) and sequential numbering — **Installment 1/12**, **Installment 2/12**… When the day doesn't exist in a month (the 31st in February), that installment falls on the month's last day. Each installment is an independent bill: it can be paid on its own, and its due date or amount can be adjusted later, one by one. info **Installments are chosen at creation.** On a bill that is already part of a series, **Type** and **Installments** are locked — *"Part of a series: the type and the number of installments can't change."* A saved **One-time** bill can become **Recurring**, but not **Installment**. ### Moving between installments[​](#moving-between-installments "Direct link to Moving between installments") On an installment's detail screen, the arrows take you to the previous and the next one in the same series. The **Installments** action, in the row menu, lists the whole series. ## Recurring[​](#recurring "Direct link to Recurring") Pick the type and the **Recurrence** field appears, required, with five periods: | Option | Interval | | ------------------- | --------- | | **Every week** | 7 days | | **Every two weeks** | 14 days | | **Every month** | 1 month | | **Every 3 months** | 3 months | | **Every year** | 12 months | **The label gets shorter in the listings** — the same recurrence shows up as **Weekly**, **Biweekly**, **Monthly**, **Quarterly** or **Yearly**. Same thing, written short to fit the row. ### The next ones are recorded ahead[​](#the-next-ones-are-recorded-ahead "Direct link to The next ones are recorded ahead") note **A recurrence is born with the coming months already recorded.** On creation the system stores the occurrences up to **12 months ahead** (the default), and the window moves by itself: every day the series are filled up to the new limit. Each occurrence is a real bill — it enters the cash flow, its amount can be changed, and it can be settled **before** the previous one. The horizon lives in **Recurrence settings**, the gear on the payables or receivables listing: **Months to provision**, from 0 to 36. Raising it fills the series at once; lowering it doesn't delete what is already recorded, it only stops recording beyond the new horizon. With **0**, each series keeps only the next bill open, and the following one is born when it is settled. With [payment approval](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/ciclo-de-vida.md) on, every occurrence of a new series enters the approval queue. **Occurrences count from the first one.** A monthly series that starts on the 31st falls on the last day of shorter months and goes back to the 31st when the month has 31 days. Moving one occurrence's due date affects only that one: the following ones stay on the series' original day. **Each recorded occurrence copies the latest one in the series** — amount, category, classification center, payment method, taxes and withholdings, document and notes. A saved **One-time** bill can become **Recurring**: change the type and pick the recurrence, and the system starts the series from it. **Repeat until** (optional, next to the recurrence) is the series' last due date; empty, the series never ends. The date applies to the whole series: shortening it removes the open bills after the new end, and extending it records again. It can't be before the due date of the bill you are editing. On an imported series (Fintera, Nibo), the end comes from the source and the field doesn't show. To change the amount of the coming months, edit an occurrence: the propagation dialog lets you choose which others in the series inherit the change — or none, with **"Only this occurrence"**. Occurrences recorded from then on follow the latest one. Beyond the horizon, the cash-flow projection continues the series at display time, without storing it. See [Dashboard](https://docs.finance.kobana.com.br/en/en/dashboard/.md). The **Recurrences** action, in the row menu, lists the recorded occurrences of the series. On the bill's detail, **Previous due date** and **Next due date** move through them. ### Deleting[​](#deleting "Direct link to Deleting") When you delete a bill that belongs to a group, the system offers: * **Delete only this one** — removes just the current occurrence. On a recurrence it isn't recorded again: the series goes on from the next one. * **Delete this and future ones** — removes the current one and every following one in the group. On a recurrence it also ends the series there: the removed bills aren't recorded again. note **What was already paid stays.** *"Occurrences already paid or reconciled are kept."* If any of the following ones can't be deleted, the notice says how many were left. **An imported series isn't deleted from here.** On a series that came from an integration (Fintera, Nibo), **Delete this and future ones** is refused — *"This series comes from an integration; delete it at the source"*. Its end also comes from the source. **The scope isn't exclusive to recurrences.** The picker looks at the **group**, so **installment and recurring bills behave the same**. On a standalone bill it doesn't appear. The picker lives **in the listing**. Delete from the detail screen and only that one bill goes. --- # Tax / tribute A payable whose **document is a Tax / tribute** stands for a federal, state or municipal tax form. In the form: **Operation type = Document payment** → **Document = Tax / tribute** (a tax is a document, not a "payment method" — see [Operation and payment](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/operacao-e-pagamento.md)). The **Tax type** field decides which tax-form-specific fields you get. ## Tax types[​](#tax-types "Direct link to Tax types") Nine, as they appear in the **"Tax type"** picker: | Tax | Structured tax form? | | ------------------------------------------------------- | -------------------- | | **ITBI** — Real Estate Transfer Tax | No | | **ICMS** — Tax on the Circulation of Goods and Services | No | | **ISS** — Service Tax | No | | **IPTU** — Urban Property and Land Tax | No | | **FGTS** — Severance Indemnity Fund | **Yes** | | **DARE** — State Revenue Collection Document | No | | **DARF** — Federal Revenue Collection Document | **Yes** | | **GRU** — Federal Collection Guide | **Yes** | | **GPS** — Social Security Guide | **Yes** | ## How to enter the tax form[​](#how-to-enter-the-tax-form "Direct link to How to enter the tax form") Once the type is chosen, **DARF, GRU, GPS and FGTS** get a second field — **"How to enter"** — with two options: * **Barcode** (the default) — a single field: **"Barcode / digitable line"**. * **Guide fields** — opens the structured sections of the document, described below. note **The other five types don't get that choice.** ICMS, ISS, IPTU, ITBI and DARE take **the barcode only** — the "How to enter" field never shows up for them. ## Tax form fields[​](#tax-form-fields "Direct link to Tax form fields") Only in **Guide fields** mode, and only for the four types above. Each tax form is laid out in sections that mirror the official document. ### DARF[​](#darf "Direct link to DARF") | Section | Fields | | --------------------------- | ----------------------------------------------------------------------- | | **Taxpayer identification** | Taxpayer type · Taxpayer CPF/CNPJ · Taxpayer name | | **Guide data** | Revenue / payment code · Reference number · Calculation date · Due date | | **Charges and income** | Fine · Interest · Gross income | DARF has the widest **Taxpayer type** list: CNPJ, CPF, NIT, PIS, PASEP, CEI, NB, Title no., DEBCAD and Reference. ### GRU[​](#gru "Direct link to GRU") | Section | Fields | | -------------------------------- | ----------------------------------------------------------------------- | | **Due date and reference** | Due date · Reference number · Total amount | | **Value adjustments (optional)** | Discount · Other deductions · Other additions · **Fine** · **Interest** | ### GPS[​](#gps "Direct link to GPS") | Section | Fields | | --------------------------- | --------------------------------------------------------------- | | **Taxpayer identification** | Taxpayer type · Taxpayer CPF/CNPJ · Taxpayer name | | **Guide data** | Revenue / payment code · Competence · Due date · Other entities | | **Charges (optional)** | Monetary update · Fine · Interest | The GPS **Taxpayer type** list is shorter than the DARF one: CNPJ, CPF, NIT, PIS, PASEP and CEI. ### FGTS[​](#fgts "Direct link to FGTS") | Section | Fields | | ------------------ | ----------------------------------------------------- | | **Identification** | Contributor code · PIS/PASEP number · Collection code | | **FGTS data** | FGTS code · JAM percentage (%) · Connectivity seal | FGTS has no taxpayer section and no charges section — the codes are what identify it. ## Sending through the Banking Gateway[​](#sending-through-the-banking-gateway "Direct link to Sending through the Banking Gateway") note **All nine types can be sent to the bank.** Routing looks at the **operation × document** pair — "Document payment" + "Tax / tribute" resolves to the gateway's tax resource, **whatever the tax type is**. An IPTU entered as a barcode goes out just as well as a DARF. What is exclusive to DARF, GRU, GPS and FGTS **isn't the sending, it's the way you enter it**: only they take the structured tax form. The rest travel on the barcode. **Sending is never automatic.** Nothing leaves on its own: you click it — **"Send to the bank"** on the detail screen, or **"Send payments"** to dispatch a batch from the listing. See [Sending to the bank](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md) and [Lifecycle](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/ciclo-de-vida.md). --- # Receivables Receivables (`/receivables`) record the organization's incoming commitments: customer subscriptions, sales, services rendered, and any amount to be received. ![Receivables list](/en/assets/images/03-receivables-29273e8403d4f45c952bd9e5ba4ab6d2.png) ![Receivable detail](/en/assets/images/04-receivable-detail-c70671181dd8dd01819f839443935c7d.png) ## In this section[​](#in-this-section "Direct link to In this section") ## [📄️Lifecycle](https://docs.finance.kobana.com.br/en/en/contas-a-receber/ciclo-de-vida.md) [States, transitions and receipt — Draft → Pending → Received.](https://docs.finance.kobana.com.br/en/en/contas-a-receber/ciclo-de-vida.md) ## [📄️Installments and recurrence](https://docs.finance.kobana.com.br/en/en/contas-a-receber/parcelas-e-recorrencia.md) [Split into installments or repeat periodically — same behavior as payables.](https://docs.finance.kobana.com.br/en/en/contas-a-receber/parcelas-e-recorrencia.md) ## [📄️Bank slip and Pix charges](https://docs.finance.kobana.com.br/en/en/contas-a-receber/cobranca-kobana.md) [Create a bank slip or a Pix charge from a receivable through the Banking Gateway — prerequisites, states and cancellation.](https://docs.finance.kobana.com.br/en/en/contas-a-receber/cobranca-kobana.md) ## [📄️CSV import](https://docs.finance.kobana.com.br/en/en/contas-a-receber/importacao-csv.md) [Import batches of receivables from a spreadsheet — accepted columns and a forgiving format.](https://docs.finance.kobana.com.br/en/en/contas-a-receber/importacao-csv.md) ## The listing[​](#the-listing "Direct link to The listing") The header opens with three totals for the period — **To receive** (what is still pending), **Received** and **Total** — plus a subtitle that sums up the situation. It is **actionable**: when something is late, the sentence *"You have 3 overdue bills"* renders the red part as a button, and clicking it applies the late-bills filter (the **Overdue** badge). With nothing late, it becomes *"You're all caught up on receivables."* The **Period** button sits in the header, next to **"New receivable"**. To the right of the totals are two action pills: **"Import"** (opens the import panel below, and clears the search and filters to leave the list in a clean state) and **"Report"** (opens in a dialog, without touching the listing). Importing requires a **specific company** selected — in the consolidated view the pill shows a notice instead of opening. ### Filters[​](#filters "Direct link to Filters") * **Search** — by description or document number. * **Quick filters** — **All**, **With attachments**, **Received**, **Reconciled**, **Drafts**. * **Advanced filters** — a panel with the combined criteria; a counter shows how many are active, and a summary lets you clear or edit them without reopening the panel. ### Columns[​](#columns "Direct link to Columns") Description, Due date, Category, Status, Amount — plus **Company**, which only shows in the consolidated view (with a single company selected, every row would carry the same value). **Tax** and **Notes** exist but come **hidden**; turn them on from the columns menu. **"Status at the bank"** shows the state of the [charge](https://docs.finance.kobana.com.br/en/en/contas-a-receber/cobranca-kobana.md) — Registering, Registered, Overdue, Paid, Cancelled — and reads **"-"** for a bill that was never charged. note **"Settlement" belongs to payables only** — here the receipt method materializes in the transaction, when the payment is received. And the general status column is simply **"Status"**, not "General status": receivables do not go through approval. ### Row actions[​](#row-actions "Direct link to Row actions") Nine actions, several of them conditional on the row's state: | Action | When it shows | | -------------------- | ---------------------------------------- | | **Mark as received** | While a manual receipt is still possible | | **Reconcile** | Already received and not yet reconciled | | **Installments** | Installment type | | **Recurrences** | Recurring type, within a series | | **Classify** | Always | | **Edit** | Always | | **Undo** | Already received | | **Cancel** | Pending only | | **Delete** | Always | **Edit** and **Delete** always appear, but with a standing charge the operation is limited: the fields that describe what was charged are locked and deletion is blocked — see [Charge](https://docs.finance.kobana.com.br/en/en/contas-a-receber/cobranca-kobana.md). ### Bulk actions[​](#bulk-actions "Direct link to Bulk actions") Once you select rows, the bar offers **"Classify selected"**, **"Mark as received"** and **"Delete"**, and shows the live **To receive**, **Received** and **Total** figures **for the selection**. "Classify selected" only exists with a **specific company** selected: creating a new customer or category by name needs an unambiguous company. **"Mark as received"** opens a dialog with the **Receipt date** (today, by default). Each bill is received at its own amount, into the **destination account** it expects; if any selected bill has none, the dialog asks for the account for those. Interest and discounts are left out — for those, settle one at a time. What the row would not let you mark as received (already received, cancelled) is left out, and the dialog says how many. ## The form[​](#the-form "Direct link to The form") Fields are grouped into sections. **The company is not a field** — it comes from the header selector, and the screen sends you back there if none is chosen. ### ESSENTIALS[​](#essentials "Direct link to ESSENTIALS") | Field | Notes | | ----------------- | ------------------------------------------------------------------------------------------------------ | | **Amount (R$)** | Required. A currency field, with a mask — you type the amount, not a decimal string | | **Due date** | Required. On create, there are relative-date shortcuts | | **Receive into** | The financial account expected to take the money in | | **Description** | Required | | **Customer** | Required. Searches among the people flagged as customer, and lets you **register one by name** on save | | **Accrual month** | Required. A month picker, not a day picker | ### CLASSIFICATION[​](#classification "Direct link to CLASSIFICATION") * **Type** (required) — **One-time**, **Recurring** or **Installment**. The choice reveals the next field: **Recurrence** (the period) for recurring, **Installments** (the count) for installment. * **Category** — revenue category; it also accepts registering one by name. It has the **Split** shortcut beside it, to divide the bill across categories. See [Categories](https://docs.finance.kobana.com.br/en/en/categorias/.md#split). * **Classification center** — with the **Split** shortcut beside it. Turn it on and the split dialog opens, and the single field gives way to a summary of the division. See [Classification centers](https://docs.finance.kobana.com.br/en/en/centros-de-classificacao/.md). ### DOCUMENT & PAYMENT[​](#document--payment "Direct link to DOCUMENT & PAYMENT") **Document number** (invoice, bill…) and **Document date**. That's all — despite the name, the section carries no payment fields on the receivables side. ### Withheld taxes · Notes and IR[​](#withheld-taxes--notes-and-ir "Direct link to Withheld taxes · Notes and IR") Two sections side by side. **Withheld taxes** is the editor for taxes withheld at source, as pills. Next to it, the **"Tax-relevant"** pill (on/off) and **"Add note"**, which opens the free-text field. ### Attachments[​](#attachments "Direct link to Attachments") When **creating**, you can attach files before saving — they are linked along with the record at save time. ## Confirm receipt[​](#confirm-receipt "Direct link to Confirm receipt") The **"Confirm receipt"** dialog has two tabs: * **Receive** — give a **Receipt date** and a **Destination account**. The system marks the bill as received and creates the **inflow** transaction. * **Receive & reconcile** — *"Receive this bill by linking it to a transaction that already exists in the statement — no duplicates."* Pick the transaction; candidates carry a **"same amount"** / **"close amount"** hint. On both tabs, the **"Receipt adjustments"** section (optional) takes **Interest** and **Discount**. Below it, **Amount received** shows what enters the account. On **Receive**, that figure, not the bill's own value, is what the incoming transaction is booked at; on **Receive & reconcile**, it is what the chosen transaction is compared with, and the interest and discount are recorded on the bill. ## Differences from payables[​](#differences-from-payables "Direct link to Differences from payables") | | Receivables | Payables | | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | **Final state** | **Received** | **Paid** | | **Approval gate** | Does not go through it — there is no approval on the receivables side | Every new bill awaits [approval](https://docs.finance.kobana.com.br/en/en/aprovar-pagamentos/.md) when the gate is on (the default) | | **Operation type and document** | There is none — the receipt method materializes in the transaction, when the payment is received | They decide how the bill will be paid and unlock the coordinates | | **Payment coordinates and tax form data** | There is none. **"Withheld taxes"** exists, but it is something else: what the payer withholds from what you have to receive, not a tax form to pay | Barcode, Pix, bank details, tax form data | | **Banking gateway** | [Create charge](https://docs.finance.kobana.com.br/en/en/contas-a-receber/cobranca-kobana.md) — a bank slip or Pix for the customer to pay | [Bank dispatch](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md) — the payment leaves your account | | **Proof of payment** | There is none: a proof of payment is about money going out | Captured on its own at confirmation — see [Receipts](https://docs.finance.kobana.com.br/en/en/comprovantes/.md) | --- # Receivables lifecycle ## States[​](#states "Direct link to States") | State | Description | | ------------- | ----------------------------------------------------------- | | **Draft** | Created but not published yet. Does not show in the totals. | | **Pending** | Awaiting receipt. | | **Received** | Linked to an inflow transaction. | | **Cancelled** | Voided, with no financial movement. | Beyond those four, the listing shows two badges that **are not states**, but derived from them: * **Overdue** — a **Pending** bill whose due date has passed. The [charge](https://docs.finance.kobana.com.br/en/en/contas-a-receber/cobranca-kobana.md) status under "Status at the bank" is also called **Overdue** — they are different things sharing a name: this badge derives from the bill's due date; that status is the bank reporting on the charge. * **Reconciled** — the receipt is tied to a transaction from the statement. When it shows, it replaces the "Received" badge: it is the stronger piece of information. ## Transitions[​](#transitions "Direct link to Transitions") * **Publish** (Draft → Pending) — the bill starts counting towards the totals. * **Mark as received** (Pending → Received) — records the receipt and generates the inflow transaction. * **Cancel** (Pending → Cancelled) — voids the bill. ## Create[​](#create "Direct link to Create") 1. Go to `/receivables/new`. 2. Fill in the required fields: **Amount (R$)**, **Due date**, **Description**, **Customer**, **Accrual month** and **Type**. 3. Finish with **Add bill**, **Add and create another** or **Save draft**. **The customer is not optional.** Without it the form will not submit: *"Select or create a customer"*. You can pick a customer that already exists **or type a new name** — in that case they get registered along with the bill. The **Company** is required too, but it is not a form field: it comes from the header selector. note **"Publish" does not exist on the create screen.** The buttons there are the three above. **Publish** shows up only on the **detail**, and only while the bill is a draft. The path is: save draft → open the bill → Publish. ## Mark as received[​](#mark-as-received "Direct link to Mark as received") From the listing or the detail, use **Mark as received**. The **Confirm receipt** dialog has two tabs: * **Receive** — give the date and the **Destination account**. The system creates the inflow transaction. * **Receive & reconcile** — ties the bill to a transaction that **already exists** in the statement, without generating a duplicate. Both tabs also carry **Receipt adjustments**, optional: **Interest** and **Discount**. Below them, **Amount received** shows what enters the account, with the arithmetic spelled out. ## Undo and reconcile[​](#undo-and-reconcile "Direct link to Undo and reconcile") * **Undo** — available on a received bill. It goes back to pending; if the transaction was generated by the receipt, it is deleted along with it. * **Reconcile** — available on a received bill that has not been reconciled yet. ## Cancel[​](#cancel "Direct link to Cancel") **Cancel only shows on pending bills** — it is not an exit available from every state. And it **is not irreversible**: the dialog itself says *"You can reopen it later by editing the status."* The bill stops showing among the pending ones; linked auto-created transactions are removed, and statement-imported transactions remain — only the link is undone. note The action lives **on the listing**. Open the detail directly and that path is not there. ## Edit[​](#edit "Direct link to Edit") **A received bill is not read-only.** There is no lock by state: the form opens normally and is editable in any status, including **Received** and **Cancelled**. The only lock comes from a [standing charge](https://docs.finance.kobana.com.br/en/en/contas-a-receber/cobranca-kobana.md), which freezes what the charge describes. This is a **difference from payables**: over there a lock does exist — a partial one — once the bank confirms the payment. Receivables never go through the dispatch to the bank, so there is nothing to lock. When you edit a bill that belongs to a group, the system offers **"Apply to other installments"**, showing you beforehand exactly what will change. That means **all** the installments in the group — including the ones **before** the one you're editing, not just the ones after. Only the already-settled ones and the edited installment itself are left out. The selection comes fully checked; uncheck whatever shouldn't inherit — or save on the open installment alone, with **"Only this installment"** (in a recurrence, **"Only this occurrence"**). ## Delete[​](#delete "Direct link to Delete") On a bill that belongs to a group — **installment or recurring** — deleting asks about the scope: * **Delete only this one** * **Delete this and future ones** The same picker covers both cases: what it looks at is the group, not the type. On a standalone bill it does not appear. note The picker shows up **both on the listing and in the bill's detail**. --- # Bank slip and Pix charges From a receivable, Smart Finance creates a **charge** through the [Banking Gateway](https://docs.finance.kobana.com.br/en/en/integracoes/kobana.md) — a **bank slip (boleto)** or a **Pix** — for the customer to pay. It is the mirror of [sending payments](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md), on the money that comes in. The action is **"Create charge"**, on the bill's detail screen. ## Prerequisites[​](#prerequisites "Direct link to Prerequisites") | Requirement | Bank slip | Pix | | ------------------------------------------------------------------------------- | --------- | --- | | Banking Gateway connected | ✅ | ✅ | | A customer linked to the bill | ✅ | ✅ | | The customer's tax ID (CPF/CNPJ) | ✅ | ✅ | | A due date on the bill | ✅ | ✅ | | **The customer's full address** (postal code, street, district, city and state) | ✅ | — | | A **bank slip agreement** registered on the gateway account | ✅ | — | | A **Pix charging account** registered on the gateway account | — | ✅ | note **The two rails are not the same charge with a different button.** They change what the customer receives and what has to be registered beforehand — which is why the choice is made through **two cards**, each stating its own prerequisite. If something is missing, the system says **exactly what**, instead of a generic error: *"The customer needs a tax ID"*, *"Bank slips require the customer full address"*, *"No Pix charging account is registered"*, and so on. ## Flow[​](#flow "Direct link to Flow") warning **A freshly created charge cannot be handed to the customer yet.** Registration at the financial institution is asynchronous: while the state reads **Registering**, the bank slip does not exist at the bank yet and the Pix has no QR code. Wait until it reaches **Registered**. ## Charge states[​](#charge-states "Direct link to Charge states") They show on the charge card and in the **Status at the bank** column of the receivables listing. | State | What it means | | --------------------------------------------------------------------------- | --------------------------------------------------------------- | | **Registering** | created; the institution has not confirmed the registration yet | | **Registered** | registered — it can go to the customer | | **Overdue** | past the due date with no payment | | **Paid** | the customer paid | | **Registration rejected** · **Registration failed** · **Generation failed** | the institution did not accept it; the charge is not valid | | **Cancelled** | undone | The **"Refresh"** button fetches the current state on demand, without waiting for the background tracking. ## Automatic receipt of payment[​](#automatic-receipt-of-payment "Direct link to Automatic receipt of payment") When the charge reaches **Paid**, the bill is marked as received on its own: it becomes **Received**, dated today, and the incoming transaction is created. warning **With no "Receive into" set, there is no automatic receipt.** That field is what says which account the money landed in — without it the system does not guess, and marking the bill as received is left for you to do by hand. The charge stays marked as Paid. ## While the charge stands, the bill does not change[​](#while-the-charge-stands-the-bill-does-not-change "Direct link to While the charge stands, the bill does not change") With a charge that is **Registering**, **Registered**, **Overdue** or **Paid**, somebody out there can pay it — or already has. That is why the bill is locked on everything that describes the charge: **amount, due date, customer and the like cannot be edited**, and the bill **cannot be deleted**. info **Editing here would not re-issue anything.** The bank slip the customer is holding would stay the same — it is the system that would start lying about what was charged. To correct it, **cancel the charge first**. **Rejected** or **cancelled** charges lock nothing: they exist for nobody. ## Canceling the charge[​](#canceling-the-charge "Direct link to Canceling the charge") **"Cancel charge"** undoes the charge on the gateway. The two rails behave differently, and the difference matters to your customer: * **Bank slip** — stops being valid as soon as the gateway confirms, and the customer can no longer pay it. * **Pix** — the cancellation is confirmed by the **financial institution**. **Until that confirmation arrives, the customer can still pay.** That is why the answer distinguishes **"Charge cancelled"** from **"Cancellation requested — waiting for the institution to confirm"**. In the second case, follow it until the state reads **Cancelled**. A charge that is **paid**, **already cancelled** or that **failed** has nothing to cancel. ## Related[​](#related "Direct link to Related") * [Receivables — lifecycle](https://docs.finance.kobana.com.br/en/en/contas-a-receber/ciclo-de-vida.md) — the states of the bill itself * [Banking Gateway integration](https://docs.finance.kobana.com.br/en/en/integracoes/kobana.md) — connecting, syncing and tracking * [People](https://docs.finance.kobana.com.br/en/en/pessoas/.md) — where the document and address the charge requires are kept --- # CSV import — Receivables Import batches of receivables from a CSV file. ## Where it lives[​](#where-it-lives "Direct link to Where it lives") **There is no "Import" in the menu**, and no import screen. The way in is: **Receivables** → the **Import** pill, on the listing itself. With no receivable yet, the listing shows the empty state with an **Import** button next to **New receivable**, which opens the same panel. You need a **specific company** selected in the header. Under "all companies", the panel only warns: *"Select a specific company to import receivables."* The **Download template** button hands you a sample CSV with the right header — the safest place to start, because it already comes in the right encoding. ## CSV columns[​](#csv-columns "Direct link to CSV columns") | Column | Required | Description | | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `description` | ✅ | Receivable description | | `amount` | ✅ | Amount in reais (e.g. `299,00`) | | `due_date` | ✅ | Due date (`dd/MM/yyyy`) | | `competence_date` | — | Competence date (`dd/MM/yyyy`) | | `document` | — | Document identifier (the **Document** form field) | | `document_date` | — | Issue date (`dd/MM/yyyy`) | | `document_number` | — | Invoice number (the **Document number** field) | | `person_name` | — | Customer name (if it doesn't exist yet, the preview asks whether to create it) | | `category_name` | — | Category name (if it doesn't exist yet, the preview asks whether to create it) | | `cost_center_name` | — | Classification center name (if it doesn't exist yet, the preview asks whether to create it) | | `payment_method` | — | Method: `pix`, `bank_billet`, `ted`, `credit_card`, `debit_card`, `cash`, `check`, `direct_debit`, `other` or `none` (the Portuguese aliases — `boleto`, `dinheiro`, … — are also accepted) — accepted and stored on the bill, though the receivables form does not expose the field | | `notes` | — | Notes | | `ir_relevant` | — | `true` or `false` | The names above are the canonical ones, but **every header also accepts its Portuguese equivalent** — `descricao`, `valor`, `vencimento`, `cliente`, `categoria`, `observacao` and so on. Spreadsheets from other systems work for customer, classification center and category too: `contraparte` counts as `person_name`; `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` count as `cost_center_name`, and `plano_de_contas`, `categoria_financeira`, `category` as `category_name`. If the workspace has a classifier with the same name as one of these columns (e.g. *Centro de Resultado*), the column goes to the classifier. If the file has more than one column for the same field (e.g. `Centro de Custo` and `Centro de Receita`), each row uses the first one that is filled in. Beyond those names, a header with the word **centro** is read as the classification center; one with **categoria** or **plano de contas** as the category (e.g. `Centro de Lucro`, `Categoria DRE`); and one with **pessoa**, **cliente** or **fornecedor** next to nothing but name words as the person (e.g. `Nome do Fornecedor`, `Cliente / Fornecedor` — but not `CNPJ do Fornecedor`). Columns the system doesn't know are **ignored silently**. The receivables file accepts the same columns as payables, except the payment ones (barcode, Pix, bank details, tax, scheduling) — those exist only on the payables side, which is the one that sends money to the bank. ## Format[​](#format "Direct link to Format") The parser is more forgiving than it looks. You don't have to normalize the file first: * **Header** — case, accents and spaces don't matter: `Descrição`, `DESCRICAO` and `descricao` are the same column. * **Separator** — `,` or `;`, detected **from the header line**. On a tie, `;`. * **Dates** — `31/12/2026`, `31-12-2026` or `2026-12-31`. * **Amounts** — `1234.56`, `1.234,56`, `1234,56`, with or without `R$`. The amount has to be **greater than zero**. * **`ir_relevant`** — `true`/`false`, `sim`/`nao`, `yes`/`no`, `1`/`0`, `s`/`y`/`n`. Accents and case don't matter. Empty leaves the field blank. warning **The encoding has to be UTF-8, and this is where most files trip up.** Excel in Portuguese saves CSV as Windows-1252 by default, and the system refuses it with a message that stays in Portuguese: *"Arquivo não está em UTF-8. Salve novamente em UTF-8 e tente novamente."* ("The file is not UTF-8. Save it again as UTF-8 and try once more.") In Excel, use **Save As → CSV UTF-8**; or start from the downloaded template. Other whole-file rejections: an extension other than `.csv`, a size above **5 MB**, an empty file, and a **missing required column** — *"Colunas obrigatórias ausentes: amount"* ("Missing required columns: amount"). In those cases there is no preview: the problem is the file, not a row. ## Importing[​](#importing "Direct link to Importing") 1. Upload the file. The system reads it and shows the preview. 2. **Valid rows come pre-selected.** Click a row to deselect it. 3. Click **Import N lines**. ### Rows with errors[​](#rows-with-errors "Direct link to Rows with errors") Invalid rows show up in the preview with a red marker, **and can't be selected or edited there**. There is no fixing them inside the system. The screen itself tells you the way out: *"Uncheck the rows with errors or fix them in the file and upload again."* The number in **Row N** is the line number **in the file**, counting the header — the first data line is 2. ### Writing happens in the background[​](#writing-happens-in-the-background "Direct link to Writing happens in the background") On confirmation you get *"Import started in the background"* and a progress dialog. **You can close the dialog** — the import keeps going, and progress stays visible in the lower-right corner. ### Links to other records[​](#links-to-other-records "Direct link to Links to other records") **Customers, categories and classification centers show up in the preview**, each with what the import will do: existing ones are linked; new ones come marked to **create** (or to **leave blank** if you can't create them); a name that only differs from an existing one in accents, case or spacing comes marked to **use the existing one**; and a classification center that only exists for the other side (e.g. one of type Cost on a receivable) comes marked to leave blank. The customer is looked up by name alone: a person already registered as a supplier works too, and becomes a customer as well. Spellings of the same name that only differ in accents, case or spacing (e.g. *Água e Luz* and *agua e luz*) count as one name. You can change any choice before importing. [Automatic rules](https://docs.finance.kobana.com.br/en/en/regras-automaticas/.md) are applied to the imported records. ## History[​](#history "Direct link to History") Below the panel, the **History** section lists the imports with date, file, status (**Queued**, **Running**, **Completed**, **Failed**, **Cancelled**), how many rows went in out of the total, and who asked for it. ## Approval[​](#approval "Direct link to Approval") note **Imported receivables don't go through approval.** The payment approval gate exists only on the **payables** side, because that's where money leaves. An imported receivable lands straight in the normal list and in the totals. --- # Installments and recurrence — Receivables The behavior is the same as on [Payables](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/parcelas-e-recorrencia.md): same types, same periods, same grouping. ## Types[​](#types "Direct link to Types") The **Type** field offers three options: | Type | Description | | --------------- | ------------------------------------------- | | **One-time** | A single bill | | **Installment** | N installments with sequential due dates | | **Recurring** | Generated automatically at a fixed interval | ## Installments[​](#installments "Direct link to Installments") Enter the amount **of each installment** and the number of **Installments**, from **2** to **120**. The system generates N bills tied by the same group, with **monthly due dates starting from the first due date**, and **each installment is received individually**. Once created, due date and amount are adjusted one by one. On a bill that is already part of a series, **Type** and **Installments** are locked. A saved **One-time** bill can become **Recurring**, but not **Installment**. ## Recurrence[​](#recurrence "Direct link to Recurrence") The **Recurrence** field appears when the type is **Recurring** and is required. There are **five** periods: | Option | Interval | | ------------------- | --------- | | **Every week** | 7 days | | **Every two weeks** | 14 days | | **Every month** | 1 month | | **Every 3 months** | 3 months | | **Every year** | 12 months | tip **There is no bimonthly or half-yearly period.** If you need an interval outside that list, the way to go is installments: they are created monthly, and you adjust each one's due date afterwards. Occurrences count from the first one: moving one occurrence's due date doesn't touch the following ones, which stay on the series' original day. Each recorded occurrence copies the latest one — amount, category, taxes and withholdings, notes. In the listing, the recurrence shows up abbreviated next to the due date — *Weekly*, *Biweekly*, *Monthly*, *Quarterly*, *Yearly*. Same thing, written short to fit the column. ## Deleting[​](#deleting "Direct link to Deleting") Deleting a bill that belongs to a group asks you for the scope: * **Delete only this one** * **Delete this and future ones** — *"Occurrences already received or reconciled are kept."* On an imported series (Fintera, Nibo), **Delete this and future ones** is refused: *"This series comes from an integration; delete it at the source"*. **The scope isn't exclusive to recurrences.** The picker looks at the **group**, so **installment and recurring bills behave the same**. On a standalone bill it doesn't appear. The picker lives **in the listing**. Delete from the detail screen and only that one bill goes. --- # Financial accounts Financial accounts (`/financial-accounts`) represent the bank and cash accounts of the workspace's companies. Each account's balance is calculated from the transactions recorded against it. Two operations live **inside** the account, and are documented separately: ## [📄️Bank statements](https://docs.finance.kobana.com.br/en/en/extratos-bancarios/.md) [Import OFX and QIF into the financial account — deduplication, history and undo.](https://docs.finance.kobana.com.br/en/en/extratos-bancarios/.md) ## [📄️Transfers](https://docs.finance.kobana.com.br/en/en/transferencias/.md) [Move money between accounts of the workspace — two mirrored transactions.](https://docs.finance.kobana.com.br/en/en/transferencias/.md) ![Financial accounts list](/en/assets/images/07-accounts-2fa10756f17cba6a4dcf6c612a609848.png) ![Financial account detail](/en/assets/images/08-account-detail-7bd636517ef8918ef25ec8fad46a6237.png) ## Account types[​](#account-types "Direct link to Account types") **Checking** · **Savings** · **Cash** · **Investment** · **Credit** The type you pick changes the form: **Cash has no bank details** — the whole section disappears, and anything already filled in is cleared. **A Credit account can become a card.** In [Cards](https://docs.finance.kobana.com.br/en/en/cartoes/.md) it gets statements, a limit and installment purchases — and every new card creates its own Credit account here. On the header's **Account** selector, a card's account carries the **Card** badge; its balance is the card's debt and stays out of cash (see [Close, review and pay](https://docs.finance.kobana.com.br/en/en/cartoes/fechar-conferir-pagar.md#in-the-cash-flow)). ## Fields[​](#fields "Direct link to Fields") ### Essentials[​](#essentials "Direct link to Essentials") | Field | Required | Notes | | ------------------- | -------- | -------------------------------------- | | **Name** | Yes | E.g.: "Main checking account" | | **Type** | Yes | — | | **Initial balance** | Yes | **On creation only** | | **Company** | **No** | Linking one lets you filter by company | ### Bank — does not appear on Cash accounts[​](#bank--does-not-appear-on-cash-accounts "Direct link to Bank — does not appear on Cash accounts") | Field | Required | | ------------------------------------- | -------- | | **Bank** | **Yes** | | **Branch** | **Yes** | | **Digit** (the branch's check digit) | No | | **Account number** | **Yes** | | **Digit** (the account's check digit) | No | ### Status[​](#status "Direct link to Status") A single option: **Disable reconciliation**, for accounts that shouldn't take part in reconciliation (a manual petty cash box, say). warning **Watch which fields are required — it's usually read backwards:** the **Company is optional** — an account can exist with no company. The **Bank, on the other hand, is required** on Checking, Savings, Investment and Credit; the branch and the account number, on Checking, Savings and Investment — a **Credit** account has no branch nor number. Only on **Cash** does none of them exist. ## Balance[​](#balance "Direct link to Balance") The **Initial balance** is entered **on creation only**. After that the field leaves the form, which then shows the hint *"Balance is updated automatically by transactions."* To correct the balance of an account that already exists, use **Adjust balance** — click the balance figure on the account detail. You enter the real balance and the date, and the system creates **one adjustment transaction** that brings the account up to the figure you gave. note **An adjustment can't be edited afterwards — only deleted.** To fix a wrong adjustment, record a new one. ## Listing[​](#listing "Direct link to Listing") Columns: **Name** (with the bank on the line below), **Type**, **Company** (only in "Consolidated" mode), **Branch**, **Account**, **Transactions** and **Balance**. The arrow at the end takes you to the account's transactions. Filters: search **by name**, tabs by type (**All** · **Checking** · **Savings** · **Cash** · **Investment** · **Credit**) and the **Status** filter (**Active** / **Archived**). The header has **New account** and **New transfer**. ## Archiving[​](#archiving "Direct link to Archiving") An archived account **stays in the listing**, with the **Archived** badge. The **Status** filter starts out with **nothing selected** — meaning you see active and archived together until you choose. Archiving and unarchiving are row-menu actions (**Archive** / **Unarchive**), not a form field. The menu also carries **Edit** and **Delete**. ## Account detail[​](#account-detail "Direct link to Account detail") Besides the transactions, the detail brings three actions: **Statements**, **Import** and **Report**. They appear once the account has transactions. **Statements** and **Import** require a **specific company** selected in the header — under "Consolidated" the panel just tells you so. ## Managers[​](#managers "Direct link to Managers") The **Managers** section, on the account detail, keeps the bank managers serving the account — **with history**. More than one manager can be active at a time. * **Add manager** has two tabs, sharing the **Start** date. In **Registered manager** you pick who serves the account among the account's company people with the **Account manager** role. In **New manager** you fill in name, e-mail, phone and notes, and **Register and add** creates the person already as a manager — they also show up in [People](https://docs.finance.kobana.com.br/en/en/pessoas/.md), where you complete the rest of the record. * Each active manager shows as a card with their phones and e-mails and the shortcuts **Chat on WhatsApp** (mobile only), **Call** and **Send e-mail**. * **End** records the **End** date: the manager leaves the active ones and moves to the **Manager history**, collapsed below the cards. * **Edit dates** fixes start and end. **Delete** erases the entry — only use it to undo an entry made by mistake. note **A manager is a person of the account's company.** An account without a company has no managers — the section asks you to link the account to a company. A manager serving two companies is registered in each. Deleting the person ends their active tenures that day; they stay in the history. ## Accesses[​](#accesses "Direct link to Accesses") The **Accesses** section, also on the account detail, records who on the team operates the account at the bank, and at what level — **Owner**, **Administrator**, **Manager**, **Viewer** or **No access**. **No access** is a level recorded on purpose, different from the person not being listed. * **Add access** picks a person from the account's company (or registers a new one by name) and the **Access level**. The person gets the **Team** role. * Each person has **one** level per account — to change it, switch the level right in the list. * **Remove access** takes the person off the list. Accesses **have no history**: what is removed is not kept. As with managers, only people of the account's company, and an account without a company has no accesses. ## Banking Gateway integration[​](#banking-gateway-integration "Direct link to Banking Gateway integration") **Checking** and **savings** accounts can be synced with the Banking Gateway, which enables statement sync and payment dispatch. Cash, Investment and Credit accounts aren't supported and stay out. There are two routes to the link, and they meet in the same place: * **From there to here** — the **Sync bank accounts** button on the integration screen imports the accounts registered in the gateway and links the ones that already exist here. See [Banking Gateway](https://docs.finance.kobana.com.br/en/en/integracoes/kobana.md). * **From here to there** — an account that only exists here gets an **Add to the banking gateway** button on its own page. You choose which one to send; the send creates the account in the gateway with the bank, branch and number registered here, and asks for a confirmation first. note **Nothing is duplicated.** The match is by **bank, branch number and account number**. If the account you send already exists in the gateway with those same coordinates, it is simply **linked**, not created again. The **check digits are left out of the comparison**: they follow from the number itself, so one side having them and the other not — or registering them glued on, as in `5555-0` — does not make it a different account. For the branch, the **first four digits** count, so `1234-5`, `12345` and `1234` are the same branch. The same rule applies to the [Fintera import](https://docs.finance.kobana.com.br/en/en/integracoes/fintera.md): an account that already exists here (created by hand or pulled from the gateway) is linked to the Fintera account, not imported again. And if the gateway itself holds two accounts with the same bank, branch and number, only the first is brought in — the other shows in the preview as **Duplicate in gateway**. An account that is already linked shows a **Kobana** badge in the listing and on its own page, and the send button disappears — there is nowhere left to send it. --- # Dashboard **Dashboard** (`/dashboard`) is the home screen of Smart Finance. It consolidates the organization's financial health into two tabs: **Performance** (what already happened) and **Cash flow** (the projection of what is coming). ![Dashboard — overview](/en/assets/images/00-dashboard-0e03c42e896df2f6dffd00a6e68b2798.png) ## Filters[​](#filters "Direct link to Filters") * **Period** — date range picker, in the header. Each tab opens on its own default preset. * **Company** — comes from the selector at the top, or consolidates every company in the workspace. * **Granularity** — **Day**, **Week**, **Month** or **Year**, at the top of the tab. Each tab has its own. * **Account** — **on the Cash flow tab only**, to project over a specific account. ## Performance tab[​](#performance-tab "Direct link to Performance tab") Looks backwards: the numbers for the period that has already settled. ### Metric cards[​](#metric-cards "Direct link to Metric cards") Four indicators, each with a trend **sparkline**: | Metric | Description | % change | | ---------------------- | ------------------------------------- | -------- | | **Total balance** | Sum of the financial account balances | — | | **Income in period** | Inflows realized | **Yes** | | **Expenses in period** | Outflows realized | **Yes** | | **Operating margin** | (income − expenses) / income | — | **Only Income and Expenses compare against the previous period.** The percentage badge exists on those two. Total balance and Operating margin show the sparkline but carry no change badge — there is nothing to compare them against honestly. ### Realized cash flow[​](#realized-cash-flow "Direct link to Realized cash flow") Chart of the **balance** across the period, with the histogram of settled inflows and outflows underneath and the **Day**, **Week**, **Month** and **Year** tabs to choose the bucket size. The peak and the lowest balance are marked on the point itself, and hovering shows the biggest entries at that point. **Options that make no sense for the period are disabled.** A granularity that would render a single bar is not offered: on "This month", **Month** drops out (it would collapse into one block) and the view opens on **Week**. On "Today", only **Day** is left. Same rule as the Cash flow tab. ### Top expenses[​](#top-expenses "Direct link to Top expenses") The **top 4 expense categories** in the period, with a shortcut to the expense listing. ### Short-term analysis[​](#short-term-analysis "Direct link to Short-term analysis") Compares **This week** against the **Last 30 days**, and shows the average value per transaction over the 30-day window. warning **This panel ignores the period picker.** Its windows are fixed — this week and the last 30 rolling days — and do not change when you switch the period in the header. It is the most common source of confusion on this screen: its numbers do not "match" the cards on purpose, because they measure something else. ## Cash flow tab[​](#cash-flow-tab "Direct link to Cash flow tab") Looks forward. The old `/cash-flow` route **redirects** here (`/dashboard?tab=cash-flow`). Besides granularity, this tab has the **Account** picker, to project over a specific account. ### The four cards[​](#the-four-cards "Direct link to The four cards") | Card | What it shows | | ---------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Current balance** | Today's balance, with the account count | | **Projected inflows** | What is due to be received in the window | | **Projected outflows** | What is due to be paid in the window | | **Projected balance** | The balance at the end of the period, with the **lowest projected balance from here on** and the change vs. today | **In a window with no future, the titles change.** Looking only at the past, the last three become **"Realized inflows"**, **"Realized outflows"** and **"End balance"** — they stop promising a projection when there is nothing to project. The low point is a warning about what lies **ahead**: it only scans future periods, because a dip that already passed warns you of nothing. And it only appears when it falls **below** the end-of-period balance — if the worst moment is the last one, repeating the number would say nothing. note **"Projected balance" is not "end-of-month balance".** It is the closing balance of the **last period in the range you picked**. Over a 90-day range, it is the balance at the end of those 90 days — not of the current month. ### What goes into the projection[​](#what-goes-into-the-projection "Direct link to What goes into the projection") Four sources, summed: 1. **Pending bills** — payables and receivables, by **due date**. Payables only enter once approved, when approval is on (the default). 2. **Forecast transactions** — those marked as provisional, by date. 3. **Virtual occurrences of recurrences** — this is the subtle one. A recurrence is recorded only up to the provisioning horizon (12 months by default; see [Installments and recurrence](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/parcelas-e-recorrencia.md)). In a projection reaching past it, the system continues the series **on read**, generating the occurrences that do not exist as records yet. They are not stored — they exist only in the projection. 4. **Card statements** — each credit card's open and future statements, at their expected total, on the due date, in the account that pays the card. Once closed, the statement comes in as a payable. Card purchases do not come in one by one: the card is not cash (see [Cards](https://docs.finance.kobana.com.br/en/en/cartoes/fechar-conferir-pagar.md#in-the-cash-flow)). note **What is past due does not vanish: it is pushed to today.** A bill that came due last week and is still pending neither stays in the past nor disappears — it lands in **today's** group, because it is still money that will go out or come in. The breakdown flags it: *"Includes R$ 1,200.00 in past-due bills"*. ### Overdue and Upcoming[​](#overdue-and-upcoming "Direct link to Overdue and Upcoming") **Two** panels, not one: **"Overdue"** and **"Upcoming (30 days)"**. Each separates what is payable from what is receivable, and says how many days ago it came due or how many days until it does. ### Chart, breakdown and scenarios[​](#chart-breakdown-and-scenarios "Direct link to Chart, breakdown and scenarios") * **Chart** of the balance per period: the line is the balance (solid where settled, dashed from **Today** on), with the peak and the lowest balance marked on the point and the zero line highlighted; underneath, the histogram of Income and Expenses for the same period. Hovering shows income, expenses, balance and the biggest entries at that point. Above it sit the **Summary** and **By category** tabs, which **drive the chart and the table at the same time** — they do not belong to the table, even though that is where the difference shows most. Under **By category** the chart swaps the balance curve for one line per category, with **income above zero and expenses below**: both sides show at once, and the zero line is the water line. The legend underneath separates each side's categories. * **"Breakdown by period"** — table with Opening balance, Inflows, Outflows, Period net and Closing balance. Those five rows are the **Summary** tab: under **By category** the balance rows **drop out**, leaving only Inflows and Outflows broken down by category — it is a flow reading, not a balance one. Clicking a period opens the entries that make it up, flagging what is **Realized**, **Projected**, **Past due** and what came from a **recurring** series. * **Scenario** — what-if simulation: **Defer** or **Remove** bills from the projection to see the effect on the **Projected balance** and the **Worst projected balance**, without changing anything for real. **Clear** undoes it. --- # Docs MCP This documentation has **its own MCP server**. It lets an AI assistant (Claude, ChatGPT, Cursor, VS Code, Claude Code) search and read the pages of this site without you copying and pasting anything, so answers about Smart Finance come from the published content, in the language you choose. ``` https://docs.finance.kobana.com.br/mcp ``` > **Not the product's MCP:** The Docs MCP only **reads the documentation**. It does not access your account, does not see payables, receivables or transactions, and changes nothing. For an agent to operate Smart Finance, use the **product MCP** (`mcp.finance.kobana.com.br`), which requires sign-in and follows your permissions — see [MCP › Clients](https://docs.finance.kobana.com.br/en/en/mcp/overview/clients.md). ## How it works[​](#how-it-works "Direct link to How it works") * **Public and read-only:** no sign-in, no token. It exposes the same content anyone sees on the site. * **Always current:** it reads the published version of the documentation. A new or changed page shows up in the MCP as soon as the site is published. * **Three languages:** Portuguese (`pt`), English (`en`) and Spanish (`es`). Without a language, it uses Portuguese. * **Transport:** Streamable HTTP, sessionless. Any MCP client that connects to a remote server by URL works. ## Tools[​](#tools "Direct link to Tools") | Tool | What it does | Parameters | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `search_docs` | Searches pages by keywords in the title, path and summary, ignoring accents and case. Returns the best pages with path and summary | `query` (required), `locale`, `limit` (1 to 25, default 8) | | `get_page` | Returns the full content of a page as Markdown | `path`: the path returned by `search_docs` or `list_pages` (e.g. `/en/conciliacao`) or the full URL | | `list_pages` | Lists every page, with path and summary | `locale` | | `search_openapi` | Searches REST API operations (endpoints) by keywords in the summary, path and description. Returns the best operations with method, path and `operationId` | `query` (required), `version`, `locale`, `limit` (1 to 25, default 8) | | `get_operation` | Returns one API operation in full: description, parameters, request body and responses with their schemas | `operation_id`, or `method` and `path`; `version`, `locale` | The assistant decides on its own when to call each tool. It usually searches with `search_docs` and then reads the relevant pages with `get_page`. ## Installing[​](#installing "Direct link to Installing") The quickest way is the **Copy page** menu at the top of every page of this site. Under **Docs MCP** you'll find: * **Connect to Cursor** and **Connect to VS Code:** install the server in one click. * **Copy MCP config:** copies the JSON block for clients configured by file. * **Copy MCP command:** copies the install command for the terminal. If you'd rather configure it by hand, the steps for each client are below. ### Any client, from the terminal[​](#any-client-from-the-terminal "Direct link to Any client, from the terminal") [`add-mcp`](https://www.npmjs.com/package/add-mcp) detects the clients installed on your machine and adds the server to them: ``` npx add-mcp "https://docs.finance.kobana.com.br/mcp" ``` ### Claude Code[​](#claude-code "Direct link to Claude Code") ``` claude mcp add --transport http kobana-finance-docs https://docs.finance.kobana.com.br/mcp ``` ### Cursor[​](#cursor "Direct link to Cursor") Use **Connect to Cursor** in the page menu, or add this to `~/.cursor/mcp.json` (all projects) or the project's `.cursor/mcp.json`: ``` { "mcpServers": { "kobana-finance-docs": { "url": "https://docs.finance.kobana.com.br/mcp" } } } ``` ### VS Code[​](#vs-code "Direct link to VS Code") Use **Connect to VS Code** in the page menu, or create `.vscode/mcp.json` in the project. In VS Code the key is `servers`, not `mcpServers`: ``` { "servers": { "kobana-finance-docs": { "type": "http", "url": "https://docs.finance.kobana.com.br/mcp" } } } ``` ### Claude and ChatGPT[​](#claude-and-chatgpt "Direct link to Claude and ChatGPT") In **Settings › Connectors**, add a custom connector and paste the URL `https://docs.finance.kobana.com.br/mcp`. There is no sign-in. ### Other clients configured by file[​](#other-clients-configured-by-file "Direct link to Other clients configured by file") ``` { "mcpServers": { "kobana-finance-docs": { "type": "http", "url": "https://docs.finance.kobana.com.br/mcp" } } } ``` ## Example questions[​](#example-questions "Direct link to Example questions") With the server connected, just ask. The assistant checks the documentation before answering: * "How do I reconcile a bank statement transaction with a payable?" * "How do I register a payable in instalments or as a recurring one?" * "How do I create automatic rules to classify transactions?" * "Write an example API call to create a receivable, based on the documentation." ## Testing without a client[​](#testing-without-a-client "Direct link to Testing without a client") ``` 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":"reconciliation","locale":"en"}}}' ``` ## Limits[​](#limits "Direct link to Limits") * The per-endpoint API reference pages are not part of `search_docs`/`get_page`: they are generated from the OpenAPI spec, so the MCP reads the spec directly, with `search_openapi` and `get_operation`. The full spec is still at [API › OpenAPI](https://docs.finance.kobana.com.br/en/en/api/overview/openapi.md). * Search is by keywords, not semantic. If nothing comes up, try other terms or ask the assistant to use `list_pages`. * You can also read any page as Markdown by appending `.md` to its URL, or download the whole documentation at [`llms-full.txt`](https://docs.finance.kobana.com.br/en/llms-full.txt). --- # Companies Companies (`/companies`) represent the legal entities (CNPJs) managed inside the workspace. Smart Finance is multi-company: a single workspace can run the financial back-office of several companies at once. ![Companies list](/en/assets/images/17-companies-a84f41b607cd577d4771a631afc2df1c.png) ## Creating a company[​](#creating-a-company "Direct link to Creating a company") The form has **two fields**, and the second depends on the first: | Field | Required | Description | | -------- | -------- | ------------------------------------------------------------------------------- | | **CNPJ** | Yes | The company's CNPJ. As soon as it is complete, the system queries Receita. | | **Name** | Yes | Filled in by the lookup. It only accepts typing when the lookup doesn't answer. | **Active** and **Financial accounts** appear **only when editing** — a new company is born active, and at creation time there are no accounts to link yet. The flow is: create the company, then create the accounts. ### The CNPJ accepts letters[​](#the-cnpj-accepts-letters "Direct link to The CNPJ accepts letters") note **A CNPJ has 14 characters, not 14 digits.** In Receita Federal's alphanumeric format, the first 12 characters (the root and the establishment number) accept **letters and numbers**; only the 2 check digits at the end are numeric-only. The field's mask handles this, and letters you type are uppercased automatically. The CNPJ is validated in the field itself before any lookup: an invalid check digit never reaches Receita. ### Automatic Receita lookup[​](#automatic-receita-lookup "Direct link to Automatic Receita lookup") **As soon as the CNPJ is complete** — typed or pasted, with no need to leave the field —, the system queries Receita Federal and uses the answer to fill in the rest: * **Legal name filled in and locked.** The **Name** field starts out blocked, with the hint *"Enter the CNPJ above"* — it exists to receive the legal name, not for you to type in. When the lookup answers, the name arrives ready. * **Registration status warning.** If the company isn't **ATIVA** at Receita, an alert shows the status found — *"Receita registration status: SUSPENSA."*, for instance. It's **only a warning**: it doesn't block the registration. * **A duplicate CNPJ blocks.** If the CNPJ already belongs to another **active company in this workspace**, the warning *"CNPJ already registered."* appears and the Save button won't go through. This check is local: the CNPJ of an **inactive company doesn't reserve the spot**, and uniqueness holds per workspace, not globally. If Receita can't find the CNPJ (*"CNPJ not found at Receita — enter the name manually."*) or the lookup fails (*"Could not query Receita — enter the name manually."*), the **Name** field unlocks and you type it in. A lookup that doesn't answer never blocks the registration. ### Type (headquarters or branch) is not a field[​](#type-headquarters-or-branch-is-not-a-field "Direct link to Type (headquarters or branch) is not a field") You don't choose it. The type is **derived from the CNPJ itself**, from the four characters of the establishment number — the `0001` in `12.345.678/0001-95`. `0001` means **Headquarters**; any other value means **Branch**. The type shows as a badge in the listing and as a filter (**All** · **Headquarters** · **Branch**), never as an editable field. If you correct the CNPJ of a company that already exists, the type is recalculated along with it. ## Financial accounts[​](#financial-accounts "Direct link to Financial accounts") Each company can have several financial accounts, linked in the **Financial accounts** section of the edit form (**Add account** links an account that already exists). **The company is optional on a financial account**, not required. An account can exist with no company. Linking is what lets you filter the Dashboard and the reports by company — it's useful, but the system doesn't demand it. ## Company filter[​](#company-filter "Direct link to Company filter") The company selector in the application header persists across screens and filters the data on display. It lists **active companies only**. ## Deactivating[​](#deactivating "Direct link to Deactivating") Deactivating does **not** take the company off the Companies screen. It stays in the listing, with the **Inactive** badge in the Status column. What deactivating does is **take the company out of the header selector and out of the forms** — it stops being an option on new entries, and the history stays intact. * **To deactivate:** open **Edit** on the company's row and turn off the **Active** switch. * **To reactivate:** the same path, turning the switch back on. * **To see the inactive ones:** they already show by default. The **Status** filter (**Active** / **Inactive**) is there to narrow down — pinning **Active** is what hides them. ## Deleting[​](#deleting "Direct link to Deleting") Deleting is permanent and cannot be undone. The dialog warns you: *"Are you sure you want to delete this company? All associated financial accounts will be removed."* note **Financial activity blocks the delete.** If the company has **transactions**, **payables**, **receivables** or **registered people**, the system refuses and tells you what it found: *"Couldn't delete this company because it has 3 transactions, 1 payable linked to it. Delete those records first and try again."* These don't block — **they are deleted along with** the company: * **Financial accounts** (that's what the dialog warns about) * The company's **categories** and **classification centers** In practice the blocker almost always wins: a financial account with activity implies transactions, and a transaction blocks. If the company has history and you only want it out of circulation, **deactivate** it instead of deleting. ## WhatsApp integration[​](#whatsapp-integration "Direct link to WhatsApp integration") Each company can have its own WhatsApp settings (via Evolution API) to display the profile photos of customers and suppliers. See [WhatsApp](https://docs.finance.kobana.com.br/en/en/integracoes/whatsapp.md). --- # Bank statements Bank statements import an account's statement and create transactions from it. The accepted formats are OFX and QIF. ## Where it lives[​](#where-it-lives "Direct link to Where it lives") Statements are **not a screen of their own** and have no menu item. It's a tab inside the account: **Financial accounts** → open the account → **Statements** tab. That's why there is no "pick the destination account" step: **the account is the one you're already in**. You need a **specific company** selected in the header — under "all companies" the panel just tells you so. ## Accepted formats[​](#accepted-formats "Direct link to Accepted formats") | Format | Extension | Description | | ------ | --------- | ---------------------------------------------------------------------- | | OFX | `.ofx` | Open Financial Exchange — the standard at most banks | | QIF | `.qif` | Quicken Interchange Format — a legacy format, still used by some banks | The **Download sample** button offers one file of each format. They are **examples so you know what the format looks like**, not templates to fill in — a statement is exported from the bank, not written by hand. ## Importing[​](#importing "Direct link to Importing") 1. Export the statement from your bank in OFX or QIF. 2. On the account's **Statements** tab, upload the file. 3. The system reads the file and shows what it found: how many transactions are importable and how many were ignored. 4. **Every line comes pre-selected.** Click a line to deselect it if you don't want it imported. 5. Click **Import N transactions**. The import **runs in the background**: you get the notice *"Import started in the background"* and follow along in a progress dialog — the screen isn't stuck waiting. Imported transactions come in **unreconciled**. To link them to bills, use [Reconciliation](https://docs.finance.kobana.com.br/en/en/conciliacao/.md). ### What gets ignored[​](#what-gets-ignored "Direct link to What gets ignored") Three cases are discarded on read and **counted**, with the summary on screen — *"Ignored: 2 future-dated, 1 zero-amount, 0 with invalid date."*: * **Future date** * **Zero amount** * **Invalid date** (an unreadable value lands here too) ## Deduplication[​](#deduplication "Direct link to Deduplication") note **Dedup identifies a line by the identifier the bank gives it (the OFX FITID) — not by "same amount, date and description".** When the file carries no such identifier (always the case with QIF), the system builds a key from date, amount and description **plus the order of occurrence**, precisely so that two identical lines are **not** mistaken for one another. **What deduplication guarantees:** re-uploading **the same file** to **the same account** duplicates nothing. Lines already known are skipped, and the history tells you how many. **A transaction the ERP already brought isn't duplicated either.** If the account has the history imported from Fintera or Nibo, a file line that is the same movement — same direction, same amount, same day — creates no new transaction: it joins the one from the ERP, which keeps the finance team's description and classification and gains the bank's text. **What it doesn't guarantee — and is worth knowing:** * **Two genuinely identical transactions both come in.** Two R$ 50 withdrawals on the same day, with the same description, are two real transactions. The system preserves them on purpose. * **There is no dedup across statement sources.** The same transaction arriving via OFX, via QIF and via Banking Gateway sync counts as **three** — each source builds its own key. (Between the statement and the ERP there is, see above.) * **Dedup is per account**, not per workspace. * **Nothing is flagged on screen.** The check happens on the server, **at import time** — not while you're reviewing the list. ## History[​](#history "Direct link to History") Below the import panel, the **History** section lists the files already imported: date, file, status, how many transactions came in out of the total, and who asked for it. The section only appears once there is history. The statuses are **Queued**, **Running**, **Completed**, **Failed** and **Cancelled**. ### Undo[​](#undo "Direct link to Undo") The **Undo** action deletes **the transactions that file created** and removes the statement from the history. The dialog warns you: *"This deletes the N transactions imported from this statement. This can't be undone."* If any of those transactions was already reconciled, **undoing also breaks the reconciliation**. A transaction that came from the ERP and received a line from the file **isn't deleted**: undoing only unlinks it from the statement. Uploading the file again joins the line to it once more. The action doesn't appear while the statement is **Queued** or **Running** — wait for it to finish. It also doesn't appear on statements that came from Fintera: *"Extratos vindos do Fintera não podem ser desfeitos aqui — desfaça no Fintera."* ("Statements that come from Fintera cannot be undone here — undo them in Fintera.") ### Deleting one transaction from a statement[​](#deleting-one-transaction-from-a-statement "Direct link to Deleting one transaction from a statement") Deleting **a single transaction** that came from a statement is different from undoing the whole statement, and the difference shows on the next import: * **You deleted the transaction** — it **doesn't come back**. Importing the same file again, or syncing the Banking Gateway once more, won't bring it back: the system remembers that you removed it. * **You undid the statement** — then yes, importing the file again brings everything back. That's the way to start over. **This is why deleting the line works, even without Undo.** The Banking Gateway statement has no batch to undo, and the sync brings the account's whole history every time. Without that guarantee, the line you deleted would return on the next sync — and if you had already entered the correction by hand, the amount would show up **twice**. ## Other statement sources[​](#other-statement-sources "Direct link to Other statement sources") Besides a file, a statement can come from: * **Banking Gateway** — the **Sync statement** button on the integration screen pulls the transactions of the selected company's linked accounts. * **Fintera** — imports the statement mirrored from the platform. **Neither runs on its own.** There is no scheduling: both are a button you press. note **The Banking Gateway statement doesn't show in this tab's History.** It isn't a file — the gateway returns a list of transactions, with no concept of an "imported statement". The **transactions** show up in the account as usual; the **batch** doesn't, and that's why there is **no Undo** for it. To take out a line, delete the transaction: it won't come back on the next sync (see [Deleting one transaction from a statement](#deleting-one-transaction-from-a-statement)). The record of those runs lives on the [Banking Gateway](https://docs.finance.kobana.com.br/en/en/integracoes/kobana.md) screen itself. --- # Taxes The Taxes section (`/taxes`) manages the registry of rates and levies that can be **linked to payables and receivables** (withholdings/taxes on the document). ![Taxes list](/en/assets/images/13-taxes-9a7f8c405d08f95722832f7229560635.png) ## Fields[​](#fields "Direct link to Fields") | Field | Description | | -------------------- | ----------------------------------------------------------------------------- | | **Name** | Tax identifier (e.g. "Employer INSS", "Municipal ISS") — unique per workspace | | **Default rate (%)** | Suggested tax percentage | | **Withheld** | Marks the tax as withholding. Default: yes | | **Active** | Whether the tax appears for selection | ## Usage[​](#usage "Direct link to Usage") Registered taxes can be **assigned as a charge** to a payable or receivable — the document records which taxes apply to it. note **Registering a tax is not paying a tax slip.** To record the **payment** of a specific slip (DARF, GPS, GRU, FGTS…), use a payable with **Document = Tax** — see [Tax / tribute in Payables](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/tributos.md). ## API[​](#api "Direct link to API") The taxes resource is available in the [Public API](https://docs.finance.kobana.com.br/en/en/api.md), with the `finance/taxes` scope and the `read` access level to read, `write` to create and update, and `delete` to delete. --- # Integrations **Integrations** (`/settings/integrations`) connects your organization to external services. It's an item in the **System** group of the menu. ![Integrations screen](/en/assets/images/19-integrations-a56b930a3f636ce17624707a854891a1.png) ## Available integrations[​](#available-integrations "Direct link to Available integrations") ## [📄️Banking Gateway](https://docs.finance.kobana.com.br/en/en/integracoes/kobana.md) [Sending payments to the bank and syncing accounts, statements and people via Kobana.](https://docs.finance.kobana.com.br/en/en/integracoes/kobana.md) ## [📄️Open Finance](https://docs.finance.kobana.com.br/en/en/integracoes/open-finance.md) [Connect the company's bank accounts through Open Finance and receive balances and statements automatically.](https://docs.finance.kobana.com.br/en/en/integracoes/open-finance.md) ## [📄️Fintera](https://docs.finance.kobana.com.br/en/en/integracoes/fintera.md) [Importing financial data from Fintera — eleven resources, company binding and schedules.](https://docs.finance.kobana.com.br/en/en/integracoes/fintera.md) ## [📄️WhatsApp](https://docs.finance.kobana.com.br/en/en/integracoes/whatsapp.md) [Profile pictures for customers and suppliers via the Evolution API — per-company setup.](https://docs.finance.kobana.com.br/en/en/integracoes/whatsapp.md) Each card leads to that integration's page, with its connection instructions. ## Status[​](#status "Direct link to Status") The status badge sits next to the integration's name, and **only appears in two cases**: | Situation | What you see | | ------------------ | ---------------------------------------------------------------------------------------------------- | | **Connected** | A **round green icon**. The word "Connected" isn't written on screen — it's in the tooltip, on hover | | **Error** | A **red badge reading "Error"** — invalid credentials or a connection failure | | **Not configured** | **Nothing.** The badge simply isn't drawn | note **The absence of a badge is the information.** An integration that hasn't been connected yet doesn't display "Not configured": the space is left empty. The text exists in the system, but no screen shows it. **The WhatsApp card has no badge at all**, not even when it's configured. Status is only computed for the Banking Gateway and for Fintera — the WhatsApp connection is per company and lives somewhere else. To find out whether it's up, open its page. --- # Fintera integration **System > Integrations > Fintera** (`/settings/integrations/fintera`). Imports data from a Fintera account into Smart Finance — for anyone migrating, or running both platforms side by side. ## Connecting[​](#connecting "Direct link to Connecting") The strip at the top shows **Status**, **Token** and how many **Companies** are bound. With no connection, **"Connect"**: paste your Fintera API token. Once connected, the "Manage Fintera connection" dialog shows the token as *"Stored encrypted"* — it's never displayed back to you. Once connected, the button becomes **"Manage connection"** — and it's inside that dialog that you'll find the **company binding**, **Update** for the token, and **Disconnect**. ## Company binding[​](#company-binding "Direct link to Company binding") **Fintera brings the companies, not the accounts.** *"These companies come from Fintera (via your token). Here you only choose which company registered in Smart Finance each one sends its data to."* ## Two gates[​](#two-gates "Direct link to Two gates") Imports stay blocked until both are satisfied: 1. **A valid token** — *"Save a valid Fintera token to enable imports."* 2. **At least one bound company** — *"Bind at least one Fintera entity to a Smart Finance company to enable imports."* ## What gets imported[​](#what-gets-imported "Direct link to What gets imported") **Eleven resources**, in two groups. Order matters: **Movements** *"depend on the records above"*. ### Base records[​](#base-records "Direct link to Base records") | Resource | Notes | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Categories** | Replicated per company; bidirectional categories become a **pair** (revenue + expense) | | **Classification centers** | Into every bound company | | **People** | Customers and suppliers | | **Taxes** | The workspace catalog. **Runs before** payables/receivables, whose per-bill taxes resolve against it | | **Financial accounts** | Fintera's bank accounts. An account that already exists here with the same bank, branch and number (by hand or from the Banking Gateway) is **linked**, not duplicated | ### Movements[​](#movements "Direct link to Movements") | Resource | Depends on | | ------------------- | ----------------------------------------------------------------------------------------- | | **Payables** | People + categories + centers | | **Receivables** | People + categories + centers | | **Transactions** | — (each account's first import brings its whole history; the next ones, the last 90 days) | | **Reconciliations** | Bills + transactions | | **Attachments** | Bills + transactions | | **Bank statements** | Transactions | note **Bank statements doesn't download an OFX file.** The import *"Mirrors the Fintera statement import history and links each transaction to its statement"* — but **the file itself doesn't come**: the Fintera API doesn't expose it. You get the structure and the links, not the document. **Reconciliations preserves the n:m.** Fintera's link between bills and transactions is mirrored as it stands. See [Reconciliation](https://docs.finance.kobana.com.br/en/en/conciliacao/.md) — an imported reconciliation is read-only. **Payables bring their payment details.** What Fintera holds under *Dados de Pagamento* — boleto, TED or Pix (key, bank details or copy-and-paste code) — lands in the bill's **Payment information**. The beneficiary doesn't come along: left empty, sending to the bank uses the supplier. When the bill in Fintera has no payment details, the import leaves whatever you filled in here alone. And once someone changes the payment details here, or the bill is sent to the bank, the import no longer replaces them. **What you do here the import does not undo.** It only updates what is still as Fintera last sent it. The classification you, an [automatic rule](https://docs.finance.kobana.com.br/en/en/regras-automaticas/.md) or the [reconciliation](https://docs.finance.kobana.com.br/en/en/conciliacao/.md) gave a transaction stays; a line reconciled here as a transfer stays a transfer; and a bill settled here stays paid, even while it is open in Fintera. The reconciliation that comes from Fintera leaves out what was already reconciled here, and a transaction deleted here does not come back. ## Importing[​](#importing "Direct link to Importing") **"Import all"** runs all eleven in sequence, respecting the dependency. Each row also has its own **"Import"**, to run a single resource on its own. Imports **run in the background** and follow the company bindings. Each row shows the progress and the result — how many created, updated, failed, or *"no changes"* / *"nothing to import"*. **Payables and receivables bring only what changed.** After each company's first import, the next ones ask Fintera only for the bills created or changed since the previous run — never the whole history again. When Fintera doesn't report when a bill changed, they ask for the bills due or paid in the last 90 days (or since the previous run, if that is older). That is why a re-import usually reports a small total: it is the changes. **A bill deleted in Fintera becomes cancelled here.** On every import, Smart Finance compares how many bills Fintera holds with the ones here — without bringing the history — and, when there are extra ones, confirms each one before marking it as cancelled: it leaves the totals, reports and cash flow, but is not deleted. If it shows up in Fintera again, the next import restores it. Bills already sent to the bank or reconciled are left untouched. To import from a specific day, some rows have a calendar icon beside the import button: * **Payables** and **Receivables** — the bills created or changed since that date (or, when Fintera doesn't report changes, the ones due or paid since it). On a company's first import it also avoids bringing the whole history: the import starts on that day. * **Transactions** — the transactions that occurred from that date until today, in every account. * **Bank statements** — the statements of the transactions already imported for that period. * **Attachments** — only the attachments uploaded to Fintera since that date. The ones already here are not downloaded again. The registries, the financial accounts and the reconciliations have no calendar: Fintera does not filter those resources by date, and they are read whole on every import. **There is no "Import data" button with a period selector.** It's the eleven resources, each with its own, plus "Import all". ## Financeiro module token mode[​](#financeiro-module-token-mode "Direct link to Financeiro module token mode") A token restricted to Fintera's Financeiro module doesn't list companies. In that case there's nothing to bind, and the screen tells you: *"Available imports apply to the workspace's active companies."* Only a subset of the resources is enabled. ## Schedules[​](#schedules "Direct link to Schedules") *"Configure automatic runs for imports."* With **"New schedule"**, an import starts running on its own at the frequency you pick. Each row shows the resource, the frequency, the **next run** and the result of the last one, with the **Active** or **Disabled** badge and the **Edit**, **Pause** / **Resume** and **Delete** actions. This is what sets Fintera apart from the [Maintenance](https://docs.finance.kobana.com.br/en/en/manutencao/.md) tools: here, scheduling **does** exist. ## Import history[​](#import-history "Direct link to Import history") A log of the runs, in four columns: **Date**, **Imports**, **Result** and **User** — who triggered it. ## Disconnecting[​](#disconnecting "Direct link to Disconnecting") Inside **"Manage connection"**. Data already imported stays put. --- # Banking Gateway integration (Kobana) **System > Integrations > Kobana** (`/settings/integrations/kobana`). The integration lets you: 1. **Send payments to the bank** — dispatch approved payables, one bill at a time or in batch. 2. **Sync bank accounts** — between Kobana and Smart Finance. 3. **Sync the statement** — pull in the transactions of the linked accounts. 4. **Sync people** — keep the records the same on both sides. It brings in everything Kobana has; from here, it sends customers only. 5. **Settle automatically** — once the payment is confirmed, the bill is settled and the transaction created. This depends on the bill having **"Pay from"** set: without knowing which account the money left, the system won't guess, and the settlement is left for you to do by hand. 6. **Create charges** — issue a **bank slip or a Pix** from a receivable, for the customer to pay. 7. **Payment receipts** — capture, on its own, the receipt of every confirmed payment. ## Connecting[​](#connecting "Direct link to Connecting") The strip at the top shows the **Status** — **Connected**, **Not connected** or **Connection error** — and the token. With no connection, the button is **"Connect"**: paste the API token generated in your Kobana panel. *"The token is stored encrypted."* The system validates it and reports how many accounts are visible. Once connected, the button becomes **"Manage connection"**. **"Disconnect" isn't on the page.** It lives inside the **"Manage Kobana connection"** dialog, next to "Update". The confirmation is reassuring: *"Only the connection is removed. Accounts and data already synced stay in Smart Finance."* ## Syncs[​](#syncs "Direct link to Syncs") note **The syncs require a specific company** in the header selector: *"Select a specific company in the header selector, not 'All companies'. Synced accounts land in the company you choose."* ### Bank accounts[​](#bank-accounts "Direct link to Bank accounts") There's no listing for linking accounts by hand. There's **one button** — **"Sync bank accounts"** — that does the whole job and links them for you. **This sync only brings accounts in.** The card carries the **"From the gateway"** badge: it imports the accounts registered in Kobana and **creates nothing there**. There's still a confirmation, because the run can **rewrite accounts that already exist here** — and the modal shows exactly which, and which fields change, before you authorise it. **The return trip is one account at a time.** To send an account from here to Kobana, open the account and use **"Add to the banking gateway"** — see [Financial accounts](https://docs.finance.kobana.com.br/en/en/contas-financeiras/.md). Creating an account in the gateway changes the external system, so you choose what goes, one account at a time, rather than a bulk run doing it for you. ### Statement[​](#statement "Direct link to Statement") **"Sync statement"** *"Import the statement of linked accounts (in the selected company): pulls Kobana transactions into Smart Finance, without duplicating the ones already imported."* **There's a single button and it covers every linked account in the company** — there's no per-account button. The imported lines feed [Reconciliation](https://docs.finance.kobana.com.br/en/en/conciliacao/.md). ### People[​](#people "Direct link to People") **"Send people"** syncs the records in both directions: it brings in whoever only exists on the Kobana side and sends the **customers** of the selected company that aren't there yet. The card carries the **"Two-way"** badge too. info **Suppliers are not sent.** The record in Kobana is for whoever pays — a supplier would occupy a place there without ever being billed. Someone who is a customer **and** a supplier is sent normally, being a customer too. Coming back there is no such filter, because Kobana draws no distinction between roles: **whoever arrives from there lands here as a customer**. If an imported person is in fact one of your suppliers, set the role on their record — that mark is yours, and later syncs do not undo it. warning **It also WRITES to Kobana**, which is why it asks for confirmation: *"Creating records in Kobana changes the external system."* **Nobody gets duplicated.** Matching is by **tax ID** — and, for anyone sent from here before, by the link stored on that earlier send. Someone who already exists on both sides simply becomes linked; the data you registered here is **not overwritten**. info **A person without a tax ID is not sent.** Without the document there's no way to tell whether they're already there, and the send would rather leave them out than risk a duplicate record. The run reports how many were left out — fill in the document and run again. The **import** has no such limit. Each run sends up to **200 people**. If your base is larger, run it again: whatever already went isn't resent. ## Payment approval[​](#payment-approval "Direct link to Payment approval") When approval is **on** (the workspace default), a bill created through the form, through CSV or through the API is **not** available for sending until a **person approves** it in [Approve payments](https://docs.finance.kobana.com.br/en/en/aprovar-pagamentos/.md). With approval off, the bill is born official and ready to send. See [Lifecycle](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/ciclo-de-vida.md). ## Sending payments[​](#sending-payments "Direct link to Sending payments") With the integration active and the bill approved, use **"Send to the bank"** — a **manual** action, on the detail screen. From the listing, the route is **"Send payments"**, which dispatches in batch. See [Sending to the bank](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/disparo-kobana.md). ## Creating charges[​](#creating-charges "Direct link to Creating charges") The integration also works in the direction of the money coming **in**: from a receivable, **"Create charge"** issues a **bank slip** or a **Pix** for the customer to pay, and a paid charge marks the bill as received on its own. Each rail has its own prerequisite on the gateway account — the bank slip needs an **agreement**, the Pix a **charging account** — and the bank slip additionally requires the customer's **full address**. See [Bank slip and Pix charges](https://docs.finance.kobana.com.br/en/en/contas-a-receber/cobranca-kobana.md). ## Receipts[​](#receipts "Direct link to Receipts") Once a payment sent to the bank is confirmed, its receipt is **captured automatically**: it is stored in the [Attachments](https://docs.finance.kobana.com.br/en/en/anexos/.md) library, shows up on the bill's screen, and is listed under [Receipts](https://docs.finance.kobana.com.br/en/en/comprovantes/.md). Whoever is selected in **"Configure delivery"** gets an email, and the addresses registered on the bill itself get the receipt **attached**; the bell notifies either way. See [Who is emailed](https://docs.finance.kobana.com.br/en/en/comprovantes/.md#who-is-emailed). ## Automatic sync[​](#automatic-sync "Direct link to Automatic sync") note **This section only appears if the server has a public webhook address configured.** Without one there's no way for the gateway to notify anything, and neither this section nor the two that follow are drawn. A single switch: *"Keeps dispatched payments' status up to date on its own, without clicking 'Refresh status'."* **It's optional, and switching it off doesn't leave you in the dark** — you just have to fetch the status by hand, through each bill's **"Refresh status"**. ## Notifications[​](#notifications "Direct link to Notifications") Another switch: *"Get an alert in the bell when a payment's status changes (confirmed, scheduled, rejected…)."* The two switches talk to each other: without automatic sync on, *"alerts may arrive late"* — the bell only rings once the system finds out about the change. ## Webhook deliveries[​](#webhook-deliveries "Direct link to Webhook deliveries") A diagnostics table: *"A log of each status-change event the Kobana payment gateway sends. If one fails, you can resend it."* It has **"Refresh"** and, per row, the resend. This is where to look when a payment seems stuck: if the event never arrived, the status here is running behind the bank. **This table only exists with automatic sync on.** It's automatic sync that makes the gateway send the events — switched off, there's no delivery to log, and the section disappears from the page. ## History[​](#history "Direct link to History") A log of the syncs that have run, by **Date**, **Type** (**Accounts**, **Statement** or **People**) and **Result** — with how many were created, updated, pushed or skipped. On the people sync, which runs both ways, the result keeps the directions apart: what **came** from Kobana shows as created or updated, and what **went** from here shows as pushed. People left out for having no tax ID are counted as skipped. The accounts sync only brings accounts in, so there it is created and updated only. --- # Open Finance **System > Integrations > Open Finance** (`/settings/integrations/open-finance`). Connect your companies' bank accounts through **Open Finance**, the data-sharing system regulated by Brazil's Central Bank, and Smart Finance starts receiving on its own: 1. **Balances** — several times a day, recorded in the account's **Balances** tab with the **Open Finance** source. 2. **Statement** — posted entries arrive as the account's entries, classified by your [automatic rules](https://docs.finance.kobana.com.br/en/en/regras-automaticas/.md). Nothing here moves money: Open Finance only **reads** the accounts you authorize. ## Connect a bank[​](#connect-a-bank "Direct link to Connect a bank") Click **"Connect bank"**. There are two steps: 1. **Company** — pick the company and enter the **CPF of who will authorize at the bank**. For business accounts, the bank asks for the CPF of a person with access to the account. The CPF is not stored. Click **"Continue"**. 2. **Authorization** — the authorization window opens with the company and the CPF already filled in: choose the bank, check the data to be shared, the purpose and the period, and confirm. If the window does not open by itself, click **"Choose the bank"**. You are taken to **the bank itself**, sign in and choose there which accounts to share. Nobody but the bank sees your password. When you finish, the bank brings you back to Financeiro Inteligente. note The sharing period is shown in the review, before you confirm, and is confirmed at the bank. You can end it earlier, here or at your bank. ## Choose what to do with each account[​](#choose-what-to-do-with-each-account "Direct link to Choose what to do with each account") Back from the bank, the screen lists the shared accounts. For each one: | Option | What happens | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Link to an existing account** | The account you already have here starts receiving balance and statement. The system suggests the right one by branch and number | | **Create a new account** | A new account is created in the company, already linked | | **Ignore this account** | Nothing is imported from it | And, for each account, **"Import statement"** with a **"from"** date. warning **The start date avoids duplicate entries.** If the account already has a statement here — imported from OFX or typed —, start after the last entry. The system suggests that date. An account that already receives its statement through the [Banking Gateway](https://docs.finance.kobana.com.br/en/en/integracoes/kobana.md) arrives with the statement **off**. Turning it on here makes Open Finance its only statement source — never both, so the same entry never lands twice. Balances from both sources coexist. ## Follow the connections[​](#follow-the-connections "Direct link to Follow the connections") Each connection (company × bank) shows its status: | Status | Meaning | | ------------------------ | ---------------------------------------------------- | | **Waiting for the bank** | Authorization at the bank is not finished yet | | **Connected** | Balances and statements are being updated | | **Not authorized** | Authorization was declined or did not finish in time | | **Ended** | Sharing was ended — by you, here or at the bank | | **Expired** | The period is over | In each connection's menu: **Update now**, **Review accounts**, **Renew** (before it expires), **Disconnect** and, once ended, **Remove from list**. You get a notification when the connection is authorized, when accounts are ready to import, near the expiry date and when it ends. **Disconnecting deletes nothing.** Entries and balances already imported stay in the accounts. ## Schedule the sync and see the history[​](#schedule-the-sync-and-see-the-history "Direct link to Schedule the sync and see the history") On the same screen, **Sync schedule** sets when a company's connections refresh on their own (balances, statements, cards and investments). Pick the company at the top and use **New schedule**; there is one per company. Without a schedule, the system refreshes every 6 hours and whenever the bank reports new data. The **Sync history** lists the latest runs — bank, source (bank notice, scheduled, manual or new connection) and what changed. ## On the account[​](#on-the-account "Direct link to On the account") A linked account shows the **Open Finance** badge. In the **Balances** tab: * **"Update via Open Finance"** reads the balance right away; * **"Statement via Open Finance"** turns the statement on or off and changes the start date. An imported entry you delete **does not come back** on the next update. --- # WhatsApp integration (Evolution API) **System > Integrations > WhatsApp** (`/settings/integrations/whatsapp`). With Evolution connected, the **Fetch photos** tool (in [Maintenance](https://docs.finance.kobana.com.br/en/en/manutencao/.md)) starts trying to pull your contacts' WhatsApp pictures. ## What it does — and what it doesn't[​](#what-it-does--and-what-it-doesnt "Direct link to What it does — and what it doesn't") note **This integration doesn't display any picture on its own.** It's a **source** for the photo fetch, not a feature in its own right. Without it, the fetch uses **Gravatar only** — *"and it rarely has a picture for a Brazilian number"*, which is precisely why the integration exists. Any picture found is **stored** on the person's record. It isn't fetched on every visit, nor behind the scenes: only when someone runs **Fetch photos**. **The picture shows up in [People](https://docs.finance.kobana.com.br/en/en/pessoas/.md)** — in the listing and on the detail screen. It does **not** show up on the payables or receivables screens. ## Per-company setup[​](#per-company-setup "Direct link to Per-company setup") The credentials are **per company**, not per workspace — each one can have its own instance. With no company selected, the page doesn't show the setup: it stays on **"Select a company"**. **The company comes from the header selector**, not from a step inside the page. There are **three** fields, and the button only unlocks with all three filled in: | Field | Example | | --------------------- | ------------------------------------------------------------------------------ | | **Evolution API URL** | `https://evolution.example.com` | | **Instance name** | `my-instance` | | **API key** | The instance's key. *"The key is stored encrypted and never returned on GET."* | The button is **"Connect"** — or **"Update"**, if credentials are already there. ## Privacy and security[​](#privacy-and-security "Direct link to Privacy and security") * The **API key is encrypted** at rest and is never returned on read. * The system **refuses private destinations**: loopback addresses, internal networks and link-local are blocked, which stops the integration being used to reach infrastructure services. warning **HTTPS isn't mandatory.** `http://` is accepted — what the system refuses is the **destination**, not the protocol. Even so, an endpoint on HTTP sends the API key in the clear: prefer HTTPS. ## Fetch photos[​](#fetch-photos "Direct link to Fetch photos") The fetch is **manual**, in [Maintenance](https://docs.finance.kobana.com.br/en/en/manutencao/.md) → **Fetch photos**. There's no periodic worker. Each run: * Tries **Gravatar first** (by email) and **WhatsApp second** (by phone), stopping at the first source that answers. * Walks **only through people who don't have a picture yet** — anyone who already has one is skipped. * Processes at most **100 people at a time**. * Waits **30 days** before retrying anyone who failed. ## Removing[​](#removing "Direct link to Removing") The button is **"Remove"**. The confirmation states the exact effect: *"The credentials for the company will be deleted. The next 'Fetch Photos' run for this company will skip WhatsApp — Gravatar only."* Pictures **already fetched stay** on the record: removing the credential doesn't erase what was found. --- # Transactions Transactions (`/financial-transactions`) are the movements of the financial accounts: money coming in and going out. They are the basis for reconciling payables and receivables. ![Transactions list](/en/assets/images/05-transactions-720f1578877683bb1b26d5044eb9a0c9.png) ![Transaction detail](/en/assets/images/06-transaction-detail-61e4d12a43b76ea1f559b00d4f84c036.png) ## In this section[​](#in-this-section "Direct link to In this section") ## [📄️CSV import](https://docs.finance.kobana.com.br/en/en/lancamentos/importacao-csv.md) [Import transactions in bulk from a spreadsheet — inside the financial account, with a Portuguese header.](https://docs.finance.kobana.com.br/en/en/lancamentos/importacao-csv.md) ## The listing[​](#the-listing "Direct link to The listing") The header carries three totals — **Inflows**, **Outflows** and **Net** — with a green arrow for money in and a red one for money out. note **The totals belong to the header, not the footer, and they have a scope of their own.** They add up **company + period** and nothing else: searching by text or applying filters **does not narrow them**. Filtering by a category and watching the total stay put is not a defect — the strip answers "how much came in and went out over the period", not "how much the list is showing". ### Filters[​](#filters "Direct link to Filters") * **Search** — by description or document. * **Quick filters** — **All**, **With attachments**, **Reconciled**, **Transfers**. * **Advanced filters** — they take **negative** clauses, not just positive ones. They come in two kinds: pills that exist in both forms (**Reconciled** / **Not reconciled**, **Transfers** / **Not transfers**, **With attachments** / **Without attachments**), and the **Uncategorized** option inside the category picker — the same going for **No customer / supplier** and **No classification center**. Picking categories always **includes**: there is no way to exclude a specific category. Next to the totals strip sits **Export** — which is not a filter but an action: it generates the transactions export file. ### Columns[​](#columns "Direct link to Columns") Description, Date, Category, Account and Amount — plus **Company**, only in the consolidated view. **Payment method** exists as a column you can turn on, and the last column is a **summary card** of the transaction (links, person, document, accrual, split, notes), visible on desktop. **Payment method is read-only.** There is no such field on the form: the column only shows what came in through **CSV or API**. Create a transaction from the screen and it stays empty. ### The badges on the Description column[​](#the-badges-on-the-description-column "Direct link to The badges on the Description column") There is no "Origin" field. Provenance is **derived** and shows up as icons next to the description: | Badge | Meaning | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Reconciled** | Linked to a bill | | **Generated by … settlement** | Created by the settlement of a bill | | **Transfer** | One leg of a transfer | | **Provisional** | Not yet effective | | **Paperclip** | Has attachments | | **Card** | A [card](https://docs.finance.kobana.com.br/en/en/cartoes/.md) purchase, with the supplier and the statement below | | **Statement payment** · **Top-up** | The legs of the transfer that pays a card's statement or tops up a prepaid card | ### Actions[​](#actions "Direct link to Actions") Per row: **Classify**, **Reconcile**, **Edit** and **Delete**. In bulk: **Reconcile selected**, **Classify selected** and **Delete**. note **Reconcile and Classify in bulk require a single company.** Categories and bills are per company, so a selection mixing companies has no way to open the dialog — in the consolidated view the system warns you and cancels instead of picking a company on its own. **Classify** also asks that the whole selection be of the same type: inflows and outflows together are refused too, because the categories of one don't serve the other. **Delete** has none of those locks — it removes the selection as it stands. ## Fields[​](#fields "Direct link to Fields") | Field | Notes | | ---------------------------------------- | ------------------------------------------------ | | **Amount (R$)** | Required | | **Date** | Required | | **Financial account** | Required — where the movement happened | | **Description** | Required | | **Accrual month** | Month picker | | **Entry type** | Credit or debit | | **Category** · **Classification center** | Classification, each with the **Split** shortcut | | **Customer / Supplier** | Associated person | | **Document number** · **Doc. date** | The external document | | **Provisional** | Marks the transaction as a forecast | | **Notes** | Free text | | **Attachments** | Files tied to the transaction | ### Provisional[​](#provisional "Direct link to Provisional") The **"Provisional"** pill marks the transaction as a forecast, not yet effective. It **shows on the listing with a badge, but does not enter the account balance nor the realized figures on the dashboard** — it counts towards the cash flow **projection**, not the realized side. ## Automatic creation[​](#automatic-creation "Direct link to Automatic creation") Some transactions you never type — the system creates them: * **Settling a payable** → an outflow in the chosen account. * **Settling a receivable** → an inflow in the chosen account. * **A transfer** → an outflow at the source and an inflow at the destination. * **An imported bank statement**, when you confirm the import. * **A Banking Gateway sync**. * **A card purchase** → an outflow on the card's account, on the purchase date, once the card launch is realized. The card manages it: edit, classify, reconcile and delete are disabled here, with the reason, and **"Open in the card"** goes to its statement. The same goes for the statement payment and the top-up — see [Cards](https://docs.finance.kobana.com.br/en/en/cartoes/.md#the-card-and-your-accounts). ## Reconciliation[​](#reconciliation "Direct link to Reconciliation") A transaction can be linked to payables and receivables. The link shows on the transaction detail and on the [Reconciliation](https://docs.finance.kobana.com.br/en/en/conciliacao/.md) screen, which closes, line by line, what came from the statement. --- # CSV import — Transactions Import transactions in bulk from a CSV file. ## Where it lives[​](#where-it-lives "Direct link to Where it lives") **There is no "Import" in the menu**, and no import screen. And, contrary to what you might expect, **the Transactions screen does not import** — the import lives inside the account: **Financial accounts** → open the account → **Import** pill. note **There is no destination account picker.** The account is the one you are already in: every transaction in the file lands there. To import into two accounts, run two imports. You need a **specific company** selected in the header, and **the account must be tied to a company**. In either case the panel tells you: *"Select a specific company to import transactions."* The **Download template** button hands you a sample CSV with the right header — the safest starting point, because it already comes in the right encoding. ## CSV columns[​](#csv-columns "Direct link to CSV columns") | Column | Required | Description | | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | ✅ | Transaction date | | `descricao` | ✅ | Transaction description | | `valor` | ✅ | Amount in reais, always positive | | `tipo` | ✅ | `entrada` (credit) or `saida` (debit) | | `categoria` | — | Category name (if it doesn't exist yet, the preview asks whether to create it). Also accepted: `plano_de_contas`, `categoria_financeira`, `category` | | `pessoa` | — | Person name (if it doesn't exist yet, the preview asks whether to create it). Also accepted: `cliente_fornecedor`, `cliente`, `fornecedor`, `favorecido`, `contraparte` | | `centro_custo` | — | Classification center name (if it doesn't exist yet, the preview asks whether to create it). Also accepted: `centro_de_custo`, `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` | | `documento` | — | Document identifier | | `observacao` | — | Notes | warning **This file's header is in Portuguese, and only in Portuguese.** Unlike the payables and receivables CSV — which takes both `description` and `descricao` — here the canonical names **are** the Portuguese ones and **the required columns have no English equivalent**. A file with `description`, `amount` and `date` is refused whole, for a missing required column. Case, accents and spaces in the header don't matter: `Centro de Receita` counts as `centro_de_receita`. If the workspace has a classifier with the same name as one of these columns (e.g. *Centro de Resultado*), the column goes to the classifier. If the file has more than one column for the same field (e.g. `Centro de Custo` and `Centro de Receita`), each row uses the first one that is filled in. Beyond those names, a header with the word **centro** is read as the classification center; one with **categoria** or **plano de contas** as the category (e.g. `Centro de Lucro`, `Categoria DRE`); and one with **pessoa**, **cliente** or **fornecedor** next to nothing but name words as the person (e.g. `Nome do Fornecedor`, `Cliente / Fornecedor` — but not `CNPJ do Fornecedor`). Columns the system doesn't know are **ignored silently**. ## Format[​](#format "Direct link to Format") * **Header** — case, accents and spaces don't matter: `Descrição`, `DESCRICAO` and `descricao` are the same column. * **Separator** — `,` or `;`, detected **from the header line**. On a tie, `;`. * **Dates** — `31/12/2026`, `31-12-2026` or `2026-12-31`. * **Amounts** — `1234.56`, `1.234,56`, `1234,56`, with or without `R$`. The amount must be **greater than zero**: what decides credit or debit is the `tipo` column, never the sign of the amount. warning **The encoding must be UTF-8, and this is where most files trip up.** Excel in Portuguese saves CSV as Windows-1252 by default, and the system refuses it with a message that stays in Portuguese: *"Arquivo não está em UTF-8. Salve novamente em UTF-8 e tente novamente."* ("The file is not UTF-8. Save it again as UTF-8 and try once more.") In Excel, use **Save as → CSV UTF-8**; or start from the downloaded template. Other refusals of the whole file: an extension other than `.csv`, a size above **5 MB**, an empty file, and a **missing required column** — *"Colunas obrigatórias ausentes: tipo"* ("Missing required columns: tipo"). In those cases there is no preview: the problem is the file's, not a row's. ## Import[​](#import "Direct link to Import") 1. Upload the file. The system reads it and shows the preview. 2. **Valid rows come already checked.** Click a row to uncheck it. 3. Click **Import N lines**. ### Rows with errors[​](#rows-with-errors "Direct link to Rows with errors") Invalid rows show in the preview with a red marker, **and cannot be selected or edited there**. There is no fixing them inside the system. The screen itself spells out the path: *"Uncheck the rows with errors or fix them in the file and upload again."* The number in **Row N** is the line number **in the file**, counting the header — the first data line is 2. ### The write runs in the background[​](#the-write-runs-in-the-background "Direct link to The write runs in the background") On confirmation you get *"Import started in the background"* and a progress dialog. **You can close the dialog** — the import carries on, and the progress stays visible in the bottom-right corner. ### Links[​](#links "Direct link to Links") **People, categories and classification centers show up in the preview**, each with what the import will do: existing ones are linked; new ones come marked to **create** (or to **leave blank** if you can't create them); a name that only differs from an existing one in accents, case or spacing comes marked to **use the existing one**; and a classification center that only exists for the other side (e.g. one of type Cost on a credit) comes marked to leave blank. A person is looked up by name alone, customer or supplier, and takes on the role of the rows that use them (customer on credits, supplier on debits); a new person used on both credits and debits is created once, as customer and supplier. A new classification center used on both credits and debits is created once, of type Both. Spellings of the same name that only differ in accents, case or spacing (e.g. *Água e Luz* and *agua e luz*) count as one name. You can change any choice before importing. The [automatic rules](https://docs.finance.kobana.com.br/en/en/regras-automaticas/.md) are applied to the imported records. ## History[​](#history "Direct link to History") Below the panel, the **History** section lists the imports with date, file, status (**Queued**, **Running**, **Completed**, **Failed**, **Cancelled**), how many rows landed out of the total, and who asked for it. --- # Maintenance **Maintenance** (`/settings/maintenance`) gathers the data hygiene tools for **people**: standardize phones and names, find duplicates, clear out empty records and fetch photos. And one for **transactions**: merging the ones an import recorded twice. ## Scope[​](#scope "Direct link to Scope") note **The tools act on one company at a time.** The scope comes from the selector at the top, and the screen says so: *"Applied only to the selected company."* Under **"Consolidated"**, it asks you to pick one before running anything. ## The six tools[​](#the-six-tools "Direct link to The six tools") | Tool | What it does | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Adjust phones** | Classifies each phone as mobile or landline using Anatel rules — 11 digits with the third one equal to 9 is a mobile; 10 digits with the third one between 2 and 5 is a landline. Anything that doesn't fit is left unclassifiable | | **Normalize names** | Converts people's names to uppercase, **preserving accents** | | **Detect duplicates** | Looks for repeated records by **same name**, **first + last name**, **same email**, **same phone** or **same document**, and groups them for you to merge | | **Clean empty people** | Lists people **with no document, no email, no phone and no linked transactions**, ready for removal | | **Fetch photos** | Looks up each person's photo on **Gravatar** (by email) and on **WhatsApp** (when the number is public and the company has Evolution credentials). **Anyone who already has a photo is skipped** | | **Deduplicate transactions** | In one account, merges the transactions that the ERP import (Fintera, Nibo) and the bank statement (Banking Gateway, Open Finance or an uploaded OFX) recorded twice | | **Delete a source's transactions** | Deletes the transactions an integration brought — Fintera, Nibo, Conta Azul, Open Finance or Banking Gateway — across the company or in one account, to restart the import | ## Nothing runs on its own[​](#nothing-runs-on-its-own "Direct link to Nothing runs on its own") **These tools cannot be scheduled: they run when you click, and only then.** There is no periodic execution and no automatic trigger — none of them fire when a person is created or a file is imported. That doesn't mean the screen freezes while they work: once started, some **run in the background and show progress right there**. Both things are true at once — what doesn't exist is **scheduling**, not asynchrony. ## Merging duplicates[​](#merging-duplicates "Direct link to Merging duplicates") Once the groups are detected, you pick which ones to merge. In each group, one record is marked **Survivor** — that's the one that stays, taking on the data and the links from the others. The button is **"Merge selected"**, and the confirmation tells you how many groups will be processed and how many people will be merged into the survivor. note **Merging doesn't touch the [Security](https://docs.finance.kobana.com.br/en/en/seguranca/.md#payees) rules.** The lists of allowed and blocked payees, and each one's limits, are by **CPF/CNPJ**, not by record: a blocked document stays blocked and an allowed one stays allowed after the merge. If the merged records had different documents, check in Security which one the rule refers to. ## Cleaning empty people[​](#cleaning-empty-people "Direct link to Cleaning empty people") The list shows each empty person and when they were created, with **"Select all"** and **"Remove selected"**. danger **Removal is the same deletion as in [People](https://docs.finance.kobana.com.br/en/en/pessoas/.md), and it is irreversible.** The confirmation is explicit — *"This action cannot be undone via the UI."* The records disappear from the screens, their financial history stays, and the document is freed up. ## Fetching photos[​](#fetching-photos "Direct link to Fetching photos") See [People](https://docs.finance.kobana.com.br/en/en/pessoas/.md) for how the photo is chosen and where it shows up. In short: **Gravatar first, WhatsApp as a fallback**, a ceiling of 100 people per run, and anyone who failed waits **30 days** before the next attempt. ## Deduplicating transactions[​](#deduplicating-transactions "Direct link to Deduplicating transactions") When the same account receives both the ERP history **and** the bank statement — automatic or an OFX/QIF file —, each movement may have come in twice — a classified copy from the ERP and a raw one from the statement. Today's imports already recognize the same movement and no longer duplicate it; this tool cleans up what came in twice before that. Choose the **account** and click **"Find duplicates"**. The screen tells you how many transactions will be merged and lists the pairs: the one that **stays** and the one that **goes**, with the origin of each. **It is the same movement** when both are in the same account, with the same direction, the same amount and the same day, and their documents (the bank's code) don't contradict each other. **The ERP copy stays**, with the description and classification the finance team gave it. **The statement copy goes**, and first hands over to the one that stays: * the link to the bank — the next statement read finds the line that stayed and creates no other; * the paid or received bill, the reconciliation, the attachments and the inbox items; * whatever the line that stays was missing: bank text and code, category, person, center, notes, splits. note **A pair whose two sides are already linked to different things** — two bills, two reconciliations or two transfers — **is left out** and shows up flagged in the list. Picking one would lose the other; resolve it by hand. danger **Merging deletes the statement transaction and cannot be undone.** Check the pairs before confirming. ## Deleting a source's transactions[​](#deleting-a-sources-transactions "Direct link to Deleting a source's transactions") To restart an integration's import, or to clean up what a source recorded twice. Choose the **source** (Fintera, Nibo, Conta Azul, Open Finance or Banking Gateway) and, optionally, an **account** — with no account it covers the whole company — and click **"Find transactions"**. The screen says how many will be deleted, the period and the count per account. A transaction belongs to the source when it came from it. **These stay, and the screen says how many:** * the ones that **also came from another source** (the same movement recognised in the statement and the ERP): deleting would take the other's data with it; * the ones **tied to a bill** (payment), a **reconciliation**, a **transfer**, a **card**, or generated by a payment. Each is undone through its own flow. What is deleted takes its classification and attachments with it, and **cannot be undone**. The deletion **does not stop** the integration from bringing the transactions again: on the next read they return, which is how you restart. It runs in batches of 500, with progress on screen. ## What about account settings?[​](#what-about-account-settings "Direct link to What about account settings?") There is no single "Settings" screen in the product — each setting has its own item in the **System** group of the menu, such as **Integrations**, **Security** and **Maintenance**. * Your account details and how signing in works: [My profile](https://docs.finance.kobana.com.br/en/en/meus-dados/.md). * Connections to external platforms: [Integrations](https://docs.finance.kobana.com.br/en/en/integracoes/.md). * Anti-fraud rules for payments and transfers: [Security](https://docs.finance.kobana.com.br/en/en/seguranca/.md). --- # Authentication The MCP server accepts a **Bearer token** in the `Authorization` header, and nothing else — no cookie, no client certificate, **no token in the URL**. A request carrying `?access_token=` (or `?token=`, `?api_key=` and the like) is refused with `401` and `error="invalid_request"`, even alongside a valid header: in the URL the token leaks into logs, browser history and intermediaries. That token is an **OAuth 2.1 access token issued by the Kobana authorization server** (`https://account.kobana.com.br`), an RS256-signed JWT issued **for this resource**: its `aud` is `https://mcp.finance.kobana.com.br`. It arrives by one of two paths — the OAuth flow, run by the client itself, or a **personal token** you create on your Kobana Account — and it is verified the same way in both cases. ``` Authorization: Bearer eyJhbGciOiJSUzI1NiIs… ``` :::info Each surface has its own audience A token issued for the MCP **does not work** on the REST API (`api.finance.*`), and an API token does not work here. That is what stops a token handed to an assistant from being reused against the API — and the other way around. ::: ## Two ways to connect[​](#two-ways-to-connect "Direct link to Two ways to connect") | | OAuth flow | Personal token | | ---------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | How you get it | Paste the URL into the client; it opens the Kobana login and you authorize | Create it under **Kobana Account → Tokens and Access → New Personal Token**: app **Smart Finance**, usage **MCP**, resources and access, validity | | How the client uses it | On its own, after authorization | You paste it into the client as `Authorization: Bearer ` | | Validity | Short, renewed by the client | From 7 days to 1 year, chosen by you | | Scope | The Smart Finance resources and the access levels you approve, one by one, on the consent screen | The resources and access you checked | | Good for | Claude, ChatGPT, IDEs and any OAuth-capable client | Clients without OAuth support, and scripts | The personal token must be created with the **MCP** usage. A token created for the **REST API** has the API's audience and is refused here with `401` — and the reverse holds too. ## The workspace[​](#the-workspace "Direct link to The workspace") The token's `org` names the organization; the **workspace** each tool acts on is decided **on every call**, in this order: | Order | Where it comes from | | ----- | ------------------------------------------------------------ | | 1 | The tool's `workspace_id` argument, when the call carries it | | 2 | The connection's default workspace (below) | | — | Neither: the tool returns the `workspace_required` error | The server URL needs no workspace — `https://mcp.finance.kobana.com.br` is enough —, and connecting never fails for lack of one. To learn where it can act, the agent calls `finance_workspaces_list`, with no arguments: it lists the organization's workspaces the token's person can reach. ``` { "data": [ { "id": "2b93f876-769a-4bdc-b23e-304957f313b4", "name": "Matriz", "default": true }, { "id": "7c1d0e52-…", "name": "Filial Sul", "default": false } ] } ``` Every other tool — except `finance_me`, `finance_organization_get`/`_update` (organization-level: they hold for the whole organization), `finance_schemas_get` and `finance_workspaces_list` itself — takes the optional `workspace_id` argument (uuid): ``` { "name": "finance_payables_list", "arguments": { "workspace_id": "2b93f876-769a-4bdc-b23e-304957f313b4", "limit": 10 } } ``` ### The default workspace[​](#the-default-workspace "Direct link to The default workspace") It applies when the call carries no `workspace_id`, and it is the one marked `default: true` in `finance_workspaces_list`: | Where | Example | | -------------------------------------- | ---------------------------------------------------------------- | | `X-Workspace-Id` header (optional) | `X-Workspace-Id: 2b93f876-769a-4bdc-b23e-304957f313b4` | | Parameter on the server URL (optional) | `https://mcp.finance.kobana.com.br/?workspace_id=2b93f876-…` | | Neither | The only workspace the person reaches, if they reach exactly one | The header and the URL parameter are still accepted, but they are now **optional and only set the default**: the `workspace_id` argument always wins over them. In every case the value is a **selector, not a grant** — it is checked against the token's organization and the person's access: * With no `workspace_id` and no default — the person reaches several workspaces —, the tool returns `workspace_required`. It is a tool result with `isError: true`, not an HTTP error: ``` { "error": { "code": "workspace_required", "message": "…" } } ``` * A `workspace_id` the person cannot reach, or that does not exist, returns the tool error `workspace_access_denied` — the same answer either way. * A header or URL parameter naming a workspace of another organization is still refused with HTTP `403` `UNKNOWN_WORKSPACE`. * A connection default that belongs to the organization but that the person cannot reach blocks nothing: `tools/list` still lists what they can run in some workspace, and a call with a valid `workspace_id` runs. Only a call that relies on that default comes back `workspace_access_denied`. Resources (`kobana://finance/…`) and completions have no workspace argument: they use the connection's default. Without one, reading a record resource fails with `workspace_required` — use the tools —, and completions suggest nothing. See [Resources and prompts](https://docs.finance.kobana.com.br/en/en/mcp/overview/resources-and-prompts.md). ## The OAuth flow[​](#the-oauth-flow "Direct link to The OAuth flow") You run none of these steps: the MCP client (Claude, ChatGPT, an IDE) does everything on its own from the URL. They are here for when something fails midway. 1. **Challenge.** A request without a token gets `401` with the challenge every OAuth 2.1 resource server must send ([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. **Resource metadata.** The client reads the document it points to. It is public and carries no secret — only pointers: ``` 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` is exactly what the client asks for on the consent screen: one `finance/{resource}` per Smart Finance resource — the money ones included (`finance/payable_dispatches`, `finance/receivable_charges`) — and every access level the Kobana Account issues: `read`, `write`, `delete`, `import` and `export`. You decide, level by level, what to grant. The token the client receives carries the approved resources, so they define its reach (see axis 1 below). Only the resource catch-all stays out, `finance/all` or `all` (the two are the same). `resource_name` is the product name, and `kobana_scopes` gives, for each Smart Finance resource scope (`finance/all` included), the text the Kobana Account shows on the consent screen, in Portuguese. An MCP client does not need to read these two members. 3. **Authorization server metadata** ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)), at `https://account.kobana.com.br/.well-known/oauth-authorization-server`. 4. **Dynamic client registration** ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)). The client registers itself; the consent screen warns that it is not a verified app. 5. **Authorization with PKCE and `resource`** ([RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707)). You sign in to Kobana, pick the organization (if you have more than one) and authorize. 6. **Token.** The client exchanges the code for a short-lived access token and sends it on every request from then on, renewing it when it expires. The token carries who you are (`sub`) and the organization you authorized (`org`); the workspace comes from each call, as above. No tool takes an organization as an argument. ## Two authorization axes[​](#two-authorization-axes "Direct link to Two authorization axes") What a caller sees is **narrower** than the catalogue, through two independent filters. Neither can *widen* the surface. ### Axis 1 — the token's scope[​](#axis-1--the-tokens-scope "Direct link to Axis 1 — the token's scope") The client's ceiling, in the `scope` claim. Each tool requires **one** access level — the same one the API endpoint it calls requires: reading (read tools, resources, prompts and completions) requires `read`; the delete tools (`*_delete`) require `delete`; everything else that changes data requires `write` — including `finance_attachments_unlink`, which undoes a link and deletes nothing, and the tools that move money. No level stands in for another: `write` does not delete, and `delete` does not write. **Token with resources** — the case of the OAuth flow token and of the personal token. The resources define how far the token reaches, and the levels apply only inside them: | Token scope | Result | | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance/payables finance/people read write` | Reads and writes payables and people — does not delete, and reaches nothing else | | `finance/payables read write delete` | Reads, writes and deletes payables | | `finance/payables read` | Only reads payables | | `finance/all read` | Reads everything, writes nothing | | `finance/all write` | Reads and writes everything, sending to the bank and charging included (the catch-all reaches the money resources) — but does not delete | | `finance/payables finance/payable_dispatches read write` | Writes payables and sends them to the bank — through the MCP, only with a token of up to 24 hours: see [Moving money through the MCP](#moving-money-through-the-mcp) | Sending to the bank and charging are `write` on their own resource — `finance/payable_dispatches` and `finance/receivable_charges`; `finance/payables write` is not enough. **Token without resources** — a token that only carries the access level, with no `finance/…` scope and no `all` (or only another app's resources), **reaches nothing**: only `finance_me` answers. `all` is not a level: it is the resource catch-all, like `finance/all` — alone it only reads, and verbs come explicit (`all write`). :::info Clients connected through the OAuth flow reach what you approved The `/.well-known/oauth-protected-resource` document announces every Smart Finance resource and every access level, and that is what the client (Claude, ChatGPT, the MCP Inspector, IDEs) asks for on the consent screen; the token it receives carries the resources and levels you approved. The MCP lists only the tools the token reaches; a tool outside it comes back `insufficient_scope`, and the way out is to authorize again granting the missing access — `delete` to delete, the money resource to send to the bank or charge. ::: The same rule applies to the REST API — see [Scopes](https://docs.finance.kobana.com.br/en/en/api/overview/authentication.md#scopes). ### Axis 2 — the permissions of the token's person[​](#axis-2--the-permissions-of-the-tokens-person "Direct link to Axis 2 — the permissions of the token's person") The token's `sub` is the person who consented. **In MCP, the tools are narrowed to what that person can do in the organization's dashboard**, resolved on every request — the same roles and permissions as the **Members** screen. | Situation | Result | | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | The person never signed in to Smart Finance, or is not a member of the organization | **Denies every tool.** Someone who is not a member reaches nothing through MCP. | | Active member, with access to the workspace | Their permissions, tool by tool. The owner (`*`) unlocks everything; `payables.*` unlocks the family. | | Active member **without access to the workspace** | **Denies every tool** in that workspace. | | Member suspended, with a pending invitation, removed, or with no permission at all | **Denies every tool.** A token outliving the person's access is exactly the case to close. | | The permission lookup fails | **Denies every tool.** Fail closed. | Permissions are read on every call: removing a permission in the dashboard takes effect on the very next tool, without waiting for the token to expire. :::tip Recommended posture for agents Connect the assistant with an account that holds only the permissions the agent needs, and, on a personal token, check only the resources and access it will use. The two axes add up: a read-only analyst's token exposes only the read tools, whatever the model on the other side does. ::: ### How the two compose[​](#how-the-two-compose "Direct link to How the two compose") The final set is the **intersection**: `tools ∩ token scopes ∩ the person's permissions`. A tool the caller cannot run **is not listed**. When `tools/call` refuses, the code says **who fixes it**: | Code | Who fixes it | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `insufficient_scope` | Use a token that reaches the resource with the requested access — for example, a personal token with write on that resource. | | `insufficient_permission` | An organization admin, granting the permission (the error names it). | | `workspace_required` | The agent passes `workspace_id` — one of the `id`s from `finance_workspaces_list` —, or the connection sets a [default workspace](#the-default-workspace). | | `workspace_access_denied` | An admin grants the person the workspace, or the agent passes another `workspace_id`. | | `membership_inactive` | Add the person to the organization or reactivate them — no permission fixes a membership that does not exist or is inactive. | | `token_not_accepted` | The tool moves money and the token lives longer than 24 hours (every personal token): connect through the OAuth flow, or move money through the REST API or the app — see [Moving money through the MCP](#moving-money-through-the-mcp). Or the call is destructive and the token was verified by the temporary pinned key: connect through the OAuth flow or with a personal token. | :::caution What axis 2 does not cover Narrowing by permission applies **to MCP only**. An API token, called directly on `api.finance.*`, is still bounded only by its scopes. ::: ### Security › Channels[​](#security--channels "Direct link to Security › Channels") The [Security › Channels](https://docs.finance.kobana.com.br/en/en/seguranca/.md#channels) rules still apply on top of both axes — the endpoint itself enforces them. An AI agent acts through the **MCP - Artificial Intelligence** channel, where, by default, **sending to the bank starts closed**: `finance_payables_send_to_bank` only works once the request has been approved. **Charge** — issuing a bank slip or Pix charge to a customer — also starts closed for the MCP. And a bill the agent creates, or whose amount, beneficiary, account or payment details it changes, goes to the **payment approval** queue even with approval turned off in the workspace: an instruction hidden in an invoice or an e-mail does not become an official payment without a person approving it. ## Personal token revocation[​](#personal-token-revocation "Direct link to Personal token revocation") Revoking a personal token on your Kobana Account **does not cut access immediately**: Smart Finance verifies the token on its own, without asking Kobana on every call, and the token is still accepted until it expires. So: * pick the **shortest validity** the use allows; * check only the **resources and access** the agent needs; * to cut off an agent immediately, suspend or remove the person in the organization, or take away their access to the workspace — permissions are read on every call and take effect at once. ### Moving money through the MCP[​](#moving-money-through-the-mcp "Direct link to Moving money through the MCP") Since revocation does not reach here before expiry, the tools that move money — `finance_payables_send_to_bank`, `finance_payables_cancel_dispatch`, `finance_receivables_charge` and `finance_receivables_charge_cancel` — only appear and only run with a **short-lived** token: at most **24 hours** between issue and expiry. They also require `write` on the money resource (`finance/payable_dispatches`, `finance/receivable_charges`), or the `write` level on a token without per-resource scopes. In practice: a client connected through the **OAuth flow** (a short-lived token the client renews) moves money if you approved the money resource and `write` on the consent screen — and every call still goes through the server's confirmation and the [Security › Channels](#security--channels) rules. A **personal token** lives at least 7 days and never moves money through the MCP (the tool comes back `token_not_accepted`): use the OAuth flow, the [REST API](https://docs.finance.kobana.com.br/en/en/api/overview/authentication.md#scopes) or the app. ## Failure modes[​](#failure-modes "Direct link to Failure modes") | HTTP | `code` | Cause | | ---- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `-32022` (JSON-RPC) | Unsupported protocol version, in the `MCP-Protocol-Version` header or in `_meta`; `data.supported` lists the supported ones. See [Transport](https://docs.finance.kobana.com.br/en/en/mcp/overview/transport.md#protocol-versions). | | 401 | `invalid_token` / `token_expired` / `token_revoked` | Token missing, malformed, invalid, issued for another resource (the API, for example) or for more than one audience (`invalid_token`); expired (`token_expired`); revoked (`token_revoked`). | | 401 | `invalid_request` | A credential in the URL (`?access_token=`, `?token=`, `?api_key=` and the like), even alongside a valid header. | | 403 | `UNKNOWN_ORGANIZATION` / `UNKNOWN_WORKSPACE` | The token's `org` is not a customer, or the workspace in `X-Workspace-Id` / `?workspace_id=` is not the organization's. | | 403 | `ORGANIZATION_SUSPENDED` | The token's organization is suspended or inactive. Nothing goes through, not even reads, until Kobana reactivates it. | | 403 | `FORBIDDEN` | `Origin` outside the allow-list (`origin_not_allowed`). | | 404 | `NOT_FOUND` | The request arrived through a host that does not serve MCP, or asked for a path the server does not have. | | 429 | `RATE_LIMITED` | Rate limit reached — see [Rate limit](https://docs.finance.kobana.com.br/en/en/mcp/overview/rate-limit.md). | | 503 | `SERVICE_UNAVAILABLE` | The Kobana Account did not respond to validate the token. It is not a token problem: try again after `Retry-After`. | Every `401` carries the `WWW-Authenticate` challenge above, which sends the client back to the OAuth flow. In the challenge every token failure shows as `error="invalid_token"` — the body's `code` is what tells an expired token from a revoked one —, and a credential in the URL as `error="invalid_request"`. Scope and permission denials are **not** HTTP errors: they come back as a tool result flagged `isError`, so the model reads them and reacts — see [Errors](https://docs.finance.kobana.com.br/en/en/mcp/overview/errors.md). ## Host and edge[​](#host-and-edge "Direct link to Host and edge") The endpoint is reachable only through `mcp.finance.*` — never through the app host nor the API host, which point at the same origin. Any other path answers `404`, always as JSON and for every method — `{ "error": { "code": "NOT_FOUND", "message": "Not found." } }`, never an HTML page. The OAuth resource identifier is derived from the **server configuration**, never from the request's `Host`, so a forged `Host` cannot steer a client to another identifier. --- # Clients Any client that speaks **Streamable HTTP** MCP and can run the MCP **OAuth 2.1** flow can connect. You only provide the URL and the client discovers on its own where to authenticate, opens the Kobana login in the browser and stores the token. See [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). A client without OAuth support connects too, with a **personal token**: create it under **Kobana Account → Tokens and Access → New Personal Token**, with the **Smart Finance** app and the **MCP** usage, and configure the client to send it in the `Authorization: Bearer ` header. The URL carries no workspace. The agent picks where to act on every call: `finance_workspaces_list` lists the workspaces you reach, and the other tools take `workspace_id` (except the organization-level ones, such as `finance_me` and `finance_organization_get`/`_update`, which take no workspace). If you reach only one, not even that is needed. To pin a **default workspace** on the connection, add `?workspace_id=` to the URL or, when the client allows it, the `X-Workspace-Id` header — both are optional. See [Authentication → The workspace](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md#the-workspace). ## Claude Code[​](#claude-code "Direct link to Claude Code") ``` claude mcp add --transport http kobana-finance https://mcp.finance.kobana.com.br ``` Then run `/mcp` in a session and pick **Authenticate** to sign in to Kobana. To set a default workspace — optional —, use the URL with it: ``` claude mcp add --transport http kobana-finance \ "https://mcp.finance.kobana.com.br/?workspace_id=$WORKSPACE_ID" ``` With a personal token, without the OAuth flow: ``` claude mcp add --transport http kobana-finance https://mcp.finance.kobana.com.br \ --header "Authorization: Bearer " ``` ## File-configured clients[​](#file-configured-clients "Direct link to File-configured clients") Clients that read a JSON configuration file ask for the URL and the transport. Through the OAuth flow, there is no authentication header: ``` { "mcpServers": { "kobana-finance": { "type": "http", "url": "https://mcp.finance.kobana.com.br" } } } ``` On the first connection the client opens the browser for you to authorize. You pick the organization on the consent screen, and it is recorded in the token; the workspace comes from each call (or from the default, if you put `?workspace_id=` on the URL). With a personal token, add the headers — the organization is the one of the account where you created the token: ``` { "mcpServers": { "kobana-finance": { "type": "http", "url": "https://mcp.finance.kobana.com.br", "headers": { "Authorization": "Bearer " } } } } ``` For a default workspace, add `"X-Workspace-Id": ""` to `headers` — optional. Treat the file as a secret: whoever reads it uses the token. ## Clients that connect by URL[​](#clients-that-connect-by-url "Direct link to Clients that connect by URL") Claude and ChatGPT connect a remote server by pasting the URL — `https://mcp.finance.kobana.com.br`, nothing else — into their connector settings. The OAuth flow runs inside the app itself, and the assistant discovers the workspaces on its own, with `finance_workspaces_list`. ## Using Billing alongside[​](#using-billing-alongside "Direct link to Using Billing alongside") This server's tools start with `finance_`, and those of [Automatic Billing](https://docs.billing.kobana.com.br) with `billing_`; the resources, with `kobana://finance/` and `kobana://billing/`. Both servers live in the same client without collisions — connect both when the agent needs both ends. ## Recommended posture for agents[​](#recommended-posture-for-agents "Direct link to Recommended posture for agents") * **Authorize with the right account.** MCP narrows the tools to what the person who authorized can do in the dashboard. A client authorized by a read-only analyst exposes only the read tools, whatever the model on the other side does. It is the strongest way to restrict an agent. * **One token per client.** Each client runs its own flow and gets its own token, which only works on the MCP — it cannot be used to call the REST API. To switch off an agent, remove its authorization on Kobana without affecting your integrations. * **Personal token: short validity and minimum scope.** Check only the resources and access the agent needs, and the shortest validity the use allows: revoking the token on Kobana does not cut access before it expires — see [Personal token revocation](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md#personal-token-revocation). An agent that records bills does not need `finance/payable_dispatches`. Through the MCP no token moves money today — neither a personal one nor the OAuth flow's: see [Moving money through the MCP](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md#moving-money-through-the-mcp). * **Keep the MCP channel closed for paying and charging.** By default, [Security › Channels](https://docs.finance.kobana.com.br/en/en/seguranca/.md#channels) does not let AI agents send to the bank or issue charges. Open it only on purpose. * **Start in sandbox.** The server asks for confirmation on destructive tools, but the first exploration should not be in production. * **Destructive tools need a client that confirms.** Deleting, sending to the bank, charging, transferring, reconciling or adjusting a balance asks for your approval: in any client, the tool returns a link you open signed in to Kobana Finance to choose **Continue** or **Cancel**. Everything else works as usual. See [Confirming destructive tools](https://docs.finance.kobana.com.br/en/en/mcp/overview/resources-and-prompts.md#confirming-destructive-tools). ## Checking the connection[​](#checking-the-connection "Direct link to Checking the connection") The simplest way is to ask the assistant: "which workspaces can you act on?" — it calls `finance_workspaces_list`. Then, "which companies exist in the Matriz workspace?" calls `finance_companies_list` with its `workspace_id`. With a token issued for the MCP — a personal token with the **MCP** usage, for example —, you can check with `curl`: ``` # How many tools does this token reach? 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' # The workspaces the token's person reaches 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":{}}}' # The companies of one 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"]}}}' ``` If the number of tools is lower than you expected, it is the permissions of whoever authorized or the token's scope — see [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). It is not an error. --- # Endpoints ## MCP server[​](#mcp-server "Direct link to MCP server") On the same domain as the API, with the `mcp` prefix: | Environment | MCP server URL | REST API | | ----------- | ------------------------------------------- | ---------------------------------------------- | | Production | `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` | The server URL is the **host root** — that is the address you paste into an MCP client, nothing else: the workspace is picked on every call, through the tools' `workspace_id` argument. `?workspace_id=` is still accepted, but it only sets a default workspace for the connection — see [Authentication → The workspace](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md#the-workspace). The root is also the OAuth *resource identifier*, which is why it carries no path. ## Routes served[​](#routes-served "Direct link to Routes served") | Method | Path | Purpose | | -------- | --------------------------------------- | ------------------------------------------------------------------- | | `POST` | `/` | One JSON-RPC message per request. The whole tool surface. | | `GET` | `/.well-known/oauth-protected-resource` | Protected-resource metadata (RFC 9728). Public, unauthenticated. | | `GET` | `/` | `405` — this server is stateless and opens no server→client stream. | | `DELETE` | `/` | `204` — there is no session to end. | tip Each environment has its own database and authorization server: a token issued in sandbox does not work in production. Start in sandbox: the destructive tools delete bills and send payments to the bank for real. :::info A separate host, on purpose The MCP server has its own host instead of a path on the API or app host. The OAuth discovery document has to live at the host root, and no dashboard cookie is ever sent to this origin — which rules out, by construction, a whole class of *confused deputy* problems. ::: ## Local development[​](#local-development "Direct link to Local development") In development the endpoint answers at `/mcp` on the app host (`http://localhost:3029/mcp`), and the discovery document at `/.well-known/oauth-protected-resource`. In sandbox and production, outside `mcp.finance.*`, the endpoint answers `404`. --- # Errors Failures arrive through **two different channels**, and the distinction matters: one is a broken request, the other is something the model should read and react to. ## Tool errors[​](#tool-errors "Direct link to Tool errors") Everything the caller can act on — validation, not found, missing scope or permission, an endpoint error — comes back as a **successful JSON-RPC response** whose result is flagged `isError`, carrying the API's own error envelope as text: ``` { "jsonrpc": "2.0", "id": 2, "result": { "isError": true, "content": [{ "type": "text", "text": "{ \"error\": { \"code\": \"NOT_FOUND\", \"message\": \"Payable not found.\" } }" }] } } ``` The `code` vocabulary is [the API's](https://docs.finance.kobana.com.br/en/en/api/overview/errors.md), unchanged. The ones you will meet most: | `code` | When | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `VALIDATION_ERROR` | The body failed the endpoint's validation; `details.issues[]` names each field. Also when the tool's own arguments (id, filters) do not match its schema — including `limit`, `cursor`, `sort_by` or `fields` inside `filters`, which are named arguments; then `details` carries no `issues[]` but `{ "formErrors": [...], "fieldErrors": { "": [...] } }` — `formErrors` for what belongs to no single argument (an unknown argument, for instance), `fieldErrors` per argument. | | `BAD_REQUEST` | Unknown filter, operator or `fields` name. | | `NOT_FOUND` | No such record, or it belongs to another workspace. | | `CONFLICT` | A duplicate, or a record still in use. | | `UNPROCESSABLE_ENTITY` | A business rule — deleting a category that has children, settling a title with no account. | | `SECURITY_BLOCKED` | The Security tab blocked the action on this channel. | | `ENTITLEMENT_REQUIRED` | The workspace has no contracted plan and the tool is an effective-use one (send to bank, issue a charge); `details.reason` says `no_plan`. Contracting fixes it, retrying does not. | | `RATE_LIMITED` | The API budget of this person in the organization ran out — see [Rate limit](https://docs.finance.kobana.com.br/en/en/mcp/overview/rate-limit.md). | And the five MCP adds itself, because they are about *authorization*, not about the resource: | `code` | Who fixes it | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `insufficient_scope` | The token's scope does not reach the tool: the resource is not in the token, or the access level the tool requires is missing — `write` to change data (moving money included, on the money resource), `delete` to delete. Use a token that reaches the resource with the requested access: through the OAuth flow, authorize again granting the missing access. | | `token_not_accepted` | The token does not serve this tool: it moves money and the token lives longer than 24 hours (every personal token) — move money through the REST API or the app —, or the call is destructive and the token was verified by the temporary pinned key — connect through the OAuth flow or with a personal token. | | `insufficient_permission` | An organization admin, granting the permission the error names. | | `workspace_access_denied` | The `workspace_id` is not one the person reaches (or does not exist). An admin grants the person the workspace, or the agent passes another one, from `finance_workspaces_list`. | | `membership_inactive` | Add the token's person to the organization or reactivate them — no permission fixes a membership that does not exist or is inactive. | They are separate **on purpose**: five different conversations, with different people. A single error would say "you can't" without saying whom to ask. See [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). There is also `workspace_required`: the call carried no `workspace_id` and the connection has no default workspace — the person reaches several. The agent calls `finance_workspaces_list` and repeats the call with one of the `id`s. See [Authentication → The workspace](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md#the-workspace). And the ones from [confirming destructive tools](https://docs.finance.kobana.com.br/en/en/mcp/overview/resources-and-prompts.md#confirming-destructive-tools) — in all of them, nothing was changed: | `code` | When | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `confirmation_required` | A destructive tool called by a client that cannot confirm, with a token that has no person behind it — no one could open an approval link. With a person, the tool returns the link (`status: approval_required`) — see [Approval by link](https://docs.finance.kobana.com.br/en/en/mcp/overview/resources-and-prompts.md#approval-by-link). | | `USER_DECLINED` | On `2026-07-28`, the person declined or cancelled the confirmation. | | `confirmation_replayed` | The resent confirmation already ran the tool once. Call again without `requestState` to ask anew. | | `confirmation_unavailable` | The server could not guarantee the confirmation at that moment. Try again later. | | `confirmation_subject_unreadable` | The tool moves money and the question shows the record, but the token's person cannot read it. An admin grants the read permission the error names. | ### `input_required` is not an error[​](#input_required-is-not-an-error "Direct link to input_required-is-not-an-error") On `2026-07-28`, the first `tools/call` of a destructive tool may come back with `resultType: "input_required"` and a confirmation request for the person. That is the normal flow, not a failure: the client shows the question and resends the same call with the answer. See [Confirming destructive tools](https://docs.finance.kobana.com.br/en/en/mcp/overview/resources-and-prompts.md#confirming-destructive-tools). ## Protocol errors[​](#protocol-errors "Direct link to Protocol errors") A malformed message gets a JSON-RPC error object, not a result: | Code | Meaning | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `-32700` | Parse error — the body is not valid JSON | | `-32600` | Invalid request — not a JSON-RPC object, or an array (batching is not supported) | | `-32601` | Method not found | | `-32602` | Invalid params — unknown tool, prompt or argument, missing `name`; on `2026-07-28`, also resource not found | | `-32002` | Resource not found — only on 2025 (`2026-07-28` uses `-32602`) | | `-32603` | Internal error — unexpected failure running the tool | | `-32020` | Header mismatch — on `2026-07-28`, an `MCP-Protocol-Version`, `Mcp-Method` or `Mcp-Name` header that does not match the body (HTTP `400`) | | `-32022` | Unsupported protocol version — the requested version is not supported; `data.supported` lists the supported ones (HTTP `400`) | ## Transport errors[​](#transport-errors "Direct link to Transport errors") Refusals that happen **before** the JSON-RPC message is read are plain HTTP responses: token missing, invalid, expired, revoked or issued for another resource (`401`, with `code` `invalid_token`, `token_expired` or `token_revoked`), a credential in the URL (`401` `invalid_request`), a default workspace (`X-Workspace-Id` / `?workspace_id=`) from another organization, `Origin` outside the allow-list, protocol rate limit, Kobana Account unavailable to validate the token (`503`), a body above 14 MB (`413`, with the JSON-RPC error `-32600` `Request body too large (limit 14680064 bytes)` and `id: null`). They are listed in [Authentication → Failure modes](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md#failure-modes). ## Why `isError` and not a JSON-RPC error[​](#why-iserror-and-not-a-json-rpc-error "Direct link to why-iserror-and-not-a-json-rpc-error") A `404` on a title is not a defect of the MCP client — it is information about the world, and the model on the other side needs it to correct itself. Burying it in a protocol error would make the client treat it as a transport failure, hide the text and, at best, retry it unchanged. Hence the rule: **if the caller can act, it is a result; if the request is broken, it is an error.** ## Observability[​](#observability "Direct link to Observability") Every `tools/call` writes a structured line with the tool, the workspace, the person, the token type (`oauth` or `personal`), the status and the duration. **Writes** are recorded with the **`mcp`** channel and the token's person, so what an agent did shows up next to what a person did, on the same screens. --- # Idempotency The create and update tools accept an `idempotency_key` argument. It is sent to the endpoint as the `X-Idempotency-Key` header the REST API already honours — see [Idempotency](https://docs.finance.kobana.com.br/en/en/api/overview/idempotency.md) in the API. ``` { "name": "finance_payables_create", "arguments": { "company_id": "…", "description": "November rent", "amount": 4500, "due_date": "2026-11-10T00:00:00Z", "person": { "name": "Downtown Realty" }, "idempotency_key": "7c4a8d09-ca37-4f21-b1f0-3d2f2b8c9a11" } } ``` | | | | -------------------------------- | ------------------------------------------------------------------- | | **Format** | Opaque string, 1 to 255 characters. A UUID is the usual choice. | | **Repeat with the same body** | Returns the original response, without running the operation again. | | **Repeat with a different body** | Conflict (`IDEMPOTENCY_KEY_REUSED`). | Delete tools do not take the argument: the route does not read it, and deleting twice already gives the same result. ## Why an agent needs this more than your backend[​](#why-an-agent-needs-this-more-than-your-backend "Direct link to Why an agent needs this more than your backend") An MCP client that times out and retries, or a model that decides "I'm not sure that worked, let me do it again", is exactly the pattern that creates the second title and the second transaction. Your backend has a retry loop you wrote; the agent has judgement. **Send a key whenever the operation creates something.** A new key is a new attempt; to retry safely, repeat the same one. ## The ones that move money: the key is required[​](#the-ones-that-move-money-the-key-is-required "Direct link to The ones that move money: the key is required") On these four the key is **not optional** — the tool refuses the call without it, like the route: | Tool | What it does | | ----------------------------------- | -------------------------------------------- | | `finance_payables_send_to_bank` | Sends the payment to the bank through Kobana | | `finance_payables_cancel_dispatch` | Cancels the bank dispatch | | `finance_receivables_charge` | Issues a bank slip or Pix to the customer | | `finance_receivables_charge_cancel` | Cancels the charge | A duplicated dispatch is a duplicated payment, and a duplicated charge is a duplicated debt — no `_delete` undoes that. They are also **destructive** tools: the server only runs them after confirming with the person — see [Confirming destructive tools](https://docs.finance.kobana.com.br/en/en/mcp/overview/resources-and-prompts.md#confirming-destructive-tools). --- # Introduction The **Smart Finance MCP server** is a remote [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the public API's operations — payables and receivables, transactions, reconciliations, financial accounts, cash flow and registers — as **tools** an AI client can call. You connect it by URL; there is nothing to install. It is served on its own host, `mcp.finance.kobana.com.br`, on the same domain as the API, with **Streamable HTTP** transport in stateless mode and authentication by a **Bearer token** issued for the MCP by the Kobana Account. No client certificate is involved. :::info Availability The server, its **96 tools**, the resources and the prompts are implemented, and authentication goes through the Kobana authorization server: through the **OAuth 2.1** flow, in which the client gets only the URL and signs in on its own, or through a **personal token** created on your Kobana Account. The endpoint is served by the dedicated `mcp.finance.*` edge, with its own distribution, WAF and DNS. ::: ## When to use it[​](#when-to-use-it "Direct link to When to use it") | | REST API (`/v1`) | MCP server (this) | | -------------- | --------------------------------------- | ----------------------------------------------------------------------------------------- | | Consumer | your backend | an AI client (Claude, ChatGPT, an IDE) | | Setup | token and `X-Workspace-Id`, out of band | just a URL; the workspace goes in each call | | Transport | HTTPS/REST | Streamable HTTP (JSON-RPC 2.0) | | Authentication | Bearer token issued for the API | OAuth 2.1 or personal token, always issued for the MCP | | Authorization | token scope | token scope **and** the person's permissions | | Surface | the `/v1` endpoints | 96 tools, one per operation of those endpoints, plus resources and prompts on top of them | The MCP server **does not replace** the REST API. Each tool dispatches in-process to the endpoint that implements the operation, so filters, validation, settlement rules, rateio and workspace isolation are exactly the same. If you are writing code, use the [REST API](https://docs.finance.kobana.com.br/en/en/api/overview/introduction.md). If you are connecting an assistant, use this. ## The principle[​](#the-principle "Direct link to The principle") **A capability exists in MCP only if it exists in the public API.** Nothing is implemented twice. The tool calls the endpoint's handler with the identity the caller's token has already proven — the same person, the same organization, the same workspace —, so it runs, checks the scope and audits as it would for any HTTP request. A tool does what the endpoint does over REST — never more. In practice: what today exists only in the dashboard (approving payments, importing statements, managing members) does not become a tool before it becomes an endpoint. ## What you see is narrower than the catalogue[​](#what-you-see-is-narrower-than-the-catalogue "Direct link to What you see is narrower than the catalogue") `tools/list` returns only the tools **this caller can run**: the ones the token's scopes reach **and** the token's person is allowed to do in the organization. An agent is not told about capabilities it would only be denied. Both axes are in [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). ## Getting started[​](#getting-started "Direct link to Getting started") 1. **Point your client at the server URL** — `https://mcp.finance.kobana.com.br`, nothing else. See [Endpoints](https://docs.finance.kobana.com.br/en/en/mcp/overview/endpoints.md) and [Clients](https://docs.finance.kobana.com.br/en/en/mcp/overview/clients.md). 2. **Authorize.** The client opens the Kobana login; sign in with an account of the organization and authorize the access. See [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). 3. **Pick the workspace.** The agent calls `finance_workspaces_list` and passes the chosen `id` as `workspace_id` to the other tools. If you reach only one workspace, it is the default and the argument can be left out. See [Authentication → The workspace](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md#the-workspace). 4. **List the tools** to confirm what your access reaches — ask the assistant, or, with a token issued for the MCP in hand: ``` 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. **Browse the catalogue** in [Tools](https://docs.finance.kobana.com.br/en/en/mcp/tools/overview.md). ## Next steps[​](#next-steps "Direct link to Next steps") * [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md) — the OAuth flow, the personal token, the workspace, the scope and permissions applied, and the failure modes. * [Endpoints](https://docs.finance.kobana.com.br/en/en/mcp/overview/endpoints.md) — URLs per environment and the routes served. * [Transport](https://docs.finance.kobana.com.br/en/en/mcp/overview/transport.md) — JSON-RPC, headers and methods. * [Clients](https://docs.finance.kobana.com.br/en/en/mcp/overview/clients.md) — how to connect Claude Code and file-configured clients. * [Listing, filters and fields](https://docs.finance.kobana.com.br/en/en/mcp/overview/pagination.md) — `cursor`, `filters`, `sort_by`, `fields`. * [Idempotency](https://docs.finance.kobana.com.br/en/en/mcp/overview/idempotency.md) — and the actions that move money. * [Resources and prompts](https://docs.finance.kobana.com.br/en/en/mcp/overview/resources-and-prompts.md) — documents by URI, ready-made scripts, autocomplete and the confirmation of destructive tools. * [Errors](https://docs.finance.kobana.com.br/en/en/mcp/overview/errors.md) — the two failure channels, and why the distinction matters. * [Tools](https://docs.finance.kobana.com.br/en/en/mcp/tools/overview.md) — the full catalogue. --- # Listing, Filters and Fields The `*_list` tools use the same pagination as the REST API: **by cursor**. | Argument | Default | Max | | -------- | ------- | ------------------------------------ | | `limit` | `25` | `100` (`10000` on the `*_ids` tools) | | `cursor` | — | — | ``` { "name": "finance_payables_list", "arguments": { "limit": 50 } } ``` The result carries the usual envelope: ``` { "data": [ /* ... */ ], "meta": { "next_cursor": "eyJpZCI6Mn0" } } ``` For the next page, send `meta.next_cursor` as `cursor`, **with the same filters**. `next_cursor: null` means this is the last page. See [Listing and pagination](https://docs.finance.kobana.com.br/en/en/api/overview/pagination.md) in the API. ## Filters[​](#filters "Direct link to Filters") `filters` is an object with **exactly** the filters the listing accepts — the tool's `inputSchema` enumerates them, with each one's operators. A filter or operator outside the list is refused before it reaches the endpoint. Pagination, sort and columns (`limit`, `cursor`, `sort_by`, `sort_order`, `fields` — and `page`, `per_page` and `sort`, from other APIs) are **named arguments**: inside `filters` they are refused with `VALIDATION_ERROR`, naming the keys, and never override the argument. | Form | Means | Becomes | | --------------------------------------------------------- | --------- | --------------------------------- | | `"status": "pending"` | equals | `?status=pending` | | `"status": ["pending", "paid"]` | is in | `?status[in]=pending,paid` | | `"due_date": { "gte": "2026-11-01", "lt": "2026-12-01" }` | operators | `?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" } } ``` The full grammar is in [Filtering and sorting](https://docs.finance.kobana.com.br/en/en/api/overview/filtering.md). ## Sorting[​](#sorting "Direct link to Sorting") | Argument | Values | Default | | ------------ | ---------------------------------------------------------------------- | ------------------- | | `sort_by` | One of the columns the listing sorts by (the `inputSchema` lists them) | varies per resource | | `sort_order` | `asc` or `desc` | `asc` | ## Fields (`fields`)[​](#fields-fields "Direct link to fields-fields") The record-read tools accept `fields`, an array of column names. Omitted, the whole record comes back; given, only those: ``` { "name": "finance_payables_list", "arguments": { "filters": { "status": "pending" }, "fields": ["description", "amount", "due_date"] } } ``` | Rule | Why | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **`id` always comes back** | A projection you cannot follow up on is useless, and silently dropping `id` would break the next call, not this one. | | **Top level only** | `fields: ["reconciliation"]` returns the whole object; there is no `reconciliation.kind` syntax. | | **Record reads only** | Writes return the whole record; totals, `*_ids` and download do not offer the argument. | | **An unknown name is an error** | `400` with `details.unknown` and `details.available`. Ignoring it would return fewer fields than asked, looking as if the record does not have them. | It is the same [`?fields=` as the API](https://docs.finance.kobana.com.br/en/en/api/overview/fields.md). And it is the cheapest way to reduce the context an agent spends. ## `finance_schemas_get` — the field catalogue[​](#finance_schemas_get--the-field-catalogue "Direct link to finance_schemas_get--the-field-catalogue") `fields` is only useful if you know what to ask for. `finance_schemas_get` answers from the published contract's schemas: ``` { "name": "finance_schemas_get", "arguments": {} } { "name": "finance_schemas_get", "arguments": { "schema": "PayableV1" } } ``` With no argument it returns the catalogue; with `schema`, that schema's fields — name, type, enum, nullability and description. It is the same OpenAPI that generates the [API reference](https://docs.finance.kobana.com.br/en/en/api/overview/introduction.md). ## Data contract[​](#data-contract "Direct link to Data contract") What holds for the API holds here, because it is the same code: * **snake\_case everywhere**, arguments and responses. * **Money is a number in BRL**, with up to 2 decimals: `1500.5` is R$ 1,500.50. Titles and transactions are always positive — direction comes from the type, not the sign. * **Dates in ISO 8601.** * **Writes accept `idempotency_key`** — see [Idempotency](https://docs.finance.kobana.com.br/en/en/mcp/overview/idempotency.md). --- # Rate Limit The MCP server spends **the same limits as the REST API**, counted **per person in the organization** — not per token —, plus a limit of its own for the protocol. Minting a new token, or re-authorizing the client, does not reset the budget. | Budget | What counts | Limit (production) | | -------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | MCP protocol | every request to `/` (`initialize`, `tools/list`, `ping`, `tools/call`) | 1000/hour per person in the organization | | API reads | every `tools/call` of a **read** tool | the [API's](https://docs.finance.kobana.com.br/en/en/api/overview/rate-limit.md) | | API writes | every `tools/call` of a **write** or **destructive** tool | the [API's](https://docs.finance.kobana.com.br/en/en/api/overview/rate-limit.md) | | Money-moving actions | `send_to_bank`, `cancel_dispatch`, `charge`, `charge_cancel` | the [API's](https://docs.finance.kobana.com.br/en/en/api/overview/rate-limit.md) | A tool call is **never cheaper than the endpoint it mirrors**: it is counted against the protocol budget and, again, against the API budget the same REST call would spend — with the same budget size as the API, per person. An agent sweeping listings in a loop does not get around the limit the same sweep would pay over REST. There is also a per-IP ceiling, far above any legitimate use. ## When the limit is reached[​](#when-the-limit-is-reached "Direct link to When the limit is reached") **On the protocol**, the server answers `429` and the JSON-RPC message is not processed at all: ``` 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." } } ``` **On the API budget**, the tool returns an error result, for the model to read and wait: ``` { "isError": true, "content": [{ "type": "text", "text": "{ \"error\": { \"code\": \"RATE_LIMITED\", \"details\": { \"retry_after_seconds\": 37 } } }" }] } ``` Either way, wait the indicated seconds before trying again. ## Spending less[​](#spending-less "Direct link to Spending less") An agent consumes the same budget as your backend — and, for reads, that budget is small. Three habits cover almost everything: * **Filter before paging.** `finance_payables_list { filters: { status: "pending", due_date: { lte: "2026-11-30" } } }` costs one call; fetching everything to filter in the model costs dozens. * **Use the ready-made totals.** "How much is due this month" is one call to `finance_payables_aggregates`, not a sweep of `finance_payables_list`. * **Ask only for the columns you need.** `fields` does not reduce the number of calls, but it greatly reduces the context spent — see [Listing, filters and fields](https://docs.finance.kobana.com.br/en/en/mcp/overview/pagination.md). --- # Resources and prompts Besides the tools, the server offers three things the **client** uses on its own: **resources** (documents you attach to the conversation), **prompts** (ready-made scripts you pick) and **completions** (autocomplete for the arguments of both). On `2026-07-28`, it also asks for **confirmation** before running a destructive tool — including the ones that move money. None of this opens a new path to your data: everything goes through the same tools, under the same permissions and the same [access level](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). Every resource and every prompt here only reads, so a `read` token reaches all of them — as long as the person can run the tools behind them. ## Resources[​](#resources "Direct link to Resources") A resource is a document identified by a URI. You pick, for example, a payable, and the client reads the record and puts it in the context, without the model having to call a tool. The URIs live under `kobana://finance/`, so they coexist with those of other Kobana products in the same client. | URI | What comes back | | ------------------------------------------------------------------ | ------------------------------------------------------- | | `kobana://finance/schemas` | The catalogue of the API contract's schemas (JSON) | | `kobana://finance/schemas/{schema}` | One schema: the fields a tool returns or accepts (JSON) | | `kobana://finance/payables/{id}` | A payable (JSON) | | `kobana://finance/receivables/{id}` | A receivable (JSON) | | `kobana://finance/financial-transactions/{id}` | A transaction (JSON) | | `kobana://finance/financial-accounts/{account_id}` | A financial account (JSON) | | `kobana://finance/financial-accounts/{account_id}/balances/latest` | The account's most recent recorded balance (JSON) | | `kobana://finance/people/{id}` | A person — supplier, customer or both (JSON) | | `kobana://finance/companies/{id}` | A company in the workspace (JSON) | | `kobana://finance/fiscal-documents/{id}` | A received fiscal document (JSON) | | `kobana://finance/attachments/{attachment_id}` | An attachment's data and what it is linked to (JSON) | | `kobana://finance/attachments/{attachment_id}/download` | The attachment's file — receipt, bank slip, XML | `resources/list` returns the fixed URIs and `resources/templates/list` the parameterized templates. * **Permissions.** Each resource is read by the matching tool (`kobana://finance/payables/{id}` is `finance_payables_get`). It only shows up, and is only read, if you can run that tool. * **Files.** An attachment's file comes back as base64 bytes (`blob`), or as text when it is text (an XML), up to **10 MB**. Unlike the tool, which only describes the file, here the document is the answer: the client asked for it. * **Not found.** An unknown URI, or a record that does not exist in this workspace, is `-32002` on 2025 and `-32602` on `2026-07-28` — see [Errors](https://docs.finance.kobana.com.br/en/en/mcp/overview/errors.md). * **Workspace.** The URI carries no workspace: the resource is read in the [connection's default workspace](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md#the-default-workspace). Without a default — the person reaches several workspaces and the connection did not pin one —, reading a record resource fails with the JSON-RPC error `-32602`, with `data.code: "workspace_required"` and a hint; use the tools, which take `workspace_id`. The schema catalog does not depend on a workspace. * **No change subscriptions.** The server is stateless: there is no `resources/subscribe` nor a list-changed notice. ## Prompts[​](#prompts "Direct link to Prompts") A prompt is a ready-made instruction you pick in the client that becomes the first message of the conversation. It only shows up if you can run **all** the tools it relies on. None of them moves money, edits or deletes: sending to the bank or charging is left for you to ask for explicitly. | Prompt | Arguments | What it does | | --------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------- | | `overdue_payables` | `company_id` (optional) | Lists the overdue payables still open, oldest first, with the total due. | | `overdue_receivables` | `person_id` (optional) | Lists the overdue receivables and groups them by customer, largest totals first. | | `cash_flow_outlook` | `until` (optional, `YYYY-MM-DD`; default: 90 days) | Today's balance and where cash is heading, week by week, with the lowest point. | | `monthly_summary` | `month` (optional, `YYYY-MM`) | What was paid, received and left open in the month. | | `person_overview` | `person_id` | A supplier or customer: their data and what is open on each side. | A missing required argument, or a `month`/`until` in the wrong format, is `-32602`. ## Completions[​](#completions "Direct link to Completions") `completion/complete` suggests values as you type an argument: * **Ids** (`person_id`, `company_id`, `account_id` and the parameter of the record templates): the most recent records from the matching listing, by the typed prefix, under the same permission as that listing. If you cannot list, there is no suggestion. The records come from the connection's default workspace; without one, the list comes back empty. * **`{schema}` of `kobana://finance/schemas/{schema}`**: the contract's names, by prefix. * **`month`**: the last twelve months. With no source of suggestions, the answer is an empty list, and you keep typing. ## Confirming destructive tools[​](#confirming-destructive-tools "Direct link to Confirming destructive tools") Tools that delete, cancel, send a payment to the bank, charge, transfer between accounts, reconcile or adjust a balance are flagged with `destructiveHint`. A client may or may not ask for confirmation because of it — so the **server** requires your approval, and a destructive tool only runs with it. On every protocol revision and in any client, a destructive tool returns an **approval link** (see [Approval by link](#approval-by-link)) — even in a client that declares form elicitation, because some clients declare it and never show the form, which would leave the call hanging with nothing recorded. The question in the conversation is only the fallback for when no approval can be recorded (a token with no person behind it) and the client speaks `2026-07-28` with form elicitation: 1. The first `tools/call` runs nothing. It comes back with `resultType: "input_required"` and a one-question form: run this action, with these arguments? 2. The client shows the question and resends the same call with your answer. 3. Only an explicit **yes** runs it. Declining or cancelling returns an `isError` result with `USER_DECLINED`, and nothing changes. Two tools are destructive only depending on their arguments: `finance_payables_update` asks for confirmation when the call sets `status` to `paid` or `cancelled`, and `finance_receivables_update` when it sets it to `received` or `cancelled`. Both are announced with `destructiveHint`, but any other change through them runs without a question. For the tools that move money, the question shows **the record the action acts on**, read by the server: amount, due date, beneficiary, Pix key, bank account, barcode. If the bill changes between the question and the **yes** — the Pix key swapped, for instance — the yes does not count and the server asks again, with the new data. If the token's person cannot read the record, the tool returns `confirmation_subject_unreadable` and nothing runs. The confirmation protects against an agent fooled by third-party text — an instruction hidden in a description or an e-mail. It does **not** replace the scope, the token lifetime, the permissions and the Channels tab: whoever holds the token can write a client that answers yes on its own. The confirmation applies **only to that call** and **only once**: the same tool, the same arguments, the same person, organization and workspace, for **5 minutes**. An answer cannot be reused for another bill or another action; if anything does not match, the server simply asks again. Resending a confirmation that already ran the tool returns `confirmation_replayed` — to repeat the action, call the tool again without `requestState` and confirm again. **Without a way to approve or ask, the tool does not run.** With no person behind the token there is no one to open the link, and the server can only ask on `2026-07-28`, to clients that declare support for elicitation forms (`elicitation: {}` or `elicitation: { form: {} }` in `clientCapabilities`). Otherwise, a `tools/call` of a destructive tool returns `isError` with `confirmation_required` and nothing is changed — reads and ordinary writes keep running. If the server itself cannot guarantee the confirmation at that moment, the answer is `confirmation_unavailable`, also changing nothing. ## Approval by link[​](#approval-by-link "Direct link to Approval by link") This is the path of every destructive tool called by a token with a person behind it, on any revision and in any client — with or without form elicitation. The destructive tool **does not run**: the server records the operation as pending and answers, as a normal result (no `isError`), a JSON text: ``` { "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." } ``` The assistant shows the URL. You open it **signed in to Kobana Finance** (if you are not, the app asks you to sign in and comes back to it), check what will happen — amount, beneficiary, source account and balance on the money tools, the affected record on the others, and every argument — and choose: * **Continue**: the operation runs right away, once, with the recorded arguments and **your permissions as they are now**. If you lost the permission in the meantime, or the app's access was revoked, it fails and nothing changes. * **Cancel**: nothing runs. The link is valid for **15 minutes** and decides **only once**. Only you can open it: for anyone else, even in your organization, it does not exist. Your approvals are listed under **System › Approvals**; clicking one opens what was requested, read-only. ### Checking the outcome[​](#checking-the-outcome "Direct link to Checking the outcome") The assistant is not notified when you decide. After you say you decided, it reads the outcome with `finance_operation_approvals_get`, passing the answer's `approval.id` — once, without calling it over and over. `finance_operation_approvals_list` lists your approvals in the call's workspace, most recent first (`status`, `created_after`, `created_before`, `page`, `per_page`; it returns `{ data, meta: { total, page, per_page, total_pages } }`). ``` { "data": { "id": "…", "status": "executed", "action": "finance_categories_delete", "title": "Delete the category", "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` (confirmed, being processed), `executed`, `failed`, `declined` (cancelled) or `expired` — a pending one past its deadline already comes back as `expired`. * `title`: what the operation does, in the language of the connection's `Accept-Language` header (Portuguese, English or Spanish; Portuguese without it). * `error`: `{ code, message }` when `failed`. `result`: what the operation returned when `executed`, with secrets (tokens, keys, passwords) masked — the clear value is shown once, on the screen. * The link, its token and the arguments are never returned. Any token with a person behind it and some Smart Finance resource scope (`finance/…` or `all`) reads its **own** approvals; there is no resource scope or permission of their own. But `error`, `result` and an amount read from the record are data of the operation's resource: they come back only when the token reads that resource and you **still** have permission to read it in the workspace (losing that permission after the operation hides the result) (for example `finance/categories` with `read` for deleting a category; for money operations — sending to the bank, charging — the money resource and the bill's together: `finance/payable_dispatches` with `finance/payables`, `finance/receivable_charges` with `finance/receivables`). Without it the approval comes with its status, title and dates, `error` and `result` set to `null` and `"result_hidden": true`; an amount the assistant itself sent in the arguments still shows. Another person's approval, another organization's, another workspace's or an id that does not exist all return the same `NOT_FOUND`. Both tools only read: none approves, cancels or reopens anything. A token with no person behind it has no one to open the link and still gets `confirmation_required`. --- # Transport **Streamable HTTP, stateless.** One JSON-RPC 2.0 message per `POST`, one JSON response. There is no `Mcp-Session-Id`, no resumability and no server→client stream: the application runs several replicas, and no operation needs to push messages to the client. ## Protocol versions[​](#protocol-versions "Direct link to Protocol versions") The server speaks two eras of the protocol on the same endpoint: | Version | Era | Status | | ------------ | ------------------------------------------------------------------------------- | --------- | | `2026-07-28` | Stateless, no handshake — discovery through `server/discover` | Supported | | `2025-06-18` | Handshake through `initialize` — the version `initialize` settles on by default | Supported | | `2025-03-26` | Handshake through `initialize` | Supported | The era is decided **by the body** of the request, with the headers as a cross-check: * **`params._meta` carries `io.modelcontextprotocol/protocolVersion`** → `2026-07-28` era (see below). * **Without that envelope**, with a 2025 `MCP-Protocol-Version` or no header at all → 2025 era, with `initialize`. * **`MCP-Protocol-Version: 2026-07-28` without the envelope** → `400` with `-32602`. The server does not silently fall back to the old era: you asked for the stateless semantics and would get the other one. A version the server does not speak — in the header or in the envelope, in either era — is answered `400` with the JSON-RPC error `-32022`, listing the supported ones: ``` { "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" } } } ``` The version in use comes back in the response's `MCP-Protocol-Version` header. ### The `2026-07-28` era[​](#the-2026-07-28-era "Direct link to the-2026-07-28-era") There is no handshake: **every** request carries its own version and the client's capabilities in `params._meta`, and the server remembers nothing between one request and the next. | `params._meta` key | Required | Meaning | | -------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `io.modelcontextprotocol/protocolVersion` | yes | `2026-07-28` | | `io.modelcontextprotocol/clientCapabilities` | yes | The client's capabilities (an object; `{}` will do). Destructive tools return an approval link with or without form `elicitation` — see [confirmation of destructive tools](https://docs.finance.kobana.com.br/en/en/mcp/overview/resources-and-prompts.md#confirming-destructive-tools) | | `io.modelcontextprotocol/clientInfo` | recommended | The client's `name` and `version` | The headers repeat what is in the body, so intermediaries can route without reading it — and that is why they must agree with it: | Header | Must equal | | ---------------------- | ----------------------------------------------------------------- | | `MCP-Protocol-Version` | The envelope's version | | `Mcp-Method` | The message's `method` | | `Mcp-Name` | Only on `tools/call`: the `params.name`, raw or as `=?base64?…?=` | Any mismatch is `400` with `-32020` (`Header mismatch: …`). A missing `clientCapabilities` is `400` with `-32602`. Results in this era always carry `resultType: "complete"` and the server in `_meta["io.modelcontextprotocol/serverInfo"]`. `server/discover`, `tools/list`, `resources/list`, `resources/templates/list`, `resources/read` and `prompts/list` also carry `ttlMs: 0` and `cacheScope: "private"`: what comes back is filtered by the caller's scope and permissions, so it must not be reused or shared. A `tools/call` of a destructive tool may come back with `resultType: "input_required"` — see [Confirming destructive tools](https://docs.finance.kobana.com.br/en/en/mcp/overview/resources-and-prompts.md#confirming-destructive-tools). ## Request headers[​](#request-headers "Direct link to Request headers") | Header | Required | Meaning | | ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | yes | `Bearer ` issued for the MCP — see [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md) | | `X-Workspace-Id` | no | The connection's default workspace, used when the tool gets no `workspace_id` — the same as `?workspace_id=` on the URL. See [Authentication → The workspace](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md#the-workspace) | | `Content-Type` | yes | `application/json` | | `Accept` | recommended | `application/json` | | `MCP-Protocol-Version` | yes in the `2026-07-28` era; recommended in the 2025 one | Protocol revision | | `Mcp-Method` | yes in the `2026-07-28` era | The message's method | | `Mcp-Name` | yes on `tools/call` in the `2026-07-28` era | The tool name | | `Origin` | conditional | Sent by browser clients; checked against an allow-list | ## Response headers[​](#response-headers "Direct link to Response headers") | Header | Meaning | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `MCP-Protocol-Version` | Revision in use | | `Cache-Control` | `no-store` on every response, error responses included (`400`, `401`, `403`, `404`, `405`, `413`, `429`, `503`) and the `204` of `DELETE`. Only the `/.well-known/oauth-protected-resource` document, public and the same for everyone, uses `public, max-age=300` | | `Content-Security-Policy` | `default-src 'none'` on every response, the metadata document's included — the server only returns JSON | | `Retry-After` | On `429` — see [Rate limit](https://docs.finance.kobana.com.br/en/en/mcp/overview/rate-limit.md) — and on `503` | ## Methods[​](#methods "Direct link to Methods") | Method | `2026-07-28` era | 2025 era | Purpose | | -------------------------- | ---------------- | -------- | ---------------------------------------------------------------------------- | | `server/discover` | yes | — | Supported versions, server capabilities and instructions | | `initialize` | — | yes | Version negotiation, server capabilities and instructions | | `ping` | — | yes | Liveness check; answers an empty result | | `tools/list` | yes | yes | The tools this caller can run, with JSON Schema and annotations | | `tools/call` | yes | yes | Runs a tool | | `resources/list` | yes | yes | The fixed-URI documents this caller can read | | `resources/templates/list` | yes | yes | The URI templates (`kobana://finance/payables/{id}`, …) this caller can read | | `resources/read` | yes | yes | Reads a document by URI | | `prompts/list` | yes | yes | The ready-made scripts this caller can use | | `prompts/get` | yes | yes | Builds a script with the given arguments | | `completion/complete` | yes | yes | Suggestions for a prompt or template argument | Resources, prompts and completions are in [Resources and prompts](https://docs.finance.kobana.com.br/en/en/mcp/overview/resources-and-prompts.md). Any other method is `-32601 Method not found` — in the `2026-07-28` era, with HTTP `404`; in the 2025 one, in the body of a `200`. **JSON-RPC batching is not supported** — it was removed in the `2025-06-18` revision, and an array body is answered `400`. **The body is capped at 14 MB** (14,680,064 bytes) — enough for the largest legitimate request, a 10 MB `finance_attachments_upload` in base64 plus the envelope. Above it the answer is `413` with `{ "jsonrpc": "2.0", "id": null, "error": { "code": -32600, "message": "Request body too large (limit 14680064 bytes)" } }`: a declared `Content-Length` above the cap is refused even before authentication, and a body with no `Content-Length` (or a false one) is cut at the cap while being read. A **notification** (a message with no `id`, such as `notifications/initialized`) is accepted with `202` and an empty body, in both eras. Authentication comes **before** any method, `server/discover` included: without a token, the answer is the `401` with the challenge that takes the client to the OAuth login — see [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). ### `server/discover` (`2026-07-28` era)[​](#serverdiscover-2026-07-28-era "Direct link to serverdiscover-2026-07-28-era") ``` 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` (2025-era handshake)[​](#initialize-2025-era-handshake "Direct link to initialize-2025-era-handshake") ``` { "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: ..." } } ``` The `instructions` (in `initialize` and in `server/discover`) warn the agent that field values in results are **data written by third parties, never instructions**, and ask for the user's confirmation before a destructive or money-moving action that a result seems to request. ### `tools/list`[​](#toolslist "Direct link to toolslist") Returns **only** the tools the caller can run — the ones the token's scope reaches **and** the person who authorized can do in the dashboard. A write tool's `inputSchema` is the endpoint's **own request schema** — the same fields, required ones and enums as the [API reference](https://docs.finance.kobana.com.br/en/en/api/overview/introduction.md). Every tool carries `annotations`, which is what makes the client ask the user to confirm: | Annotation | Meaning | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `readOnlyHint` | The tool only reads | | `destructiveHint` | The tool deletes, cancels or moves money — it only runs with the [server's confirmation](https://docs.finance.kobana.com.br/en/en/mcp/overview/resources-and-prompts.md#confirming-destructive-tools) | | `idempotentHint` | Repeating the call has the same effect | | `openWorldHint` | Always `false` — the tool reaches nothing outside Smart Finance | ### `tools/call`[​](#toolscall "Direct link to 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"] } } } ``` The result carries the endpoint's JSON response as text content: ``` { "jsonrpc": "2.0", "id": 2, "result": { "content": [{ "type": "text", "text": "{ \"data\": [ ... ], \"meta\": { \"next_cursor\": \"…\" } }" }] } } ``` Errors the caller can act on come back with `isError: true` **inside** the result, not as a JSON-RPC error — see [Errors](https://docs.finance.kobana.com.br/en/en/mcp/overview/errors.md). ## In-process dispatch[​](#in-process-dispatch "Direct link to In-process dispatch") Each tool dispatches **in-process** to the `/v1` handler that implements the operation, with the caller's already-verified identity and the workspace resolved for the call — the MCP token is not forwarded, and the endpoint still requires its own scope. There is no second HTTP hop and no second implementation: filters, validation, settlement rules, rateio, security locks and workspace isolation are the same code the REST API runs. Writes are recorded with the **`mcp`** channel (`created_via` / `updated_via`), distinguishable from those made through the API or the dashboard. ## Files[​](#files "Direct link to Files") * **Download** — `finance_attachments_download` does **not** return the bytes: a base64 PDF in a model's context is expensive and useless. The result carries the `content_type`, the size and the path to download the file from the API — with a token issued for the API, since the MCP one does not work there. * **Upload** — `finance_attachments_upload` takes the file in `content_base64` (up to 10 MB) and sends it to the endpoint as `multipart/form-data`. Then `finance_attachments_link` attaches it to a title or transaction. --- # Financial accounts and cash flow Financial accounts, the computed balance and the balances each source observed, the bank catalogue, the cash-flow projection, and credit cards with their statements, launches and recurrences, and the IOF rates. ## Families on this page[​](#families-on-this-page "Direct link to Families on this page") | Family | Tools | read | write | destructive | | ------------------------------------------------------ | ----- | ---- | ----- | ----------- | | `financial_accounts` — Financial accounts and balances | 10 | 4 | 3 | 3 | | `banks` — Banks | 1 | 1 | 0 | 0 | | `cash_flow` — Cash flow | 1 | 1 | 0 | 0 | | `credit_cards` — Credit cards | 5 | 2 | 2 | 1 | | `card_statements` — Card statements | 9 | 3 | 2 | 4 | | `card_transactions` — Card transactions | 8 | 3 | 3 | 2 | | `card_recurrences` — Card recurrences | 5 | 2 | 2 | 1 | | `iof_rates` — IOF rates | 1 | 1 | 0 | 0 | ## `financial_accounts`[​](#financial_accounts "Direct link to financial_accounts") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | -------------------------------------------- | ----------- | -------- | ------------------ | ------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `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 "Direct link to banks") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | -------------------- | ---- | ------ | --------------- | ---------- | --------------- | ----------------------------------------------------------------------------------------- | | `finance_banks_list` | read | `read` | `finance/banks` | — (none) | `GET /v1/banks` | The Brazilian bank catalog (COMPE/BACEN codes) — use it to find `bank_id` for an account. | ## `cash_flow`[​](#cash_flow "Direct link to cash_flow") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ----------------------- | ---- | ------ | ------------------- | ---------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Direct link to credit_cards") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ----------------------------- | ----------- | ------- | ---------------------- | --------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `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 "Direct link to card_statements") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ----------------------------------------- | ----------- | -------- | ---------------------- | ------------------------ | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Direct link to card_transactions") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | -------------------------------------- | ----------- | -------- | ---------------------- | -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Direct link to card_recurrences") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | --------------------------------- | ----------- | -------- | ---------------------- | -------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Direct link to iof_rates") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ------------------------ | ---- | ------ | ---------------------- | ---------- | ------------------- | ------------------------------------------------------------------------------- | | `finance_iof_rates_list` | read | `read` | `finance/credit_cards` | — (none) | `GET /v1/iof-rates` | List the IOF rates with their validity (global and this workspace's overrides). | *** The fields of each resource are in the [API reference](https://docs.finance.kobana.com.br/en/en/api/overview/introduction.md) and in `finance_schemas_get`. A tool you cannot run is not listed by `tools/list` at all. If one from this page is missing, see [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). --- # Payables and receivables The titles: create, update, settle, cancel and delete payables and receivables, the totals per period, send a payment to the bank and issue a charge (bank slip or Pix). ## Families on this page[​](#families-on-this-page "Direct link to Families on this page") | Family | Tools | read | write | destructive | | --------------------------- | ----- | ---- | ----- | ----------- | | `payables` — Payables | 10 | 4 | 1 | 5 | | `receivables` — Receivables | 10 | 4 | 1 | 5 | ## `payables`[​](#payables "Direct link to payables") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ---------------------------------- | ------------- | -------- | ---------------------------- | ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `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 "Direct link to receivables") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ----------------------------------- | ------------- | -------- | ---------------------------- | -------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `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. | *** The fields of each resource are in the [API reference](https://docs.finance.kobana.com.br/en/en/api/overview/introduction.md) and in `finance_schemas_get`. A tool you cannot run is not listed by `tools/list` at all. If one from this page is missing, see [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). --- # Attachments, fiscal documents, schemas and workspaces Files attached to records, received fiscal documents, `finance_schemas_get` — the catalogue of the fields each tool returns, i.e. what to ask for in `fields` — and `finance_workspaces_list`, the workspaces the other tools' `workspace_id` comes from — and `finance_me`, the identity behind the connection's token — and `finance_organization_get`/`_update`, the token's organization — and `finance_operation_approvals_get`/`_list`, the outcome of the operations you approved through the link. ## Families on this page[​](#families-on-this-page "Direct link to Families on this page") | Family | Tools | read | write | destructive | | ---------------------------------------------- | ----- | ---- | ----- | ----------- | | `attachments` — Attachments | 7 | 3 | 2 | 2 | | `fiscal_documents` — Received fiscal documents | 2 | 2 | 0 | 0 | | `schemas` — Field catalogue | 1 | 1 | 0 | 0 | | `workspaces` — Workspaces | 1 | 1 | 0 | 0 | | `me` — Identity | 1 | 1 | 0 | 0 | | `organization` — Organization | 2 | 1 | 1 | 0 | | `operation_approvals` — Approvals by link | 2 | 2 | 0 | 0 | ## `attachments`[​](#attachments "Direct link to attachments") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ------------------------------ | ----------- | -------- | --------------------- | ---------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `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 "Direct link to fiscal_documents") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ------------------------------- | ---- | ------ | -------------------------- | ----------------------- | ------------------------------- | ---------------------------------------------------------------------------------- | | `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 "Direct link to schemas") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | --------------------- | ---- | ------ | ----- | ---------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `finance_schemas_get` | read | `read` | — | — (none) | — (local) | Describe a schema of the Finance API contract: the fields a tool returns (`PayableDetailV1`, `FinancialTransactionV1`…) or accepts. | ## `workspaces`[​](#workspaces "Direct link to workspaces") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ------------------------- | ---- | ------ | ----- | ---------- | --------- | -------------------------------------------------------- | | `finance_workspaces_list` | read | `read` | — | — (none) | — (local) | List the workspaces of this organization you can act on. | ## `me`[​](#me "Direct link to me") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ------------ | ---- | ---- | ----- | ---------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_me` | read | — | — | — (none) | — (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 "Direct link to organization") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ----------------------------- | ----- | ------- | ------------------ | ----------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Direct link to operation_approvals") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ---------------------------------- | ---- | ------ | ----- | ---------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_operation_approvals_get` | read | `read` | — | — (none) | — (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` | — | — (none) | — (local) | List the operation approvals you asked for in this workspace, most recent first, with the same fields as finance\_operation\_approvals\_get. | *** The fields of each resource are in the [API reference](https://docs.finance.kobana.com.br/en/en/api/overview/introduction.md) and in `finance_schemas_get`. A tool you cannot run is not listed by `tools/list` at all. If one from this page is missing, see [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). --- # Tools The server exposes **148 tools** over **30 resource families**. Each one dispatches in-process to the `/v1` endpoint that already implements the operation, so filters, validation, settlement rules and workspace isolation are exactly the REST API's — the tool *is* the endpoint. The exceptions, `finance_schemas_get` (the published contract), `finance_workspaces_list` (the workspaces the person can reach), `finance_me` (the token's identity) and `finance_operation_approvals_get`/`_list` (your approvals by link), answer locally. `finance_organization_get`/`_update` go to the endpoint, but are organization-level: like `finance_me`, they take no workspace. Every other tool takes `workspace_id`. ## How to read these pages[​](#how-to-read-these-pages "Direct link to How to read these pages") Every tool carries six facts: > `finance_payables_send_to_bank` · **destructive** · verb `write` · scope `finance/payable_dispatches` · permission `payables.dispatch` · `POST /v1/payables/{id}/send-to-bank` | Field | Meaning | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **read** / **write** / **destructive** | The annotation the MCP client reads. A `destructive` one runs only after the server asks the person to confirm — on a client that cannot ask, the tool returns a link for you to confirm in the app. See [Confirming destructive tools](https://docs.finance.kobana.com.br/en/en/mcp/overview/resources-and-prompts.md#confirming-destructive-tools). | | **destructive\*** | Destructive on some calls only: the `*_update` that settles or cancels the title (`status` `paid`/`received`/`cancelled`). Only that call asks for confirmation; other updates run directly. | | **verb** | The access level the token must carry: `read`, `write`, `delete`, `import` or `export`. None stands in for another — `write` does not delete. `—` when the tool needs no scope (only `finance_me`). | | **scope** | The resource the token must reach: `finance/` or `finance/all` (or `all`, the same thing). It applies to a token that carries `finance/…` scopes (an OAuth client's); a token with only an access level, no `finance/…` scope and no `all`, reaches nothing. Sending to the bank and charging are `write` on the money resources (`finance/payable_dispatches`, `finance/receivable_charges`) — see [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). | | **permission** | The permission the token's person must hold in the organization — the same the action requires in the dashboard. | | **`METHOD /path`** | The `/v1` endpoint the tool dispatches to, to cross-reference with the [API reference](https://docs.finance.kobana.com.br/en/en/api/overview/introduction.md). The token needs the scope that endpoint requires. | ## Common arguments[​](#common-arguments "Direct link to Common arguments") These appear across many tools and always mean the same thing. | Argument | Type | Description | | ----------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `limit` | integer | Page size. Default `25`, max `100` (`10000` on the `*_ids` tools). | | `cursor` | string | The previous page's `meta.next_cursor`. `null` there means the last page. | | `filters` | object | The filters the listing accepts: a scalar is equality, an array is `in`, an object picks operators (`{ "gte": …, "lt": … }`). | | `sort_by` | enum | Sort column, among the ones the listing accepts. | | `sort_order` | `asc` \| `desc` | Direction. Default `asc`. | | `fields` | string\[] | Columns to return. Omit for the whole record; `id` always comes back. | | `idempotency_key` | string | Replay guard, sent as `X-Idempotency-Key`. Required on the money-moving actions. | | `custom_metadata` | object | Free-form JSON owned by you, echoed on every read. | ## The catalogue[​](#the-catalogue "Direct link to The catalogue") | Family | Tools | read | write | destructive | | ------------------------------------------------------------------------------------------------------------------------ | ----- | ---- | ----- | ----------- | | [`payables` — Payables](https://docs.finance.kobana.com.br/en/en/mcp/tools/billings.md) | 10 | 4 | 1 | 5 | | [`receivables` — Receivables](https://docs.finance.kobana.com.br/en/en/mcp/tools/billings.md) | 10 | 4 | 1 | 5 | | [`financial_transactions` — Transactions](https://docs.finance.kobana.com.br/en/en/mcp/tools/transactions.md) | 11 | 5 | 2 | 4 | | [`transfers` — Transfers](https://docs.finance.kobana.com.br/en/en/mcp/tools/transactions.md) | 2 | 1 | 0 | 1 | | [`reconciliations` — Reconciliations](https://docs.finance.kobana.com.br/en/en/mcp/tools/transactions.md) | 3 | 1 | 0 | 2 | | [`receipts` — Receipts](https://docs.finance.kobana.com.br/en/en/mcp/tools/transactions.md) | 2 | 2 | 0 | 0 | | [`financial_accounts` — Financial accounts and balances](https://docs.finance.kobana.com.br/en/en/mcp/tools/accounts.md) | 10 | 4 | 3 | 3 | | [`banks` — Banks](https://docs.finance.kobana.com.br/en/en/mcp/tools/accounts.md) | 1 | 1 | 0 | 0 | | [`cash_flow` — Cash flow](https://docs.finance.kobana.com.br/en/en/mcp/tools/accounts.md) | 1 | 1 | 0 | 0 | | [`credit_cards` — Credit cards](https://docs.finance.kobana.com.br/en/en/mcp/tools/accounts.md) | 5 | 2 | 2 | 1 | | [`card_statements` — Card statements](https://docs.finance.kobana.com.br/en/en/mcp/tools/accounts.md) | 9 | 3 | 2 | 4 | | [`card_transactions` — Card transactions](https://docs.finance.kobana.com.br/en/en/mcp/tools/accounts.md) | 8 | 3 | 3 | 2 | | [`card_recurrences` — Card recurrences](https://docs.finance.kobana.com.br/en/en/mcp/tools/accounts.md) | 5 | 2 | 2 | 1 | | [`iof_rates` — IOF rates](https://docs.finance.kobana.com.br/en/en/mcp/tools/accounts.md) | 1 | 1 | 0 | 0 | | [`companies` — Companies](https://docs.finance.kobana.com.br/en/en/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`people` — People](https://docs.finance.kobana.com.br/en/en/mcp/tools/registers.md) | 6 | 3 | 2 | 1 | | [`categories` — Categories](https://docs.finance.kobana.com.br/en/en/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`classification_centers` — Classification centers](https://docs.finance.kobana.com.br/en/en/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`custom_classifiers` — Custom classifiers](https://docs.finance.kobana.com.br/en/en/mcp/tools/registers.md) | 8 | 2 | 4 | 2 | | [`taxes` — Taxes](https://docs.finance.kobana.com.br/en/en/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`automatic_rules` — Automatic rules](https://docs.finance.kobana.com.br/en/en/mcp/tools/registers.md) | 6 | 2 | 3 | 1 | | [`ai_agents` — AI agents](https://docs.finance.kobana.com.br/en/en/mcp/tools/registers.md) | 9 | 3 | 4 | 2 | | [`ai_skills` — AI skills](https://docs.finance.kobana.com.br/en/en/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`attachments` — Attachments](https://docs.finance.kobana.com.br/en/en/mcp/tools/documents.md) | 7 | 3 | 2 | 2 | | [`fiscal_documents` — Received fiscal documents](https://docs.finance.kobana.com.br/en/en/mcp/tools/documents.md) | 2 | 2 | 0 | 0 | | [`schemas` — Field catalogue](https://docs.finance.kobana.com.br/en/en/mcp/tools/documents.md) | 1 | 1 | 0 | 0 | | [`workspaces` — Workspaces](https://docs.finance.kobana.com.br/en/en/mcp/tools/documents.md) | 1 | 1 | 0 | 0 | | [`me` — Identity](https://docs.finance.kobana.com.br/en/en/mcp/tools/documents.md) | 1 | 1 | 0 | 0 | | [`organization` — Organization](https://docs.finance.kobana.com.br/en/en/mcp/tools/documents.md) | 2 | 1 | 1 | 0 | | [`operation_approvals` — Approvals by link](https://docs.finance.kobana.com.br/en/en/mcp/tools/documents.md) | 2 | 2 | 0 | 0 | A tool you cannot run is not listed by `tools/list` at all. If one from this page is missing, see [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). --- # Registers What classifies titles and transactions: companies, people, categories, classification centers, custom classifiers, taxes and the automatic classification rules — and the AI agents, instructions the assistant runs on its own on a schedule, and the AI skills, instructions it loads when a task calls for them. ## Families on this page[​](#families-on-this-page "Direct link to Families on this page") | Family | Tools | read | write | destructive | | ------------------------------------------------- | ----- | ---- | ----- | ----------- | | `companies` — Companies | 5 | 2 | 2 | 1 | | `people` — People | 6 | 3 | 2 | 1 | | `categories` — Categories | 5 | 2 | 2 | 1 | | `classification_centers` — Classification centers | 5 | 2 | 2 | 1 | | `custom_classifiers` — Custom classifiers | 8 | 2 | 4 | 2 | | `taxes` — Taxes | 5 | 2 | 2 | 1 | | `automatic_rules` — Automatic rules | 6 | 2 | 3 | 1 | | `ai_agents` — AI agents | 9 | 3 | 4 | 2 | | `ai_skills` — AI skills | 5 | 2 | 2 | 1 | ## `companies`[​](#companies "Direct link to companies") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | -------------------------- | ----------- | -------- | ------------------- | ------------------ | --------------------------- | -------------------------------------------- | | `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 "Direct link to people") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ----------------------- | ----------- | -------- | ---------------- | --------------- | ------------------------ | ---------------------------------------------------------------- | | `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 "Direct link to categories") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | --------------------------- | ----------- | -------- | -------------------- | ------------------- | ---------------------------- | ----------------------------------------------------------------- | | `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 "Direct link to classification_centers") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | --------------------------------------- | ----------- | -------- | ---------------------- | --------------------- | ---------------------------------------- | ----------------------------------------------------------------------- | | `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 "Direct link to custom_classifiers") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ------------------------------------------ | ----------- | -------- | ---------------------------- | --------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `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 "Direct link to taxes") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ---------------------- | ----------- | -------- | --------------- | -------------- | ----------------------- | --------------------------------------------------------------- | | `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 "Direct link to automatic_rules") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | --------------------------------- | ----------- | -------- | ------------------------- | ------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `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 "Direct link to ai_agents") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ---------------------------------- | ----------- | -------- | ------------------- | ------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Direct link to ai_skills") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | -------------------------- | ----------- | -------- | ------------------- | ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | *** The fields of each resource are in the [API reference](https://docs.finance.kobana.com.br/en/en/api/overview/introduction.md) and in `finance_schemas_get`. A tool you cannot run is not listed by `tools/list` at all. If one from this page is missing, see [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). --- # Transactions and reconciliation The realised side: each account's transactions, transfers between accounts, reconciling titles against transactions, and payment receipts. ## Families on this page[​](#families-on-this-page "Direct link to Families on this page") | Family | Tools | read | write | destructive | | --------------------------------------- | ----- | ---- | ----- | ----------- | | `financial_transactions` — Transactions | 11 | 5 | 2 | 4 | | `transfers` — Transfers | 2 | 1 | 0 | 1 | | `reconciliations` — Reconciliations | 3 | 1 | 0 | 2 | | `receipts` — Receipts | 2 | 2 | 0 | 0 | ## `financial_transactions`[​](#financial_transactions "Direct link to financial_transactions") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ----------------------------------------------------------- | ----------- | -------- | ------------------------- | ------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Direct link to transfers") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | -------------------------- | ----------- | ------- | ---------------------- | ------------------- | --------------------------------- | -------------------------------------------------------------------------------------------- | | `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 "Direct link to reconciliations") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | -------------------------------- | ----------- | -------- | ------------------------- | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------- | | `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 "Direct link to receipts") | Tool | Kind | Verb | Scope | Permission | Endpoint | What it does | | ----------------------- | ---- | ------ | ------------------ | --------------- | ----------------------- | ------------------------------------------------------- | | `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. | *** The fields of each resource are in the [API reference](https://docs.finance.kobana.com.br/en/en/api/overview/introduction.md) and in `finance_schemas_get`. A tool you cannot run is not listed by `tools/list` at all. If one from this page is missing, see [Authentication](https://docs.finance.kobana.com.br/en/en/mcp/overview/authentication.md). --- # My profile **My profile** (`/profile`) shows your account information. It is the **only internal destination in the user menu** — the avatar in the top right corner. ![My profile](/en/assets/images/20-profile-8d7da5c9d80d605c59fd2762a86e5823.png) ## What the screen shows[​](#what-the-screen-shows "Direct link to What the screen shows") The cards: | Card | Content | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **Profile** | Name and email, as they came from the sign-in, plus the active workspace. With no selection, it shows *"No workspace selected"* | | **Preferences** | Theme (light, dark or the system's) and language — the same controls as the header, somewhere you can go looking for them | | **Organizations** | Only for members of two or more organizations: what each one is called in the selector — see below | | **Notifications** | **Receive the Daily agenda** by email | | **Getting Started** | Turns the **Getting Started** item in the sidebar on and off | note **Who you are is not editable here.** Name and email come from the sign-in, and there is no password — see below for why. What the screen does keep are preferences: theme, language, the organization names in the selector, the Daily agenda and whether Getting Started is shown. ## Organization names in the selector[​](#organization-names-in-the-selector "Direct link to Organization names in the selector") Members of two or more organizations see the **Organizations** card. There you give each organization the name you want to see in the header selector and in the organization choice when you sign in — "Samsung" instead of the full legal name, for example. * **The name is yours alone.** Other members keep seeing the name they gave, or the official one. * **The official name doesn't change here.** It comes from your Kobana account and shows as the title of each field. * **A blank field goes back to the official name** — clear it and click **Save**. * **The selector updates right away**, with no need to sign out and back in. ## How you sign in[​](#how-you-sign-in "Direct link to How you sign in") **This product does not use passwords.** There are two paths, and neither asks for one — but they are not interchangeable: * **Sign in with Kobana** — this is the front door. Your Kobana account authenticates you, and it is how anyone without access to Smart Finance arrives. * **Magic link** — you give your email and get a single-use sign-in link, valid for **15 minutes**. **It only works for someone who already has access**: an email that has not been granted anything receives no link at all. note **The email form may not be on the sign-in screen.** Some environments leave only **"Sign in with Kobana"**. The magic link still works for whoever already uses it — it simply stops being offered. That is why there is no password to register, no password to change, and no "forgot my password": the email **is** the identity. The time zone is not configurable here either. ## Signing in is not the same as having access[​](#signing-in-is-not-the-same-as-having-access "Direct link to Signing in is not the same as having access") Authenticating proves **who you are**; getting into the product depends on your having a **workspace**. When the two do not line up, the sign-in works and you stop at a screen that explains why: | Screen | When it appears | What to do | | --------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | **Create your company workspace** | Your Kobana account has no workspace here yet | Check the details and click **Create workspace** | | **You have not been invited yet** | Your company already has a workspace, and your email is not a member of it | Ask an administrator to grant you access | | **Your access is suspended** | You were a member and an administrator paused your access | Talk to whoever administers the account — this is not the same as never having been invited | | **Sign-up unavailable** | Creating new workspaces is switched off in this environment | If your company already uses Smart Finance, ask for an invitation | info **The creation screen is not a form.** Company name and tax ID come from your Kobana account's registration — you check and confirm, typing nothing. That is also why it only appears on the Kobana sign-in: the magic link authenticates an email, not an account, and carries none of that data. tip **If you administer the account on Kobana** and your company's workspace already exists, you get in directly: the sign-in recognizes your administrator role and grants access without an invitation. The exception is having had your access paused — the pause wins. The **Back** button, in the corner, returns to the previous screen. ## Getting there[​](#getting-there "Direct link to Getting there") Click your avatar in the top right corner and choose **My profile**. The top of the menu shows your email, your name and the active workspace, with **Manage account** — which opens your Kobana account in another tab, and only appears in environments where that address is configured. Below it, the menu also offers **Privacy policy**, **Security policy**, **Terms of use**, and **Sign out** — the first three open external pages. ## Switching workspaces[​](#switching-workspaces "Direct link to Switching workspaces") Not here. The card only **shows** which one is active. To switch, use the selector in the application header or the [Workspaces](https://docs.finance.kobana.com.br/en/en/workspaces/.md) screen. --- # Fiscal documents **Documents > Fiscal documents** (`/fiscal-documents`) gathers the *"Notes received against the workspace's companies"* — the NF-e (product) and NFS-e (service) invoices your suppliers issued against your registered CNPJs. They come in automatically through the integrations or by hand, and from here you reconcile them and turn them into bills. note **These are the notes YOU receive, not the ones you issue.** Smart Finance never emits or cancels a fiscal document — it stores, reads and reconciles what arrives. Cancelling or reissuing always belongs to whoever issued the note. ## Where each note comes from[​](#where-each-note-comes-from "Direct link to Where each note comes from") | Origin | How it enters | How it appears | | -------------- | ------------------------------------------------- | ------------------------------------------ | | **nfe.io** | automatic capture of received NFS-e service notes | **Service** notes, ready in the list | | **XML import** | you send the files under **"Import XML"** | a single XML or a ZIP with the whole month | | **SEFAZ** | lookup by access key | the note pulled from SEFAZ by its key | tip **A ZIP with the whole month works.** Under *"Import XML"* you can drop a package with many XMLs at once — anything that already exists is skipped, and only what is new comes in. ## Finding a note[​](#finding-a-note "Direct link to Finding a note") The search box accepts *"Search by key, number or issuer"*. The tabs split by type — *All*, *Service* and *Product* — and the filters narrow what matters: | Filter | What it shows | | -------------------------- | --------------------------------------------- | | **No linked company** | notes whose recipient CNPJ matched no company | | **With generated bill** | notes that already became a payable | | **Without generated bill** | notes not yet turned into a bill | | **Creation date** | when the note entered the workspace | Each note shows its **status** — *Authorized*, *Cancelled* or *Undefined* — and, when only the note's summary is known, the *Summary* marker. info **A summary is a note without the detail.** SEFAZ hands the recipient only the NF-e header until you acknowledge it — no items, no duplicates. A *Summary* note shows up in the list but has no items to check nor installments to turn into bills. ## The linked company[​](#the-linked-company "Direct link to The linked company") A note is tied to a workspace company by the **recipient's CNPJ**. When no registered CNPJ matches, it stays *No linked company* — expected, not an error: the note may have been issued against a CNPJ you have not registered yet, or against a CPF. On the note screen, when there is no link, the **Register company** button opens the company form already filled with the taker's CNPJ; saving it moves the note (and any others waiting for that CNPJ) to the new company. If a company with that CNPJ already exists, the same button links the note to it right away, without opening the form. ## Reading the note[​](#reading-the-note "Direct link to Reading the note") Opening a note shows: * **Provider** and **Customer** — legal name, CNPJ and address on each side. * **Amounts and taxes** — service value, tax base, ISS and the withheld taxes (IRRF, PIS, COFINS, CSLL, INSS), with the net amount. * **Service** (NFS-e) or **Items** (NF-e) — the description and fiscal codes, or the product list. * **Duplicates** and **Payables** — the note's installments and the bills already generated from it. ## Turning it into a payable[​](#turning-it-into-a-payable "Direct link to Turning it into a payable") From the note's duplicates you **generate the payables** — one per installment. Notes with no duplicate use the due date you supply at generation time. What has been generated appears under the note's *Payables* tab, and the *With generated bill* filter separates in the list what has already been converted from what is still pending. ## Downloading the files[​](#downloading-the-files "Direct link to Downloading the files") | Action | What it does | | ---------------- | -------------------------------------------------------------- | | **Copy XML** | copies the note's XML to the clipboard | | **Download XML** | downloads the note's stored XML | | **Download all** | builds a ZIP with the XMLs of every note in the current filter | warning **Not every note keeps a stored XML.** A *Summary* note may have no XML — in that case *"Download XML"* is unavailable and the label reads *"No stored XML"*. ## Through the API[​](#through-the-api "Direct link to Through the API") Fiscal documents are also exposed, **read-only**, on the v1 API under the `finance/fiscal_documents` scope (`read` access level): * [List fiscal documents](https://docs.finance.kobana.com.br/en/en/api/v1/list-fiscal-documents) — a paginated page, with filters by company, kind, status, source, key, number and date. * [Get a fiscal document by id](https://docs.finance.kobana.com.br/en/en/api/v1/get-fiscal-document) — the individual note. The `xml_download_url` the API returns points at the attachments resource, so fetching the XML bytes also requires the `finance/attachments` scope. ## Related[​](#related "Direct link to Related") * [Payment receipts](https://docs.finance.kobana.com.br/en/en/comprovantes/.md) — the proof of a payment that leaves * [Attachments](https://docs.finance.kobana.com.br/en/en/anexos/.md) — where the notes' files are kept * [Payables](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/.md) — what a note turns into * [Integrations](https://docs.finance.kobana.com.br/en/en/integracoes/.md) — the NFS-e capture through nfe.io --- # People People (`/people`) are the customers, suppliers and contacts registered in the workspace. A single record can carry more than one role — customer, supplier, both, or neither — without becoming a duplicate. ![People list](/en/assets/images/09-people-5396781029d5a461423cfda964b831ec.png) ![Person detail](/en/assets/images/10-person-detail-bcde4c552ebae5af747a4b5c5b6f85b8.png) ## The listing[​](#the-listing "Direct link to The listing") Columns: **photo**, **Name**, **Role**, **Document**, **Email** and **Phone** — plus **Registered under**, which only shows in the consolidated view. Each role becomes a badge — **Customer**, **Supplier**, **Account manager**, **Team** — or the text **No role** shows. Above the table sit the **search** (by name or document) and the **Role** filter: **All**, **Customers**, **Suppliers**, **Managers**, **Team** and **No role**. Each row has two actions — **Edit** and **Delete**. The create button is **"New person"**. ## The form[​](#the-form "Direct link to The form") Four tabs: **Identification**, **Contact**, **Address** and **Banking**. ### Identification[​](#identification "Direct link to Identification") | Field | Notes | | ------------------ | ----------------------------------------------------------------------------------------------------------- | | **Name** | Required | | **Nickname** | Optional | | **Legal name** | *"For legal entities — official legal name"* | | **Register under** | **Required** — the company the person is registered under | | **Role** | The **Customer**, **Supplier**, **Account manager** and **Team** checkboxes. Leaving all unchecked is valid | | **Kind** | **Detect automatically** (default), **Natural person** or **Legal entity** | | **CPF** / **CNPJ** | The label and the mask follow the Kind — CPF by default, CNPJ for a legal entity | | **Date of birth** | Optional | **You don't have to pick a Kind.** On the default, the system infers it from the document you type. ### Contact[​](#contact "Direct link to Contact") **Emails** and **Phones**, both as lists — add as many as you need. **Only the email has a label.** Each email takes a free-form label (finance, sales…). Phones have no such field. And **"primary email" is not a concept here** — no email is singled out as the main one. ### Address and Banking[​](#address-and-banking "Direct link to Address and Banking") Two tabs of their own. **Banking** covers bank, branch and account (with check digits), PIX key and key type. ## Roles[​](#roles "Direct link to Roles") | Combination | Typical use | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Customer** | Someone who pays the company | | **Supplier** | Someone the company pays | | **Customer + Supplier** | A partner that both buys and sells | | **Account manager** | A bank manager serving one of the company's accounts — see [Managers](https://docs.finance.kobana.com.br/en/en/contas-financeiras/.md#managers) | | **Team** | The company's own people: partners, finance staff — see [Accesses](https://docs.finance.kobana.com.br/en/en/contas-financeiras/.md#accesses) | | None | A contact with no active financial relationship | The role decides where the person shows up: the **Customer** field on receivables searches customers only; the **Supplier** field on payables, suppliers only. For someone who is or was a manager, the person detail shows **Accounts managed**, with the period of each; for someone with account accesses, **Account accesses**, with the level of each. ## Search and automatic creation[​](#search-and-automatic-creation "Direct link to Search and automatic creation") As you type a name in the payable or receivable form, the system searches the existing records and, finding none, offers to **register the person by that name** — they are created along with the bill on save. The CSV import does the same. ## Profile photo[​](#profile-photo "Direct link to Profile photo") The system looks for the photo in **two** sources, in this order: 1. **Gravatar** — by the registered email. This is the primary source. 2. **WhatsApp** — by the phone number, and only if the integration is configured for the company. This is the **fallback**, used when Gravatar returns nothing. note **No photo appears on its own.** The lookup doesn't run in the background, nor when you save the person: it's a manual tool, under **Maintenance → Fetch photos**. Each run covers **only people who still have no photo**, capped at **100 at a time**, and waits **30 days** before retrying anyone who failed. The photo it finds is **stored** on the record — it isn't fetched again on every visit. The photo shows in the listing and at the top of the person's detail page. ## Transfers and Security[​](#transfers-and-security "Direct link to Transfers and Security") The **Payees** tab in [Security](https://docs.finance.kobana.com.br/en/en/seguranca/.md#payees) decides which payees **transfers (Pix and TED)** can be sent to at the bank. The rule looks at the **CPF/CNPJ**, not the record: * **One rule per document.** The same person registered in several companies shows up only once in Security, and allowing, blocking or limiting applies to every record with that CPF/CNPJ — with the daily and monthly limits added up across companies. * **Registering is not blocked.** In *Block everyone and allow some* mode, a new person can be registered and used on bills as usual; only **sending** transfers to them is held back (*"Beneficiary not allowed"*) until someone requests the document be allowed and Kobana approves. In *Allow everyone and block some* mode, they start allowed. * **Bank slips, taxes and utilities don't go through this rule** — the money goes wherever the barcode says, and the control lives in Operation types. * **Deleting or merging records doesn't change the rule.** A blocked document stays blocked even with no active record (it shows in Security as *"No active record"*), and an allowed one stays allowed. ## Deleting[​](#deleting "Direct link to Deleting") There is a single blocker: **an [automatic rule](https://docs.finance.kobana.com.br/en/en/regras-automaticas/.md) pointing at the person**. While one exists, the delete fails — the rule would go on classifying against someone invisible, and there is nobody to repoint it to. Edit or remove the rule first. **Payables, receivables and transactions don't block.** The dialog shows you what is linked, but lets you delete anyway. danger **Deleting cannot be undone — and that's deliberate.** The person leaves the screens, but their financial history stays intact, still pointing at the deleted record. There is no "restore": once deleted, the **CPF/CNPJ is released**, and nothing stops another record from taking it. That's why coming back isn't offered — it could collide with whoever took the spot. --- # Automatic rules Automatic rules (`/automatic-rules`) classify transactions automatically according to configured criteria, saving you from categorizing recurring documents by hand. ![Automatic rules list](/en/assets/images/14-automatic-rules-602f690dff9e5e6e7089ca9b73f299c8.png) ## Rule scope[​](#rule-scope "Direct link to Rule scope") Each rule has a **fixed scope** (set at creation, **immutable**) and belongs to an **entity**. The scope is a pair of tabs at the top of the form, with no label — the two options are: * **Financial Accounts** — fires on newly created transactions. * **Accounts Payable / Receivable** — fires on newly created bills. ## How it works[​](#how-it-works "Direct link to How it works") When a document is evaluated, the system walks the rules **of the same entity and the same scope**, in precedence order. The **first** active rule whose criteria all match is applied — and only it. The fields set by the rule **overwrite** the document's values, even ones already filled in. ## Criteria[​](#criteria "Direct link to Criteria") A rule combines criteria with **AND** logic — all of them must match. The builder has two sides, **WHEN** (criteria) and **THEN** (actions), with a plain-language preview. | Criterion | How it compares | | ------------------------ | ---------------------------------------- | | **Entity** | Required — the rule's company | | **Account** | Equality (Financial Accounts scope only) | | **Entry type** | **Payments** or **Receipts** | | **Customer/Supplier** | Equality | | **Description contains** | Substring, ignoring case | | **Notes contain** | Substring, ignoring case | warning **Case is ignored; accents are not.** The comparison lowercases both ends, but does **not** strip accents: a rule with **"Pao"** won't catch a description written **"Pão"**. Write the criterion the way the text actually arrives. There is no **amount or range** criterion, nor "equals / starts with / ends with" operators — text is always "contains". tip The **"Show entries affected by this criteria"** link opens the preview with what the rule would catch today — worth checking before you save. ## Actions[​](#actions "Direct link to Actions") | Action | Description | | ------------------------- | -------------------------------------------------------------------- | | **Description** | Rewrites the description | | **Customer/Supplier** | Assigns the person | | **Category** | Assigns the category | | **Classification center** | Assigns **one** center | | **Pay/Receive via** | Sets the expected account (Accounts Payable / Receivable scope only) | note **The classification-center action doesn't split.** It assigns a single center — the picker is single-choice. To divide across centers, use **Split** on the bill's form. See [Classification centers](https://docs.finance.kobana.com.br/en/en/centros-de-classificacao/.md). **A rule doesn't undo a split.** On a bill already split across two or more categories, the rule leaves the category alone; the same goes for the classification center. The rule's other actions apply as usual, and the preview shows *"split — the rule keeps it"* on the preserved field. To replace a split with a single classification, use **Classify selected**. ## Precedence[​](#precedence "Direct link to Precedence") Rules only compete **inside their own group: entity × scope**. Each card carries the **"Move up"** and **"Move down"** arrows, and the rule with the lowest position wins first. **The arrows stop at the group's edge.** Even when there is a card right above on screen, the arrow won't jump over it if it belongs to another group — the listing shows every group in a single column, but the ordering is per group. It isn't a lock-up: moving it there would make no sense, because rules from different groups never contend for the same document. * In a group with **a single rule**, the arrows **don't appear** — there is nothing to order against. * On the first rule of the group, the up arrow is disabled; on the last, the down arrow. * **There is no confirmation when moving**: the card changing place is the confirmation. **The order of the groups among themselves means nothing.** Groups are listed by the entity's internal identifier, not by name or relevance. One group appearing above another gives it no precedence — the contest never crosses groups. ## Activate and pause[​](#activate-and-pause "Direct link to Activate and pause") The pill at the foot of the card shows the **state** — **"Rule active"** or **"Rule disabled"** — and clicking it performs the **opposite action**, which the tooltip announces: **"Pause"** or **"Resume"**. The toasts are **"Rule activated"** and **"Rule deactivated"**. **A paused rule never fires.** It isn't merely dimmed in the listing: evaluation only considers active rules. Pausing is how you switch a rule off without losing it. ## Where rules fire[​](#where-rules-fire "Direct link to Where rules fire") * **Creation** of transactions and bills (form and API). * **CSV import** — transactions, payables and receivables. * **Bank statements**, when you confirm the statement import. * **Generated installments** — each installment in the group is evaluated on its own, because a description criterion may depend on the suffix ("1/12"). * **Fintera import** — in all three importers: payables, receivables and transactions. * **Banking Gateway statement sync**. ## Apply to existing ones[​](#apply-to-existing-ones "Direct link to Apply to existing ones") note **This is not a listing action.** It's the **"Apply rule to existing entries?"** checkbox, at the **foot of the form**. When ticked, saving asks for confirmation and queues the retroactive apply — which runs in the background (*"Retroactive apply queued"*). Different from the bulk **"Classify"** dialog, which sets category and center manually over a selection, without creating a rule. ## Create a rule[​](#create-a-rule "Direct link to Create a rule") 1. In `/automatic-rules`, use **"New Rule"**. 2. Pick the **Entity** and, in the tabs at the top, the scope — **"Financial Accounts"** or **"Accounts Payable / Receivable"**. Now is the only chance to choose: once saved, the rule cannot change scope. 3. Build the criteria (**WHEN**) and the actions (**THEN**), checking the preview. 4. Save — the rule takes effect immediately for **new** documents. ## Delete[​](#delete "Direct link to Delete") The dialog is **"Delete automatic rule"**: *"The rule will be permanently removed. Entries already classified are not affected."* --- # Smart Finance SDKs The SDKs are the official libraries for calling the Smart Finance REST API from **Node.js / TypeScript**, **Python**, **Ruby** and **PHP**, without building HTTP requests, authentication, pagination and error handling by hand. ## Languages[​](#languages "Direct link to Languages") | Language | Package | Registry | Status | | -------------------- | ------- | --------- | ----------- | | Node.js / TypeScript | — | npm | Coming soon | | Python | — | PyPI | Coming soon | | Ruby | — | RubyGems | Coming soon | | PHP | — | Packagist | Coming soon | :::info Coming soon The Smart Finance SDKs have not been published yet. Once they are, this page will list the package name and the install command for each language. ::: ## What to expect[​](#what-to-expect "Direct link to What to expect") * Clients generated from the API OpenAPI specification, with the same resources and names as the [API reference](https://docs.finance.kobana.com.br/en/en/api/overview/introduction.md). * Authentication, pagination, retries and errors handled by the library. * One package per language, published on the official registry: npm, PyPI, RubyGems and Packagist. ## In the meantime[​](#in-the-meantime "Direct link to In the meantime") You can already integrate Smart Finance in other ways: * [REST API](https://docs.finance.kobana.com.br/en/en/api/overview/introduction.md): the complete endpoint reference. * [MCP](https://docs.finance.kobana.com.br/en/en/mcp/overview/introduction.md): for AI agents to operate the product. * [CLI](https://docs.finance.kobana.com.br/en/en/cli/overview/introduction.md): the `kobana finance` command in the terminal. The SDKs of every Kobana product are in the [SDK catalog](https://www.kobana.com.br/desenvolvedores/sdks). --- # Security **Security** (`/settings/security`) gathers the rules that protect the money leaving through the bank: **what can be sent, from which accounts, to which payees, through which channels and within which limits**. It applies only to **payments and transfers** — charges are out of scope. The rules belong to the **workspace**: they apply to all of its companies at once, and the screen says so at the top (*"Applies to every company in the … workspace."*). With no workspace selected, it asks you to pick one. ## Where it lives[​](#where-it-lives "Direct link to Where it lives") ![Limits tab of the Security screen](/en/assets/images/21-security-limits-d24c64276190efa3e43242f08a958f50.png) **System** menu → **Security**. ## What the rules hold back[​](#what-the-rules-hold-back "Direct link to What the rules hold back") Almost everything here acts **when sending to the bank**. Creating and approving bills stays free: a bill of a type that is off, from a blocked account or to a payee that is not allowed can be created and approved as usual — it just doesn't leave for the bank. There are three exceptions, which act before dispatch: * the **Channels** tab, which has its own **Create** and **Approve** switches; * the **Allow approvals at night** switch, on the Limits tab; * the [Approval Settings](https://docs.finance.kobana.com.br/en/en/aprovar-pagamentos/.md#turn-it-on-or-off), which also go through Kobana (see [Who can request changes](#who-can-request-changes)). note A limit **is not freed by editing or deleting a bill**. What was already sent to the bank is recorded separately, with the amount sent: deleting the bill or changing its amount or payee afterwards gives nothing back to the limit. Only a payment that was **canceled, rejected, reproved or failed** at the bank stops counting. ## Nothing takes effect right away[​](#nothing-takes-effect-right-away "Direct link to Nothing takes effect right away") ![Changes sidebar with one change ready to send](/en/assets/images/27-security-changes-2a7b1fde32ff6c4aa77a3480bf8f40b9.png) **No change on this screen takes effect immediately.** Every change becomes a **request**, which **Kobana reviews and approves or denies**. A security rule anyone could loosen on the spot would protect nothing. In practice: 1. You change whatever you want, on as many tabs as you want. The changes stay in a draft until you send them; once sent, the screen goes back to showing the values **in force**. 2. Each change shows up in the **Changes sidebar**, on the right, with the value before and after and an **Undo** button per item. 3. The **Reason (optional)** field explains the request to whoever reviews it. 4. **Send for approval** sends everything as a single request. The button is always visible — pinned to the top of the sidebar and, on narrow screens, in a bar stuck to the bottom. warning **The draft lives only in the browser.** If you leave the page without sending, the changes are lost — the browser warns you before leaving. While requests are under review, the screen shows the notice *"1 request is waiting for Kobana's approval. The values on screen are the ones in force now."* The new rule only takes effect once Kobana approves it. ### Requests[​](#requests "Direct link to Requests") ![Requests screen](/en/assets/images/28-security-requests-3f793d0ac7a35a0ab2daaa112c2c8058.png) The **Requests** button, at the top of the page, shows how many are pending and opens the list of every request in the workspace, with search by requester or reason and a status filter. | Column | What it shows | | ----------------- | ----------------------------------------------------------------------------------------------- | | **Date and time** | When the request was sent | | **Requester** | Who asked | | **Changes** | What changes, item by item | | **Reason** | The text sent along | | **Status** | **Pending**, **Approved**, **Denied** or **Canceled** — plus Kobana's reason, when there is one | | **Actions** | **Cancel**, on pending ones | **Cancel** withdraws the request from review (*"Kobana will no longer review these changes."*). To ask again, redo the changes on the screen. Anyone who can create that request can cancel it — not only its author. Canceled requests stay on the list as history. Requests made from the Approval Settings screen show up here too. More than one request can be pending at the same time. If two touch the same value, the second one to be reviewed is denied for conflict — the value it expected to change is no longer the same. ## The tabs[​](#the-tabs "Direct link to The tabs") ### Limits[​](#limits "Direct link to Limits") Sets **when it is day and when it is night** and **how much can be sent to the bank** in each period. * **Time zone** — the clock for every rule: what is day, night, "today" and "this month". The search accepts a city, region or UTC; the **Brazil** zones come first, then **Other time zones**. Default: São Paulo. * **Day and night hours** — drag the two handles to set when day and night start, in 30-minute steps. **The day starts at 05:00 at the earliest and ends at 22:00 at the latest.** Default: day from 06:00 to 20:00, which is also the Central Bank default for Pix. * **Night period**, with two switches: | Switch | On (default) | Off | | -------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------- | | **Allow approvals at night** | Approving works at any time | The approve buttons are blocked between the start of the night and the start of the day | | **Allow sending to the bank at night** | Sending works as usual, within the night limits | **Nothing goes to the bank at night** — see [Night sending off](#night-sending-off) | * **Amount limits** — a matrix with **Payments** (bank slips, taxes and utilities) and **Transfers** (Pix and TED) as rows, and **Day limit** and **Night limit** as columns, each with: * **Per transaction** — the maximum amount of a single dispatch; * **Daily total** — the sum of everything sent to the bank in the period, **across every company in the workspace**. A blank field means **No limit**. The per-transaction limit can't exceed the daily total. With night sending off, the night limits have no effect. ### Accounts[​](#accounts "Direct link to Accounts") ![Accounts tab](/en/assets/images/22-security-accounts-d0b4e7b53a68177599645796fdb5fe10.png) Chooses **which accounts** payments and transfers can leave from, and **how much each one can send per day**. Accounts are grouped by company; each has a switch for **Payments** and another for **Transfers**, each with its own **Daily sending limit**. * **New accounts** — the first row is the template: the settings **each account gets when it is connected to the bank**. It can be adjusted on its own row afterwards. Changing the template does not change accounts that already exist. * Accounts **Not connected to the bank** show up locked — there is nothing to send through them. * **All enabled accounts** applies the same limit to every enabled account in every company, with **Apply to all**. A blank field on that row **keeps** each account's current limit. The account limit applies together with the ones on the Limits tab: when both apply, the lower one wins. ### Payees[​](#payees "Direct link to Payees") ![Beneficiaries tab](/en/assets/images/23-security-beneficiaries-f17598bac7339eefc33123d731b4b5b9.png) Chooses **which payees transfers can be sent to** and how much each one can receive. note **Transfers only — Pix and TED.** Bank slips, taxes and utilities don't go through this rule: there, the money goes wherever the barcode says, and a supplier list would protect nothing. They are controlled in [Operation types](#operation-types). **General rule**, in two modes: | Mode | Who receives | New payees | | ------------------------------------------- | ---------------------------------- | ------------- | | **Allow everyone and block some** (default) | Everyone except the ones you block | Start allowed | | **Block everyone and allow some** | Only the ones you allow | Start blocked | Each mode keeps its own list: switching from one to the other doesn't erase the other's marks. **The payee is identified by CPF/CNPJ**, not by the person record. That's why the same supplier registered in several companies shows up **only once** (*"Registered in 3 companies"*), and its limits count across companies. The document compared at dispatch is: * the **Pix key's**, when the key is a CPF or CNPJ; * the **payee's CPF/CNPJ entered on the bill**, otherwise. warning For Pix by **email, phone or random** key, the system can't tell who owns the key: the document entered on the bill is what counts. If you want full rigor, turn those key types off in Operation types. For each payee, the list shows the **Allowed** switch, the **Daily limit**, the **Monthly limit** and **Transferred this month**. The month is the calendar month, in the Limits tab's time zone. The search accepts a name or CPF/CNPJ, and the filter separates **Allowed** from **Blocked**. Documents the rule mentions but that no longer have a record show up as **No active record**. **All allowed** applies the same limits to every allowed payee — on every page, or only those found by the search. A blank field on that row keeps each payee's current limit. ### Operation types[​](#operation-types "Direct link to Operation types") ![Operation types tab](/en/assets/images/24-security-operation-types-a1c212e844adeb9afa5c07301dcd412d.png) A tree with everything that can be sent to the bank, with switches that turn each type on and off: * **Payments** — Bank slip; Utilities; Taxes (Federal: DARF, GPS, GRU and FGTS; State: ICMS and DARE; Municipal: ISS, IPTU and ITBI); Pix copy-and-paste. * **Transfers** — Pix by key type (CPF, CNPJ, email, phone, random); TED to a payee account or a judicial deposit. Turning a group off turns off everything inside it; a group with some types on and some off shows in yellow. Types only turn on and off — there is no limit per type. Types that are off can still be created and approved, but **are not sent to the bank**. ### Channels[​](#channels "Direct link to Channels") ![Channels tab](/en/assets/images/25-security-channels-96550ff3d0c02ad4f864de7b7e7eeb82.png) A matrix with what can be done on each channel: **Create**, **Approve**, **Pay** (*"Send to the bank"*) and **Charge** (*"Issue a bank slip or Pix charge to the customer"*). **Access channels** — the way a person or a system gets in: | Channel | Note | | ---------------------------------- | --------------------------------------------------------------------------------------------- | | **Dashboard** | This web interface | | **Desktop app** and **Mobile app** | **In development** — shown locked | | **API** | Integrations with your system | | **MCP - Artificial Intelligence** | AI agents: **Kadu**, **Kia** and **Others**. Turning MCP on or off changes all three together | | **CLI - Command line** | | **Origin channels** — where a bill comes from without anyone typing it. **They only create bills**: Approve, Pay and Charge show as *"Not applicable"*. | Channel | What it covers | | ------------------- | ------------------------------------- | | **Import** | CSV spreadsheets | | **Inbox** | Documents received by email or upload | | **Invoices (NF-e)** | Bills generated from invoices | | **Integrations** | Nibo, Fintera and upcoming ones | When a person generates a bill from an origin channel — say, from an invoice, in the Dashboard —, **both channels must allow Create**. Recurring bills follow the channel the series was created on. **All channels** turns an action on or off on every channel at once, except those in development. Lookups stay allowed on every channel. warning **Default: Pay on only for the Dashboard.** Create and Approve ship on for every access channel, and Create for the origin channels — but sending to the bank through the API, the CLI or AI agents **requires an approved request**. Those are the paths that can be automated, so they start closed. **Charge** ships on for the Dashboard, the API and the CLI, and off for AI agents: an agent issues a bank slip or Pix charge on the organization's behalf only if someone turns that on. Automatic dispatch after approval (see [Approval Settings](https://docs.finance.kobana.com.br/en/en/aprovar-pagamentos/.md#turn-it-on-or-off)) uses the channel of whoever gave the last approval. ### Users[​](#users "Direct link to Users") ![Users tab](/en/assets/images/26-security-users-6d49632762db005fbb3824d0a838ff69.png) **Read-only.** Lists who has access to the workspace, each person's roles and what those roles allow: **Create**, **Approve**, **Pay** and **Force resend**. Hover a mark to see which role grants the permission. The same permission covers payments and transfers. To change it, use **Change**, which takes you to the person's roles in Members — the link only shows for those who can view members. Pending invitations and suspended users can't operate until they are active. ## When a rule blocks[​](#when-a-rule-blocks "Direct link to When a rule blocks") When sending to the bank, the rules are checked in this order, and the first that fails decides: channel, operation type, account, payee (transfers only), night hours, per-transaction limit, period total, account daily limit and payee limits. **Nothing is rescheduled.** A blocked bill stays where it is, with the reason in sight, and must be sent again once the rule allows it. ### In the dispatch list[​](#in-the-dispatch-list "Direct link to In the dispatch list") In the **Send payments to the bank** dialog — the "Send to bank" list in Payables —, a bill held back by a rule that depends only on the bill itself shows **disabled**, with the reason: | Reason on the list | What to do | | -------------------------------------- | -------------------------------------------------- | | **Channel not allowed to dispatch** | Request Pay for the channel, on the Channels tab | | **Operation type turned off** | Request the type, in Operation types | | **Account blocked for this operation** | Request the operation for the account, in Accounts | | **Beneficiary not allowed** | Request the CPF/CNPJ be allowed, in Payees | | **Night dispatch blocked** | Wait for the day period to start | | **Above the per-transaction limit** | Request a higher limit, in Limits | The limits that depend on what **has already been sent** — period total, account daily limit, payee daily and monthly limits — show as a **warning**, and the row stays selectable: *"Would exceed the period limit"*, *"Would exceed the account's daily limit"*, *"Would exceed the beneficiary's daily limit"*, *"Would exceed the beneficiary's monthly limit"*. Hover to see the limit, how much was already sent and how much is left. In a batch send, bills go in due-date order; once a limit is reached, the following ones that would exceed it **are not sent**, and the result lists each one with its reason. If the automatic dispatch was refused by a rule, the row carries the **Automatic dispatch blocked** badge. ### Night sending off[​](#night-sending-off "Direct link to Night sending off") With **Allow sending to the bank at night** off: * **nothing goes to the bank** between the start of the night and the start of the day — neither through the button nor through the automatic dispatch after approval; * the list shows the notice **"Bank dispatch blocked until 06:00"** (with your hour); * what was approved at night **is not sent on its own in the morning**: it stays on the list and must be sent again during the day period. ### Batch held at the bank[​](#batch-held-at-the-bank "Direct link to Batch held at the bank") A payment may be created at the bank at the end of the day while the batch's automatic approval falls in the night period. In that case the batch **is not approved**: it is **held at the bank**. * On the bill, the payment card shows the **"Held at the bank: night dispatch blocked"** badge. * On the dispatch list, those bills show up in the **Held at the bank** section. * The **Approve at the bank** button — on the card and in the section — only works during the day period. It checks the rules again, approves the batch and resumes tracking the payment. "Refresh status" and the automatic tracking **do not** approve a held batch. ### On approval[​](#on-approval "Direct link to On approval") With night approvals off or **Approve** off for the channel, the [Approval](https://docs.finance.kobana.com.br/en/en/aprovar-pagamentos/.md) screen shows a notice and disables the approve buttons. **Rejecting is never blocked.** The same screen warns, on each bill, when it **won't be able to be sent** as it is (*"Sending blocked by Security"*) — so whoever approves knows the release must be requested. ### On creation[​](#on-creation "Direct link to On creation") With **Create** off for a channel, the bill is not created: *"The … channel can't create bills. Ask for it to be enabled in Security."* For imports and integrations, the reason is recorded in the run's report, and a recurrence created through a channel that is off stops generating occurrences while it stays off. ## Who can request changes[​](#who-can-request-changes "Direct link to Who can request changes") | Who | What they can request | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Owner** | Any change, on every tab | | Whoever has the **Approval settings** permission | Only changes to the approval settings, through the [Approval Settings](https://docs.finance.kobana.com.br/en/en/aprovar-pagamentos/.md#turn-it-on-or-off) screen | | Other roles (Admin, Viewer…) | None: they see the rules, and the sidebar warns *"Only people allowed to request security changes can send requests."* | By default, **only the Owner** requests security changes — not even the Admin. The decision is always **Kobana's**. --- # Transfers A transfer moves money between two financial accounts of the same workspace, generating **two mirrored transactions**: an outflow at the source and an inflow at the destination. ## Where it lives[​](#where-it-lives "Direct link to Where it lives") note **A transfer is not a menu item.** There is no transfers screen: it is the **"New transfer"** dialog, opened from two places, both under **Financial accounts**: * From the **listing header** of the accounts. * From the **detail of an account** — and there the **source comes pre-filled** with the account you are looking at. ## Fields[​](#fields "Direct link to Fields") Six fields, and **five are required**: | Field | Notes | | --------------- | ----------------------------------------------------------------------------- | | **From** | Required — the account sending the money | | **To** | Required — the account receiving it | | **Amount** | Required — must be **greater than zero** | | **Date** | Required — comes pre-filled with today | | **Description** | **Required** — unlike an ordinary transaction, here you cannot leave it blank | | **Notes** | Optional. *"Additional information — visible on both transactions."* | The button is **"Create transfer"**. **"From" and "To" are the labels.** "Source account" and "Destination account" show as supporting text inside the fields, not as their names. **There is no "Accrual month" and no "Provisional" on a transfer.** Both fields exist in the API, but the screen doesn't offer them — a transfer created here is always effective, and the accrual follows the date. ### What the system refuses[​](#what-the-system-refuses "Direct link to What the system refuses") * **Zero or negative amount** — *"Value must be greater than zero"*. * **Source equal to destination** — *"Source and destination must be different accounts"*. * **Empty description** — *"Enter a description"*. ## The two transactions[​](#the-two-transactions "Direct link to The two transactions") Once the transfer is confirmed, two records are born: | Record | Account | | ---------- | ------------------- | | **Debit** | Source account | | **Credit** | Destination account | Both carry the same transfer identifier, which marks them as the two legs of the same movement and keeps reconciliation from treating them as new money. ## How they show up afterwards[​](#how-they-show-up-afterwards "Direct link to How they show up afterwards") On the [Transactions](https://docs.finance.kobana.com.br/en/en/lancamentos/.md) listing, each leg gets the **transfer** badge next to the description, and the **Transfers** quick filter isolates all of them. Open a leg and the card at the top says **"Transfer sent to another account"** or **"Transfer received from another account"**, shows the account on the other side, the date and the amount, and carries the **"Open opposite side →"** shortcut. ## Delete[​](#delete "Direct link to Delete") danger **There is no editing a transfer, and deleting does not cascade.** The two legs are independent transactions once created: deleting one removes only that one and **leaves the other orphaned**, with the balance distorted on both sides. To undo the whole thing, delete **both** — the "Open opposite side →" is how you find the second one. ## Difference from an ordinary transaction[​](#difference-from-an-ordinary-transaction "Direct link to Difference from an ordinary transaction") An inflow or outflow transaction affects **one** account and moves the workspace's total balance. A transfer affects **two** and keeps the total intact — it is the right mechanism for moving balance between accounts without inventing revenue or expense. --- # Workspaces A workspace is the box that holds everything you register in Smart Finance. Each user can belong to several workspaces, and the data in one never shows up in another. ![Workspaces list](/en/assets/images/18-workspaces-f6a3fc9597802af3ea2e2b3bc1b752ca.png) ## Isolation model[​](#isolation-model "Direct link to Isolation model") ``` User (email) ├── Workspace A │ ├── Company 1 (CNPJ) │ ├── Company 2 (CNPJ) │ ├── People (customers and suppliers) │ ├── Financial accounts │ ├── Categories │ ├── Classification centers │ ├── Payables │ ├── Receivables │ └── Transactions └── Workspace B └── ... ``` No data crosses the boundary between workspaces. A workspace is the equivalent of an organization or a group of companies managed by the same person. ## The screen[​](#the-screen "Direct link to The screen") At `/workspaces` you get **one card per workspace**, not a table. Each card shows the name at the top and, below it, the list of companies it holds, under the **Companies (N)** label. The card for the active workspace stands out with a colored border. **Clicking the card switches to that workspace and takes you to the Dashboard** — the same effect as the selector at the top of the application. ## Create[​](#create "Direct link to Create") Click **New workspace** and fill in the **Name**. That's the only field. The workspace is created right away, becomes the active one and shows up in the selector at the top. note **Your first workspace is not born here.** It is created right after your first Kobana sign-in, on a confirmation screen that already carries your company's name and tax ID — see [Signing in is not the same as having access](https://docs.finance.kobana.com.br/en/en/meus-dados/.md#signing-in-is-not-the-same-as-having-access). This screen is for the **rest**: a second workspace, created from a name alone. ## Rename[​](#rename "Direct link to Rename") In the card's action menu (the three-dot icon), choose **Edit**. Only the name changes — there is no way to move companies from one workspace to another. ## Switch[​](#switch "Direct link to Switch") The selector in the header lists all of your workspaces. When you switch, every screen reloads with the data from the workspace you picked. If you belong to more than one organization, both choices live in the same selector, labeled **Org / Workspace**: organizations in one column, the current organization's workspaces in the other. Switching organization reloads the app on the **Dashboard**. ## Deletion[​](#deletion "Direct link to Deletion") danger **There is no safety catch. Deleting a workspace wipes everything inside it, for good.** It doesn't matter how many companies, accounts or transactions it holds: the deletion goes through, the contents go with it, and there is no recycle bin and no undo. This runs against what happens one level down, and it's worth knowing: a **company** with a single transaction, payable or receivable **cannot be deleted** — the system refuses and asks you to remove the records first. But deleting the **workspace** that holds that company **works**, and takes the company and all of its records along. The shortest path is also the most destructive one. That's why the dialog is there for you to **check before you sign**. In the card's action menu, choose **Delete**: 1. The dialog **counts what will be destroyed** and mentions only what actually exists — companies, payables, receivables, transactions, people, financial accounts, reconciliations and audit logs: > These go with it, permanently: 2 companies, 1 payable, 14 transactions. If nothing is attached, it says so: *"It is empty — nothing is attached to it."* 2. Right below, the reminder of what goes along without being counted: **settings, attachments, schedules and import history**. 3. **To unlock the button, you type the workspace name.** The text has to match **exactly**, uppercase and lowercase included. Only then does **Delete workspace** become clickable. If the count can't be loaded, the dialog warns you — *"We couldn't check what will be removed. Please verify before continuing."* — and still requires you to type the name. Deleting the active workspace clears the selection; pick another one in the selector at the top. --- # Smart Finance — Documentation Welcome! Smart Finance is the multi-company financial back-office platform for the Brazilian market: payables and receivables, transactions, reconciliation, imports, and payment dispatch to the bank — several companies, in one place. This documentation describes what you see and can do on the product's screens. To integrate your systems via REST, see the [API reference](https://docs.finance.kobana.com.br/en/en/api.md). ## What is in this documentation[​](#what-is-in-this-documentation "Direct link to What is in this documentation") | Section | For whom | What you will find | | ---------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Documentation** (this section) | people who use the dashboard | financial accounts, entries, payables and receivables, reconciliation, documents, classification and registries | | [API](https://docs.finance.kobana.com.br/en/en/api/overview/introduction.md) | people who integrate another system | the v1 API: authentication, pagination, filtering, idempotency, errors and the reference for each endpoint | | [MCP](https://docs.finance.kobana.com.br/en/en/mcp/overview/introduction.md) | people who use the product from an AI client (Claude, ChatGPT…) | the remote MCP server: authentication, transport and the reference for each tool | | [CLI](https://docs.finance.kobana.com.br/en/en/cli/overview/introduction.md) | people who operate from the terminal or a script | `kobana`, the command-line tool for every Kobana product: installation, authentication and usage | ## Getting started[​](#getting-started "Direct link to Getting started") If you are just arriving, this is the natural path: 1. [Create a workspace](https://docs.finance.kobana.com.br/en/en/workspaces/.md) — the box that isolates each organization's data. 2. [Register the companies](https://docs.finance.kobana.com.br/en/en/empresas/.md) — the legal entities (CNPJ) it administers. 3. [Create the financial accounts](https://docs.finance.kobana.com.br/en/en/contas-financeiras/.md) — checking, savings, cash, investment, and credit. 4. [Record payables](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/.md) and [receivables](https://docs.finance.kobana.com.br/en/en/contas-a-receber/.md) — one-off, in installments, or recurring — or import them in bulk via CSV. 5. [Import the statement](https://docs.finance.kobana.com.br/en/en/extratos-bancarios/.md) and [reconcile](https://docs.finance.kobana.com.br/en/en/conciliacao/.md) — match what happened at the bank with what was expected. ## The sections[​](#the-sections "Direct link to The sections") The sections below follow the product's **six menu groups** — here you walk the same tree you see on screen. Only **My profile** is reached differently in the product: through the avatar menu. ### Main[​](#main "Direct link to Main") * [Dashboard](https://docs.finance.kobana.com.br/en/en/dashboard/.md) — metrics, realized and projected cash flow, upcoming due dates. * [Workspaces](https://docs.finance.kobana.com.br/en/en/workspaces/.md) — the isolation between organizations: creation, switching, and deletion. * [Companies](https://docs.finance.kobana.com.br/en/en/empresas/.md) — multi-company register (CNPJ), headquarters and branches, Receita Federal (the Brazilian federal revenue service) lookup. ### Financial[​](#financial "Direct link to Financial") * [Financial accounts](https://docs.finance.kobana.com.br/en/en/contas-financeiras/.md) — checking, savings, cash, investment, and credit accounts, with the balance calculated from the transactions. * [Bank statements](https://docs.finance.kobana.com.br/en/en/extratos-bancarios/.md) — OFX and QIF import into the account. * [Transfers](https://docs.finance.kobana.com.br/en/en/transferencias/.md) — movement between accounts of the same workspace. * [Cards](https://docs.finance.kobana.com.br/en/en/cartoes/.md) — credit, prepaid and benefit cards: statements, limit, installments, international purchases with IOF, recurrences and paying the statement. * [Transactions](https://docs.finance.kobana.com.br/en/en/lancamentos/.md) — the movements of the financial accounts; the basis of reconciliation. * [Payables](https://docs.finance.kobana.com.br/en/en/contas-a-pagar/.md) — outgoing commitments: installments, recurrence, taxes, and bank dispatch. * [Approve payments](https://docs.finance.kobana.com.br/en/en/aprovar-pagamentos/.md) — the gate that requires a person's approval before a bill enters the list. * [Receivables](https://docs.finance.kobana.com.br/en/en/contas-a-receber/.md) — incoming commitments, with installments and recurrence, and charging by bank slip or Pix. * [Reconciliation](https://docs.finance.kobana.com.br/en/en/conciliacao/.md) — matching between bills and transactions coming from the statement. ### Documents[​](#documents "Direct link to Documents") * [Receipts](https://docs.finance.kobana.com.br/en/en/comprovantes/.md) — the proof of every payment: captured on its own when the bank confirms, or uploaded by you. * [Attachments](https://docs.finance.kobana.com.br/en/en/anexos/.md) — the workspace file library, linkable to any record. ### Axes[​](#axes "Direct link to Axes") * [Categories](https://docs.finance.kobana.com.br/en/en/categorias/.md) — classification in up to three levels, by revenue and expense. * [Classification centers](https://docs.finance.kobana.com.br/en/en/centros-de-classificacao/.md) — allocation by department or project, with apportionment. * [Custom classifiers](https://docs.finance.kobana.com.br/en/en/classificadores-personalizados/.md) — classification dimensions you create, with their own values, beyond categories and centers. * [Automatic rules](https://docs.finance.kobana.com.br/en/en/regras-automaticas/.md) — automatic classification by criteria you define. ### Registers[​](#registers "Direct link to Registers") * [People](https://docs.finance.kobana.com.br/en/en/pessoas/.md) — customers and suppliers (individuals and companies), with cumulative roles. * [Taxes](https://docs.finance.kobana.com.br/en/en/impostos/.md) — the catalog of taxes linkable to bills. ### System[​](#system "Direct link to System") * [Integrations](https://docs.finance.kobana.com.br/en/en/integracoes/.md) — Banking Gateway (payments, accounts, statement, and people), Fintera (data import), and WhatsApp (profile photos). * [Maintenance](https://docs.finance.kobana.com.br/en/en/manutencao/.md) — data hygiene tools for the people register. * [My profile](https://docs.finance.kobana.com.br/en/en/meus-dados/.md) — your account information and how login works. ### API[​](#api "Direct link to API") * [API reference](https://docs.finance.kobana.com.br/en/en/api.md) — REST with Bearer JWT authentication: endpoints, pagination, filtering, idempotency, and errors. ---