# Financeiro Inteligente — Documentação > Documentação do Financeiro Inteligente: contas a pagar, contas a receber, transações, conciliações e API. ## es ¡Bienvenido! Finanzas Inteligentes es la plataforma de back-office financiero multi-empresa para el mercado brasileño: cuentas por pagar y por cobrar, transacciones, conciliación, importaciones y envío de pagos al banco — varias empresas, en un solo lugar. - [Finanzas Inteligentes — Documentación](https://docs.finance.kobana.com.br/es/index.md): ¡Bienvenido! Finanzas Inteligentes es la plataforma de back-office financiero multi-empresa para el mercado brasileño: cuentas por pagar y por cobrar, transacciones, conciliación, importaciones y envío de pagos al banco — varias empresas, en un solo lugar. ### search - [Buscar en la documentación](https://docs.finance.kobana.com.br/es/search.md) ### anexos La biblioteca de archivos del espacio de trabajo — vínculo de muchos a muchos con títulos y transacciones. - [Adjuntos](https://docs.finance.kobana.com.br/es/anexos.md): La biblioteca de archivos del espacio de trabajo — vínculo de muchos a muchos con títulos y transacciones. ### api - [Referencia de la API](https://docs.finance.kobana.com.br/es/api.md) #### overview - [Visión general](https://docs.finance.kobana.com.br/es/api/overview.md) - [Autenticación](https://docs.finance.kobana.com.br/es/api/overview/authentication.md): La API de Finanzas Inteligentes usa un access token de la Cuenta Kobana para autenticar todas las solicitudes. - [Retención de datos](https://docs.finance.kobana.com.br/es/api/overview/data-retention.md): Esta página describe por cuánto tiempo se conserva cada tipo de dato en Finanzas Inteligentes. - [Endpoints](https://docs.finance.kobana.com.br/es/api/overview/endpoints.md): | Ambiente | Plataforma (acceso web) | API (v1) | - [Errores](https://docs.finance.kobana.com.br/es/api/overview/errors.md): Toda respuesta de error usa un sobre JSON estable. - [Selección de campos](https://docs.finance.kobana.com.br/es/api/overview/fields.md): Las lecturas de registros — los listados y los GET de un ítem — aceptan ?fields= para devolver solo las columnas que vas a usar: - [Filtros y ordenación](https://docs.finance.kobana.com.br/es/api/overview/filtering.md): Los endpoints GET de colección aceptan filtros y ordenación por query string, además de la paginación por cursor. Qué campos son filtrables y ordenables varía por recurso — consulta la especificación OpenAPI de cada endpoint. Aquí está la gramática común. - [Idempotencia](https://docs.finance.kobana.com.br/es/api/overview/idempotency.md): La API soporta idempotencia para reintentar solicitudes de forma segura, sin ejecutar la misma operación dos veces. Útil cuando una llamada se interrumpe en tránsito y no recibes respuesta — por ejemplo, una solicitud para crear una cuenta por pagar que falla por un error de red puede reintentarse con la misma clave, garantizando que solo se cree un registro. - [Introducción](https://docs.finance.kobana.com.br/es/api/overview/introduction.md): Tú que eres dev, ¡diviértete! ✨ - [OpenAPI](https://docs.finance.kobana.com.br/es/api/overview/openapi.md): La especificación de la API de Finanzas Inteligentes está disponible en formato OpenAPI 3.1 para importar en la herramienta de tu preferencia. - [Listado y paginación](https://docs.finance.kobana.com.br/es/api/overview/pagination.md): Todos los endpoints GET que devuelven colecciones usan paginación por cursor. - [Postman](https://docs.finance.kobana.com.br/es/api/overview/postman.md): Descarga la colección en el idioma de tu preferencia e impórtala en Postman, o abre la versión online directamente desde el workspace público de Kobana. - [Límite de solicitudes](https://docs.finance.kobana.com.br/es/api/overview/rate-limit.md): Los límites son por ventana deslizante de 1 hora — cada solicitud cuenta contra el límite durante los 60 minutos siguientes; no hay un reinicio a hora fija — y se separan en tres franjas: lectura (GET), escritura (POST, PUT, PATCH, DELETE) y las acciones que mueven dinero, que tienen su propio cubo, más restrictivo. - [User-Agent](https://docs.finance.kobana.com.br/es/api/overview/user-agent.md): El encabezado User-Agent identifica tu integración. Incluye tu nombre y una dirección de correo electrónico válida para que el equipo de Kobana pueda ponerse en contacto en caso de que: ### aprovar-pagamentos La puerta que exige el visto bueno de una persona antes de que un título entre en la lista oficial de cuentas por pagar. - [Aprobar pagos](https://docs.finance.kobana.com.br/es/aprovar-pagamentos.md): La puerta que exige el visto bueno de una persona antes de que un título entre en la lista oficial de cuentas por pagar. ### cartoes Tarjetas de crédito, prepago y de beneficio — resúmenes, límite, cuotas, compras internacionales, suscripciones y el pago del resumen. - [Tarjetas](https://docs.finance.kobana.com.br/es/cartoes.md): Tarjetas de crédito, prepago y de beneficio — resúmenes, límite, cuotas, compras internacionales, suscripciones y el pago del resumen. #### cadastrar-e-converter Registrar una tarjeta con una cuenta nueva, convertir una cuenta de crédito que ya existe, y la vista previa de los resúmenes que el formulario calcula mientras escribes. - [Registrar y convertir](https://docs.finance.kobana.com.br/es/cartoes/cadastrar-e-converter.md): Registrar una tarjeta con una cuenta nueva, convertir una cuenta de crédito que ya existe, y la vista previa de los resúmenes que el formulario calcula mientras escribes. #### fatura-e-corte La pantalla de la tarjeta — resúmenes por mes, el encabezado del resumen, los movimientos, la fecha de cierre prevista y la confirmada, y el historial. - [Resumen y cierre](https://docs.finance.kobana.com.br/es/cartoes/fatura-e-corte.md): La pantalla de la tarjeta — resúmenes por mes, el encabezado del resumen, los movimientos, la fecha de cierre prevista y la confirmada, y el historial. #### fechar-conferir-pagar El cierre automático y la cuenta por pagar del resumen, la revisión con el total del banco, el pago total o parcial, deshacer, reabrir, la recarga de la prepago y la tarjeta en el flujo de caja. - [Cerrar, revisar y pagar](https://docs.finance.kobana.com.br/es/cartoes/fechar-conferir-pagar.md): El cierre automático y la cuenta por pagar del resumen, la revisión con el total del banco, el pago total o parcial, deshacer, reabrir, la recarga de la prepago y la tarjeta en el flujo de caja. #### lancamentos-e-iof Cargar compras al contado, en cuotas e internacionales, reembolsos, intereses y tarifas — en qué resumen cae cada uno, el IOF y la cotización, editar una serie, mover y anticipar. - [Movimientos e IOF](https://docs.finance.kobana.com.br/es/cartoes/lancamentos-e-iof.md): Cargar compras al contado, en cuotas e internacionales, reembolsos, intereses y tarifas — en qué resumen cae cada uno, el IOF y la cotización, editar una serie, mover y anticipar. #### recorrencias Suscripciones cobradas en la tarjeta — los cobros previstos en cada resumen, confirmar con el importe real, no cobrado, la sugerencia de actualizar el importe, editar y terminar. - [Recurrencias](https://docs.finance.kobana.com.br/es/cartoes/recorrencias.md): Suscripciones cobradas en la tarjeta — los cobros previstos en cada resumen, confirmar con el importe real, no cobrado, la sugerencia de actualizar el importe, editar y terminar. #### relatorios IOF pagado en las compras internacionales, por mes, tarjeta, categoría o proveedor, y el previsto × realizado de las recurrencias — con exportación en CSV y XLSX. - [Informes](https://docs.finance.kobana.com.br/es/cartoes/relatorios.md): IOF pagado en las compras internacionales, por mes, tarjeta, categoría o proveedor, y el previsto × realizado de las recurrencias — con exportación en CSV y XLSX. ### categorias Clasificación jerárquica de hasta tres niveles, por ingresos y gastos. - [Categorías](https://docs.finance.kobana.com.br/es/categorias.md): Clasificación jerárquica de hasta tres niveles, por ingresos y gastos. ### centros-de-classificacao Asignar costos e ingresos a departamentos y proyectos — con distribución entre centros. - [Centros de clasificación](https://docs.finance.kobana.com.br/es/centros-de-classificacao.md): Asignar costos e ingresos a departamentos y proyectos — con distribución entre centros. ### classificadores-personalizados Dimensiones de clasificación que tú creas — como "Región" o "Producto" — cada una con sus valores. - [Clasificadores personalizados](https://docs.finance.kobana.com.br/es/classificadores-personalizados.md): Dimensiones de clasificación que tú creas — como "Región" o "Producto" — cada una con sus valores. ### cli #### overview - [Autenticación](https://docs.finance.kobana.com.br/es/cli/overview/authentication.md): KOBANA_TOKEN guarda la credencial de un producto por vez. Un token de Finanzas Inteligentes no autentica en ningún otro producto Kobana, y viceversa. - [Variables de ambiente](https://docs.finance.kobana.com.br/es/cli/overview/environment-variables.md): Todas las variables también pueden definirse en un archivo .env (cargado vía dotenvy). - [Códigos de salida](https://docs.finance.kobana.com.br/es/cli/overview/exit-codes.md): Cada ejecución de kobana termina con uno de estos códigos, para que un script decida qué hacer sin interpretar el cuerpo JSON del error. - [Instalación](https://docs.finance.kobana.com.br/es/cli/overview/installation.md): Homebrew (macOS y Linux) - [Introducción](https://docs.finance.kobana.com.br/es/cli/overview/introduction.md): kobana es una única herramienta de línea de comandos para las APIs de todos los productos Kobana — Finanzas Inteligentes incluido. Se construye y mantiene en su propio repositorio (kobana-cli), no en este producto, y no tiene ningún endpoint escrito a mano: al arrancar lee las specs OpenAPI 3.1 embebidas en el binario y arma su árbol de comandos a partir de ellas. Actualizar la superficie de la API es cuestión de refrescar la spec embebida y publicar un build nuevo — nada de código por endpoint. #### resources - [Agentes de IA](https://docs.finance.kobana.com.br/es/cli/resources/ai-agents.md): Instrucciones que el asistente ejecuta por su cuenta, con los permisos de la persona dueña del token — por ejemplo, un resumen diario de las cuentas por pagar que vencieron. El listado trae solo los agentes de la persona del token en el workspace, nunca los de otro miembro. Cada ejecución gasta crédito de IA y se convierte en una nueva conversación del asistente (lastrun.conversationid); una acción destructiva espera la confirmación de la persona en el asistente. - [Habilidades de IA](https://docs.finance.kobana.com.br/es/cli/resources/ai-skills.md): Conjuntos de instrucciones, en el formato Agent Skills, que el asistente carga cuando una tarea coincide con la description de la habilidad — es todo lo que lee para decidir. El listado trae las habilidades que la persona del token ve en el workspace: las suyas y las que otros miembros compartieron con ella (is_owner las distingue; mine=true deja solo las propias). - [Adjuntos](https://docs.finance.kobana.com.br/es/cli/resources/attachments.md): Archivos — factura, contrato, comprobante — enviados al acervo y vinculados a uno o más títulos. links crea ese vínculo y unlink lo deshace. - [Reglas automáticas](https://docs.finance.kobana.com.br/es/cli/resources/automatic-rules.md): Las reglas que clasifican movimientos por sí solas, evaluadas en el orden en que están. reorder es lo que cambia ese orden. - [Bancos](https://docs.finance.kobana.com.br/es/cli/resources/banks.md): La tabla de bancos soportados, para completar los datos bancarios de una cuenta o persona. Solo lectura. - [Flujo de caja](https://docs.finance.kobana.com.br/es/cli/resources/cash-flow.md): La proyección consolidada: entradas y salidas realizadas y previstas por período, saldo acumulado y el hito de hoy. Solo lectura — es el resultado de todo lo demás, no una colección editable. - [Categorías](https://docs.finance.kobana.com.br/es/cli/resources/categories.md): El plan de cuentas: el árbol de ingresos y gastos por el que se clasifica cada movimiento. - [Centros de clasificación](https://docs.finance.kobana.com.br/es/cli/resources/classification-centers.md): La segunda dimensión de clasificación — centro de costo, proyecto, sucursal —, usada para prorratear un mismo título entre áreas. - [Empresas](https://docs.finance.kobana.com.br/es/cli/resources/companies.md): Las empresas del grupo. Toda cuenta, título y movimiento pertenece a una de ellas, y casi todo filtro acepta company_id. - [Clasificadores personalizados](https://docs.finance.kobana.com.br/es/cli/resources/custom-classifiers.md): Dimensiones de clasificación que la propia empresa define — proyecto, contrato, sucursal — junto a categoría y centro de clasificación. Cada clasificador pertenece a una empresa (filtra con company_id) y trae sus values[] incluidos; los valores son lo que se asigna a cuentas por pagar, por cobrar y movimientos. - [Cuentas financieras](https://docs.finance.kobana.com.br/es/cli/resources/financial-accounts.md): Las cuentas por donde entra y sale el dinero — cuenta corriente, caja, tarjeta. Cada movimiento, pago y cobro apunta a una cuenta financiera, y es su saldo lo que proyecta el flujo de caja. - [Movimientos](https://docs.finance.kobana.com.br/es/cli/resources/financial-transactions.md): El extracto en sí: cada crédito y débito ocurrido en una cuenta financiera, clasificado por categoría y centro de clasificación. El endpoint aggregates devuelve totales en lugar de la lista completa. - [Notas fiscales](https://docs.finance.kobana.com.br/es/cli/resources/fiscal-documents.md): Las notas fiscales (NF-e y NFS-e) recibidas contra las empresas del workspace — por NFE.io, carga de XML o SEFAZ. Son de solo lectura: el producto no emite notas, así que no hay create ni cancelación. El listado viene ordenado por la emisión más reciente. - [Identidad del token](https://docs.finance.kobana.com.br/es/cli/resources/me.md): Quién está detrás del token: la persona (user, nulo en un token de integración), la organización y los detalles del propio token. Sirve para probar que el token configurado vale — es el primer comando a ejecutar después de definir KOBANA_TOKEN. El token en sí nunca vuelve en la respuesta. - [Organización](https://docs.finance.kobana.com.br/es/cli/resources/organization.md): El perfil de la organización del token, en la cima de la jerarquía: vale para todos los workspaces. El recurso es singular — no hay list ni id, porque un token siempre alcanza una sola organización, la suya. - [Recursos](https://docs.finance.kobana.com.br/es/cli/resources/overview.md): Todo recurso de finance abajo se genera a partir de la misma spec OpenAPI documentada en la Referencia de la API — el CLI llama exactamente a los mismos endpoints, así que filtros, validación y comportamiento de borrado son idénticos. Recurre a la introspección de schema siempre que los parámetros exactos de un comando no sean obvios en los ejemplos de estas páginas. - [Cuentas por pagar](https://docs.finance.kobana.com.br/es/cli/resources/payables.md): Las obligaciones por vencer y ya pagadas, con aprobación de pago, envío al banco y prorrateo por centro de clasificación. Las cuentas pendientes de aprobación solo aparecen en el listado si filtras por paymentapproval=pendingapproval. - [Personas](https://docs.finance.kobana.com.br/es/cli/resources/people.md): Clientes y proveedores — la contraparte de cualquier título. ids devuelve solo los identificadores, útil para no llenar la ventana de contexto de un agente. - [Comprobantes](https://docs.finance.kobana.com.br/es/cli/resources/receipts.md): Los comprobantes de pago generados por la plataforma. Solo lectura. - [Cuentas por cobrar](https://docs.finance.kobana.com.br/es/cli/resources/receivables.md): Lo que tienes por cobrar, con emisión y cancelación de cobro por el Gateway Bancario desde el propio título. Para mover el dinero, el comando es charge — el registro en sí queda aquí. - [Conciliaciones](https://docs.finance.kobana.com.br/es/cli/resources/reconciliations.md): El vínculo entre un movimiento del extracto y el título que liquida. Crear la conciliación liquida el título; eliminarla deshace la liquidación. - [Impuestos](https://docs.finance.kobana.com.br/es/cli/resources/taxes.md): Los tributos retenidos o por recaudar vinculados a un título. - [Transferencias](https://docs.finance.kobana.com.br/es/cli/resources/transfers.md): Movimientos entre dos cuentas financieras tuyas. Genera los dos movimientos — salida y entrada — en una sola llamada. #### usage - [Flags globales](https://docs.finance.kobana.com.br/es/cli/usage/global-flags.md): | Flag | Descripción | - [Helpers](https://docs.finance.kobana.com.br/es/cli/usage/helpers.md): Los helpers son comandos con prefijo + que entregan flujos de varios pasos que los comandos dinámicos por sí solos no dan: interfaces simplificadas, operaciones en lote o llamadas compuestas por varios endpoints. No envuelven una única llamada de API ya disponible por los comandos dinámicos — cada flag de helper controla lógica de orquestación, no una versión remodelada de --params/--json. - [Uso](https://docs.finance.kobana.com.br/es/cli/usage/overview.md): Sintaxis - [Introspección de schema](https://docs.finance.kobana.com.br/es/cli/usage/schema.md): Devuelve parámetros, campos obligatorios, tipos y respuestas — todo derivado de la spec OpenAPI embebida, así que siempre está sincronizado con lo que el comando de hecho acepta. La ruta sigue la misma forma del comando: ... ### comprovantes Dónde viven los comprobantes de pago — los capturados solos y los que subes a mano. - [Comprobantes](https://docs.finance.kobana.com.br/es/comprovantes.md): Dónde viven los comprobantes de pago — los capturados solos y los que subes a mano. ### conciliacao Cerrar cada línea del extracto con la cuenta por pagar o por cobrar que paga, o registrar lo que falta — una a una (Manual) o varias a la vez (En lote). - [Conciliación](https://docs.finance.kobana.com.br/es/conciliacao.md): Cerrar cada línea del extracto con la cuenta por pagar o por cobrar que paga, o registrar lo que falta — una a una (Manual) o varias a la vez (En lote). ### contas-a-pagar Los compromisos de salida de la organización — cuotas, recurrencia, tributos y envío al banco. - [Cuentas por pagar](https://docs.finance.kobana.com.br/es/contas-a-pagar.md): Los compromisos de salida de la organización — cuotas, recurrencia, tributos y envío al banco. #### ciclo-de-vida Estados, transiciones y la puerta de aprobación — Borrador → Pendiente → Pagado. - [Ciclo de vida de las cuentas por pagar](https://docs.finance.kobana.com.br/es/contas-a-pagar/ciclo-de-vida.md): Estados, transiciones y la puerta de aprobación — Borrador → Pendiente → Pagado. #### disparo-kobana Enviar al banco las cuentas por pagar aprobadas mediante el Gateway Bancario — prerrequisitos, estado y liquidación automática. - [Envío de pagos al banco](https://docs.finance.kobana.com.br/es/contas-a-pagar/disparo-kobana.md): Enviar al banco las cuentas por pagar aprobadas mediante el Gateway Bancario — prerrequisitos, estado y liquidación automática. #### importacao-csv Importar lotes de cuentas por pagar mediante planilla — columnas aceptadas, formato tolerante y la puerta de aprobación. - [Importación CSV — Cuentas por pagar](https://docs.finance.kobana.com.br/es/contas-a-pagar/importacao-csv.md): Importar lotes de cuentas por pagar mediante planilla — columnas aceptadas, formato tolerante y la puerta de aprobación. #### operacao-e-pagamento Tipo de operación, documento (boleto, factura de servicios, tributo, PIX), transferencia (TED, PIX) o débito automático, y las coordenadas de pago. - [Operación y pago](https://docs.finance.kobana.com.br/es/contas-a-pagar/operacao-e-pagamento.md): Tipo de operación, documento (boleto, factura de servicios, tributo, PIX), transferencia (TED, PIX) o débito automático, y las coordenadas de pago. #### parcelas-e-recorrencia Dividir en cuotas o repetir periódicamente — los tres tipos de cuenta y el comportamiento de las series. - [Cuotas y recurrencia](https://docs.finance.kobana.com.br/es/contas-a-pagar/parcelas-e-recorrencia.md): Dividir en cuotas o repetir periódicamente — los tres tipos de cuenta y el comportamiento de las series. #### tributos DARF, DARE, GRU, GPS, FGTS, ICMS, ISS, IPTU e ITBI — cómo informar la guía y qué se envía al banco. - [Tributos](https://docs.finance.kobana.com.br/es/contas-a-pagar/tributos.md): DARF, DARE, GRU, GPS, FGTS, ICMS, ISS, IPTU e ITBI — cómo informar la guía y qué se envía al banco. ### contas-a-receber Los compromisos de entrada de la organización — cuotas, recurrencia y cobro. - [Cuentas por cobrar](https://docs.finance.kobana.com.br/es/contas-a-receber.md): Los compromisos de entrada de la organización — cuotas, recurrencia y cobro. #### ciclo-de-vida Estados, transiciones y cobro — Borrador → Pendiente → Recibido. - [Ciclo de vida de las cuentas por cobrar](https://docs.finance.kobana.com.br/es/contas-a-receber/ciclo-de-vida.md): Estados, transiciones y cobro — Borrador → Pendiente → Recibido. #### cobranca-kobana Generar boleto o Pix desde una cuenta por cobrar mediante el Gateway Bancario — requisitos, estados y cancelación. - [Cobro por boleto y Pix](https://docs.finance.kobana.com.br/es/contas-a-receber/cobranca-kobana.md): Generar boleto o Pix desde una cuenta por cobrar mediante el Gateway Bancario — requisitos, estados y cancelación. #### importacao-csv Importar lotes de cuentas por cobrar vía planilla — columnas aceptadas y formato tolerante. - [Importación CSV — Cuentas por cobrar](https://docs.finance.kobana.com.br/es/contas-a-receber/importacao-csv.md): Importar lotes de cuentas por cobrar vía planilla — columnas aceptadas y formato tolerante. #### parcelas-e-recorrencia Dividir en cuotas o repetir periódicamente — mismo comportamiento que las cuentas por pagar. - [Cuotas y recurrencia — Cuentas por cobrar](https://docs.finance.kobana.com.br/es/contas-a-receber/parcelas-e-recorrencia.md): Dividir en cuotas o repetir periódicamente — mismo comportamiento que las cuentas por pagar. ### contas-financeiras Las cuentas bancarias y de efectivo de las empresas — saldo calculado a partir de las transacciones. - [Cuentas financieras](https://docs.finance.kobana.com.br/es/contas-financeiras.md): Las cuentas bancarias y de efectivo de las empresas — saldo calculado a partir de las transacciones. ### dashboard La pantalla de inicio — indicadores de desempeño y la proyección del flujo de caja. - [Dashboard](https://docs.finance.kobana.com.br/es/dashboard.md): La pantalla de inicio — indicadores de desempeño y la proyección del flujo de caja. ### docs-mcp Esta documentación tiene su propio servidor MCP. Con él, un asistente de IA - [MCP de la Documentación](https://docs.finance.kobana.com.br/es/docs-mcp.md): Esta documentación tiene su propio servidor MCP. Con él, un asistente de IA ### empresas Las entidades jurídicas (CNPJ) del espacio de trabajo — consulta a la Receita, sede y sucursal. - [Empresas](https://docs.finance.kobana.com.br/es/empresas.md): Las entidades jurídicas (CNPJ) del espacio de trabajo — consulta a la Receita, sede y sucursal. ### extratos-bancarios Importar OFX y QIF en la cuenta financiera — deduplicación, historial y deshacer. - [Extractos bancarios](https://docs.finance.kobana.com.br/es/extratos-bancarios.md): Importar OFX y QIF en la cuenta financiera — deduplicación, historial y deshacer. ### impostos El catálogo de tasas y tributos vinculables a cuentas por pagar y por cobrar. - [Impuestos](https://docs.finance.kobana.com.br/es/impostos.md): El catálogo de tasas y tributos vinculables a cuentas por pagar y por cobrar. ### integracoes Conexiones con servicios externos — Gateway Bancario, Open Finance, Fintera y WhatsApp. - [Integraciones](https://docs.finance.kobana.com.br/es/integracoes.md): Conexiones con servicios externos — Gateway Bancario, Open Finance, Fintera y WhatsApp. #### fintera Importación de datos financieros de Fintera — once recursos, vínculo de empresas y programaciones. - [Integración Fintera](https://docs.finance.kobana.com.br/es/integracoes/fintera.md): Importación de datos financieros de Fintera — once recursos, vínculo de empresas y programaciones. #### kobana Envío de pagos al banco y sincronización de cuentas, extractos y personas vía Kobana. - [Integración Gateway Bancario (Kobana)](https://docs.finance.kobana.com.br/es/integracoes/kobana.md): Envío de pagos al banco y sincronización de cuentas, extractos y personas vía Kobana. #### open-finance Conecta las cuentas bancarias de la empresa por Open Finance y recibe saldos y extractos automáticamente. - [Open Finance](https://docs.finance.kobana.com.br/es/integracoes/open-finance.md): Conecta las cuentas bancarias de la empresa por Open Finance y recibe saldos y extractos automáticamente. #### whatsapp Fotos de perfil de clientes y proveedores vía Evolution API — configuración por empresa. - [Integración WhatsApp (Evolution API)](https://docs.finance.kobana.com.br/es/integracoes/whatsapp.md): Fotos de perfil de clientes y proveedores vía Evolution API — configuración por empresa. ### lancamentos Los movimientos de las cuentas financieras — entradas y salidas; la base de la conciliación. - [Transacciones](https://docs.finance.kobana.com.br/es/lancamentos.md): Los movimientos de las cuentas financieras — entradas y salidas; la base de la conciliación. #### importacao-csv Importar transacciones en lote desde una planilla — dentro de la cuenta financiera, con encabezado en portugués. - [Importación CSV — Transacciones](https://docs.finance.kobana.com.br/es/lancamentos/importacao-csv.md): Importar transacciones en lote desde una planilla — dentro de la cuenta financiera, con encabezado en portugués. ### manutencao Herramientas de higiene de los datos — personas (teléfonos, nombres, duplicados, vacíos y fotos) y movimientos duplicados. - [Mantenimiento](https://docs.finance.kobana.com.br/es/manutencao.md): Herramientas de higiene de los datos — personas (teléfonos, nombres, duplicados, vacíos y fotos) y movimientos duplicados. ### mcp #### overview - [Autenticación](https://docs.finance.kobana.com.br/es/mcp/overview/authentication.md): El servidor MCP acepta un Bearer token en el encabezado Authorization, y nada más — sin cookie, sin certificado de cliente, sin token en la URL. Una solicitud con ?accesstoken= (o ?token=, ?apikey= y similares) se rechaza con 401 y error="invalid_request", incluso junto a un encabezado válido: en la URL el token se filtra a logs, historial del navegador e intermediarios. - [Clientes](https://docs.finance.kobana.com.br/es/mcp/overview/clients.md): Cualquier cliente que hable Streamable HTTP MCP y sepa hacer el flujo OAuth 2.1 del MCP puede conectarse. Solo indicas la URL y el cliente descubre solo dónde autenticarse, abre el login de Kobana en el navegador y guarda el token. Ver Autenticación. - [Endpoints](https://docs.finance.kobana.com.br/es/mcp/overview/endpoints.md): Servidor MCP - [Errores](https://docs.finance.kobana.com.br/es/mcp/overview/errors.md): Las fallas llegan por dos canales distintos, y la distinción importa: uno es una solicitud rota, el otro es algo que el modelo debe leer y a lo que debe reaccionar. - [Idempotencia](https://docs.finance.kobana.com.br/es/mcp/overview/idempotency.md): Las tools de creación y modificación aceptan un argumento idempotency_key. Se envía al endpoint como el encabezado X-Idempotency-Key que la API REST ya respeta — ver Idempotencia en la API. - [Introducción](https://docs.finance.kobana.com.br/es/mcp/overview/introduction.md): El servidor MCP de Finanzas Inteligentes es un servidor Model Context Protocol remoto que expone las operaciones de la API pública — cuentas por pagar y por cobrar, movimientos, conciliaciones, cuentas financieras, flujo de caja y registros — como tools que un cliente de IA puede llamar. Lo conectas por URL; no hay nada que instalar. - [Listado, Filtros y Campos](https://docs.finance.kobana.com.br/es/mcp/overview/pagination.md): Las tools _list usan la misma paginación que la API REST: por cursor*. - [Límite de Solicitudes](https://docs.finance.kobana.com.br/es/mcp/overview/rate-limit.md): El servidor MCP gasta los mismos límites que la API REST, contados por persona en la organización — no por token —, más un límite propio para el protocolo. Generar un token nuevo, o reautorizar el cliente, no reinicia el presupuesto. - [Resources y prompts](https://docs.finance.kobana.com.br/es/mcp/overview/resources-and-prompts.md): Además de las tools, el servidor ofrece tres cosas que el cliente usa por su cuenta: resources (documentos que adjuntas a la conversación), prompts (guiones listos que eliges) y completions (autocompletado de los argumentos de ambos). En la era 2026-07-28, también pide confirmación antes de ejecutar una tool destructiva — incluidas las que mueven dinero. - [Transporte](https://docs.finance.kobana.com.br/es/mcp/overview/transport.md): Streamable HTTP, stateless. Un mensaje JSON-RPC 2.0 por POST, una respuesta JSON. No hay Mcp-Session-Id, no hay reanudación y no hay stream servidor→cliente: la aplicación corre varias réplicas, y ninguna operación necesita empujar mensajes al cliente. #### tools - [Cuentas financieras y flujo de caja](https://docs.finance.kobana.com.br/es/mcp/tools/accounts.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} - [Cuentas por pagar y por cobrar](https://docs.finance.kobana.com.br/es/mcp/tools/billings.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} - [Adjuntos, notas fiscales, esquemas y espacios](https://docs.finance.kobana.com.br/es/mcp/tools/documents.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} - [Tools](https://docs.finance.kobana.com.br/es/mcp/tools/overview.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} - [Registros](https://docs.finance.kobana.com.br/es/mcp/tools/registers.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} - [Movimientos y conciliación](https://docs.finance.kobana.com.br/es/mcp/tools/transactions.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} ### meus-dados La información de tu cuenta y cómo funciona el inicio de sesión sin contraseña. - [Mi perfil](https://docs.finance.kobana.com.br/es/meus-dados.md): La información de tu cuenta y cómo funciona el inicio de sesión sin contraseña. ### notas-fiscais Las notas fiscales (NF-e y NFS-e) recibidas contra las empresas del espacio — de dónde vienen, cómo se vinculan a una empresa y cómo se vuelven cuentas por pagar. - [Notas fiscales](https://docs.finance.kobana.com.br/es/notas-fiscais.md): Las notas fiscales (NF-e y NFS-e) recibidas contra las empresas del espacio — de dónde vienen, cómo se vinculan a una empresa y cómo se vuelven cuentas por pagar. ### pessoas Clientes, proveedores y contactos — roles acumulables, fotos y eliminación. - [Personas](https://docs.finance.kobana.com.br/es/pessoas.md): Clientes, proveedores y contactos — roles acumulables, fotos y eliminación. ### regras-automaticas Clasificación automática de transacciones y cuentas por criterios que tú defines. - [Reglas automáticas](https://docs.finance.kobana.com.br/es/regras-automaticas.md): Clasificación automática de transacciones y cuentas por criterios que tú defines. ### sdk Los SDKs son las bibliotecas oficiales para llamar a la API REST de Finanzas Inteligentes desde Node.js / TypeScript, Python, Ruby y PHP, sin armar solicitudes HTTP, autenticación, paginación y manejo de errores a mano. - [SDKs de Finanzas Inteligentes](https://docs.finance.kobana.com.br/es/sdk.md): Los SDKs son las bibliotecas oficiales para llamar a la API REST de Finanzas Inteligentes desde Node.js / TypeScript, Python, Ruby y PHP, sin armar solicitudes HTTP, autenticación, paginación y manejo de errores a mano. ### seguranca Reglas antifraude para pagos y transferencias — límites, cuentas, beneficiarios, tipos de operación y canales, con todo cambio aprobado por Kobana. - [Seguridad](https://docs.finance.kobana.com.br/es/seguranca.md): Reglas antifraude para pagos y transferencias — límites, cuentas, beneficiarios, tipos de operación y canales, con todo cambio aprobado por Kobana. ### transferencias Mover dinero entre cuentas del espacio de trabajo — dos transacciones espejadas. - [Transferencias](https://docs.finance.kobana.com.br/es/transferencias.md): Mover dinero entre cuentas del espacio de trabajo — dos transacciones espejadas. ### workspaces La caja que aísla los datos de cada organización — creación, cambio y eliminación. - [Espacios de trabajo](https://docs.finance.kobana.com.br/es/workspaces.md): La caja que aísla los datos de cada organización — creación, cambio y eliminación. --- # Full Documentation Content [Saltar al contenido principal](#__docusaurus_skipToContent_fallback) [![Kobana](/es/img/kobana-logo-hor-positivo.png)![Kobana](/es/img/kobana-logo-hor-negativo.png)](https://docs.finance.kobana.com.br/es/es/.md) [**Finanzas Inteligentes**](https://docs.finance.kobana.com.br/es/es/.md) Documentación [Documentación](https://docs.finance.kobana.com.br/es/es/.md)[API](https://docs.finance.kobana.com.br/es/es/api/overview.md)[MCP](https://docs.finance.kobana.com.br/es/es/mcp/overview/introduction.md)[CLI](https://docs.finance.kobana.com.br/es/es/cli/overview/introduction.md)[SDK](https://docs.finance.kobana.com.br/es/es/sdk.md) Preguntar a la IA [](#) * [🇧🇷 Português](https://docs.finance.kobana.com.br/es/pt/search) * [🇺🇸 English](https://docs.finance.kobana.com.br/es/en/search) * [🇪🇸 Español](https://docs.finance.kobana.com.br/es/es/search.md) Buscar # Buscar en la documentación ![Empresa Neutra em Carbono](/es/img/badge-neutra-carbono.webp)![Empresa Parceira da Natureza](/es/img/badge-parceira-natureza.webp) Comercial[3003-0386](tel:+551130030386) [](https://wa.me/551130030386)[](mailto:comercial@kobana.com.br) ![Kobana](/es/img/kobana-logo-site.webp)![](/es/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 --- # Adjuntos La **Biblioteca de adjuntos** (`/attachments`) guarda todos los archivos del espacio de trabajo — vinculados o no a cuentas por pagar, cuentas por cobrar y transacciones. ![Biblioteca de adjuntos](/es/assets/images/15-attachments-45de5c2df08be1b8ced40ed5a126fead.png) ## Dos puertas al mismo acervo[​](#dos-puertas-al-mismo-acervo "Enlace directo al Dos puertas al mismo acervo") Los adjuntos aparecen en dos lugares, y la diferencia es la dirección: * **La biblioteca** (`/attachments`) parte **del archivo**: subes un documento y eliges a qué registros pertenece. * **La sección Adjuntos** — dentro de una cuenta por pagar, por cobrar o de una transacción — parte **del registro**: estás en un título y eliges qué archivos vincularle. nota **Es el mismo acervo.** Todo archivo que subas cae en la biblioteca, incluidos los que subes desde un formulario. No existe el adjunto privado de un registro. El vínculo es de **muchos a muchos**: un archivo puede servir a varios registros, y un registro puede tener varios archivos. ## Alcance[​](#alcance "Enlace directo al Alcance") La biblioteca es **de todo el espacio de trabajo**, no de una empresa. Funciona con el selector del encabezado en "todas las empresas", y un archivo vinculado al título de una empresa sigue visible para todo el espacio de trabajo. ## Subir[​](#subir "Enlace directo al Subir") Haz clic en **Adjuntar archivos** y elige un archivo — arrástralo al área o haz clic en ella. | | | | ------------ | ---------------------------------------- | | **Formatos** | pdf, png, jpg, jpeg, xml, ofx, csv, xlsx | | **Tamaño** | hasta 10 MB | Un archivo por encima del límite se rechaza ahí mismo: *"El archivo supera el límite de 10 MB"*. **Es un archivo por vez**, a pesar del botón en plural. El sistema también comprueba que el **contenido coincida con la extensión** — un archivo renombrado se rechaza. ## El listado[​](#el-listado "Enlace directo al El listado") Columnas: **Nombre** (el título, cuando lo hay, con el nombre del archivo debajo), **Uso**, **Tamaño**, **Subido el** y **Subido por**. Un archivo ya vinculado a algún registro muestra la marca **Ya adjunto** en la columna Uso. * **Búsqueda** por **nombre de archivo o título** — busca en ambos, así que el archivo se encuentra tanto por su nombre original como por el nombre que le hayas puesto. * **Pestañas**: **Todos** y **Ya adjunto**. No hay filtro inverso (solo los no vinculados), ni por tipo, fecha o autor. * El listado va siempre **de lo subido más recientemente a lo más antiguo**, 25 por página. > **Hacer clic en el encabezado de una columna reordena solo la página que está en pantalla**, no toda la biblioteca. El icono a la derecha de cada fila abre una ficha con **los registros vinculados a ese archivo**, cada uno con enlace para abrirlo. No es una vista previa del archivo. ## Acciones de la fila[​](#acciones-de-la-fila "Enlace directo al Acciones de la fila") | Acción | Qué hace | | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | | **Ver** | Abre el archivo en una pestaña nueva. Los PDF y las imágenes se abren en el navegador; xml, ofx, csv y xlsx **se descargan**. | | **Editar** | Cambia el **Título** — el único campo editable | | **Vincular** | Vincula (y desvincula) el archivo de registros | | **Eliminar** | Quita el archivo de la biblioteca | ### Título[​](#título "Enlace directo al Título") El único campo que editas. Si lo rellenas, aparece en lugar del nombre del archivo en los listados; si lo dejas en blanco, vuelve a valer el nombre del archivo. No hay descripción, categoría, carpetas ni versiones, y **no se puede sustituir el archivo** — solo el título. ## Vincular[​](#vincular "Enlace directo al Vincular") **Vincular** abre un diálogo con tres pestañas — **Por pagar**, **Por cobrar** y **Transacción**. Busca por la descripción, marca los registros y confirma. Cosas que conviene saber antes: * **La selección no cruza pestañas.** Cambiar de pestaña borra las marcas, así que vincular el mismo archivo a un título y a una transacción son dos operaciones. * **El diálogo muestra los 25 primeros** de cada pestaña, sin paginación. Para el resto, usa la búsqueda. * Los registros **ya vinculados** suben al principio, ya marcados y bloqueados. **Desvincular también vive aquí**: cada fila ya vinculada tiene un botón para deshacerlo. En este camino no hay confirmación — la acción es inmediata. ## Eliminar[​](#eliminar "Enlace directo al Eliminar") nota **Un archivo vinculado no se puede eliminar.** El sistema lo rechaza y dice a cuántos registros está vinculado: *"Adjunto vinculado a 2 cuentas por pagar, 1 cuenta por cobrar y 0 transacciones."* Desvincúlalo de todos antes. **Un comprobante de pago también retiene su archivo.** Ahí no existe desvincular: el dueño del archivo es el comprobante, y el mensaje es otro — *"El adjunto es el documento de un comprobante — elimina el comprobante para quitar el archivo"*. Ver [Comprobantes](https://docs.finance.kobana.com.br/es/es/comprovantes/.md). No hay cascada: eliminar nunca borra los registros, y nunca deshace vínculos por su cuenta. El diálogo avisa: *"El archivo se eliminará permanentemente. Si está vinculado a algún registro, desvincúlalo primero."* La acción aparece en cualquier fila, incluidas las que están vinculadas — en esos casos solo descubres el bloqueo después de confirmar. ## Adjuntar desde dentro de un registro[​](#adjuntar-desde-dentro-de-un-registro "Enlace directo al Adjuntar desde dentro de un registro") En la sección **Adjuntos** de una cuenta o de una transacción, el botón **Adjuntar archivo** abre un diálogo con dos caminos, uno al lado del otro: * **Seleccionar del computador** — sube ahora. Aquí la subida arranca **en cuanto eliges el archivo**, sin botón de confirmar. * **Seleccionar de la biblioteca** — toma un archivo que ya existe. Muestra 5 por página, sin búsqueda; los ya adjuntos aparecen marcados. El pie trae **Ir a la biblioteca de adjuntos**, que lleva a `/attachments`. En esta sección, **Desvincular** pide confirmación y explica: *"El archivo permanece en la biblioteca y en cualquier otro registro al que esté vinculado."* nota **En una cuenta aún sin guardar, depende de cómo entró el archivo.** Si **subiste el archivo ahí mismo** y cambiaste de idea, Desvincular también lo borra de la biblioteca — se deshace la subida entera, que es lo que se espera de una creación abandonada. Si lo **tomaste de la biblioteca**, Desvincular solo lo suelta del borrador: el archivo era de la biblioteca antes de que empezaras y ahí sigue. --- # Referencia de la API --- # Visión general --- # Autenticación La API de Finanzas Inteligentes usa un **access token de la Cuenta Kobana** para autenticar todas las solicitudes. ## El token[​](#el-token "Enlace directo al El token") El token es un JWT `RS256` emitido por el **Authorization Server de Kobana** (`account.kobana.com.br`). Esta API solo lo **verifica**, contra la clave pública que ese servidor publica — no guarda clave de firma y no puede emitir ningún token. Requisitos comprobados en cada solicitud: | Claim | Exigencia | | ----- | ------------------------------------------------------------------------------------------------------------------------------ | | `iss` | El identificador del Authorization Server, como URL: `https://account[.{env}].kobana.com.br` | | `aud` | La URL de esta API: `https://api.finance[.{env}].kobana.com.br`. Puede ser una **lista** — la regla es *contiene*, no igualdad | | `exp` | **Obligatoria.** Un token sin expiración se rechaza | | `org` | **La cuenta Kobana** en cuyo nombre actúa el token. Es la que resuelve la organización aquí, y es **obligatoria** | | `sub` | **La persona** (`users.public_id`). Va a la auditoría y a la atribución; no limita nada | | `jti` | Id único del token — la base de la revocación y de la auditoría | El **workspace** viene del header `X-Workspace-Id`: el `org` dice la organización, y una organización puede tener varios workspaces. Es un **selector, no una concesión** — un workspace de otra organización no se alcanza adivinando su id. Sin el header, cuando hay más de un workspace, la respuesta es `400 WORKSPACE_REQUIRED`. Las excepciones son `GET /v1/me` y `GET`/`PATCH /v1/organization`: son de **nivel de organización** — responden por la organización del token y valen para todos los workspaces — y no llevan el header. :::caution Cambio respecto al token generado en el dashboard Antes la credencial era un token generado en la plataforma, con secret mostrado una única vez. El mismo valor firmaba y verificaba, así que una fuga en cualquiera de los dos lados era una fuga de la **emisión**. Ahora quien emite es el Authorization Server, y esta API solo verifica. ::: Si el Authorization Server está inalcanzable, la respuesta es **`5xx`, nunca `401`** — un `401` ahí te mandaría a depurar una credencial perfecta durante una caída nuestra. ## Cómo enviar el token[​](#cómo-enviar-el-token "Enlace directo al Cómo enviar el token") Incluye el encabezado `Authorization: Bearer ` en cada solicitud. ``` export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx curl -i \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'Content-Type: application/json' \ -H 'User-Agent: Mi Sistema (contacto@miempresa.com.br)' \ -X GET 'https://api.finance.kobana.com.br/v1/financial-accounts' ``` ## Alcances (scopes)[​](#alcances-scopes "Enlace directo al Alcances (scopes)") Los alcances tienen **dos ejes**: el **recurso**, siempre con el prefijo de la app (`finance/payables`), y el **nivel de acceso**, un alcance global sin prefijo — `read`, `write`, `delete`, `import` o `export`. Toda solicitud exige **un** nivel, dado por el método HTTP, sobre **el recurso** que nombra el endpoint; cada operación de la referencia declara el par en la frase "Requires scope `finance/` with access level ``". | Método | Nivel exigido | | ---------------------- | ------------------------------------------------------------- | | `GET` | ninguno — el alcance del recurso solo ya lee | | `POST`, `PUT`, `PATCH` | `write` — enviar un pago al banco y emitir un cobro incluidos | | `DELETE` | `delete` — **`write` no elimina** | Ningún nivel sustituye a otro: `write` no elimina, y `delete` no lee ni escribe. Un nivel también puede valer solo en un recurso, en la forma `finance/:` (`finance/payables:delete`); solo cuentan los alcances con el prefijo `finance/`. `import` y `export` son para endpoints de importación y exportación masiva — esta API no tiene ninguno hoy. Toda eliminación es un `DELETE`, y todo `DELETE` es una eliminación. | Recurso | Alcance | Qué cubre la lectura | | ------------------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Cuentas financieras | `finance/accounts` | cuentas y saldos | | Catálogo de bancos | `finance/banks` | solo lectura, no hay escritura | | Cuentas por pagar | `finance/payables` | títulos por pagar | | Cuentas por cobrar | `finance/receivables` | títulos por cobrar | | Envío al banco | `finance/payable_dispatches` | los envíos de pago y su estado | | Emisión de cobro | `finance/receivable_charges` | los cobros (boleto/Pix) emitidos | | Comprobantes de pago | `finance/receipts` | solo lectura | | Notas fiscales recibidas | `finance/fiscal_documents` | solo lectura | | Transacciones | `finance/transactions` | movimientos y transferencias | | Conciliaciones | `finance/reconciliations` | conciliaciones (la escritura cubre crear y deshacer) | | Flujo de caja proyectado | `finance/cash_flow` | solo lectura | | Empresas | `finance/companies` | | | Personas | `finance/people` | | | Categorías | `finance/categories` | | | Centros de clasificación | `finance/cost_centers` | el alcance nombra el grant, por eso `cost_centers` y no `classification-centers` como en la URL | | Reglas automáticas | `finance/automatic_rules` | la escritura incluye reordenar | | Impuestos | `finance/taxes` | | | Adjuntos | `finance/attachments` | la escritura cubre subida y gestión | | Organización | `finance/settings` | el perfil de la organización del token (`/organization`); la escritura exige el dueño de la organización o acceso a todos los espacios | | **Comodín del recurso** | `finance/all` | lee **todos** los recursos anteriores — y **no concede ningún verbo** | Dos ejemplos: `finance/payables read` lee cuentas por pagar y no escribe; `finance/payables read write delete` también crea, modifica y elimina, y sigue sin alcanzar cuentas por cobrar. La forma granular `finance/payables:write` es una **excepción** de la gramática, no el formato por defecto: satisface los dos ejes para ese recurso solo, y existe para "lee un recurso, escribe otro". `finance/*` es un comodín de **registro** y nunca se emite en un token — la comparación aquí siempre es literal. En la gramática por recurso, leer es el recurso sin verbo; el `read` que existe es el **nivel de acceso** de la Cuenta Kobana, más abajo. Reglas de resolución: * `finance/all` alcanza **todos** los recursos, pero no concede ningún nivel. `finance/all read` lee todo; para escribir se necesita el nivel: `finance/all write`. * `finance/receipts` lista los comprobantes, pero **no descarga el documento**: el `download_url` apunta al recurso de adjuntos, así que obtener los bytes exige también `finance/attachments`. * `finance/fiscal_documents` lista las notas recibidas, pero **no descarga el XML**: el `xml_download_url` apunta al recurso de adjuntos, así que obtener los bytes exige también `finance/attachments`. aviso **Mover dinero es un recurso propio, no un nivel propio.** Enviar un pago al banco (y cancelar el envío) y emitir un cobro (y cancelarlo) son `write` en recursos separados: `finance/payable_dispatches` y `finance/receivable_charges`. Un token con `finance/payables write` registra títulos y **no** dispara pagos. `finance/all write` (o `all write`) alcanza los dos, porque el comodín cubre todo recurso. Un token solo con el nivel `write`, sin alcance por recurso, no alcanza nada. ### Nivel de acceso[​](#nivel-de-acceso "Enlace directo al Nivel de acceso") El alcance **se exige en toda ruta** (solo `GET /me` lo dispensa, para que pruebes un token). Los alcances por recurso de arriba están registrados en la Cuenta Kobana, y el token personal los lleva según los recursos que marcaste. Todo token lleva también el **nivel de acceso** que concediste al autorizar, y solo vale dentro del alcance de los alcances de recurso (`finance/…` o `all`). **Un token sin alcance de recurso de esta app — solo con niveles (`read write`) o solo con recursos de otra app (`billing/invoices write`) — no alcanza nada**; solo `GET /me` lo atiende. Dentro del alcance: | Nivel | Qué alcanza | | ------------------- | --------------------------------------------------------------------------------------------------------- | | `read` | lectura (`GET`) — el alcance del recurso solo ya lee | | `write` | toda escritura (`POST`, `PUT`, `PATCH`), incluidos enviar pagos al banco y emitir cobros — **no elimina** | | `delete` | `DELETE`, y solo eso | | `import` / `export` | importación / exportación masiva (ningún endpoint hoy) | **`all` no es un nivel de acceso.** Es el comodín de recurso, igual a `finance/all`: alcanza todo recurso y no concede ningún verbo. `all` solo lee todo; `all write` lee y escribe todo; eliminar, importar y exportar exigen el verbo explícito (`all delete`). **Cuando el token lleva alcances por recurso** — el token personal que creas en la Cuenta Kobana, por ejemplo —, **son ellos los que definen el alcance**, y los niveles solo valen dentro de esos recursos: `finance/payables read write` lee y escribe cuentas por pagar y nada más; `finance/all read` (o solo `all`) lee todo y no escribe nada. Si falta cualquiera de los dos ejes, la respuesta es `403 INSUFFICIENT_SCOPE`, con `required` (el conjunto mínimo de alcances a sumar — el recurso primero, después el verbo: `["finance/payables", "delete"]`), `access` (el verbo de la solicitud) y `granted` en `details`. Un token sin ningún alcance de recurso que esta API reconozca no alcanza nada. :::caution Cambios incompatibles * Los alcances antiguos `finance.`, `finance..write`, `finance.all`, `finance.all.write` y los sufijos `.dispatch` / `.charge` **ya no se aceptan**: usa `finance/` y los niveles de acceso. * Un `DELETE` exige `delete`: `write` ya no elimina. * Un token solo con niveles de acceso, sin alcance `finance/…` ni `all`, ya no alcanza nada (antes alcanzaba todo recurso). Pide los recursos junto, o `all`. * `all` ya no concede ningún verbo: es el comodín de recurso, como `finance/all`. Un token solo con `all` pasa a solo leer; para escribir, eliminar, importar o exportar, pide el verbo junto (`all write delete`). * Enviar al banco y emitir un cobro exigen `write` (en el recurso de dinero, cuando el token lleva alcances por recurso); `all` ya no se exige. * Desvincular un adjunto pasó de `DELETE /v1/attachments/{id}/links` a `POST /v1/attachments/{id}/unlink`, con el mismo cuerpo `{ type, id }`. * El `details` del `403 INSUFFICIENT_SCOPE` trae `required` como lista: el conjunto mínimo de alcances que falta (ej. `["finance/payables", "delete"]`), nunca vacío; `accepted_levels` salió. ::: ## Buenas prácticas[​](#buenas-prácticas "Enlace directo al Buenas prácticas") * **Nunca** versiones tokens en git. Usa variables de entorno o bóvedas (AWS Secrets Manager, Vault, etc.). * Usa tokens distintos por integración — facilita rotarlos/revocarlos sin tumbar todo. * Pide los alcances mínimos necesarios (principio del menor privilegio) — `read` cuando la integración solo lee, `delete` solo para quien elimina, y el recurso de dinero (`finance/payable_dispatches`, `finance/receivable_charges`) solo para quien envía al banco o cobra. * Revoca inmediatamente cualquier token filtrado. * Apunta siempre a `https://` — las llamadas en el puerto 80 son redirigidas al 443, pero los clientes no reenvían el cuerpo en un redirect. --- # Retención de datos Esta página describe por cuánto tiempo se conserva cada tipo de dato en Finanzas Inteligentes. ## Workspaces activos[​](#workspaces-activos "Enlace directo al Workspaces activos") | Tipo de dato | Retención | | ------------------------------------- | --------------- | | Logs de Solicitudes de la API | 30 días | | Transacciones | Indefinidamente | | Cuentas por Pagar | Indefinidamente | | Cuentas por Cobrar | Indefinidamente | | Cuentas Financieras | Indefinidamente | | Empresas y Personas | Indefinidamente | | Categorías y Centros de Clasificación | Indefinidamente | | Adjuntos | Indefinidamente | | Cualquier dato no listado | Indefinidamente | ## Workspaces inactivos[​](#workspaces-inactivos "Enlace directo al Workspaces inactivos") Los workspaces sin acceso durante un período prolongado pueden tener sus datos archivados. Ponte en contacto con el soporte para la restauración. Los tiempos indicados arriba pueden ser modificados en cualquier momento. --- # Endpoints | Ambiente | Plataforma (acceso web) | API (v1) | | -------------- | ------------------------------------------------------------------------------ | ---------------------------------------------- | | **Producción** | [app.finance.kobana.com.br](https://app.finance.kobana.com.br) | `https://api.finance.kobana.com.br/v1` | | **Sandbox** | [app.finance.sandbox.kobana.com.br](https://app.finance.sandbox.kobana.com.br) | `https://api.finance.sandbox.kobana.com.br/v1` | Esta documentación está publicada en [docs.finance.kobana.com.br](https://docs.finance.kobana.com.br). tip Desarrolla contra el **sandbox** y cambia a producción solo modificando la base URL — los contratos son los mismos. --- # Errores Toda respuesta de error usa un sobre JSON estable. aviso **Ramifica tu lógica por el `code`, nunca por el texto de `message`** — el mensaje es legible por humanos y puede cambiar; el `code` es el contrato. ## Sobre[​](#sobre "Enlace directo al Sobre") ``` { "error": { "code": "VALIDATION_ERROR", "message": "Request body validation failed.", "details": { "issues": [ { "path": "amount", "code": "invalid_type", "message": "Expected number, received string" } ] } } } ``` | Campo | Descripción | | --------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `error.code` | Código estable (tabla de abajo). Ramifica por él. | | `error.message` | Texto legible, en inglés. **No lo parsees.** | | `error.details` | Presente en algunos errores — datos estructurados útiles (campo ofensor, motivo, scope faltante). Mira los ejemplos de abajo. | ## Códigos[​](#códigos "Enlace directo al Códigos") | `code` | HTTP | Cuándo | | ------------------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BAD_REQUEST` | 400 | Query/body malformado — JSON inválido, filtro/operador desconocido, cursor inválido, valor de filtro vacío, `limit` inválido. | | `INVALID_TOKEN` | 401 | Token ausente, malformado, firma inválida o expirado. | | `INVALID_AUDIENCE` | 401 | El `aud` del token no es aceptado. | | `TOKEN_REVOKED` | 401 | Token revocado. | | `INSUFFICIENT_SCOPE` | 403 | Token válido, pero sin el scope exigido. `details.required` es el conjunto mínimo de scopes a sumar al token para que la solicitud pase — el scope del recurso primero (`finance/`, o `finance/all` fuera del catálogo), después el verbo; nunca vacío, nunca `all`. `details` trae también `access` y `granted`. | | `UNKNOWN_ORGANIZATION` | 403 | El `sub` del token no corresponde a ningún workspace. | | `NOT_FOUND` | 404 | Recurso inexistente **o fuera de tu workspace** — por aislamiento, un recurso de otro tenant se lee como `404`. | | `CONFLICT` | 409 | Conflicto de estado: solicitud idéntica todavía en curso, o carrera en una constraint única. | | `IDEMPOTENCY_KEY_REUSED` | 409 | `X-Idempotency-Key` reutilizada con un cuerpo distinto. Reenvía los parámetros originales o genera una clave nueva. | | `VALIDATION_ERROR` | 422 | El cuerpo no satisface el schema — campo ausente, tipo equivocado, clave desconocida. `details.issues` dice dónde. Reenviar el mismo cuerpo no sirve. | | `UNPROCESSABLE_ENTITY` | 422 | Cuerpo bien formado que el dominio rechazó — FK fuera del tenant, transición de estado inválida. Puede pasar cuando el estado cambie. | | `RATE_LIMITED` | 429 | Límite de solicitudes alcanzado. Mira [Límite de solicitudes](https://docs.finance.kobana.com.br/es/es/api/overview/rate-limit.md). | | `INTERNAL_ERROR` | 500 | Falla inesperada en el servidor. **Nunca** trae `details`. Reenvía con backoff. | ## Ejemplos de `details`[​](#ejemplos-de-details "Enlace directo al ejemplos-de-details") **Validación de schema (422):** ``` { "error": { "code": "VALIDATION_ERROR", "message": "Request body validation failed.", "details": { "issues": [ { "path": "amount", "code": "invalid_type", "message": "Expected number, received string" } ] } } } ``` **Scope insuficiente (403):** ``` { "error": { "code": "INSUFFICIENT_SCOPE", "message": "Token is missing required scope: `finance/payable_dispatches`, to change payable_dispatches.", "details": { "required": ["finance/payable_dispatches"], "access": "write", "granted": ["finance/payables", "read", "write"] } } } ``` **Idempotency-Key reutilizada con un cuerpo distinto (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." } } ``` --- # Selección de campos Las lecturas de registros — los listados y los `GET` de un ítem — aceptan `?fields=` para devolver solo las columnas que vas a usar: ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: Mi Sistema (contacto@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": "Alquiler", "amount": 1500.5, "due_date": "2026-11-10T00:00:00.000Z" } ], "meta": { "next_cursor": null } } ``` Reglas: * Nombres separados por coma, en snake\_case — los mismos que trae la respuesta completa. * Sin el parámetro (o con él vacío), vuelven **todos** los campos. * El **`id` siempre vuelve**, aunque no se pida. * Solo el **primer nivel**: pedir un campo que es objeto (`reconciliation`, `classification_centers`) devuelve el objeto entero. No existe la sintaxis `objeto.campo`. * Un nombre que el recurso no tiene → `400 BAD_REQUEST`, con `details.unknown` (lo que no se reconoció) y `details.available` (lo que existe). Un nombre equivocado nunca se ignora en silencio. * El `meta` del listado no se altera — el `next_cursor` sigue ahí. * Se combina con [filtros, ordenación](https://docs.finance.kobana.com.br/es/es/api/overview/filtering.md) y [paginación](https://docs.finance.kobana.com.br/es/es/api/overview/pagination.md). No aplica a escrituras (que devuelven el registro entero), a los totales (`/aggregates`, `/cash-flow`), al barrido de ids (`/ids`) ni a la descarga de adjuntos — ahí el parámetro se rechaza con `400`. --- # Filtros y ordenación Los endpoints `GET` de colección aceptan filtros y ordenación por query string, además de la [paginación por cursor](https://docs.finance.kobana.com.br/es/es/api/overview/pagination.md). **Qué campos son filtrables y ordenables varía por recurso** — consulta la [especificación OpenAPI](https://docs.finance.kobana.com.br/es/es/api/overview/openapi.md) de cada endpoint. Aquí está la **gramática** común. ## Filtros[​](#filtros "Enlace directo al Filtros") Sintaxis: `?campo=valor` (igualdad) o `?campo[operador]=valor`. | Operador | Sintaxis | Significado | | ---------------- | ----------------------------------- | ---------------------------------- | | `eq` (implícito) | `?status=paid` o `?status[eq]=paid` | Igual a | | `in` | `?status[in]=pending,paid` | Está en (lista separada por comas) | | `gte` | `?due_date[gte]=2026-01-01` | Mayor o igual | | `lte` | `?due_date[lte]=2026-01-31` | Menor o igual | | `gt` | `?amount[gt]=100.00` | Mayor que | | `lt` | `?amount[lt]=100.00` | Menor que | | `not` | `?status[not]=cancelled` | Distinto de | Reglas: * Cada recurso permite un **subconjunto** de campos y operadores; un campo u operador fuera de la allowlist → `400 bad_request`. * `eq` siempre está permitido cuando el campo es filtrable. * Valor vacío (`?campo=` o `?campo[in]=`) → `400`. Omite el parámetro para no filtrar. * Varios filtros se combinan con **Y** lógico. ## Ordenación[​](#ordenación "Enlace directo al Ordenación") `?sort_by=campo` elige el campo y `?sort_order=asc|desc` la dirección (por defecto `asc`). Un único campo a la vez; un campo fuera de la allowlist → `400`, y también `sort_order` sin `sort_by`. ## Ejemplo[​](#ejemplo "Enlace directo al Ejemplo") ``` # Cuentas por pagar de una empresa, con vencimiento en enero, más recientes primero curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: Mi Sistema (contacto@example.com)' \ 'https://api.finance.kobana.com.br/v1/payables?company_id=00000000-0000-0000-0000-000000000001&due_date[gte]=2026-01-01&due_date[lte]=2026-01-31&sort_by=due_date&sort_order=desc&limit=100' ``` ## Combinando con paginación[​](#combinando-con-paginación "Enlace directo al Combinando con paginación") Los filtros y la ordenación se mantienen entre páginas — pasa el `cursor` de la respuesta anterior junto con los **mismos** filtros. Ver [Listado y Paginación](https://docs.finance.kobana.com.br/es/es/api/overview/pagination.md). --- # Idempotencia La API soporta idempotencia para reintentar solicitudes de forma segura, sin ejecutar la misma operación dos veces. Útil cuando una llamada se interrumpe en tránsito y no recibes respuesta — por ejemplo, una solicitud para crear una cuenta por pagar que falla por un error de red puede reintentarse con la misma clave, garantizando que solo se cree un registro. ## Cómo usarlo[​](#cómo-usarlo "Enlace directo al Cómo usarlo") Envía el encabezado `X-Idempotency-Key: ` en cualquier solicitud `POST`, `PUT` o `PATCH`. La clave es libre, generada por tu lado. Recomendamos `UUID v4` u otra cadena aleatoria con entropía suficiente para evitar colisiones. En las **acciones de dinero** el encabezado es **obligatorio**: enviar al banco, cancelar el envío, emitir un cobro y cancelar un cobro responden `400 bad_request` (`details.reason = "idempotency_key_required"`) sin él. ``` curl -i \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: 8c0f5d6e-3f8b-4cb5-9a47-d8f5b15e9b21' \ -H 'User-Agent: Mi Sistema (contacto@example.com)' \ -d '{ "account_id": "00000000-0000-0000-0000-000000000001", "description": "Alquiler Enero/2026", "amount": 3500.0, "due_date": "2026-01-10" }' \ -X POST 'https://api.finance.kobana.com.br/v1/payables' ``` ## Cómo funciona[​](#cómo-funciona "Enlace directo al Cómo funciona") Cuando el servidor recibe una solicitud con `X-Idempotency-Key`: 1. **Reserva la clave** de forma atómica, en el ámbito del **workspace**. Dos workspaces distintos pueden usar la misma clave sin conflicto. 2. **Calcula la huella de la solicitud** — SHA-256 de `método + ruta + cuerpo en bruto`. Ese hash se almacena junto a la clave. 3. **Ejecuta el handler**. Si devuelve una respuesta, el servidor registra `status_code`, cuerpo y encabezados relevantes vinculados a la clave. 4. **Marca la clave como completada**. Cualquier nueva solicitud con la misma clave dentro de **24 horas** recibe la respuesta original verbatim — mismo `status_code`, mismo cuerpo, mismos encabezados — más el encabezado `X-Idempotent-Replay: true` para indicar que se trata de una reejecución. aviso La capa guarda el resultado **independientemente de si fue éxito o fracaso**. Los reintentos con la misma clave devuelven el mismo resultado, **incluyendo errores `5xx`** — para volver a intentarlo de verdad después de un error del servidor, genera una clave nueva. ### Límites[​](#límites "Enlace directo al Límites") * Longitud máxima de la clave: **255 caracteres**. * Retención: las claves expiran automáticamente **24 horas** después de su creación. * Ámbito: por workspace. Una clave usada en un workspace no interfiere con otro. * Caracteres aceptados: cualquier cadena UTF-8 imprimible. ## Conflictos[​](#conflictos "Enlace directo al Conflictos") Si la misma clave se reutiliza con una solicitud diferente (cualquier cambio en método, ruta o cuerpo), la API responde `409` con el código `IDEMPOTENCY_KEY_REUSED`. ``` { "error": { "code": "IDEMPOTENCY_KEY_REUSED", "message": "X-Idempotency-Key was already used with different request parameters. Reuse the original parameters or generate a new key." } } ``` ## Métodos aceptados[​](#métodos-aceptados "Enlace directo al Métodos aceptados") | Método | ¿Acepta `X-Idempotency-Key`? | | -------- | ---------------------------------------- | | `POST` | ✅ Sí | | `PUT` | ✅ Sí | | `PATCH` | ✅ Sí | | `GET` | ❌ No (ya es idempotente por definición) | | `DELETE` | ❌ No (ya es idempotente por definición) | ## Buenas prácticas[​](#buenas-prácticas "Enlace directo al Buenas prácticas") * **Una clave por operación lógica**. No reutilices la misma clave para crear dos recursos diferentes — recibirás `409 IDEMPOTENCY_KEY_REUSED`. * **Persiste la clave junto con el estado de la operación** en tu lado, para que el reintento tras un crash o reinicio use la misma clave. * **Combínalo con backoff exponencial** al recibir `5xx` o timeout. * **Descarta la clave después de 24 horas**. No hay ganancia en mantenerla en tu lado después de ese plazo. --- # Introducción Tú que eres dev, ¡diviértete! ✨ La API de Finanzas Inteligentes es **REST sobre HTTPS, con JSON y autenticación Bearer**. Todo lo que las pantallas hacen con cuentas por pagar, cuentas por cobrar, transacciones, registros y conciliaciones está disponible para tus sistemas — con el mismo aislamiento por espacio de trabajo del producto. ## Primeros pasos[​](#primeros-pasos "Enlace directo al Primeros pasos") 1. **Genera un token** en la plataforma, en **Integraciones → Token de API** — ver [Autenticación](https://docs.finance.kobana.com.br/es/es/api/overview/authentication.md). 2. **Haz la primera llamada**: ``` export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: Mi Sistema (contacto@miempresa.com.br)' \ 'https://api.finance.kobana.com.br/v1/financial-accounts' ``` 3. **Explora los recursos** — la categoría **Recursos**, en la barra lateral, documenta cada endpoint con ejemplos. O importa la [especificación OpenAPI](https://docs.finance.kobana.com.br/es/es/api/overview/openapi.md) / la [colección de Postman](https://docs.finance.kobana.com.br/es/es/api/overview/postman.md). tip Prefiere el **sandbox** (`https://api.finance.sandbox.kobana.com.br/v1`) para desarrollar — ver [Endpoints](https://docs.finance.kobana.com.br/es/es/api/overview/endpoints.md). ## Formato[​](#formato "Enlace directo al Formato") La API acepta únicamente el formato `JSON`. Todas las solicitudes deben usar `Content-Type: application/json`. Todas las respuestas usan `snake_case`. | Tipo de campo | Formato | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **DateTime** | Formato [ISO8601](https://es.wikipedia.org/wiki/ISO_8601). Ejemplos — Fecha: `2026-01-24`. Fecha y Hora: `2026-01-24T10:07Z` | | **Money** | **String decimal** con 2 decimales y punto como separador, en BRL. Ej.: `"100.00"`. Siempre enviado/recibido como string (nunca número), para preservar la precisión de los centavos; hasta 13 dígitos enteros. Las transacciones y títulos son siempre positivos — la dirección (débito/crédito, costo/ingreso) va en `type`/polaridad, nunca en el signo. Los saldos de cuenta pueden ser negativos | | **UUID** | Identificadores de recursos en formato UUID v4 | ## Convenciones[​](#convenciones "Enlace directo al Convenciones") Convenciones usadas en esta documentación: | Convención | Descripción | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`:variable`** | Nombre de variable que debe ser reemplazada en una URL. | | **`#{variable}`** | Nombre de variable que debe ser reemplazada por valores de tu cuenta. | | **`...`** | Contenido de la respuesta truncado para facilitar la lectura. | | **`$KOBANA_TOKEN`** | Token de acceso. Para pruebas en línea de comandos, expórtalo: `export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx` y pega los comandos de la documentación en la terminal. | ## Códigos de respuesta[​](#códigos-de-respuesta "Enlace directo al Códigos de respuesta") La API devuelve códigos HTTP estándar: | | Código | Descripción | | -- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | ✅ | **200 OK** | Solicitud exitosa. Toda respuesta de éxito trae cuerpo, incluido `DELETE`: `{ "data": { "id": "…", "deleted": true } }`. | | ✅ | **201 Created** | Recurso creado exitosamente. | | ❌ | **400 Bad Request** | Solicitud inválida, generalmente contenido malformado. | | ❌ | **401 Unauthorized** | Token de acceso ausente o inválido. | | ❌ | **403 Forbidden** | Acceso a la API bloqueado o usuario sin permiso. | | ❌ | **404 Not Found** | La dirección solicitada no existe. | | ❌ | **409 Conflict** | Conflicto con el estado actual del recurso — p.ej. reutilizar una `X-Idempotency-Key` con otro cuerpo. | | ❌ | **422 Unprocessable Entity** | Solicitud válida, pero los datos enviados no lo son. | | ❌ | **429 Too Many Requests** | Límite de solicitudes alcanzado. | | ❌ | **500 Internal Server Error** | Error interno en el procesamiento. Consulta el [estado de los servidores](https://status.kobana.com.br). | El envoltorio y el vocabulario estable de códigos de error están en [Errores](https://docs.finance.kobana.com.br/es/es/api/overview/errors.md). ## ID de solicitudes (Request-Id)[​](#id-de-solicitudes-request-id "Enlace directo al ID de solicitudes (Request-Id)") Cada solicitud tiene un identificador asociado, disponible en el encabezado `Request-Id` de la respuesta. Este valor ayuda en la depuración y auditoría — las solicitudes y sus IDs pueden consultarse en el panel del sistema. El registro de solicitudes está disponible por **30 días**. Al abrir un ticket de soporte sobre una solicitud específica, informa el `Request-Id` para agilizar la investigación. ## Seguridad[​](#seguridad "Enlace directo al Seguridad") La API de Finanzas Inteligentes usa certificados **SSL de 2048 bits**. Toda solicitud debe realizarse a través de **HTTPS** — las llamadas en el puerto 80 son redirigidas al 443. Los clientes deben soportar `TLSv1.2` o `TLSv1.3` con uno de los siguientes cifrados: `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` y `TLSv1.1` no son compatibles. ## Caché HTTP[​](#caché-http "Enlace directo al Caché HTTP") Usa los encabezados HTTP de caché para reducir la carga y ganar velocidad. La mayoría de las respuestas incluyen `ETag` y/o `Last-Modified` — almacena estos valores y reenvíalos en las siguientes solicitudes mediante `If-None-Match` e `If-Modified-Since`. Si el recurso no ha cambiado, la respuesta será `304 Not Modified`, sin cuerpo y sin reprocesamiento. Más información: [HTTP Cache Docs](http://www.mnot.net/cache_docs/). ## Manejo de errores[​](#manejo-de-errores "Enlace directo al Manejo de errores") Los errores 5xx indican fallas en el servidor: **500 Internal Server Error** (aplicación no disponible), **502 Bad Gateway**, **503 Service Unavailable** y **504 Gateway Timeout** (fallas puntuales de infraestructura). Tu aplicación debe identificar estos códigos y reprogramar la solicitud después de unos minutos con backoff. Estado de los servidores: . ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Especificaciones](https://docs.finance.kobana.com.br/es/es/api/overview/openapi.md) — OpenAPI 3.1 en YAML para descargar. * [Endpoints](https://docs.finance.kobana.com.br/es/es/api/overview/endpoints.md) — URLs de producción y sandbox. * [User-Agent](https://docs.finance.kobana.com.br/es/es/api/overview/user-agent.md) — encabezado para identificar tu aplicación. * [Límite de solicitudes](https://docs.finance.kobana.com.br/es/es/api/overview/rate-limit.md) — throttling y encabezados de respuesta. * [Listado y paginación](https://docs.finance.kobana.com.br/es/es/api/overview/pagination.md) — cursor y envoltorio de las colecciones. * [Filtros y ordenación](https://docs.finance.kobana.com.br/es/es/api/overview/filtering.md) — gramática de `?campo[operador]=`, `?sort_by=` y `?sort_order=`. * [Selección de campos](https://docs.finance.kobana.com.br/es/es/api/overview/fields.md) — `?fields=` para devolver solo las columnas que usas. * [Idempotencia](https://docs.finance.kobana.com.br/es/es/api/overview/idempotency.md) — `X-Idempotency-Key` para reintentos seguros. * [Errores](https://docs.finance.kobana.com.br/es/es/api/overview/errors.md) — envoltorio y vocabulario de códigos de error. * [Retención de datos](https://docs.finance.kobana.com.br/es/es/api/overview/data-retention.md) — política de retención por tipo de recurso. --- # OpenAPI La especificación de la API de Finanzas Inteligentes está disponible en formato OpenAPI 3.1 para importar en la herramienta de tu preferencia. ## OpenAPI 3.1[​](#openapi-31 "Enlace directo al OpenAPI 3.1") | Versión | Idioma | Archivo | | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | v1 | Português | [openapi-v1-pt.yaml](https://docs.finance.kobana.com.br/es/es/assets/files/openapi-v1-pt-9a63c71c25a9b0816c435bf01a39950f.yaml) | | v1 | English | [openapi-v1-en.yaml](https://docs.finance.kobana.com.br/es/es/assets/files/openapi-v1-en-152fe871601f9ff86730d43fa9d0f068.yaml) | | v1 | Español | [openapi-v1-es.yaml](https://docs.finance.kobana.com.br/es/es/assets/files/openapi-v1-es-e15db594e818543214dbd31b2ba92c0b.yaml) | También disponible a través de la propia API en tiempo real, en el host de producción o de sandbox (incluye la URL del servidor actual): | Formato | Endpoint | | ------- | ---------------------- | | YAML | `GET /v1/openapi.yaml` | | JSON | `GET /v1/openapi.json` | ## Colección de Postman[​](#colección-de-postman "Enlace directo al Colección de Postman") Disponible también como colección lista para importar en Postman. Detalles y archivos en [Postman](https://docs.finance.kobana.com.br/es/es/api/overview/postman.md). --- # Listado y paginación Todos los endpoints `GET` que devuelven colecciones usan paginación por **cursor**. ## Parámetros[​](#parámetros "Enlace directo al Parámetros") Enviados vía query string: | Parámetro | Tipo | Default | Descripción | | --------- | ------------ | ------- | ------------------------------------------------------------------ | | `limit` | entero 1–100 | `25` | Cantidad de ítems por página. Máximo **100**. | | `cursor` | string | — | Cursor opaco devuelto en `meta.next_cursor` de la página anterior. | ## Respuesta[​](#respuesta "Enlace directo al Respuesta") Toda respuesta exitosa de la API viene en `{ data }`. En un listado, `data` es el array de la página y `meta` trae el cursor: ``` { "data": [ { "id": "00000000-0000-0000-0000-000000000001", "name": "Conta Corrente" } ], "meta": { "next_cursor": "eyJpZCI6Mn0" } } ``` | Campo | Descripción | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | `data` | Array con los ítems de la página actual. En un recurso único (`GET /{id}`, `POST`, `PATCH`, `DELETE`) es el objeto en lugar del array. | | `meta.next_cursor` | Cursor para la próxima página. `null` cuando no hay más ítems. | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") ### Primera página[​](#primera-página "Enlace directo al Primera página") ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: Mi Sistema (contacto@example.com)' \ 'https://api.finance.kobana.com.br/v1/financial-accounts?limit=25' ``` ### Próxima página[​](#próxima-página "Enlace directo al Próxima página") ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'User-Agent: Mi Sistema (contacto@example.com)' \ 'https://api.finance.kobana.com.br/v1/financial-accounts?limit=25&cursor=eyJpZCI6Mn0' ``` ## Iterando todas las páginas[​](#iterando-todas-las-páginas "Enlace directo al Iterando todas las páginas") Patrón recomendado en pseudocódigo: ``` async function fetchAll(url, token) { const out = []; let cursor = null; while (true) { const params = cursor ? `?limit=100&cursor=${cursor}` : '?limit=100'; const res = await fetch(`${url}${params}`, { headers: { Authorization: `Bearer ${token}` }, }); const { data, meta } = await res.json(); out.push(...data); if (!meta.next_cursor) break; cursor = meta.next_cursor; } return out; } ``` ## Buenas prácticas[​](#buenas-prácticas "Enlace directo al Buenas prácticas") * `limit=100` minimiza el número de solicitudes y consume menos del [límite de solicitudes](https://docs.finance.kobana.com.br/es/es/api/overview/rate-limit.md). * Aplica [filtros](https://docs.finance.kobana.com.br/es/es/api/overview/filtering.md) (ej.: `?company_id=`, `?occurred_at[gte]=2026-01-01`) para reducir el volumen antes de paginar. aviso **El cursor es opaco** — no intentes decodificarlo ni construirlo manualmente. Guárdalo exactamente como vino en `meta.next_cursor` y devuélvelo en `?cursor=`. --- # Postman Descarga la colección en el idioma de tu preferencia e impórtala en Postman, o abre la versión online directamente desde el workspace público de Kobana. ## Workspace público[​](#workspace-público "Enlace directo al Workspace público") Las colecciones v1 de la API de Finanzas Inteligentes están publicadas en el workspace [**universokobana/kobana-finance-api**](https://www.postman.com/universokobana/kobana-finance-api/overview), con una colección por idioma. ## Colección online[​](#colección-online "Enlace directo al Colección online") Ábrela directamente en Postman (web o app): [**API de Finanzas Inteligentes (v1.0.0) — Portugués**](https://www.postman.com/universokobana/kobana-finance-api/collection/46791755-98450bf6-afcd-4de0-8072-7632cad6445b) ## Colecciones descargables[​](#colecciones-descargables "Enlace directo al Colecciones descargables") Importa el archivo `.json` directamente en Postman (**File → Import**): | Versión | Idioma | Archivo | | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | v1 | Português | [postman-v1-pt.json](https://docs.finance.kobana.com.br/es/es/assets/files/postman-v1-pt-2805a6b38f13dd4bdf8c3b8ab53636a5.json) | | v1 | English | [postman-v1-en.json](https://docs.finance.kobana.com.br/es/es/assets/files/postman-v1-en-9bce9f42b878da0bc64550a5d2670a02.json) | | v1 | Español | [postman-v1-es.json](https://docs.finance.kobana.com.br/es/es/assets/files/postman-v1-es-5df4535af8486782d042bb3326191e79.json) | ## Uso[​](#uso "Enlace directo al Uso") 1. Descarga e importa el archivo `.json` en Postman (**File → Import**) — o abre la [colección online](#colecci%C3%B3n-online) directamente. 2. Abre la pestaña **Variables** de la colección y rellena: * `baseUrl` — producción (`https://api.finance.kobana.com.br/v1`) o sandbox (`https://api.finance.sandbox.kobana.com.br/v1`). * `bearerToken` — tu JWT, generado en la configuración de la plataforma en **Integraciones → Token de API**. 3. La autenticación `Bearer` ya viene configurada a nivel de colección, apuntando a `{{bearerToken}}`. 4. Abre cualquier request, ajusta los parámetros si es necesario y haz clic en **Send**. --- # Límite de solicitudes Los límites son por **ventana deslizante de 1 hora** — cada solicitud cuenta contra el límite durante los 60 minutos siguientes; no hay un reinicio a hora fija — y se separan en tres franjas: **lectura** (`GET`), **escritura** (`POST`, `PUT`, `PATCH`, `DELETE`) y las **acciones que mueven dinero**, que tienen su propio cubo, más restrictivo. | Tipo | Límite | | --------------------------------------------------------------------------- | ------------------------- | | Lectura (`GET`) | **60 solicitudes/hora** | | Escritura (`POST`, `PUT`, `PATCH`, `DELETE`) | **1000 solicitudes/hora** | | Movimiento de dinero (emitir/cancelar cobro, enviar/cancelar pago al banco) | **60 solicitudes/hora** | Las acciones que mueven dinero cuentan solo contra su propia franja (`throttle_v1_money`), no contra la de escritura. Si tu operación necesita un número mayor, habla con el soporte o el área comercial. ## Headers de respuesta[​](#headers-de-respuesta "Enlace directo al Headers de respuesta") En cada solicitud, el servidor adjunta a los encabezados de la respuesta los límites utilizados y cuándo se libera el conteo: | Header | Ejemplo | Descripción | | ----------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `X-RateLimit-Limit` | `60` | Límite de solicitudes para el cliente. | | `X-RateLimit-Name` | `throttle_v1_write` | Nombre del throttle utilizado. | | `X-RateLimit-Remaining` | `0` | Número de solicitudes disponibles. | | `X-RateLimit-Reset` | `1782648000000` | [Unix time](https://en.wikipedia.org/wiki/Unix_time) en **milisegundos** — cuándo se reinicia el conteo. | | `Retry-After` | `30` | Segundos hasta que el conteo se reinicie. Ver [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). | ### Ejemplo de respuesta en éxito[​](#ejemplo-de-respuesta-en-éxito "Enlace directo al Ejemplo de respuesta en éxito") ``` Date: Fri, 17 Jul 2026 12:00:00 GMT Content-Type: application/json; charset=utf-8 X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 486 ``` ### Ejemplo de respuesta en bloqueo[​](#ejemplo-de-respuesta-en-bloqueo "Enlace directo al Ejemplo de respuesta en bloqueo") Cuando se alcanza el límite, el servidor devuelve `HTTP 429 Too Many Requests`. Espera el número de segundos del header `Retry-After` antes de la próxima solicitud. ``` 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 Usa `limit=100` en los [listados](https://docs.finance.kobana.com.br/es/es/api/overview/pagination.md) y los [filtros](https://docs.finance.kobana.com.br/es/es/api/overview/filtering.md) para reducir el número de solicitudes — y trata el `429` con backoff según el `Retry-After`, nunca con reintento inmediato. Referencia: [RateLimit header fields for HTTP](https://ietf-wg-httpapi.github.io/ratelimit-headers/draft-ietf-httpapi-ratelimit-headers.html) --- # User-Agent El encabezado `User-Agent` identifica tu integración. Incluye tu nombre y una dirección de correo electrónico válida para que el equipo de Kobana pueda ponerse en contacto en caso de que: 1. Estés haciendo algo mal, y podamos avisarte antes de bloquear; 2. Estés haciendo algo muy genial, y podamos felicitarte 🙂 Ejemplo: ``` User-Agent: Mi Nombre (minombre@example.com) ``` Ejemplo de cómo pasar este encabezado usando cURL: ``` curl -i \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'Content-Type: application/json' \ -H 'User-Agent: Mi Nombre (minombre@example.com)' \ -X GET 'https://api.finance.kobana.com.br/v1/financial-accounts' ``` aviso Envía este encabezado en **todas** las solicitudes — queda registrado en el log de accesos de la API y es lo que identifica tu integración en un contacto con soporte. --- # Aprobar pagos **Aprobar pagos** (`/payables/approvals`) es la puerta de entrada de las cuentas por pagar: un título nuevo — creado por formulario, CSV o API — **no entra en la lista oficial** hasta que alguien lo apruebe. Es la traba contra el registro indebido — nada que una persona (o la API) cree como obligación nueva se convierte en dinero que sale sin un segundo par de ojos. Viene **activada por defecto** y se puede desactivar por espacio de trabajo (ver [Activar o desactivar](#activar-o-desactivar)). ## Dónde está[​](#dónde-está "Enlace directo al Dónde está") Menú **Financiero** → **Aprobar pagos**, justo debajo de Cuentas por Pagar. El ítem muestra un **badge con el número de títulos que aún necesitan aprobación** — los en espera y los aprobados parcialmente, no los ya aprobados o rechazados. El número respeta la empresa seleccionada en el encabezado. ## Activar o desactivar[​](#activar-o-desactivar "Enlace directo al Activar o desactivar") La aprobación es una **configuración del espacio de trabajo**, y viene **activada por defecto**. El control está en la pantalla **Configuración de Aprobación**, que se abre con el **ícono de engranaje, en la esquina superior derecha de esta pantalla** — el interruptor **"Exigir aprobación"**, con la explicación de los dos estados justo debajo. | Estado | Qué pasa al crear un título | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Activada** (por defecto) | Entra en la cola y solo se vuelve oficial después de que alguien lo aprueba — aplica todo lo que describe esta página. | | **Desactivada** | Entra **directo a la lista oficial** de cuentas por pagar, sin pasar por aquí. | nota El interruptor gobierna **solo títulos nuevos**. Desactivar no libera lo que ya está esperando, y activar no lleva a la cola lo que ya es oficial; los títulos rechazados siguen bloqueados. ### Los cambios pasan por Kobana[​](#los-cambios-pasan-por-kobana "Enlace directo al Los cambios pasan por Kobana") ![Configuración de aprobación](/es/assets/images/31-payment-approval-settings-73bcb1e9bebba3648bce43a94b4ed79d.png) **Nada en esa pantalla cambia en el acto.** Activar o desactivar la aprobación, cambiar el número de aprobaciones, permitir que quien creó apruebe, enviar al banco después de aprobar y aprobar lotes en el gateway automáticamente — todo se convierte en una **solicitud** que Kobana aprueba o deniega, igual que las reglas de [Seguridad](https://docs.finance.kobana.com.br/es/es/seguranca/.md#nada-vale-en-el-acto). * Al confirmar el cambio, el botón es **Enviar para aprobación**, y el aviso dice: *"El cambio entra en vigor cuando Kobana lo apruebe."* * La pantalla muestra siempre los valores **vigentes**. Con un pedido en análisis, aparece el aviso *"Hay 1 solicitud pendiente de cambio de estas configuraciones"*, con el enlace **Ver solicitudes**, que abre la lista de [Solicitudes](https://docs.finance.kobana.com.br/es/es/seguranca/.md#solicitudes) — donde se puede seguir o cancelar el pedido. * Pedir estos cambios exige el permiso **Configuración de aprobación**, que de forma predeterminada solo tiene el Propietario. ## Cuántas aprobaciones[​](#cuántas-aprobaciones "Enlace directo al Cuántas aprobaciones") En la misma pantalla, **Aprobaciones necesarias** define cuántas **personas distintas** deben aprobar cada título — de 1 (por defecto) a 10. El número no puede superar cuántas personas **con acceso al espacio y permiso para aprobar pagos** hay: la pantalla muestra ese conteo y bloquea los valores por encima. Si alguien pierde el permiso después, la pantalla avisa en rojo que los títulos nuevos quedarán detenidos en la cola. Con más de una, cada aprobación queda registrada y el título queda como **Aprobado parcialmente** hasta la última: sigue **fuera de la lista oficial** y aparece en la pestaña del mismo nombre, con el progreso (*"1 de 2 aprobaciones"*). Cuando la última persona aprueba, entra en la lista. Si alguien **edita el pago** de un título que aún espera aprobación — monto, fechas, proveedor, código de barras, Pix o datos bancarios —, las aprobaciones ya dadas se descartan y vuelve a **Esperando**: cada persona aprueba de nuevo lo que cambió. Editar la categoría, el centro de clasificación o las notas no toca las aprobaciones. nota El número se **congela cuando el título entra en la cola**: subir la configuración vale solo para los títulos nuevos. **Bajarla** vale también para los que ya están esperando — es la salida cuando alguien pierde el permiso y la cola exige más personas de las que quedan. Cuando Kobana aprueba la reducción, un título que ya tiene las aprobaciones del número nuevo entra en la lista en el acto. ## Qué bloquea la puerta[​](#qué-bloquea-la-puerta "Enlace directo al Qué bloquea la puerta") Mientras espera aprobación, el título **existe** pero queda fuera de todo: * **No aparece** en la lista de cuentas por pagar * **No cuenta** en totales, en vencidos, en el flujo de caja, en los informes ni en el Dashboard * **No puede** enviarse al banco * **No acepta** baja manual — "Pagar" no aparece Es decir: para el resto del sistema, todavía no es una obligación. ## Quién pasa por la puerta[​](#quién-pasa-por-la-puerta "Enlace directo al Quién pasa por la puerta") | Origen | ¿Pasa? | | ----------------------------------------------- | ---------------------------------------------------------- | | Formulario (`/payables/new`) | **Sí** | | Importación CSV | **Sí** | | API | **Sí** | | Publicar un borrador | **Sí** — guardar como borrador no es un atajo para escapar | | Cuotas de recurrencia generadas automáticamente | Solo si la serie todavía espera aprobación | | Títulos importados de Fintera | No | | Títulos anteriores a la creación de la puerta | No | La regla en una frase: **todo lo que alguien crea como obligación nueva pasa; todo lo que es derivado, sincronizado o heredado nace ya oficial.** ## La pantalla[​](#la-pantalla "Enlace directo al La pantalla") ![Pantalla de aprobación de pagos](/es/assets/images/30-payment-approvals-0a14b88e9851ca10ccc20cc6c366eca0.png) Cuatro pestañas, cada una con su contador: | Pestaña | Lista | | -------------------------- | ------------------------------------------------------------------------ | | **Esperando** | La cola que necesita tu ok, ordenada por vencimiento | | **Aprobados parcialmente** | Títulos que ya recibieron aprobaciones pero aún esperan a otras personas | | **Aprobados** | Historial, de lo más reciente | | **Rechazados** | Historial, de lo más reciente, con el motivo | Columnas: **Descripción** (con el proveedor debajo, y el motivo del rechazo en la pestaña Rechazados), **Origen**, **Vencimiento**, **Estado** e **Importe**. En "todas las empresas" entra también la columna **Empresa**. La búsqueda cubre **descripción y nombre del proveedor**. ### Origen[​](#origen "Enlace directo al Origen") Dice de dónde vino el título, y es el campo que sostiene la decisión: * **Manual** — creado en el formulario o por la API * **Importación CSV** — vino de un archivo ## Aprobar[​](#aprobar "Enlace directo al Aprobar") En las pestañas **Esperando** y **Aprobados parcialmente**, por tres caminos: * **Botón Aprobar** en la propia fila * **Menú de acciones** de la fila * **En lote** — marca las filas y usa **Aprobar seleccionados** (hasta 25 por vez) El diálogo **¿Aprobar pago?** confirma: *"1 pago será aprobado y entra en la lista de cuentas por pagar."* Cuando aún faltan aprobaciones, avisa que la tuya quedará registrada y que el título solo entra en la lista cuando se den todas. Después de aprobar un título que aún espera a otras personas, la fila muestra **"Ya aprobaste"** en lugar del botón. nota **Aprobar no envía al banco.** El título pasa a ser oficial y entra en la lista — el envío es un paso aparte, que se hace en Cuentas por Pagar. Ver [Envío al banco](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md). En una aprobación en lote, un fallo aislado no tumba a los demás. ## Rechazar[​](#rechazar "Enlace directo al Rechazar") Por el **menú de acciones** de la fila — no hay rechazo en línea ni en lote. Un título aprobado parcialmente también puede rechazarse: basta con que una persona lo rechace. El diálogo **¿Rechazar pago?** avisa: *"El título queda bloqueado para siempre y nunca entra en la lista de cuentas por pagar. Registra el motivo (opcional)."* El **motivo es opcional** (hasta 500 caracteres), pero es lo que la pestaña Rechazados va a mostrar después — sin él, el historial no explica la decisión. peligro **Rechazar no tiene vuelta atrás por la interfaz.** Un título rechazado no puede aprobarse después ni puede ir al banco. Queda en la pestaña Rechazados como registro, y nada más. Las pestañas **Aprobados** y **Rechazados** no tienen acciones — son auditoría. Al hacer clic en la descripción se abre el título. ## Quién puede aprobar[​](#quién-puede-aprobar "Enlace directo al Quién puede aprobar") **Cualquier persona con acceso al espacio de trabajo y permiso para aprobar**, con dos trabas: * **Quien creó el título no puede aprobarlo** — salvo que sea el **único miembro** del espacio de trabajo. A solas, no hay a quién pedir la aprobación, así que la pantalla avisa *"Eres el único miembro de este espacio, así que puedes aprobar los pagos que tú mismo creaste. Cuando otra persona entre al espacio, la aprobación volverá a exigir a alguien distinto de quien creó el pago."* y permite aprobar. El bloqueo vuelve solo cuando otra persona obtiene acceso al espacio. Quien está suspendido o con el acceso pausado sigue contando como miembro; solo la eliminación del miembro libera la aprobación. * **Cada persona cuenta una vez.** Cuando el espacio exige más de una aprobación, deben venir de personas distintas. Aprobar tampoco **está expuesto en la API** — es una acción exclusiva de la pantalla. ### Aprobación nocturna y por canal[​](#aprobación-nocturna-y-por-canal "Enlace directo al Aprobación nocturna y por canal") La [Seguridad](https://docs.finance.kobana.com.br/es/es/seguranca/.md) del espacio de trabajo puede restringir **cuándo** y **por dónde** se aprueba: * **Período nocturno** — con **Permitir aprobaciones en el período nocturno** desactivado, la pantalla muestra *"Las aprobaciones están bloqueadas en el período nocturno. Vuelven a estar permitidas a las 06:00."* (con el horario de tu espacio) y deshabilita los botones de aprobar, en la fila y en lote. * **Canal** — con **Aprobar** desactivado para el canal en uso, aparece *"La Seguridad de este espacio no permite aprobar pagos por este canal."* **Rechazar nunca se bloquea** — ni de noche ni por canal. La regla nocturna vale solo para la aprobación hecha por personas: recurrencias, importaciones de ERP y la aprobación del lote en el gateway no son aprobaciones de esta puerta. ### Envío bloqueado por Seguridad[​](#envío-bloqueado-por-seguridad "Enlace directo al Envío bloqueado por Seguridad") Cuando un título, tal como está, **no va a poder ir al banco** — tipo de operación desactivado, cuenta bloqueada, beneficiario no habilitado, monto por encima del límite por transacción —, la fila muestra la etiqueta **"Envío bloqueado por Seguridad"**: *"Tal como está, este título no podrá enviarse al banco. Solicita la liberación en Seguridad."* Aprobar sigue siendo posible; la etiqueta solo avisa que el envío será frenado. ## Editar un título aprobado[​](#editar-un-título-aprobado "Enlace directo al Editar un título aprobado") La aprobación vale para el pago **tal como se vio**. Con la aprobación activada, si alguien cambia cualquiera de estos campos en un título **aprobado y todavía no enviado** al banco, **vuelve a la cola** (**Esperando**), con las aprobaciones en cero, y sale de la lista de Cuentas por Pagar hasta ser aprobado de nuevo: * monto; * proveedor; * beneficiario — nombre, CPF/CNPJ, clave Pix, tipo de clave y datos bancarios; * código de barras o línea digitable; * cuenta de origen ("Pagar desde"); * tipo de operación y forma de pago; * datos del tributo. Vale también para ediciones hechas por la API. Fechas, intereses, descuentos, categoría, centro de clasificación y observaciones no devuelven el título a la cola. Una vez que el título se **envía al banco**, esos campos quedan **bloqueados** — ver [Editar después del envío](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md#editar-despu%C3%A9s-del-env%C3%ADo). ## Cómo aparece el estado en Cuentas por Pagar[​](#cómo-aparece-el-estado-en-cuentas-por-pagar "Enlace directo al Cómo aparece el estado en Cuentas por Pagar") En el listado de cuentas por pagar, un título aprobado muestra un **sello redondo con un escudo**; pasa el ratón para leer **"Creación aprobada"**, seguido de quién aprobó y cuándo — ahí queda la auditoría a mano, sin abrir el título. Los demás estados no aparecen ahí — por la propia regla de la puerta, no llegan a la lista. Después de que el título se envía al banco, el sello deja paso al estado del gateway. --- # Tarjetas Tarjetas (`/credit-cards`, menú **Movimientos › Tarjetas**) sigue las tarjetas de las empresas del espacio de trabajo: en qué resumen cae cada compra, cuánto del límite ya se usó, las cuotas y suscripciones que todavía van a llegar, el IOF de las compras internacionales, la revisión con el resumen del banco y el pago. ![Lista de tarjetas con el resumen de cada una, el límite usado y el resumen cerrado por pagar](/es/assets/images/36-credit-cards-bafadcdbfc8183a80526387f87b8f926.png) ## En esta sección[​](#en-esta-sección "Enlace directo al En esta sección") ## [📄️Registrar y convertir](https://docs.finance.kobana.com.br/es/es/cartoes/cadastrar-e-converter.md) [Registrar una tarjeta con una cuenta nueva, convertir una cuenta de crédito que ya existe, y la vista previa de los resúmenes que el formulario calcula mientras escribes.](https://docs.finance.kobana.com.br/es/es/cartoes/cadastrar-e-converter.md) ## [📄️Resumen y cierre](https://docs.finance.kobana.com.br/es/es/cartoes/fatura-e-corte.md) [La pantalla de la tarjeta — resúmenes por mes, el encabezado del resumen, los movimientos, la fecha de cierre prevista y la confirmada, y el historial.](https://docs.finance.kobana.com.br/es/es/cartoes/fatura-e-corte.md) ## [📄️Movimientos e IOF](https://docs.finance.kobana.com.br/es/es/cartoes/lancamentos-e-iof.md) [Cargar compras al contado, en cuotas e internacionales, reembolsos, intereses y tarifas — en qué resumen cae cada uno, el IOF y la cotización, editar una serie, mover y anticipar.](https://docs.finance.kobana.com.br/es/es/cartoes/lancamentos-e-iof.md) ## [📄️Recurrencias](https://docs.finance.kobana.com.br/es/es/cartoes/recorrencias.md) [Suscripciones cobradas en la tarjeta — los cobros previstos en cada resumen, confirmar con el importe real, no cobrado, la sugerencia de actualizar el importe, editar y terminar.](https://docs.finance.kobana.com.br/es/es/cartoes/recorrencias.md) ## [📄️Cerrar, revisar y pagar](https://docs.finance.kobana.com.br/es/es/cartoes/fechar-conferir-pagar.md) [El cierre automático y la cuenta por pagar del resumen, la revisión con el total del banco, el pago total o parcial, deshacer, reabrir, la recarga de la prepago y la tarjeta en el flujo de caja.](https://docs.finance.kobana.com.br/es/es/cartoes/fechar-conferir-pagar.md) ## [📄️Informes](https://docs.finance.kobana.com.br/es/es/cartoes/relatorios.md) [IOF pagado en las compras internacionales, por mes, tarjeta, categoría o proveedor, y el previsto × realizado de las recurrencias — con exportación en CSV y XLSX.](https://docs.finance.kobana.com.br/es/es/cartoes/relatorios.md) ## Los tres tipos[​](#los-tres-tipos "Enlace directo al Los tres tipos") | Tipo | Cómo funciona | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Crédito** | Un resumen por mes. Al cerrar, el resumen se convierte en una [cuenta por pagar](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/.md) y el pago sale de la cuenta que paga el resumen. Tiene límite. | | **Prepago** | Recibe recargas desde una cuenta bancaria y las compras salen del saldo. El límite es el propio saldo. El resumen cierra sin cuenta por pagar. | | **Beneficio** | Funciona como la prepago (vale de comida, de alimentación). | ## La tarjeta y tus cuentas[​](#la-tarjeta-y-tus-cuentas "Enlace directo al La tarjeta y tus cuentas") Cada tarjeta tiene una cuenta de tipo **Crédito** en [Mis cuentas](https://docs.finance.kobana.com.br/es/es/contas-financeiras/.md): creada junto con la tarjeta, o una cuenta de crédito que ya existía y fue convertida (ver [Registrar y convertir](https://docs.finance.kobana.com.br/es/es/cartoes/cadastrar-e-converter.md)). Cada compra cargada en la tarjeta aparece **una vez** en el resto del sistema: | Dónde | Qué aparece | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Transacciones** | La compra, en su fecha y en su categoría, con la etiqueta **Tarjeta**. El pago del resumen es una transferencia, con la etiqueta **Pago de resumen**; la recarga de la prepago, con la etiqueta **Recarga**. | | **Mis cuentas** | El saldo de la cuenta de la tarjeta es la deuda: las compras lo bajan y el pago lo devuelve. | | **Dashboard** | Las compras entran como gasto en la fecha de la compra; el pago del resumen, por ser transferencia, no cuenta de nuevo. | | **Flujo de caja** | La tarjeta no es caja. La salida es el pago del resumen, en el vencimiento, por la cuenta que paga el resumen. Ver [Cerrar, revisar y pagar](https://docs.finance.kobana.com.br/es/es/cartoes/fechar-conferir-pagar.md#en-el-flujo-de-caja). | | **Cuentas por Pagar** | El resumen cerrado se convierte en una cuenta por pagar, con el origen **Resumen de tarjeta**. | nota **Lo que vino de la tarjeta se cambia desde la tarjeta.** En [Transacciones](https://docs.finance.kobana.com.br/es/es/lancamentos/.md), la compra aparece con las acciones de editar, clasificar, conciliar y eliminar deshabilitadas, y el motivo al pie del menú: *"Movimiento de la tarjeta: cámbialo desde la tarjeta."* **"Abrir en la tarjeta"** lleva directo a su resumen. Lo mismo vale para las dos puntas del pago (*"Pago de resumen: deshazlo desde el resumen de la tarjeta."*) y de la recarga (*"Recarga de la tarjeta: elimínala desde la tarjeta."*). ## La lista[​](#la-lista "Enlace directo al La lista") Cada tarjeta es una ficha, en el orden del próximo vencimiento: * **Apodo**, marca y, en la prepago y la de beneficio, el tipo. Debajo, el banco emisor, el producto y la terminación (`···· 4821`). * **El resumen cerrado que falta pagar**, destacado: el importe, el vencimiento (*"vence 9/11 · en 4 días"*) y el botón **Pagar**, que abre el pago en el propio resumen. * **El resumen actual** — *"Resumen de Dic/26"*, su estado, el total previsto y *"cierra 2/12 · vence 9/12"*. * **La barra del límite** — *"Usado R$ 22.007,75 de R$ 60.000,00"* y el porcentaje. La barra se pone amarilla a partir de la **Alerta de límite** definida en la tarjeta y roja cuando pasa del 100%. * En la prepago y la de beneficio, en lugar del resumen y del límite: **Saldo**, cuánto se usó y el botón **Recargar**. * Al pie, de dónde sale el dinero: *"Pagada desde Itaú — Conta Corrente · Débito automático"*, o *"Recarga desde …"*. El menú **⋯** de cada ficha tiene **Editar tarjeta** y **Ver la cuenta en Mis cuentas**. Arriba están la búsqueda, las pestañas **Activas**, **Bloqueadas**, **Canceladas** y **Todas**, con la cantidad de cada una, la píldora **Informe** (ver [Informes](https://docs.finance.kobana.com.br/es/es/cartoes/relatorios.md)) y **Nueva tarjeta**. Si el espacio tiene cuentas de tipo Crédito que todavía no son tarjeta, un aviso arriba de la lista ofrece **Convertir en tarjeta**. ## Estado de la tarjeta[​](#estado-de-la-tarjeta "Enlace directo al Estado de la tarjeta") **Activa**, **Bloqueada** o **Cancelada**, en la propia tarjeta. El ícono (i) del campo explica: *"Una tarjeta cancelada deja de generar resúmenes nuevos. Las tarjetas no se eliminan, porque sus resúmenes quedan como historial."* ## Permisos[​](#permisos "Enlace directo al Permisos") En el editor de roles, el módulo tiene tres grupos: **Tarjetas de crédito**, **Movimientos de la tarjeta** y **Resúmenes de la tarjeta**. | Para | Necesitas | | ------------------------------------------------------------------ | ----------------------------------------------------------------- | | Ver la lista | Tarjetas de crédito › **Listar** | | Abrir una tarjeta, sus resúmenes, el historial y los informes | Tarjetas de crédito › **Ver detalles** | | Registrar, convertir y editar una tarjeta | Tarjetas de crédito › **Crear** / **Editar** | | Cargar, editar, mover, anticipar y eliminar compras y recurrencias | Movimientos de la tarjeta › **Crear** / **Editar** / **Eliminar** | | Cambiar la fecha de cierre y revisar el resumen | Resúmenes de la tarjeta › **Editar** | | Cerrar y reabrir el resumen | Resúmenes de la tarjeta › **Cerrar y reabrir** | | Pagar, deshacer el pago y recargar | Resúmenes de la tarjeta › **Pagar** | Como en el resto del sistema, la pantalla no esconde el botón a quien no tiene el permiso: el sistema rechaza la acción al guardar. ## Por la API y por el MCP[​](#por-la-api-y-por-el-mcp "Enlace directo al Por la API y por el MCP") Todo lo que describe esta sección también está en la API v1 — [tarjetas](https://docs.finance.kobana.com.br/es/es/api/v1/list-credit-cards), [resúmenes](https://docs.finance.kobana.com.br/es/es/api/v1/get-card-statement), [movimientos](https://docs.finance.kobana.com.br/es/es/api/v1/list-card-transactions), [recurrencias](https://docs.finance.kobana.com.br/es/es/api/v1/list-card-recurrences) y [alícuotas de IOF](https://docs.finance.kobana.com.br/es/es/api/v1/list-iof-rates) — y en las [herramientas del servidor MCP](https://docs.finance.kobana.com.br/es/es/mcp/tools/accounts.md#credit_cards). El número completo de la tarjeta nunca entra al sistema por ninguna de ellas: solo los 4 últimos dígitos. --- # Registrar y convertir **Nueva tarjeta** (`/credit-cards/new`) abre el registro en una página. A la derecha, el panel **Vista previa de los resúmenes** muestra, mientras escribes, el mejor día de compra y los próximos resúmenes con cierre y vencimiento. ![Registro de la tarjeta con la vista previa de los resúmenes al lado](/es/assets/images/38-credit-card-form-d3bbec21819f93fca7f70d4e5cfa98fb.png) **El ícono (i) al lado del nombre de un campo explica el campo.** Pasa el mouse sobre él, o llega a él con Tab, para leer la explicación. En las tablas de abajo, los textos marcados con (i) son esos. ## Cuenta nueva o conversión[​](#cuenta-nueva-o-conversión "Enlace directo al Cuenta nueva o conversión") El primer bloque, **Cuenta de la tarjeta**, decide qué cuenta de Mis cuentas guarda los movimientos de la tarjeta: | Opción | Qué hace | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Crear una cuenta nueva** | *"Creamos en Mis cuentas una cuenta de tipo crédito para esta tarjeta, con su apodo y su banco."* Una tarjeta no tiene agencia ni número de cuenta, así que la cuenta se crea sin ellos. | | **Convertir una cuenta de crédito** | *"Una cuenta de tipo crédito que ya tienes pasa a tener resúmenes y sigue en Mis cuentas. La empresa es la de la cuenta, y el banco emisor ya viene completado con el de ella."* Solo aparecen cuentas de tipo Crédito que todavía no son tarjeta. | El aviso de la lista de tarjetas, *"… es una cuenta de crédito que todavía no es tarjeta"*, lleva directo a la conversión, con la cuenta ya elegida. Una cuenta convertida no puede convertirse de nuevo en otra tarjeta. aviso **Una compra cargada en los dos lugares cuenta dos veces.** *"Los movimientos que ya están en … siguen ahí. Para no contar una compra dos veces, elige una fecha de inicio posterior al último movimiento hecho en esa cuenta."* La conversión no mueve ni borra el historial de la cuenta: sigue en la cuenta como estaba, y los resúmenes empiezan por el que incluye la **Fecha de inicio**. ## Identificación[​](#identificación "Enlace directo al Identificación") | Campo | Observaciones | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tipo** | **Crédito**, **Prepago** o **Beneficio**. No cambia después del registro. | | **Apodo** | Obligatorio, hasta 60 caracteres. Es el nombre de la tarjeta en todo el sistema. | | **Banco emisor** | Obligatorio, de la lista de bancos. | | **Marca** | Obligatoria: Visa, Mastercard, Elo, American Express, Hipercard u Otra. | | **Nombre del producto** | Opcional (*"Ej.: Black, Infinite"*). | | **Últimos 4 dígitos** | Obligatorio. (i) *"Por seguridad, guardamos solo los 4 últimos dígitos. El número completo de la tarjeta nunca se guarda."* | | **Estado** | Activa, Bloqueada o Cancelada. (i) *"Una tarjeta cancelada deja de generar resúmenes nuevos. Las tarjetas no se eliminan, porque sus resúmenes quedan como historial."* | peligro **El número completo de la tarjeta se rechaza en cualquier campo de texto.** Apodo, producto, descripción y notas rechazan una secuencia con cara de número de tarjeta — así un número pegado por error no se guarda. CVV y vencimiento de la tarjeta no existen en el registro. ## Fechas del resumen[​](#fechas-del-resumen "Enlace directo al Fechas del resumen") | Campo | Observaciones | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Día de cierre** | De 1 a 31. En un mes más corto, vale el último día. (i) *"Día en que el banco cierra el resumen. Las compras hasta ese día entran en el resumen del mes; desde el día siguiente, en el próximo."* | | **Cierre anticipado (días)** | De 0 a 15. (i) *"Algunos bancos cierran el resumen unos días antes del día de cierre. Si el tuyo lo hace, indica cuántos días. Ej.: cierre el día 10 y 2 días antes: las compras hasta el día 8 entran en este resumen. Si tienes dudas, deja 0."* | | **Día de vencimiento** | De 1 a 31. (i) *"Día en que vence el resumen. Si cae en fin de semana o feriado, se aplica la regla de Vencimiento en día no hábil."* | | **Vencimiento en día no hábil** | Siguiente día hábil, día hábil anterior o mantener la fecha. | | **Fecha de inicio** | (i) *"Los resúmenes empiezan por el que incluye esta fecha. Las compras anteriores no entran en la tarjeta."* Una fecha pasada crea los resúmenes desde ella. | **Cómo salen las fechas.** El resumen lleva el nombre del **mes del vencimiento**. El cierre cae en el mismo mes cuando el día de cierre es antes del vencimiento (cierra el 2, vence el 9: las dos fechas en diciembre); cuando es después, cae en el mes anterior (cierra el 25, vence el 5: cierre en noviembre, vencimiento en diciembre). El cierre es **inclusivo**: la compra hecha el mismo día del cierre todavía entra en el resumen. Con **Cierre anticipado (días)**, la fecha de cierre de cada resumen es el día de cierre menos esos días. **Los días hábiles** son los del calendario bancario de Brasil: sábados, domingos, los feriados nacionales y los móviles de la Pascua — lunes y martes de Carnaval, Viernes Santo y Corpus Christi. En el panel, un vencimiento ajustado aparece con el aviso *"9/1 no es día hábil"*. ### El panel Vista previa de los resúmenes[​](#el-panel-vista-previa-de-los-resúmenes "Enlace directo al El panel Vista previa de los resúmenes") * **Mejor día de compra** — el día siguiente al cierre: *"Las compras a partir del 3/12 entran en el resumen de Ene/27, que vence el 11/1: el plazo más largo para pagar."* * **Los próximos tres resúmenes**, con cierre, vencimiento y el día de la semana de cada uno. * En el registro, *"Primer resumen en el sistema: … (compras del … al …)."* y, al pie, *"Al registrar, creamos el resumen actual y los 12 próximos."* El panel usa las mismas reglas que el servidor: las fechas que muestra son las que los resúmenes van a tener. ### Cambiar las fechas después[​](#cambiar-las-fechas-después "Enlace directo al Cambiar las fechas después") *"Al cambiar el cierre o el vencimiento, los próximos resúmenes que aún no tienen la fecha de cierre confirmada se recalculan, y los movimientos van al resumen correcto."* Los resúmenes abiertos, cerrados y pagados no cambian, ni los futuros cuya fecha de cierre alguien ya confirmó. Para ajustar la fecha de cierre de un solo resumen, usa **Cambiar fecha de cierre** en él — ver [Resumen y cierre](https://docs.finance.kobana.com.br/es/es/cartoes/fatura-e-corte.md#cambiar-la-fecha-de-cierre). ## Límite y pago[​](#límite-y-pago "Enlace directo al Límite y pago") | Campo | Observaciones | | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Límite** | Solo en crédito. Sin límite, la ficha no muestra la barra. | | **Alerta de límite** | (i) *"La barra de límite se pone amarilla cuando el uso pasa de este porcentaje. Ej.: 80%."* | | **Cuenta que paga el resumen** | (i) *"La cuenta bancaria, de la misma empresa, desde la que sale el pago del resumen. La cuenta por pagar de cada resumen ya viene con ella."* En la prepago el campo se llama **Cuenta que hace las recargas**. | | **Forma de pago** | Débito automático, Boleto o Pix. (i) *"Cómo se suele pagar el resumen. Va en la cuenta por pagar de cada resumen."* | | **Proveedor del resumen** | (i) *"Quién aparece como proveedor en la cuenta por pagar de cada resumen. En blanco, usamos el banco emisor."* | | **Categoría predeterminada** · **Centro de clasificación predeterminado** | (i) *"Ya viene completada en cada movimiento nuevo de la tarjeta. Puedes cambiarla en el movimiento."* | En la prepago y la de beneficio, el límite no se escribe: *"En las tarjetas prepago y de beneficio, el límite es el saldo cargado: sube con cada recarga."* ## Compras internacionales[​](#compras-internacionales "Enlace directo al Compras internacionales") | Campo | Observaciones | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Alícuota de IOF** | (i) *"En blanco, cada compra usa la alícuota oficial vigente en su fecha. Complétala solo si tu banco cobra una alícuota distinta."* | | **Spread del banco** | En puntos porcentuales (4 = 4%). (i) *"Porcentaje que el banco suma a la cotización oficial (PTAX del Banco Central) en las compras internacionales. Lo usamos para estimar la cotización hasta que llegue el resumen."* | Ver [Movimientos e IOF](https://docs.finance.kobana.com.br/es/es/cartoes/lancamentos-e-iof.md#compra-internacional). ## Después de guardar[​](#después-de-guardar "Enlace directo al Después de guardar") **Registrar tarjeta** (o **Convertir en tarjeta**) crea el resumen abierto y los 12 siguientes y lleva a la pantalla de la tarjeta. Desde ahí, todos los días, de madrugada, el sistema cierra el resumen cuya fecha de cierre pasó y abre el siguiente — ver [Cerrar, revisar y pagar](https://docs.finance.kobana.com.br/es/es/cartoes/fechar-conferir-pagar.md). Para editar, usa el lápiz al lado del nombre de la tarjeta o **Editar tarjeta** en el menú de la ficha. En la edición, **Tipo** y empresa no cambian, y la **Fecha de inicio** solo se mueve hacia atrás. ### Cargar un resumen anterior[​](#cargar-un-resumen-anterior "Enlace directo al Cargar un resumen anterior") Para cargar las compras de un resumen de antes del registro (el PDF de un resumen ya vencido, por ejemplo), edita la tarjeta y mueve la **Fecha de inicio** hacia atrás, al inicio del período de ese resumen — como máximo 24 meses. (i) *"Mueve la fecha hacia atrás para cargar compras de resúmenes anteriores: se crean los resúmenes desde ella, y los que ya pasaron el cierre se cierran en la rutina diaria."* El más antiguo queda abierto para recibir los movimientos; a la madrugada siguiente, el sistema cierra los que ya pasaron el cierre, cada uno con su cuenta por pagar en su vencimiento, y vuelve a abrir el resumen actual. Sin esto, un movimiento con fecha anterior al primer resumen se rechaza: *"La fecha es anterior al primer resumen de la tarjeta en el sistema. Para cargarla, mueve hacia atrás la fecha de inicio de la tarjeta."* --- # Resumen y cierre Al hacer clic en una tarjeta se abre su pantalla (`/credit-cards/`), con dos pestañas arriba: **Resúmenes** y **Recurrencias** (ver [Recurrencias](https://docs.finance.kobana.com.br/es/es/cartoes/recorrencias.md)). La píldora **Informe**, a la derecha de las pestañas, abre los [informes](https://docs.finance.kobana.com.br/es/es/cartoes/relatorios.md) ya filtrados por esta tarjeta. ![Resumen abierto con cuotas, compra internacional con IOF y cobros recurrentes previstos](/es/assets/images/37-credit-card-statement-644d568fba681ca6e4733d94e8e99f91.png) ## El encabezado de la tarjeta[​](#el-encabezado-de-la-tarjeta "Enlace directo al El encabezado de la tarjeta") El apodo, la marca y el lápiz de editar; debajo, el tipo, el banco emisor, el producto, la terminación y la cuenta que paga el resumen. A la derecha, el **Límite disponible** con la barra *"Usado … de …"* — en la prepago y la de beneficio, el **Saldo** y el botón **Recargar**. Y el botón **Nuevo movimiento** (ver [Movimientos e IOF](https://docs.finance.kobana.com.br/es/es/cartoes/lancamentos-e-iof.md)). ## Los resúmenes, mes a mes[​](#los-resúmenes-mes-a-mes "Enlace directo al Los resúmenes, mes a mes") Una franja de pestañas muestra seis resúmenes a la vez, cada uno con el mes y un punto de color del estado; las flechas traen los anteriores y los próximos. La pantalla abre en el resumen **Abierto**, y el elegido queda en la dirección (`?statement=2026-12`), para enviar el enlace de un resumen específico. | Estado | Qué significa | | ------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Futuro** | Todavía no empezó. Ya recibe las cuotas y los cobros recurrentes previstos, y su fecha de cierre ya puede confirmarse. | | **Abierto** | El ciclo actual: recibe las compras. Hay uno solo por tarjeta. | | **Cerrado** | La fecha de cierre pasó. En la tarjeta de crédito, ya tiene cuenta por pagar. | | **Revisado** | El total coincidió con el del resumen del banco. | | **Pagado** | El pago cubrió el total. Los movimientos quedan **Conciliados**. | | **Pagado en parte** | Se pagó menos que el total; el resto pasó al resumen siguiente. | ## El encabezado del resumen[​](#el-encabezado-del-resumen "Enlace directo al El encabezado del resumen") *"Resumen de diciembre de 2026"* y su estado, con una línea de números. Los campos con el ícono (i) explican el número al pasar el mouse: | Campo | Qué trae | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Período** | Del día siguiente al cierre anterior hasta la fecha de cierre de este resumen. (i) *"Las compras hechas en este período entran en este resumen."* | | **Cierre** | La fecha, con la etiqueta **Previsto** o **Confirmado** y, en un resumen abierto o futuro, el lápiz para cambiarla. (i) *"Último día de compras de este resumen. Queda como previsto hasta que confirmes la fecha que muestra la app del banco."* | | **Vencimiento** | Ya ajustado a día hábil. | | **Total previsto** | Lo que está en el resumen: realizados, previstos e IOF, menos reembolsos, más el saldo anterior. Los no cobrados y los cancelados no entran. (i) *"La suma de los movimientos de este resumen, con el IOF y ya descontadas las devoluciones."* | | **Total del banco** · **Diferencia** | Después de la revisión: el total del resumen del banco y cuánto falta para que coincida. (i) en **Total del banco**: *"El total que muestra el resumen del banco, informado al revisar el resumen."* | Debajo, una línea dice lo que viene: * Abierto: *"Cierra automáticamente en la madrugada del 03/12/2026 y genera una cuenta por pagar de R$ 6.348,80, con vencimiento el 9/12."* * Futuro: *"Resumen futuro: ya recibe las cuotas y los cobros recurrentes previstos. La fecha de cierre ya puede confirmarse."* * Cerrado o revisado: la cuenta por pagar, con su estado y vencimiento — y, si el total no coincidió, *"El total del banco no coincide: revisa los movimientos y carga lo que falta."* * Pagado: *"Pagado el 08/10/2026: R$ 10.142,65 salieron de Itaú — Conta Corrente. Los movimientos están conciliados."* ### Las acciones del resumen[​](#las-acciones-del-resumen "Enlace directo al Las acciones del resumen") Los botones cambian con el estado: | Acción | Aparece en | | ------------------------------------ | ------------------------------------------------------------------ | | **Cambiar fecha de cierre** | Abierto y futuro (también por el lápiz del cierre) | | **Confirmar cobros recurrentes (n)** | Futuro, abierto y cerrado, cuando hay cobros recurrentes previstos | | **Cerrar resumen ahora** | Abierto | | **Revisar con el banco** | Cerrado (destacado) y revisado | | **Pagar resumen** | Cerrado y revisado, en la tarjeta de crédito | | **Deshacer pago** | Pagado y pagado en parte | | **Reabrir** | Cerrado, revisado, pagado y pagado en parte | | Historial (ícono del reloj) | Siempre | Cerrar, revisar, pagar, deshacer y reabrir están en [Cerrar, revisar y pagar](https://docs.finance.kobana.com.br/es/es/cartoes/fechar-conferir-pagar.md). ## Los movimientos del resumen[​](#los-movimientos-del-resumen "Enlace directo al Los movimientos del resumen") La tabla lista lo que está en el resumen, con las columnas **Fecha**, **Descripción** (y el proveedor debajo), **Categoría**, **Cuota**, **Previsto**, **Realizado**, **IOF**, **Total** y **Estado**. La primera fila suma el resumen: la cantidad de movimientos y el total de cada columna de importe, sin los no cobrados y los cancelados. * El cobro **previsto** de una recurrencia aparece en cursiva y gris, con la etiqueta **Recurrente**, hasta que se confirma. * La compra internacional lleva la etiqueta de la moneda (**USD**) y, debajo del importe, la cuenta: el importe en la moneda × la cotización, con la marca *estimada* mientras la cotización sea la estimada. El IOF va en su propia columna, con la alícuota. * El reembolso aparece con la etiqueta **Reembolso** y el importe negativo. * Los no cobrados y los cancelados aparecen tachados. * Un movimiento movido manualmente a este resumen muestra un candado: *"Movido manualmente a este resumen: queda en él aunque cambie la fecha de cierre."* La búsqueda, los filtros **Tipo** y **Categoría** y las pestañas **Todos**, **Previstos** e **Internacionales**, cada una con la cantidad. El menú de cada fila está en [Movimientos e IOF](https://docs.finance.kobana.com.br/es/es/cartoes/lancamentos-e-iof.md#el-men%C3%BA-del-movimiento). ## Cambiar la fecha de cierre[​](#cambiar-la-fecha-de-cierre "Enlace directo al Cambiar la fecha de cierre") El banco no cierra el resumen siempre el mismo día. Cada resumen guarda **su propio** cierre: nace **Previsto**, calculado por las fechas de la tarjeta, y pasa a **Confirmado** cuando alguien verifica la fecha en la app o en el resumen del banco. **Cambiar fecha de cierre** (o el lápiz del cierre) abre *"Fecha de cierre · resumen de …"*, con la fecha actual (**Cierre previsto** o **Cierre confirmado**) y el campo **Fecha de cierre en el banco**. *"Las compras hechas hasta la fecha de cierre, inclusive, quedan en este resumen. Desde el día siguiente, van al próximo."* Al elegir la fecha, el diálogo muestra **antes de aplicar** lo que va a pasar: * *"3 movimientos cambian de resumen"*, cada uno con a dónde va; * *"El resumen de Ene/27 pasa a empezar el …"*; * o, si nada cambia, *"Ningún movimiento cambia de resumen."* Con la misma fecha del cierre previsto, nada se mueve: *"Ningún movimiento cambia de resumen: el cierre solo pasa a Confirmado."* — y el botón dice **Confirmar fecha**. Con otra fecha, **Aplicar nueva fecha**. *"El cambio queda en el historial del resumen, con quién lo hizo."* nota **Qué acompaña al cambio y qué no.** Las cuotas acompañan a la primera: si la cuota 1 cambia de resumen, las siguientes cambian con ella, un resumen después del otro. Un movimiento **movido manualmente** queda donde está, y el **saldo anterior** de un pago parcial también. Un resumen cerrado nunca gana ni pierde movimientos por el cambio de la fecha de cierre. **Los límites.** La nueva fecha de cierre no puede ser anterior al comienzo del período del resumen ni llegar a la fecha de cierre del siguiente. Un resumen cerrado, revisado o pagado no acepta el cambio: reábrelo antes (ver [Reabrir](https://docs.finance.kobana.com.br/es/es/cartoes/fechar-conferir-pagar.md#reabrir)). aviso **El resumen cierra en la fecha prevista si nadie la confirma.** El cierre automático de la madrugada no espera la confirmación. Si el banco cerró después de lo previsto, las compras de esos días caen en el resumen siguiente; para corregirlo, reabre el resumen y cambia la fecha de cierre. ## Historial del resumen[​](#historial-del-resumen "Enlace directo al Historial del resumen") El ícono del reloj abre el **Historial** del resumen: *"Todo lo que pasó en este resumen, del más reciente al más antiguo, con quién lo hizo y desde dónde."* | Evento | Cómo aparece | | -------------------------- | ---------------------------------------------------------------------------------- | | Fecha de cierre confirmada | *"Fecha de cierre confirmada: 2/12"* | | Fecha de cierre cambiada | *"Fecha de cierre cambiada del 2/12 al 4/12 · 3 movimientos cambiaron de resumen"* | | Cerrado | *"Cerrado · total R$ 8.908,95 · cuenta por pagar creada"* | | Revisado | *"Revisado: total del banco R$ 8.908,95"* | | Reabierto | *"Reabierto (estaba Pagado)"* | | Pagado | *"Pagado: R$ 8.908,95 desde Itaú — Conta Corrente"* | | Pago deshecho | *"Pago deshecho: R$ 8.908,95"* | Lo que hizo el cierre automático aparece como **Sistema**; el resto, con el correo de quien lo hizo y el canal (pantalla, API o MCP). --- # Cerrar, revisar y pagar ## Cerrar[​](#cerrar "Enlace directo al Cerrar") **El resumen cierra automáticamente.** Cada madrugada el sistema cierra el resumen abierto cuya fecha de cierre ya pasó y abre el siguiente. La línea del resumen abierto avisa cuándo: *"Cierra automáticamente en la madrugada del 03/12/2026 y genera una cuenta por pagar de R$ 6.348,80, con vencimiento el 9/12."* **Cerrar resumen ahora** lo adelanta: *"Genera ahora la cuenta por pagar de …, con vencimiento el …. Si no lo cierras, cierra automáticamente en la madrugada del …. Las compras de este resumen cargadas después del cierre van al próximo resumen abierto."* ### La cuenta por pagar del resumen[​](#la-cuenta-por-pagar-del-resumen "Enlace directo al La cuenta por pagar del resumen") En la tarjeta de crédito, cerrar crea una [cuenta por pagar](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/.md): | Campo | Valor | | ------------------------- | ------------------------------------------------------------- | | Descripción | *"Fatura Itaú Empresas Visa — 11/2026"* | | Proveedor | El **Proveedor del resumen** de la tarjeta, o el banco emisor | | Importe | El total del resumen | | Vencimiento y competencia | El vencimiento del resumen | | Pagar vía | La **Cuenta que paga el resumen**, del registro de la tarjeta | | Forma de pago | La de la tarjeta | | Categoría | Ninguna: cada compra ya está en su categoría | Aparece en Cuentas por Pagar con el origen **Resumen de tarjeta**. Con la [aprobación de pagos](https://docs.finance.kobana.com.br/es/es/aprovar-pagamentos/.md) activada, entra en la cola de aprobación como cualquier cuenta por pagar. aviso **El importe de esa cuenta por pagar es el del resumen.** Cambia con la revisión (pasa a ser el total del banco) y con el pago parcial — nunca editando la cuenta por pagar, que rechaza el cambio de importe. Tampoco puede eliminarse mientras exista el resumen. Descripción, vencimiento y lo demás siguen editables. La prepago y la de beneficio cierran **sin** cuenta por pagar, y un resumen con total cero o negativo también. ## Revisar por el total[​](#revisar-por-el-total "Enlace directo al Revisar por el total") Con el resumen del banco en la mano, **Revisar con el banco** abre *"Revisar con el resumen del banco"*: el **Total en el sistema**, la **Diferencia** en vivo, el **Total del resumen del banco** y el **Pago mínimo** (opcional). | Resultado | Qué pasa | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Coincide | *"Coincide: el resumen pasa a Revisado y la cuenta por pagar pasa a …."* | | No coincide | *"No coincide: los valores quedan guardados y el resumen sigue Cerrado, mostrando la diferencia, hasta que se cargue lo que falta."* | Para que coincida: carga lo que faltó (una compra que llegó tarde, intereses y tarifas, un reembolso), confirma los cobros recurrentes con el importe real o ajusta la cotización de las compras internacionales. Después, revisa de nuevo. ## Pagar[​](#pagar "Enlace directo al Pagar") **Pagar resumen** — en el resumen cerrado o revisado, o con el **Pagar** de la ficha en la lista — abre el pago: ![Pagar el resumen cerrado, total u otro importe](/es/assets/images/40-card-pay-statement-87f0029e03071d28784290645e1d3df5.png) | Opción | Qué hace | | ---------------- | ---------------------------------------------------------------------------------------- | | **Total** | *"Cancela el resumen."* | | **Mínimo** | Solo cuando el pago mínimo se indicó en la revisión. *"El resto va al próximo resumen."* | | **Otro importe** | Cualquier importe hasta el total del resumen. | **Sale de** es la cuenta que paga el resumen (puedes cambiarla) y **Fecha del pago**, el día en que salió el dinero. **Registrar pago** graba una **transferencia** de esa cuenta a la cuenta de la tarjeta, da de baja la cuenta por pagar y deja los movimientos del resumen **Conciliados**. tip **Pagar por cualquier puerta da lo mismo.** Dar de baja la cuenta por pagar del resumen en Cuentas por Pagar, por la API, o por la confirmación del banco cuando el pago se envió por [Kobana](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md) produce exactamente el mismo resultado: la transferencia, el resumen pagado y los movimientos conciliados. *"¿Vas a pagar por el banco? Envía la cuenta por pagar por Kobana: cuando el banco confirme, el pago se registra aquí automáticamente."* ### Pago parcial[​](#pago-parcial "Enlace directo al Pago parcial") Pagando menos que el total, el resumen queda **Pagado en parte** y la diferencia pasa al resumen siguiente como **Saldo anterior** — el movimiento *"Saldo da fatura 11/2026"*. El diálogo avisa: *"Los … que faltan pasan al resumen siguiente, como saldo anterior. Cuando aparezcan intereses y multas en el resumen, cárgalos como Intereses y tarifas."* El sistema no calcula intereses. ### Deshacer el pago[​](#deshacer-el-pago "Enlace directo al Deshacer el pago") **Deshacer pago** pide confirmación: *"Borra el pago de … (la transferencia a la cuenta de la tarjeta) y el saldo que pasó al resumen siguiente. El resumen vuelve a Revisado o Cerrado."* La cuenta por pagar vuelve a pendiente, con el total del resumen. Si el resumen que recibió el saldo anterior ya cerró, se rechaza: reábrelo primero. ## Reabrir[​](#reabrir "Enlace directo al Reabrir") **Reabrir** vuelve el resumen a **Abierto** — para cargar una compra que faltó, corregir un importe o una fecha, o cambiar la fecha de cierre. *"El resumen vuelve a Abierto, y el historial registra quién lo reabrió y cuándo. La cuenta por pagar sigue; el total se recalcula cuando vuelva a cerrar."* En un resumen pagado: *"El pago sigue registrado, el saldo que había pasado al resumen siguiente se retira y los movimientos vuelven a Realizado. El total se recalcula cuando vuelva a cerrar."* Al cerrar de nuevo, el resumen vuelve a **Pagado** si el pago cubre el nuevo total, o queda **Pagado en parte** con la diferencia en el siguiente. Hay un solo resumen abierto por tarjeta: el que estaba abierto vuelve a futuro mientras el reabierto no cierre. Si la fecha de cierre del reabierto ya pasó, cierra de nuevo en la madrugada siguiente — ciérralo antes con **Cerrar resumen ahora** si terminaste los ajustes. ## Prepago y beneficio[​](#prepago-y-beneficio "Enlace directo al Prepago y beneficio") **Recargar** (en la ficha de la lista o en el encabezado de la tarjeta) registra una recarga: el importe, la fecha y la cuenta de la que sale (**Sale de**, la cuenta que hace las recargas de la tarjeta). *"Entra como crédito en el resumen abierto (…). El saldo pasa a …."* La recarga es una transferencia de la cuenta bancaria a la cuenta de la tarjeta; eliminarla en el resumen borra la transferencia. El resumen de la prepago tiene el mismo ciclo y la misma revisión, pero cierra sin cuenta por pagar: revisado, termina en **Revisado**. ## En el flujo de caja[​](#en-el-flujo-de-caja "Enlace directo al En el flujo de caja") **La tarjeta no es caja.** En el [flujo de caja](https://docs.finance.kobana.com.br/es/es/dashboard/.md#pesta%C3%B1a-flujo-de-caja): * **Lo que ya pasó** — la salida es el **pago** del resumen, en el día del pago, por la cuenta que paga el resumen. Las compras no entran una por una. * **Lo que viene** — el resumen abierto y los futuros entran por el **total previsto**, en el **vencimiento**, en la cuenta que paga el resumen. Cerrado, el resumen entra por su cuenta por pagar (sin contar dos veces). * **Prepago** — la salida de caja es la recarga; el resumen nunca entra en la proyección. Al elegir la cuenta de la tarjeta en el selector **Cuenta**, las pestañas de proyección y flujo de caja muestran un aviso en lugar del gráfico — *"Itaú Empresas Visa es una tarjeta: no entra en el flujo de caja"* — con el atajo **Ver** a la cuenta que paga el resumen. Los saldos suman solo las cuentas de caja; las tarjetas aparecen después, en gris. El **Dashboard** (desempeño del mes, principales gastos) sigue viendo cada compra en su fecha: es la vista del gasto, no de la caja. --- # Movimientos e IOF **Nuevo movimiento**, en el encabezado de la tarjeta, abre el diálogo de carga. El tipo elegido arriba cambia los campos: | Tipo | Para qué | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Al contado** | Una compra, en un solo resumen. | | **En cuotas** | Una compra dividida en cuotas, una por resumen. | | **Recurrente** | Una suscripción cobrada cada mes, trimestre o año. *"Crea un cobro recurrente: el importe previsto aparece en cada resumen, y confirmas el importe real cuando llegue el resumen."* Ver [Recurrencias](https://docs.finance.kobana.com.br/es/es/cartoes/recorrencias.md). | | **Reembolso** | El banco devolvió el importe de una compra. *"Descuenta el importe del resumen."* | | **Intereses y tarifas** | *"Intereses, multa, anualidad e IOF de financiación. Entra en el resumen como gasto, en la categoría elegida."* | Los campos comunes son **Fecha de la compra**, **Importe**, **Descripción**, **Proveedor**, **Categoría** y **Centro de clasificación** — los dos últimos ya vienen con los predeterminados de la tarjeta. **Prorratear** divide el centro de clasificación entre varios, como en las cuentas por pagar. Un movimiento **realizado** entra en el momento en la cuenta de la tarjeta, en Mis cuentas — y es él el que aparece en Transacciones, en el Dashboard y en los informes por categoría, en la fecha de la compra. ## En qué resumen cae[​](#en-qué-resumen-cae "Enlace directo al En qué resumen cae") Antes de guardar, el diálogo dice dónde va a parar el movimiento: | Situación | El diálogo dice | | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | La fecha está en el período de un resumen abierto o futuro | *"Cae en el resumen de Dic/26, con vencimiento el 9/12."* | | El resumen de la fecha ya cerró | *"El resumen de Nov/26 ya cerró: el movimiento va al de Dic/26, que está abierto. El resumen cerrado no cambia."* | | La fecha está más allá de los resúmenes creados | *"Cae en el resumen de …, que se creará."* | | La fecha es anterior al primer resumen de la tarjeta | *"La fecha es anterior al primer resumen de la tarjeta en el sistema (…)."* — al contado, el movimiento se rechaza. | nota **Un resumen cerrado no cambia.** Una compra que llega después del cierre — el banco tardó en informarla, o alguien se olvidó — va al resumen abierto, con el aviso *"El resumen de la fecha ya cerró: el movimiento fue al resumen abierto."* El total del resumen cerrado, su cuenta por pagar y su revisión quedan como estaban. Para poner la compra en el resumen cerrado, reábrelo antes (ver [Reabrir](https://docs.finance.kobana.com.br/es/es/cartoes/fechar-conferir-pagar.md#reabrir)). ## En cuotas[​](#en-cuotas "Enlace directo al En cuotas") Indica el **Importe total** y el **Número de cuotas**. El diálogo muestra la división — *"6 × R$ 1.500,00"*, o *"1.ª de R$ 33,34 + 2 × R$ 33,33"* cuando los centavos no cierran: **los centavos de la división van en la primera cuota**. Y dónde cae cada una: *"Una cuota por resumen, de Sep/26 a Feb/27."* * La cuota **k** cae **k − 1** resúmenes después de la compra. * Una compra anterior al inicio del control de la tarjeta carga solo las cuotas que caen a partir del primer resumen, con la numeración original (**4/10** a **10/10**): *"Las cuotas anteriores al primer resumen de la tarjeta en el sistema no se cargarán."* * **Una compra internacional no puede cargarse en cuotas aquí.** En la tabla del resumen, cada cuota aparece con su número en la columna **Cuota** (**4/6**) y la fecha de la compra original. ## Compra internacional[​](#compra-internacional "Enlace directo al Compra internacional") Marca **Compra internacional** e indica la **Moneda** y el **Importe en USD** (o en la moneda elegida). El diálogo calcula el resto en vivo: | Campo | De dónde viene | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cotización** | Estimada: la PTAX de venta del Banco Central del día hábil anterior a la compra, más el **Spread del banco** definido en la tarjeta — *"Estimación: cotización oficial (PTAX) del 3/11, 5,2600, más 4% de spread del banco. Cámbiala por la cotización real cuando llegue el resumen."* | | **Alícuota de IOF** | Solo lectura. (i) *"La alícuota oficial en la fecha de la compra, o la de la tarjeta, si tiene una. Queda guardada en el movimiento, aunque la alícuota cambie después."* | | **IOF cobrado por el banco** | Opcional. (i) *"Si el IOF del resumen del banco es distinto del calculado, escribe su importe aquí."* | | **Total en el resumen** | El importe en la moneda × la cotización = el importe en reales + el IOF. | **El IOF es parte del movimiento.** Entra en el total del resumen, en la cuenta de la tarjeta y en los informes en la misma categoría y el mismo centro de clasificación de la compra — y, en el prorrateo, cada parte lleva la suya. El [informe de IOF pagado](https://docs.finance.kobana.com.br/es/es/cartoes/relatorios.md#iof-pagado) lo separa como impuesto. **Estimada hasta que llegue el resumen del banco.** Mientras la cotización sea la estimada, la tabla muestra *"estimada"* debajo del importe. Cuando llegue el resumen del banco, edita el movimiento con la cotización (o el IOF) que vino en él. tip **El Banco Central fuera de línea no traba la carga.** Si la PTAX no responde, la cotización queda en blanco con el aviso *"El Banco Central no respondió ahora. Escribe la cotización para cargar."* **Una alícuota nueva no cambia el pasado.** La alícuota queda guardada en cada compra: cuando la tabla cambia, las compras anteriores mantienen la que valía en su fecha. ## Reembolso[​](#reembolso "Enlace directo al Reembolso") Elige la **Compra reembolsada** y el importe. El reembolso entra negativo en el resumen abierto y descuenta del total. En un reembolso de compra internacional, moneda, cotización y alícuota vienen de la original; marca **IOF devuelto** solo si el resumen del banco también devolvió el IOF. El ícono (i) del campo lo recuerda: *"Márcalo solo si el resumen del banco también devolvió el IOF. Varía de banco a banco."* **Reembolsar**, en el menú de una compra realizada, abre el diálogo con la original ya elegida. ## El menú del movimiento[​](#el-menú-del-movimiento "Enlace directo al El menú del movimiento") | Acción | Cuándo aparece | | -------------------------- | ------------------------------------------------------------ | | **Editar** | Siempre, salvo en el saldo anterior | | **Mover** | En un resumen abierto o futuro | | **Anticipar** | En cuotas | | **Reembolsar** | En compras ya realizadas | | **Marcar como no cobrado** | En un cobro recurrente todavía previsto | | **Eliminar** | En un resumen abierto o futuro, salvo los cobros recurrentes | ### Editar[​](#editar "Enlace directo al Editar") *"Importe y fecha cambian solo en un resumen abierto o futuro."* En un resumen cerrado, el diálogo avisa: *"El resumen de … ya cerró: importe y fecha quedan bloqueados. Descripción, proveedor y clasificación siguen editables."* **En una serie** — cuotas o cobros de una recurrencia —, al guardar se pregunta el alcance: | Opción | Cuotas | Recurrencia | | ------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Solo esta** | Cambia solo esta cuota | Cambia solo el cobro de este mes | | **Esta y las siguientes** | De esta hasta la última | Cambia la recurrencia y los cobros previstos desde ahí, salvo los que ya se editaron | | **Todas** | La compra entera | Cambia la recurrencia y todos los cobros previstos, salvo los que ya se editaron. *"Lo ya confirmado no cambia."* | Una opción cuyo alcance toma una cuota de un resumen cerrado aparece deshabilitada, con el motivo: *"La cuota 2/6 está en el resumen de Oct/26, que ya cerró: reábrelo para cambiar su importe o su fecha."* La fecha de una compra en cuotas solo cambia con **Todas**; en una recurrencia, la fecha, el prorrateo, la cotización, el IOF y las notas valen solo para ese cobro. ### Mover[​](#mover "Enlace directo al Mover") Lleva el movimiento a otro resumen abierto o futuro. *"El movimiento queda fijo en el resumen elegido, aunque cambie la fecha de cierre."* — por eso recibe el candado en la tabla. ### Anticipar[​](#anticipar "Enlace directo al Anticipar") Cuando el banco adelanta cuotas (con o sin descuento), **Anticipar** lleva las últimas cuotas que están en resúmenes futuros al resumen abierto, y quedan fijas en él. El **Descuento del banco**, si lo hay, entra como el reembolso *"Desconto por antecipação"*. ### Eliminar[​](#eliminar "Enlace directo al Eliminar") *"El movimiento sale del resumen y de la cuenta de la tarjeta."* En una compra en cuotas, el alcance pregunta qué cuotas salen. Los cobros de una recurrencia no se eliminan: usa **Marcar como no cobrado** o termina la recurrencia. --- # Recurrencias Las suscripciones y servicios cobrados cada mes en la tarjeta — software, hosting, correo — pasan a ser **recurrencias**. Cada recurrencia pone un cobro **previsto** en cada resumen abierto y futuro; cuando llega el resumen del banco, confirmas el importe real. ![Recurrencias de la tarjeta, con la sugerencia de actualizar el importe](/es/assets/images/39-card-recurrences-7aa5a77bb2d4ce8ca81e11fb23f0cf06.png) ## Crear[​](#crear "Enlace directo al Crear") En la pestaña **Recurrencias** de la tarjeta, **Nueva recurrencia** — o **Nuevo movimiento** con el tipo **Recurrente**. Los campos: | Campo | Observaciones | | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Primer cobro** | Desde cuándo se cobra la suscripción. | | **Importe** | El importe esperado de cada cobro. En una suscripción en moneda extranjera, el importe en esa moneda. | | **Día del cobro** | El día del mes en que la suscripción se cobra en la tarjeta (limitado al último día del mes). | | **Frecuencia** | **Mensual**, **Trimestral** o **Anual**. | | **Fecha de fin** | (i) *"En blanco, el cobro sigue sin fecha de fin. Si la finalizas después, los cobros previstos desde entonces se cancelan."* | | **Descripción** · **Proveedor** · **Categoría** · **Centro de clasificación** | Se copian a cada previsto. | *"Un cobro previsto en cada resumen, a partir del de Dic/26."* Un resumen cerrado nunca recibe un cobro previsto nuevo. nota **El cobro previsto todavía no es gasto.** Entra en el **Total previsto** del resumen y en el límite usado, pero no en la cuenta de la tarjeta, ni en Transacciones, ni en el Dashboard. Pasa a ser gasto cuando se confirma. En una suscripción en moneda extranjera, el cobro previsto se convierte con la PTAX del día hábil anterior más el **Spread del banco** de la tarjeta. Si el Banco Central no responde y no hay cotización guardada, los cobros previstos esperan: *"Sin cotización de USD ahora: los cobros previstos entran cuando el Banco Central responda."* ## Confirmar con el importe real[​](#confirmar-con-el-importe-real "Enlace directo al Confirmar con el importe real") En el resumen, **Confirmar cobros recurrentes (3)** abre la lista de los cobros previstos de ese resumen: *"Escribe el importe que vino en el resumen del banco. Enter confirma y pasa al siguiente. En blanco, confirma el importe previsto."* * Una variación de más del 5% sobre el previsto aparece en ámbar. * En una suscripción internacional, indica también la **Cotización real**. * **No cobrado** saca el cobro del total del resumen: el banco no lo cobró este mes. La confirmación también vale con el resumen **cerrado** — así se revisa con el resumen del banco. Un resumen revisado o pagado ya no acepta confirmaciones: reábrelo antes. Cada cobro también tiene acciones en el menú de la fila del resumen: **Editar** (para confirmar uno solo) y **Marcar como no cobrado**. ## La pestaña Recurrencias[​](#la-pestaña-recurrencias "Enlace directo al La pestaña Recurrencias") | Columna | Qué trae | | ----------------------- | --------------------------------------------------- | | **Descripción** | Con el proveedor y la categoría debajo | | **Importe** | El importe esperado, en la moneda de la recurrencia | | **Cobro** | *"día 4 · mensual"* | | **Próximo cobro** | La fecha del próximo cobro y el resumen en que cae | | **Último importe real** | El último importe confirmado y el mes | | **Variación** | Del último importe real sobre el previsto | | **Estado** | **Activa** o **Terminada** | La búsqueda, las pestañas **Activas** y **Terminadas** y el botón **Nueva recurrencia**. La pestaña **Recurrencias** de arriba muestra cuántas están activas. ### La sugerencia de actualizar el importe[​](#la-sugerencia-de-actualizar-el-importe "Enlace directo al La sugerencia de actualizar el importe") Cuando los **tres últimos** cobros confirmados vinieron todos más de 5% por encima (o por debajo) de lo previsto, un aviso arriba de la pestaña propone su promedio: > *"Hospedagem dos sites vino más de 5% por encima de lo previsto en los últimos 3 meses (promedio R$ 947,90). ¿Actualizar el importe de la recurrencia?"* **Actualizar a R$ 947,90** cambia el importe de la recurrencia y de los cobros previstos que aún no se editaron. **Ahora no** oculta el aviso hasta que la sugerencia cambie. Un mes **no cobrado** en el medio corta la secuencia, y no hay sugerencia si el promedio queda a menos del 5% del importe actual — el caso de una suscripción estable en dólares con el tipo de cambio oscilando. ## Editar, terminar, eliminar[​](#editar-terminar-eliminar "Enlace directo al Editar, terminar, eliminar") | Acción | Qué hace | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Editar** | *"Los cobros previstos que aún no se editaron pasan a seguir la recurrencia. Lo ya confirmado no cambia."* | | **Terminar** | Pide la fecha del fin. *"Los cobros previstos después de esta fecha se cancelan. Lo ya confirmado no cambia."* | | **Eliminar** | *"… y sus cobros previstos salen de los resúmenes. Solo puede eliminarse mientras ningún cobro se haya confirmado; después, finaliza la recurrencia."* | Editar un cobro en el resumen con el alcance **Esta y las siguientes** o **Todas** también actualiza la recurrencia — ver [Movimientos e IOF](https://docs.finance.kobana.com.br/es/es/cartoes/lancamentos-e-iof.md#editar). ## En el informe[​](#en-el-informe "Enlace directo al En el informe") El informe [Previsto × realizado](https://docs.finance.kobana.com.br/es/es/cartoes/relatorios.md#previsto--realizado) compara, mes a mes, lo que preveía cada recurrencia y lo que se cobró. --- # Informes La píldora **Informe** — en la lista de tarjetas o en la pantalla de una tarjeta — abre **Generar informe** con dos tipos: **IOF pagado** y **Previsto × realizado**. Abierto desde la pantalla de una tarjeta, ya viene con esa tarjeta en el filtro y con el tipo de la pestaña en la que estabas. | Paso | Opciones | | -------------------- | -------------------------------------------------------------------------------------------------- | | **Tipo** | **IOF pagado** o **Previsto × realizado** | | **Nivel de detalle** | **Resumen** (los grupos) o **Detalle** (los grupos y, debajo de cada uno, sus movimientos) | | **Agrupar por** | Solo en el IOF: **Mes**, **Tarjeta**, **Categoría** o **Proveedor** | | **Período** | Obligatorio. En el IOF, por **fecha de compra**; en el previsto × realizado, por **mes del cobro** | | **Filtros** | **Tarjetas**, **Categoría** y **Proveedor** (opcionales) | **Incluir gráfico** agrega el gráfico arriba de la tabla. **Generar informe** abre el informe en una página propia, lista para imprimir. ![IOF pagado en las compras internacionales, por proveedor](/es/assets/images/41-card-iof-report-161f3d246377f2eec200ac6e82fe2386.png) ## IOF pagado[​](#iof-pagado "Enlace directo al IOF pagado") El IOF de las compras internacionales tratado como impuesto: para cada grupo, el **Importe de la compra** (en reales, sin el IOF), el **IOF**, la **Alícuota** y la cantidad de compras, con el total al final. * Entran solo movimientos **realizados** o **conciliados** con IOF. Un previsto todavía no pagó ningún impuesto. * Un reembolso con el IOF devuelto **descuenta** del grupo. * **Por categoría**, una compra prorrateada entre categorías reparte el IOF en la misma proporción. Al filtrar por categoría, cuenta solo la parte de la compra en las categorías elegidas. * En el **Detalle**, cada compra muestra la moneda, el importe en la moneda, la cotización, el importe de la compra, la alícuota guardada en ella y el IOF. nota **La alícuota del grupo es la efectiva: el IOF dividido por el importe de la compra.** Como el IOF de cada compra se redondea al centavo, puede salir *3,4999%* en un grupo de compras al 3,5%. La de cada compra, en el detalle, es la alícuota guardada en ella. ## Previsto × realizado[​](#previsto--realizado "Enlace directo al Previsto × realizado") Para cada recurrencia, mes a mes: el **Previsto** (el importe esperado), el **Realizado** (lo confirmado; no cobrado cuenta cero), la **Diferencia** y la **Diferencia (%)**, siempre en reales y sin IOF — la misma cuenta de la columna **Variación** de la pestaña Recurrencias. Un mes todavía previsto entra en el previsto y queda sin realizado ni diferencia. La columna **Meses** muestra cuántos ya se confirmaron: *"6 (2 por confirmar)"*. *"La diferencia compara solo los meses ya confirmados; el previsto los suma todos."* ## Exportar en CSV o XLSX[​](#exportar-en-csv-o-xlsx "Enlace directo al Exportar en CSV o XLSX") En la página del informe, **Exportar a Excel** abre la exportación con la elección del **Formato**: CSV o XLSX. Las columnas son las mismas de la pantalla, en los dos formatos: * **CSV** en el formato brasileño (punto y coma, coma decimal), como los demás informes del sistema; * **XLSX** con números de verdad — moneda, porcentaje y fecha con formato, encabezado fijo —, listo para sumar y filtrar en la planilla. ## Por la API y por el MCP[​](#por-la-api-y-por-el-mcp "Enlace directo al Por la API y por el MCP") Los mismos números salen de [`GET /card-transactions/aggregates`](https://docs.finance.kobana.com.br/es/es/api/v1/aggregate-card-transactions), agrupando por `card`, `statement`, `category`, `person` o `month`, con `sum_iof_amount` y `sum_base_amount` en cada grupo, y de la herramienta `finance_card_transactions_aggregates` del [servidor MCP](https://docs.finance.kobana.com.br/es/es/mcp/tools/accounts.md#card_transactions). --- # Categorías Las categorías (`/categories`) clasifican cuentas por pagar, cuentas por cobrar y transacciones. La estructura es jerárquica, de hasta **tres niveles**. ![Listado de categorías](/es/assets/images/11-categories-9cf1be66dc3b10c386f82708eed3858e.png) ## Campos[​](#campos "Enlace directo al Campos") | Campo | Obligatorio | Descripción | | ------------------- | ----------- | ---------------------------------- | | **Nombre** | Sí | Nombre de la categoría | | **Tipo** | Sí | **Ingresos** o **Gasto** | | **Empresa** | Sí | La empresa dueña de la categoría | | **Categoría padre** | No | Categoría superior en la jerarquía | **En una subcategoría, Tipo y Empresa no aparecen** — se heredan del padre. Solo eliges los dos al crear una categoría raíz. ## Tipo: ingreso o gasto[​](#tipo-ingreso-o-gasto "Enlace directo al Tipo: ingreso o gasto") * **Gasto** — aparece en el selector de cuentas por pagar y de transacciones de salida. * **Ingresos** — aparece en el selector de cuentas por cobrar y de transacciones de entrada. **Una subcategoría es siempre del mismo tipo que el padre.** No hay forma de mezclar: el sistema rechaza el guardado con *"Una subcategoría debe tener el mismo tipo que su categoría padre"*. Cambiar el tipo de una categoría **raíz** está permitido, y el cambio **baja a todo el subárbol** — hijos y nietos acompañan. ## Jerarquía[​](#jerarquía "Enlace directo al Jerarquía") ``` Gastos Operativos (Gasto) ├── Alquiler ├── Energía y Agua │ ├── Energía Eléctrica │ └── Agua y Alcantarillado └── Nómina ├── Salarios └── Cargas Sociales Ingresos (Ingresos) ├── Cuotas Mensuales └── Servicios ├── Consultoría └── Soporte ``` nota **El límite es de tres niveles.** En el tercer nivel el botón **Agregar subcategoría** deja de aparecer, y un intento por otro camino se rechaza con *"Se alcanzó el límite de 3 niveles de jerarquía."* ## La pantalla[​](#la-pantalla "Enlace directo al La pantalla") Las categorías se muestran en **tarjetas**, no en tabla. Cada tarjeta es una categoría raíz, con sus subcategorías listadas dentro. * **Búsqueda** por nombre. Un resultado en nivel 2 o 3 trae la tarjeta entera del ancestro a la pantalla, para que veas dónde está. * **Pestañas** con contadores: **Todas** · **Gastos** · **Ingresos**. Los contadores cuentan solo categorías raíz — es el número de tarjetas. * **Doble clic en el nombre** abre la edición ahí mismo, sin diálogo. * **Distintivos:** **Ingresos** o **Gasto** en la tarjeta raíz, y **Sin uso** cuando ni la categoría ni ninguna subcategoría suya tienen vínculos. * El conteo de transacciones de una tarjeta **suma el subárbol** — el número en el padre incluye lo que está en los hijos. Con el selector de empresa en "Todas", las tarjetas se agrupan en secciones plegables por empresa. Al elegir una empresa específica, se vuelve una cuadrícula única. ## Filtrar por categoría en otras pantallas[​](#filtrar-por-categoría-en-otras-pantallas "Enlace directo al Filtrar por categoría en otras pantallas") Al filtrar transacciones o cuentas por una categoría padre, **las subcategorías no entran automáticamente**. Dentro del filtro de Categoría existe la opción **Incluir subcategorías** — márcala para que el filtro alcance el subárbol entero. La opción **Sin categoría**, en el mismo filtro, es mutuamente excluyente: marcarla deshabilita **Incluir subcategorías**. ## Distribución[​](#distribución "Enlace directo al Distribución") Una cuenta puede dividirse entre **varias categorías** — por ejemplo, 60% en **Alquiler** y 40% en **Energía**. El atajo **Distribución**, al lado del campo **Categoría** en los formularios de **cuentas por pagar**, **cuentas por cobrar** y **transacciones**, abre el diálogo **"División por categoría"**. El diálogo funciona igual que el del centro de clasificación — **"Modo de división"** por porcentaje o por monto, un **"Total restante"** que tiene que cerrar, sin categoría repetida. Ver [Distribución en Centros de clasificación](https://docs.finance.kobana.com.br/es/es/centros-de-classificacao/.md#distribuci%C3%B3n). Las dos distribuciones son **independientes**: una cuenta puede distribuirse por categoría, por centro, por ambos o por ninguno. Qué cambia con una cuenta distribuida: * **Informes y la vista general** suman cada categoría por su parte: una cuenta de R$ 1.000 distribuida 60/40 entra con R$ 600 en Alquiler y R$ 400 en Energía — incluidas las ocurrencias futuras de una serie recurrente. * **El filtro por categoría** encuentra la cuenta por **cualquiera** de sus categorías. **Sin categoría** nunca trae una cuenta distribuida. * **Los informes filtrados por categoría** suman solo la parte de la cuenta en las categorías filtradas: filtrar **Energía** trae R$ 400 de la cuenta anterior, no R$ 1.000. El filtro por centro de clasificación funciona igual. * **Las listas** muestran la primera categoría de la distribución, con un **+N** para las demás. * **Cuotas, recurrencia y liquidación** heredan la distribución — la transacción de la liquidación sale distribuida igual. * **Las reglas automáticas no deshacen la distribución**: la regla mantiene las categorías de una cuenta ya distribuida. **Clasificar seleccionados**, por ser una acción explícita, cambia la distribución por una sola categoría. Elegir una única categoría para una cuenta que estaba distribuida deshace la distribución. ## Importación de CSV[​](#importación-de-csv "Enlace directo al Importación de CSV") La importación acepta **una categoría por fila** — la distribución por categoría se configura en el formulario. En la vista previa de la importación, cada categoría de la planilla aparece con lo que va a pasar: la que ya existe se vincula; la que todavía no existe viene marcada para **crear** (si tienes permiso para crear categorías); y un nombre casi igual a uno existente — solo cambia acento, mayúscula o espacio — viene marcado para **usar la existente**. Puedes cambiar cada elección, incluso a **dejar en blanco**. La categoría creada en la importación es **raíz**, del tipo del lado del archivo: **Gasto** para cuentas por pagar, **Ingresos** para cuentas por cobrar y, en las transacciones, el tipo de cada línea. La búsqueda es por el nombre de la categoría, no por su ruta en el árbol. Detalles en las páginas de importación de [transacciones](https://docs.finance.kobana.com.br/es/es/lancamentos/importacao-csv.md), [cuentas por pagar](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/importacao-csv.md) y [cuentas por cobrar](https://docs.finance.kobana.com.br/es/es/contas-a-receber/importacao-csv.md). ## Eliminar[​](#eliminar "Enlace directo al Eliminar") peligro **La eliminación borra también las subcategorías.** Eliminar una categoría la quita **a ella y a todo su subárbol**. Las transacciones, cuentas por pagar y cuentas por cobrar vinculadas **no se borran**: quedan **sin categoría**. **Lo único que bloquea la eliminación es una distribución.** Si la categoría — o alguna subcategoría suya — es una de las partes de una cuenta distribuida, la eliminación se rechaza con *"Esta categoría está en una distribución de movimientos y no se puede eliminar. Ajuste la distribución antes."* Sacar la categoría de la distribución dejaría las partes sin cerrar, así que eres tú quien decide adónde va esa parte. El diálogo dice exactamente eso antes de que confirmes: *"Esto eliminará esta categoría y todas sus subcategorías. Esta acción no se puede deshacer."*, seguido de lo que encontró — *"Esta categoría está vinculada a 12 transacciones, 3 cuentas por pagar (15 en total). Estas transacciones quedarán sin categoría tras la eliminación."* Si no hay vínculo, también lo dice. El aviso es **informativo, no impide**. Si quieres preservar la clasificación, reclasifica los registros antes: en las pantallas de Transacciones, Cuentas por Pagar y Cuentas por Cobrar, selecciona las filas y usa **Clasificar seleccionados**. --- # Centros de clasificación Los centros de clasificación (`/classification-centers`) permiten asignar gastos e ingresos a departamentos, proyectos o áreas de la empresa. Una sola cuenta puede dividirse entre varios centros — la **distribución**. ![Listado de centros de clasificación](/es/assets/images/12-classification-centers-c237430d80013463d06fb27e2bd7e138.png) ## Campos[​](#campos "Enlace directo al Campos") | Campo | Descripción | | --------------- | ------------------------------------------------------------------------------------------- | | **Nombre** | Obligatorio | | **Tipo** | Obligatorio. **Costo**, **Ingresos** o **Ambos** | | **Empresa** | Obligatorio. El centro pertenece a una empresa | | **Descripción** | Opcional | | **Activo** | Activa/desactiva. *"Los centros de clasificación inactivos no aparecen en los formularios"* | Un centro **Ambos** sirve a las dos polaridades — útil para proyectos o áreas que concentran costos e ingresos. **En el listado, "Ambos" no tiene distintivo propio.** Un centro de ese tipo aparece con **dos** distintivos lado a lado, **Costo** e **Ingresos**, cada uno en el color de su polaridad. Se lee como "sirve a los dos", no como un tercer tipo. ## Activo e Inactivo[​](#activo-e-inactivo "Enlace directo al Activo e Inactivo") La columna de estado muestra **Activo** o **Inactivo**. **Desactivar no lo quita del listado.** El centro sigue ahí, con el distintivo **Inactivo**. La promesa *"no aparecerá en nuevos movimientos"* es sobre los **selectores**: sale de los formularios de cuentas por pagar, por cobrar y transacciones, pero el historial que ya lo referencia permanece intacto. ## Eliminación[​](#eliminación "Enlace directo al Eliminación") El camino depende de si el centro está en uso, y la pantalla decide por ti: **Sin vínculo** — diálogo **"¿Eliminar centro de clasificación?"**: *"Esto eliminará este centro de clasificación. Esta acción no se puede deshacer."* **En uso** — no hay eliminación. El diálogo es **"Centro de clasificación en uso"**: > *"Este centro de clasificación está en uso por movimientos y no se puede eliminar. ¿Deseas desactivarlo? Seguirá en el historial pero no aparecerá en nuevos movimientos."* El botón es **"Desactivar"**. Es decir: el producto **convierte la eliminación en desactivación** — no existe un camino de eliminación forzada que deje las transacciones sin centro. ## Distribución[​](#distribución "Enlace directo al Distribución") La distribución **no se configura en esta pantalla**. Vive en el diálogo **"División por centro de clasificación"**, abierto desde el atajo **Distribución** en los formularios de **cuentas por pagar**, **cuentas por cobrar** y **transacciones**. ### Modo de división[​](#modo-de-división "Enlace directo al Modo de división") El campo **"Modo de división"** elige qué columna completas: | Modo | Tú completas | El sistema calcula | | ------------------------------------- | -------------------------- | ------------------ | | **Porcentaje (%)** *(predeterminado)* | El porcentaje de cada fila | El monto en reales | | **Monto (R$)** | El monto de cada fila | El porcentaje | La columna del modo inactivo queda **deshabilitada** — las dos son siempre visibles, pero solo una es editable. ### Cerrar la cuenta[​](#cerrar-la-cuenta "Enlace directo al Cerrar la cuenta") El pie muestra el **"Total restante"**, en porcentaje y en reales, y queda en rojo mientras no cierre. **"Guardar división"** solo se habilita cuando se cumplen las tres condiciones: * El total cierra (restante cero, con tolerancia de un centavo). * **Toda fila tiene un centro elegido** — *"Todas las filas necesitan un centro de clasificación seleccionado."* * **No hay centro repetido** — *"Centro de clasificación duplicado — cada fila necesita un centro distinto."* nota **Editar una fila no redistribuye las otras.** Bajar un centro del 60% al 50% **no** traspasa el 10% a nadie: el "Total restante" pasa a mostrar 10%, y eres tú quien cierra la cuenta. Lo mismo vale al **agregar** una fila (entra con cero) y al **eliminar** (su porción se vuelve sobrante). El sistema **valida**; quien redistribuye eres tú. ### Qué rebalancea el sistema por su cuenta[​](#qué-rebalancea-el-sistema-por-su-cuenta "Enlace directo al Qué rebalancea el sistema por su cuenta") Una cosa, y solo ella: **cambiar el monto total de la cuenta**. Los porcentajes se preservan y los montos en reales se recalculan — la última fila absorbe el residuo de centavos, para que la suma cuadre exacta. Por eso corregir el monto de una cuenta ya distribuida no desarma la distribución. En el modo **Monto (R$)** el efecto se invierte: los montos se preservan y son los **porcentajes** los que se recalculan. Una **regla automática** no deshace esta distribución — ver [Reglas automáticas](https://docs.finance.kobana.com.br/es/es/regras-automaticas/.md). La categoría también puede distribuirse, de forma independiente: ver [Categorías](https://docs.finance.kobana.com.br/es/es/categorias/.md#distribuci%C3%B3n). ## Distribución en cuotas[​](#distribución-en-cuotas "Enlace directo al Distribución en cuotas") Al **crear** una cuenta en cuotas, la distribución se propaga a **todas** las cuotas del grupo, automáticamente. Al **editar** una cuota que ya existe, no: el sistema **pregunta**. Al alterar la distribución de una cuota de un grupo, el diálogo de propagación muestra lo que cambió y te deja elegir qué cuotas hermanas heredan el cambio. Ver [Cuotas y recurrencia](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/parcelas-e-recorrencia.md). ## Importación CSV[​](#importación-csv "Enlace directo al Importación CSV") La importación acepta **un único centro por línea**. El nombre de la columna cambia según el archivo: | Importación | Columna | También acepta | | ------------------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | Cuentas por pagar / por cobrar | `cost_center_name` | `centro_custo`, `centro_de_custo`, `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` | | Transacciones | `centro_custo` | `centro_de_custo`, `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` | Además de esos nombres, una columna con la palabra **centro** en el encabezado también se lee como centro de clasificación. En la vista previa, cada centro de la planilla aparece con lo que va a pasar: el que ya existe se vincula — sin distinguir mayúsculas, e ignorando espacios en los extremos; el que todavía no existe viene marcado para **crear** (si tienes permiso para crear centros de clasificación); y un nombre casi igual a uno existente — solo cambia acento, mayúscula o espacio — viene marcado para **usar el existente**. Puedes cambiar cada elección, incluso a **dejar en blanco**. El lado del archivo decide **cuáles** centros valen: una importación de cuentas por pagar solo ve centros de **Costo**, y una de cuentas por cobrar, solo los de **Ingresos**. Un centro **Ambos** atiende a los dos. Si hay dos centros del mismo nombre, el del lado exacto le gana al **Ambos**. Un centro que solo existe del otro lado viene marcado para dejar en blanco; eligiendo crear, nace otro centro, del lado del archivo. El centro creado en la importación es del lado del archivo — en las transacciones, un centro nuevo usado en entradas y salidas se crea una sola vez, del tipo **Ambos**. Detalles en las páginas de importación de [transacciones](https://docs.finance.kobana.com.br/es/es/lancamentos/importacao-csv.md), [cuentas por pagar](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/importacao-csv.md) y [cuentas por cobrar](https://docs.finance.kobana.com.br/es/es/contas-a-receber/importacao-csv.md). Para distribuir entre varios centros, edita la cuenta después de importar. --- # Clasificadores personalizados Los clasificadores personalizados (`/custom-classifiers`) son **dimensiones de clasificación que tú creas** — como "Región", "Producto" o "Canal" — más allá de los ejes fijos (categoría y centro de clasificación). Cada dimensión tiene sus propios **valores**, y un mismo título puede llevar **varias** dimensiones a la vez. *"Crea tus propias dimensiones (ej.: Región, Producto) y sus valores para clasificar tus registros."* ## Dos niveles: dimensión y valor[​](#dos-niveles-dimensión-y-valor "Enlace directo al Dos niveles: dimensión y valor") El catálogo tiene dos niveles: * **Dimensión** — el eje. Solo tiene un **nombre** (ej.: "Región"). * **Valor** — cada opción dentro de la dimensión (ej.: "Sur", "Sudeste"). Vive **dentro** de la dimensión. Una dimensión sin valores aparece en el listado marcada como **"Sin valores"** — existe, pero no clasifica nada hasta que agregues al menos un valor. ## Campos[​](#campos "Enlace directo al Campos") | Campo | Nivel | Descripción | | -------------------------- | --------- | ----------------------------------------------------------------------------- | | **Nombre de la dimensión** | Dimensión | Obligatorio. Ej.: "Región" | | **Empresa** | Dimensión | La dimensión pertenece a una empresa | | **Activo** | Dimensión | Enciende/apaga. *"Las dimensiones inactivas no aparecen en los formularios."* | | **Valor** | Valor | Obligatorio. Ej.: "Sudeste" | | **Activo** | Valor | Enciende/apaga el valor individualmente | ## La pantalla[​](#la-pantalla "Enlace directo al La pantalla") La gestión está en **Ejes → Clasificadores personalizados**, en una tabla donde cada fila es una **dimensión** con sus valores como chips al lado. * **Búsqueda** por nombre de la dimensión. * **Nueva dimensión** crea el eje; el diálogo de valores agrega, renombra, activa/desactiva y elimina cada valor **en vivo**. * Un valor puede **activarse o desactivarse** individualmente sin salir de la dimensión. Cuando no hay ninguna dimensión, la pantalla muestra el estado vacío: *"Ningún clasificador registrado — Crea dimensiones como 'Región' o 'Producto' y sus valores para clasificar tus registros."* ## Activo e inactivo[​](#activo-e-inactivo "Enlace directo al Activo e inactivo") El indicador **Activo** existe en los dos niveles, y el efecto coincide con los centros de clasificación: **desactivar no elimina**. * Una **dimensión** inactiva sale de los formularios, pero el historial que ya la referencia permanece. * Un **valor** inactivo desaparece del selector **para nuevas elecciones** — pero, si un título ya lo usa, sigue apareciendo allí como el valor seleccionado, para no perderse del registro. ## Eliminar[​](#eliminar "Enlace directo al Eliminar") Como en los centros de clasificación, el producto **convierte la eliminación en desactivación** cuando hay uso — no existe un camino que deje los registros sin clasificación. **Valor en uso** — no hay eliminación: *"El valor está en uso por registros. Desactívalo en lugar de eliminarlo."* **Dimensión en uso** — el diálogo es **"Clasificador en uso"**: > *"Este clasificador está en uso por registros y no puede eliminarse. ¿Deseas desactivarlo?"* El botón es **"Desactivar"**. Eliminar la dimensión solo es posible cuando **ninguno** de sus valores está asignado a un título. ## Clasificar un registro[​](#clasificar-un-registro "Enlace directo al Clasificar un registro") El bloque **"Clasificadores personalizados"** aparece en los formularios de **cuentas por pagar**, **cuentas por cobrar** y **transacciones** — las **tres** pantallas, y también en la vista de detalle de cada una. * Hay **un selector por dimensión activa**. Todas las dimensiones activas están siempre visibles. * La selección es **un valor por dimensión** (selección única) — a diferencia del prorrateo de centros de clasificación, aquí un título no se divide entre valores. * El selector hace **"seleccionar o crear"**: al escribir un valor que aún no existe, ofrece registrarlo y crea el valor en la dimensión cuando guardas el título. nota **La clasificación no se propaga automáticamente a las cuotas 2 en adelante.** Al publicar un título en cuotas, la dimensión queda en la cuota ancla — el mismo comportamiento del centro de clasificación. Para aplicarla a varias filas de una vez, usa **Clasificar seleccionados** en los listados de Transacciones, Cuentas por pagar y Cuentas por cobrar. ## Búsqueda avanzada[​](#búsqueda-avanzada "Enlace directo al Búsqueda avanzada") La búsqueda avanzada de Transacciones, Cuentas por pagar y Cuentas por cobrar tiene un único facet **"Clasificador"** que reúne los valores de **cualquier** dimensión. Marca uno o más valores y la búsqueda trae los títulos que los llevan. El mismo facet ofrece **"Sin clasificador"**, para encontrar los títulos sin ninguna dimensión. El facet solo aparece cuando existe al menos una dimensión. ## Informes[​](#informes "Enlace directo al Informes") Los informes (normal y fiscal) permiten **agrupar por clasificador**: elegida una dimensión, cada fila del informe es uno de sus valores, y los títulos sin esa dimensión caen en **"(sin clasificador)"** — nunca se pierden del total. ## Importación de CSV[​](#importación-de-csv "Enlace directo al Importación de CSV") A diferencia de categorías y centros de clasificación, la importación de CSV **crea los valores que faltan**. * Cada dimensión activa se vuelve una **columna** en el archivo, con el **nombre de la dimensión** en el encabezado. * Al importar, el valor de cada fila es **buscado y creado si no existe** en esa dimensión. Las dimensiones en sí **no** son creadas por la importación — regístralas antes; los valores, en cambio, nacen del archivo. ## En la API[​](#en-la-api "Enlace directo al En la API") La API pública v1 expone el catálogo en `/api/v1/custom-classifiers` (dimensiones, con sus valores en rutas anidadas `/{id}/values`) bajo el scope `finance/custom_classifiers`, con el nivel de acceso `read` para leer, `write` para crear y modificar y `delete` para eliminar. En los títulos, el campo `custom_classifications` acompaña a **cuentas por pagar**, **cuentas por cobrar** y **transacciones**: un conteo en el listado, la lista completa en el detalle y, al escribir, informas el valor por id **o** por nombre (seleccionar-o-crear). Detalles en la **referencia de la API**. ## Origen Fintera[​](#origen-fintera "Enlace directo al Origen Fintera") Cuando la integración con Fintera está activa, los clasificadores y sus valores se **importan** desde allí (solo lectura). El vínculo de un título nombra el valor por **texto**, resuelto al valor correspondiente en Finanzas Inteligentes al momento de la importación. Ver [Integración Fintera](https://docs.finance.kobana.com.br/es/es/integracoes/fintera.md). --- # Autenticación :::caution Los productos no comparten credenciales `KOBANA_TOKEN` guarda la credencial **de un producto por vez**. Un token de Finanzas Inteligentes no autentica en ningún otro producto Kobana, y viceversa. ::: ## El token[​](#el-token "Enlace directo al El token") Finanzas Inteligentes autentica con un **JWT firmado en RS256** por el servidor de autorización de Kobana, enviado como `Authorization: Bearer `. Mira [Autenticación de la API](https://docs.finance.kobana.com.br/es/es/api/overview/authentication.md) para saber cómo se emite ese token y qué scopes lleva — `kobana auth login`, que es del Gateway Bancario, **no** lo produce. :::caution El token por sí solo no basta El JWT identifica la **organización** (claim `org`). Como una organización puede tener varios espacios de trabajo, la API exige además la cabecera `X-Workspace-Id` indicando en cuál actuar — sin ella la respuesta es `400 WORKSPACE_REQUIRED`. Las excepciones son `me` y [`organization`](https://docs.finance.kobana.com.br/es/es/cli/resources/organization.md), de nivel de organización, que no llevan la cabecera. Mira [Autenticación de la API](https://docs.finance.kobana.com.br/es/es/api/overview/authentication.md). ::: Pon el JWT en `KOBANA_TOKEN` antes de llamar al producto: ``` export KOBANA_TOKEN=$JWT_FINANCE kobana finance financial-accounts list --fields "id,name,balance" ``` Como la variable es la misma para todos los productos, expórtala por comando (o usa un `.env` por proyecto) si alternas entre productos en la misma sesión: ``` KOBANA_TOKEN=$JWT_FINANCE kobana finance financial-accounts list --fields "id,name,balance" ``` ## Prioridad de resolución[​](#prioridad-de-resolución "Enlace directo al Prioridad de resolución") | Prioridad | Método | Configuración | | --------- | ----------------------- | ------------------------------------------- | | 1 | Token directo | `KOBANA_TOKEN` | | 2 | Archivo de credenciales | `KOBANA_CREDENTIALS_FILE` | | 3 | Credenciales guardadas | `kobana auth login` (solo Gateway Bancario) | ## Ambientes[​](#ambientes "Enlace directo al Ambientes") El CLI opera en tres ambientes, y cada producto tiene sus propios hosts. **Producción es el valor por defecto.** | Ambiente | API | `--env` | | ---------- | ----------------------------------- | -------------------------- | | Producción | `api.finance.kobana.com.br` | `production` (por defecto) | | Sandbox | `api.finance.sandbox.kobana.com.br` | `sandbox` | Finanzas Inteligentes no tiene host de desarrollo propio: con `--env development` el CLI cae en producción. ``` # Producción (por defecto — sin flag) kobana finance financial-accounts list # Sandbox kobana finance financial-accounts list --env sandbox # Vía variable de ambiente export KOBANA_ENVIRONMENT=sandbox kobana finance financial-accounts list ``` Los tokens son **diferentes entre ambientes** — un token de sandbox no funciona en producción, y viceversa. ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Uso](https://docs.finance.kobana.com.br/es/es/cli/usage/overview.md) — sintaxis, recursos, ejemplos. * [Variables de ambiente](https://docs.finance.kobana.com.br/es/es/cli/overview/environment-variables.md) — la referencia completa, incluyendo configuración y logs. --- # Variables de ambiente Todas las variables también pueden definirse en un archivo `.env` (cargado vía `dotenvy`). ## Autenticación[​](#autenticación "Enlace directo al Autenticación") | Variable | Descripción | | ------------------------- | ---------------------------------------------------------------------------- | | `KOBANA_TOKEN` | Token del producto que vas a llamar (Bearer). No se comparte entre productos | | `KOBANA_CREDENTIALS_FILE` | Ruta a un archivo JSON de credenciales OAuth | | `KOBANA_CLIENT_ID` | OAuth client ID (Gateway Bancario) | | `KOBANA_CLIENT_SECRET` | OAuth client secret (Gateway Bancario) | ## Configuración[​](#configuración "Enlace directo al Configuración") | Variable | Descripción | | -------------------- | ------------------------------------------------------------- | | `KOBANA_CONFIG_DIR` | Directorio de configuración (por defecto: `~/.config/kobana`) | | `KOBANA_ENVIRONMENT` | `production` (por defecto), `sandbox` o `development` | ## Logs[​](#logs "Enlace directo al Logs") | Variable | Descripción | | ----------------- | ------------------------------------------------------------------------------ | | `KOBANA_LOG` | Nivel de log en stderr (ej.: `kobana=debug`). Apagado por defecto. | | `KOBANA_LOG_FILE` | Directorio para archivos de log JSON con rotación diaria. Apagado por defecto. | ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Autenticación](https://docs.finance.kobana.com.br/es/es/cli/overview/authentication.md) — prioridad de resolución y credenciales por producto. * [Códigos de salida](https://docs.finance.kobana.com.br/es/es/cli/overview/exit-codes.md) — códigos de salida del proceso, para scripts. --- # Códigos de salida Cada ejecución de `kobana` termina con uno de estos códigos, para que un script decida qué hacer sin interpretar el cuerpo JSON del error. | Código | Significado | | ------ | ---------------------- | | `0` | Éxito | | `1` | Error de API (4xx/5xx) | | `2` | Error de autenticación | | `3` | Error de validación | | `4` | Error de schema | | `5` | Error interno | ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Uso](https://docs.finance.kobana.com.br/es/es/cli/usage/overview.md) — sintaxis, recursos, ejemplos. * [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) — `--dry-run`, `--output-format` y las demás. --- # Instalación ### Homebrew (macOS y Linux)[​](#homebrew-macos-y-linux "Enlace directo al Homebrew (macOS y Linux)") ``` brew tap universokobana/tap brew install kobana ``` Para actualizar: ``` brew update && brew upgrade kobana ``` ### Binarios precompilados[​](#binarios-precompilados "Enlace directo al Binarios precompilados") Descarga el binario de tu plataforma en la [página de Releases](https://github.com/universokobana/kobana-cli/releases/latest) y ponlo en tu `PATH`. | Plataforma | Archivo | | ------------------- | -------------------------- | | 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 "Enlace directo al Nix") ``` # Ejecutar directo desde GitHub nix run github:universokobana/kobana-cli # Instalar en el perfil nix profile install github:universokobana/kobana-cli ``` ### Build desde el source[​](#build-desde-el-source "Enlace directo al Build desde el source") ``` git clone https://github.com/universokobana/kobana-cli.git cd kobana-cli cargo install --path crates/kobana-cli ``` Requiere [Rust](https://rustup.rs/) 1.70+. ## Completions de shell[​](#completions-de-shell "Enlace directo al Completions de shell") ``` # Bash kobana completions bash > /etc/bash_completion.d/kobana # Zsh kobana completions zsh > ~/.zfunc/_kobana # Fish kobana completions fish > ~/.config/fish/completions/kobana.fish # PowerShell kobana completions powershell > kobana.ps1 ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Autenticación](https://docs.finance.kobana.com.br/es/es/cli/overview/authentication.md) — tokens y ambientes. * [Uso](https://docs.finance.kobana.com.br/es/es/cli/usage/overview.md) — sintaxis, recursos, ejemplos. --- # Introducción **`kobana`** es una única herramienta de línea de comandos para las APIs de todos los productos Kobana — Finanzas Inteligentes incluido. Se construye y mantiene en su propio repositorio ([`kobana-cli`](https://github.com/universokobana/kobana-cli)), no en este producto, y no tiene ningún endpoint escrito a mano: al arrancar lee las specs OpenAPI 3.1 embebidas en el binario y arma su árbol de comandos a partir de ellas. Actualizar la superficie de la API es cuestión de refrescar la spec embebida y publicar un build nuevo — nada de código por endpoint. ``` kobana [flags] ``` Pensada tanto para personas como para agentes de IA: salida JSON estructurada por defecto, introspección de schema, `--dry-run` y paginación automática. ## Productos[​](#productos "Enlace directo al Productos") | Producto | Descripción | | ------------ | ---------------------------------------------------------------------------------- | | `banking` | Gateway Bancario — cobros, pagos, transferencias (API v1 y v2) | | `finance` | Finanzas Inteligentes — cuentas por pagar y por cobrar, movimientos, flujo de caja | | `billing` | Facturación Automática — suscripciones, planes, facturas, notas fiscales | | `inbox` | Inbox Autónomo — casillas de entrada, agentes, correos, webhooks | | `dunning` | Cobranza — deudores, cobros, flujos de cobranza, acuerdos, reportes a burós | | `dashboards` | Dashboard Mágico — fuentes de datos, entidades, portal, workspaces | El producto `finance` habla con la misma API documentada en este sitio. Sus recursos — mira el [catálogo completo](https://docs.finance.kobana.com.br/es/es/cli/resources/overview.md) — apuntan a los mismos endpoints de la [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api/v1); el CLI es solo otra forma de llamarla. No comparte credenciales con los otros productos: mira [Autenticación](https://docs.finance.kobana.com.br/es/es/cli/overview/authentication.md). ## Comenzando[​](#comenzando "Enlace directo al Comenzando") 1. **Instálalo** — mira [Instalación](https://docs.finance.kobana.com.br/es/es/cli/overview/installation.md). 2. **Autentícate** en el producto que vas a usar. Mira [Autenticación](https://docs.finance.kobana.com.br/es/es/cli/overview/authentication.md). 3. **Haz la primera llamada**: ``` kobana finance financial-accounts list --fields "id,name,balance" ``` 4. **Explora la superficie** — todo comando acepta `--help`, y `kobana schema` muestra parámetros y cuerpo de cualquier endpoint sin salir de la terminal. ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Instalación](https://docs.finance.kobana.com.br/es/es/cli/overview/installation.md) — Homebrew, binarios precompilados, Nix, build desde el source. * [Autenticación](https://docs.finance.kobana.com.br/es/es/cli/overview/authentication.md) — tokens, ambientes y las credenciales propias de `finance`. * [Uso](https://docs.finance.kobana.com.br/es/es/cli/usage/overview.md) — sintaxis, recursos, ejemplos. * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — `kobana schema` para parámetros y formato de solicitud y respuesta. * [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) — las flags que acepta todo comando. * [Helpers](https://docs.finance.kobana.com.br/es/es/cli/usage/helpers.md) — atajos `+verbo` para flujos comunes. * [Variables de ambiente](https://docs.finance.kobana.com.br/es/es/cli/overview/environment-variables.md) — autenticación, configuración y logs. * [Códigos de salida](https://docs.finance.kobana.com.br/es/es/cli/overview/exit-codes.md) — códigos de salida del proceso, para scripts. --- # Agentes de IA Instrucciones que el asistente ejecuta por su cuenta, con los permisos de la persona dueña del token — por ejemplo, un resumen diario de las cuentas por pagar que vencieron. El listado trae solo los agentes de la persona del token en el workspace, nunca los de otro miembro. Cada ejecución gasta crédito de IA y se convierte en una nueva conversación del asistente (`last_run.conversation_id`); una acción destructiva espera la confirmación de la persona en el asistente. | Comando | HTTP | Descripción | | --------------------------- | ---------------------------------------------------- | ------------------------------------------ | | `ai-agents list` | `GET /v1/ai-agents` | Listar agentes de IA | | `ai-agents create` | `POST /v1/ai-agents` | Crear agente de IA | | `ai-agents get` | `GET /v1/ai-agents/{id}` | Obtener agente de IA por ID | | `ai-agents update` | `PATCH /v1/ai-agents/{id}` | Actualizar agente de IA | | `ai-agents delete` | `DELETE /v1/ai-agents/{id}` | Eliminar agente de IA | | `ai-agents triggers get` | `GET /v1/ai-agents/{id}/triggers` | Listar los disparadores de un agente de IA | | `ai-agents triggers create` | `POST /v1/ai-agents/{id}/triggers` | Agregar disparador a un agente de IA | | `ai-agents triggers update` | `PATCH /v1/ai-agents/{id}/triggers/{triggerId}` | Actualizar disparador de un agente de IA | | `ai-agents triggers delete` | `DELETE /v1/ai-agents/{id}/triggers/{triggerId}` | Eliminar disparador de un agente de IA | | `ai-agents triggers token` | `POST /v1/ai-agents/{id}/triggers/{triggerId}/token` | Renovar el token de un disparador de API | El agente nace activo con un disparador `manual`; los demás entran por `triggers create`: `event` (con `event_type`: `receipt.saved`, `fiscal_document.received`, `payable.created` o `receivable.created`), `schedule` (con un `cron` de 5 campos, como máximo cada 15 minutos, y `timezone` opcional — por defecto `America/Sao_Paulo`) y `api`. El token de un disparador `api` solo aparece en la respuesta de `triggers create` y de `triggers token` — guárdalo; `triggers token` invalida el anterior al instante. Por eso esas dos rutas no aceptan `--idempotency-key`. `update` con `active: false` pausa todos los disparadores automáticos y `active: true` los reanuda. Eliminar el agente elimina sus disparadores; las ejecuciones pasadas quedan en el asistente. Los scopes son `finance/ai_agents` (lectura, escritura y eliminación). ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar agentes de IA kobana finance ai-agents list \ --params '{"active": true}' \ --fields "id,title,active,next_run_at,last_run" # Obtener agente de IA por ID kobana finance ai-agents get \ --params '{"id": "AI_AGENT_ID"}' # Crear agente de IA kobana finance ai-agents create \ --json '{"title": "Resumen de cuentas vencidas", "instructions": "Lista las cuentas por pagar que vencieron ayer, agrupadas por proveedor, con el total."}' # Pausar todos los disparadores automáticos kobana finance ai-agents update \ --params '{"id": "AI_AGENT_ID"}' \ --json '{"active": false}' # Listar los disparadores de un agente de IA kobana finance ai-agents triggers get \ --params '{"id": "AI_AGENT_ID"}' # Programar el agente los días hábiles a las 6h kobana finance ai-agents triggers create \ --params '{"id": "AI_AGENT_ID"}' \ --json '{"kind": "schedule", "cron": "0 6 * * 1-5", "timezone": "America/Sao_Paulo"}' # Actualizar disparador de un agente de IA kobana finance ai-agents triggers update \ --params '{"id": "AI_AGENT_ID", "triggerId": "TRIGGER_ID"}' \ --json '{"cron": "0 7 * * 1-5"}' # Renovar el token de un disparador de API kobana finance ai-agents triggers token \ --params '{"id": "AI_AGENT_ID", "triggerId": "TRIGGER_ID"}' # Eliminar disparador de un agente de IA kobana finance ai-agents triggers delete \ --params '{"id": "AI_AGENT_ID", "triggerId": "TRIGGER_ID"}' \ --dry-run # Eliminar agente de IA kobana finance ai-agents delete \ --params '{"id": "AI_AGENT_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Habilidades de IA](https://docs.finance.kobana.com.br/es/es/cli/resources/ai-skills.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Habilidades de IA Conjuntos de instrucciones, en el formato Agent Skills, que el asistente carga cuando una tarea coincide con la `description` de la habilidad — es todo lo que lee para decidir. El listado trae las habilidades que la persona del token ve en el workspace: las suyas y las que otros miembros compartieron con ella (`is_owner` las distingue; `mine=true` deja solo las propias). | Comando | HTTP | Descripción | | ------------------ | --------------------------- | ------------------------------ | | `ai-skills list` | `GET /v1/ai-skills` | Listar habilidades de IA | | `ai-skills create` | `POST /v1/ai-skills` | Crear habilidad de IA | | `ai-skills get` | `GET /v1/ai-skills/{id}` | Obtener habilidad de IA por ID | | `ai-skills update` | `PATCH /v1/ai-skills/{id}` | Actualizar habilidad de IA | | `ai-skills delete` | `DELETE /v1/ai-skills/{id}` | Eliminar habilidad de IA | `create` pide `name`, `description` e `instructions` (el cuerpo del SKILL.md, en Markdown); `slug` sale del `name` si se omite y es único entre las habilidades de la persona (`409 slug_taken`). `files` lleva archivos de texto además del SKILL.md, hasta 200 000 caracteres en total. La habilidad nace activa y `private`; `visibility` (`restricted` con `member_ids`, o `workspace`) la comparte, y exige el permiso `ai-skills.share` de la persona. Son como máximo 100 habilidades por persona y workspace. Solo la dueña la cambia o elimina (`403`, `details.reason: not_owner`); en el `update`, `files` y `member_ids` reemplazan la lista entera y `active: false` oculta la habilidad del asistente. Los scopes son `finance/ai_skills`. ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar habilidades de IA kobana finance ai-skills list \ --params '{"mine": true}' \ --fields "id,slug,name,visibility,active,is_owner" # Obtener habilidad de IA por ID kobana finance ai-skills get \ --params '{"id": "AI_SKILL_ID"}' # Crear habilidad de IA kobana finance ai-skills create \ --json '{"name": "Cierre del mes", "description": "Úsala al cerrar el mes: revisa conciliaciones pendientes y cuentas vencidas.", "instructions": "1. Lista los movimientos sin conciliar del mes.\n2. Lista las cuentas por pagar vencidas."}' # Compartirla con el workspace kobana finance ai-skills update \ --params '{"id": "AI_SKILL_ID"}' \ --json '{"visibility": "workspace"}' # Eliminar habilidad de IA kobana finance ai-skills delete \ --params '{"id": "AI_SKILL_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Agentes de IA](https://docs.finance.kobana.com.br/es/es/cli/resources/ai-agents.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Adjuntos Archivos — factura, contrato, comprobante — enviados al acervo y vinculados a uno o más títulos. `links` crea ese vínculo y `unlink` lo deshace. | Comando | HTTP | Descripción | | ---------------------- | ----------------------------------- | ------------------------------------ | | `attachments list` | `GET /v1/attachments` | Listar adjuntos | | `attachments create` | `POST /v1/attachments` | Enviar un adjunto | | `attachments get` | `GET /v1/attachments/{id}` | Obtener metadatos del adjunto por ID | | `attachments delete` | `DELETE /v1/attachments/{id}` | Eliminar adjunto | | `attachments download` | `GET /v1/attachments/{id}/download` | Descargar los bytes del adjunto | | `attachments links` | `POST /v1/attachments/{id}/links` | Vincular adjunto a un registro | | `attachments unlink` | `POST /v1/attachments/{id}/unlink` | Desvincular adjunto de un registro | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar adjuntos kobana finance attachments list \ --fields "id,file_name,title,mime_type,file_size" # Obtener metadatos del adjunto por ID kobana finance attachments get --params '{"id": "ATTACHMENT_ID"}' # Enviar un adjunto, con título kobana finance attachments create \ --file file=factura-junio.pdf \ --json '{"title": "Factura de junio"}' # Eliminar adjunto kobana finance attachments delete --params '{"id": "ATTACHMENT_ID"}' --dry-run ``` `attachments create` va como `multipart/form-data`: el archivo va en `--file file=…` (pdf, png, jpg/jpeg, xml, ofx, csv o xlsx, hasta 10 MB), y `title` va en `--json`, como parte de texto. Después, `attachments links` vincula el adjunto a un registro. Vea [Envío de archivos](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md#env%C3%ADo-de-archivos). ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Comprobantes](https://docs.finance.kobana.com.br/es/es/cli/resources/receipts.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Reglas automáticas Las reglas que clasifican movimientos por sí solas, evaluadas en el orden en que están. `reorder` es lo que cambia ese orden. | Comando | HTTP | Descripción | | ------------------------- | ---------------------------------- | ------------------------------- | | `automatic-rules list` | `GET /v1/automatic-rules` | Listar reglas automáticas | | `automatic-rules create` | `POST /v1/automatic-rules` | Crear regla automática | | `automatic-rules get` | `GET /v1/automatic-rules/{id}` | Obtener regla automática por ID | | `automatic-rules update` | `PATCH /v1/automatic-rules/{id}` | Actualizar regla automática | | `automatic-rules delete` | `DELETE /v1/automatic-rules/{id}` | Eliminar regla automática | | `automatic-rules reorder` | `POST /v1/automatic-rules/reorder` | Reordenar reglas automáticas | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar reglas automáticas kobana finance automatic-rules list \ --fields "id,company_id,scope,position,active" # Obtener regla automática por ID kobana finance automatic-rules get --params '{"id": "AUTOMATIC_RULE_ID"}' # Crear regla automática kobana finance automatic-rules create \ --json '{"company_id": "COMPANY_ID", "scope": "transactions"}' # Actualizar regla automática kobana finance automatic-rules update \ --params '{"id": "AUTOMATIC_RULE_ID"}' \ --json '{"active": true, "account_id": "ACCOUNT_ID", "transaction_type": "debit"}' # Eliminar regla automática kobana finance automatic-rules delete \ --params '{"id": "AUTOMATIC_RULE_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Personas](https://docs.finance.kobana.com.br/es/es/cli/resources/people.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Bancos La tabla de bancos soportados, para completar los datos bancarios de una cuenta o persona. Solo lectura. | Comando | HTTP | Descripción | | ------------ | --------------- | ------------- | | `banks list` | `GET /v1/banks` | Listar bancos | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar bancos kobana finance banks list --fields "id,code,name" ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Organización](https://docs.finance.kobana.com.br/es/es/cli/resources/organization.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Flujo de caja La proyección consolidada: entradas y salidas realizadas y previstas por período, saldo acumulado y el hito de hoy. Solo lectura — es el resultado de todo lo demás, no una colección editable. | Comando | HTTP | Descripción | | --------------- | ------------------- | -------------------------------------- | | `cash-flow get` | `GET /v1/cash-flow` | Obtener la proyección de flujo de caja | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Obtener la proyección de flujo de caja kobana finance cash-flow get \ --fields "granularity,current_balance,today_bucket,truncated,retroactive_overdue" ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Conciliaciones](https://docs.finance.kobana.com.br/es/es/cli/resources/reconciliations.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Categorías El plan de cuentas: el árbol de ingresos y gastos por el que se clasifica cada movimiento. | Comando | HTTP | Descripción | | ------------------- | ---------------------------- | ------------------------ | | `categories list` | `GET /v1/categories` | Listar categorías | | `categories create` | `POST /v1/categories` | Crear categoría | | `categories get` | `GET /v1/categories/{id}` | Obtener categoría por ID | | `categories update` | `PATCH /v1/categories/{id}` | Actualizar categoría | | `categories delete` | `DELETE /v1/categories/{id}` | Eliminar categoría | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar categorías kobana finance categories list --fields "id,company_id,name,parent_id,level" # Obtener categoría por ID kobana finance categories get --params '{"id": "CATEGORIE_ID"}' # Crear categoría kobana finance categories create \ --json '{"company_id": "COMPANY_ID", "name": "NAME", "type": "debit"}' # Actualizar categoría kobana finance categories update \ --params '{"id": "CATEGORIE_ID"}' \ --json '{"name": "NAME", "type": "debit"}' # Eliminar categoría kobana finance categories delete --params '{"id": "CATEGORIE_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Centros de clasificación](https://docs.finance.kobana.com.br/es/es/cli/resources/classification-centers.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Centros de clasificación La segunda dimensión de clasificación — centro de costo, proyecto, sucursal —, usada para prorratear un mismo título entre áreas. | Comando | HTTP | Descripción | | ------------------------------- | ---------------------------------------- | -------------------------------------- | | `classification-centers list` | `GET /v1/classification_centers` | Listar centros de clasificación | | `classification-centers create` | `POST /v1/classification_centers` | Crear centro de clasificación | | `classification-centers get` | `GET /v1/classification_centers/{id}` | Obtener centro de clasificación por ID | | `classification-centers update` | `PATCH /v1/classification_centers/{id}` | Actualizar centro de clasificación | | `classification-centers delete` | `DELETE /v1/classification_centers/{id}` | Eliminar centro de clasificación | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar centros de clasificación kobana finance classification-centers list \ --fields "id,company_id,name,type,description" # Obtener centro de clasificación por ID kobana finance classification-centers get \ --params '{"id": "CLASSIFICATION_CENTER_ID"}' # Crear centro de clasificación kobana finance classification-centers create \ --json '{"company_id": "COMPANY_ID", "name": "NAME", "type": "cost"}' # Actualizar centro de clasificación kobana finance classification-centers update \ --params '{"id": "CLASSIFICATION_CENTER_ID"}' \ --json '{"name": "NAME", "type": "cost", "description": "DESCRIPTION"}' # Eliminar centro de clasificación kobana finance classification-centers delete \ --params '{"id": "CLASSIFICATION_CENTER_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Reglas automáticas](https://docs.finance.kobana.com.br/es/es/cli/resources/automatic-rules.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Empresas Las empresas del grupo. Toda cuenta, título y movimiento pertenece a una de ellas, y casi todo filtro acepta `company_id`. | Comando | HTTP | Descripción | | ------------------ | --------------------------- | ---------------------- | | `companies list` | `GET /v1/companies` | Listar empresas | | `companies create` | `POST /v1/companies` | Crear empresa | | `companies get` | `GET /v1/companies/{id}` | Obtener empresa por ID | | `companies update` | `PATCH /v1/companies/{id}` | Actualizar empresa | | `companies delete` | `DELETE /v1/companies/{id}` | Eliminar empresa | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar empresas kobana finance companies list --fields "id,name,cnpj,type,active" # Obtener empresa por ID kobana finance companies get --params '{"id": "COMPANIE_ID"}' # Crear empresa kobana finance companies create \ --json '{"name": "ACME Comércio Ltda", "cnpj": "12345678000190"}' # Actualizar empresa kobana finance companies update \ --params '{"id": "COMPANIE_ID"}' \ --json '{"name": "NAME", "active": true, "trade_name": "TRADE_NAME"}' # Eliminar empresa kobana finance companies delete --params '{"id": "COMPANIE_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Impuestos](https://docs.finance.kobana.com.br/es/es/cli/resources/taxes.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Clasificadores personalizados Dimensiones de clasificación que la propia empresa define — proyecto, contrato, sucursal — junto a categoría y centro de clasificación. Cada clasificador pertenece a una empresa (filtra con `company_id`) y trae sus `values[]` incluidos; los valores son lo que se asigna a cuentas por pagar, por cobrar y movimientos. | Comando | HTTP | Descripción | | ---------------------------------- | ----------------------------------------------------- | ---------------------------------------------- | | `custom-classifiers list` | `GET /v1/custom-classifiers` | Listar clasificadores personalizados | | `custom-classifiers create` | `POST /v1/custom-classifiers` | Crear clasificador personalizado | | `custom-classifiers get` | `GET /v1/custom-classifiers/{id}` | Obtener clasificador personalizado por ID | | `custom-classifiers update` | `PATCH /v1/custom-classifiers/{id}` | Actualizar clasificador personalizado | | `custom-classifiers delete` | `DELETE /v1/custom-classifiers/{id}` | Eliminar clasificador personalizado | | `custom-classifiers values create` | `POST /v1/custom-classifiers/{id}/values` | Agregar valor a un clasificador personalizado | | `custom-classifiers values update` | `PATCH /v1/custom-classifiers/{id}/values/{valueId}` | Actualizar valor de clasificador personalizado | | `custom-classifiers values delete` | `DELETE /v1/custom-classifiers/{id}/values/{valueId}` | Eliminar valor de clasificador personalizado | `field_type` define el campo (`dropdown`, el predeterminado, `radio`, `multi_select`, `number`, `text`, `phone`, `url`, `date`, `datetime`); `number_format` solo vale para `number` y `option_style` solo para los tipos de lista. Un valor recibe `color` en hex (`#rrggbb`), o un color de la paleta si se omite; `color: null` en `values update` vuelve a la paleta. Eliminar un clasificador, o un valor, ya asignado a algún título o movimiento da `422` (`reason: in_use`) — en ese caso desactívalo con `active: false`, que conserva las asignaciones. Los scopes son `finance/custom_classifiers`. ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar clasificadores personalizados kobana finance custom-classifiers list \ --params '{"company_id": "COMPANY_ID", "active": true}' \ --fields "id,company_id,name,field_type,active,values" # Obtener clasificador personalizado por ID kobana finance custom-classifiers get \ --params '{"id": "CUSTOM_CLASSIFIER_ID"}' # Crear clasificador personalizado kobana finance custom-classifiers create \ --json '{"company_id": "COMPANY_ID", "name": "Proyecto", "field_type": "dropdown"}' # Actualizar clasificador personalizado kobana finance custom-classifiers update \ --params '{"id": "CUSTOM_CLASSIFIER_ID"}' \ --json '{"name": "Proyecto (2026)"}' # Agregar valor a un clasificador personalizado kobana finance custom-classifiers values create \ --params '{"id": "CUSTOM_CLASSIFIER_ID"}' \ --json '{"value": "Obra Centro", "color": "#2a78d6"}' # Desactivar un valor en uso kobana finance custom-classifiers values update \ --params '{"id": "CUSTOM_CLASSIFIER_ID", "valueId": "VALUE_ID"}' \ --json '{"active": false}' # Eliminar valor de clasificador personalizado kobana finance custom-classifiers values delete \ --params '{"id": "CUSTOM_CLASSIFIER_ID", "valueId": "VALUE_ID"}' \ --dry-run # Eliminar clasificador personalizado kobana finance custom-classifiers delete \ --params '{"id": "CUSTOM_CLASSIFIER_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Centros de clasificación](https://docs.finance.kobana.com.br/es/es/cli/resources/classification-centers.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Cuentas financieras Las cuentas por donde entra y sale el dinero — cuenta corriente, caja, tarjeta. Cada movimiento, pago y cobro apunta a una cuenta financiera, y es su saldo lo que proyecta el flujo de caja. | Comando | HTTP | Descripción | | ---------------------------------------- | --------------------------------------------------------- | -------------------------------------- | | `financial-accounts list` | `GET /v1/financial-accounts` | Listar cuentas financieras | | `financial-accounts create` | `POST /v1/financial-accounts` | Crear cuenta financiera | | `financial-accounts get` | `GET /v1/financial-accounts/{id}` | Obtener cuenta financiera por ID | | `financial-accounts update` | `PATCH /v1/financial-accounts/{id}` | Actualizar cuenta financiera | | `financial-accounts delete` | `DELETE /v1/financial-accounts/{id}` | Eliminar cuenta financiera | | `financial-accounts adjust-balance` | `POST /v1/financial-accounts/{id}/adjust-balance` | Ajustar el saldo de la cuenta | | `financial-accounts balances list` | `GET /v1/financial-accounts/{id}/balances` | Listar saldos registrados de la cuenta | | `financial-accounts balances create` | `POST /v1/financial-accounts/{id}/balances` | Registrar un saldo | | `financial-accounts balances latest get` | `GET /v1/financial-accounts/{id}/balances/latest` | Último saldo de cada origen | | `financial-accounts balances delete` | `DELETE /v1/financial-accounts/{id}/balances/{balanceId}` | Eliminar saldo registrado | Los `balances` son **saldos observados**, no el saldo calculado de la cuenta (ese es el `balance` del `get`): cada fila guarda la `source` que la produjo, para separar lo que informó el banco de lo que alguien escribió. `balances create` solo registra la observación — no mueve dinero ni crea movimiento; para corregir el libro usa `adjust-balance`. La `source` por defecto es `api`; envía `cli` para que el registro de auditoría nombre el canal real (`manual`, `banking`, `open_finance`, `calculated` e `imported` son del propio producto y dan `422`). `balances latest get` trae la observación más reciente de cada origen en una sola llamada — un origen que nunca informó vuelve con `amount: null`. Un saldo `banking` o `calculated` no se puede eliminar (`422`): su productor lo volvería a crear. ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar cuentas financieras kobana finance financial-accounts list \ --fields "id,company_id,name,type,bank_id" # Obtener cuenta financiera por ID kobana finance financial-accounts get \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' # Crear cuenta financiera kobana finance financial-accounts create \ --json '{"company_id": "COMPANY_ID", "name": "NAME", "type": "checking"}' # Actualizar cuenta financiera kobana finance financial-accounts update \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --json '{"company_id": "COMPANY_ID", "name": "NAME", "type": "checking"}' # Ajustar el saldo de la cuenta kobana finance financial-accounts adjust-balance \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --json '{"target_balance": "1500.00", "category_id": "CATEGORY_ID"}' # Eliminar cuenta financiera kobana finance financial-accounts delete \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --dry-run # Listar saldos registrados de la cuenta kobana finance financial-accounts balances list \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --fields "id,source,capture_date,amount,external_id" # Registrar un saldo kobana finance financial-accounts balances create \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' \ --json '{"amount": 1530.45, "capture_date": "2026-01-31T23:59:00Z", "source": "cli", "external_id": "EXTERNAL_ID"}' # Último saldo de cada origen kobana finance financial-accounts balances latest get \ --params '{"id": "FINANCIAL_ACCOUNT_ID"}' # Eliminar saldo registrado kobana finance financial-accounts balances delete \ --params '{"id": "FINANCIAL_ACCOUNT_ID", "balanceId": "BALANCE_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Movimientos](https://docs.finance.kobana.com.br/es/es/cli/resources/financial-transactions.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Movimientos El extracto en sí: cada crédito y débito ocurrido en una cuenta financiera, clasificado por categoría y centro de clasificación. El endpoint `aggregates` devuelve totales en lugar de la lista completa. | Comando | HTTP | Descripción | | --------------------------------------- | ------------------------------------------- | ---------------------------- | | `financial-transactions list` | `GET /v1/financial-transactions` | Listar movimientos | | `financial-transactions create` | `POST /v1/financial-transactions` | Crear movimiento | | `financial-transactions get` | `GET /v1/financial-transactions/{id}` | Obtener movimiento por ID | | `financial-transactions update` | `PATCH /v1/financial-transactions/{id}` | Actualizar movimiento | | `financial-transactions delete` | `DELETE /v1/financial-transactions/{id}` | Eliminar movimiento | | `financial-transactions aggregates get` | `GET /v1/financial-transactions/aggregates` | Sumar totales de movimientos | | `financial-transactions ids list` | `GET /v1/financial-transactions/ids` | Listar IDs de movimientos | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar movimientos kobana finance financial-transactions list \ --fields "id,company_id,financial_account_id,description,bank_description" # Obtener movimiento por ID kobana finance financial-transactions get \ --params '{"id": "FINANCIAL_TRANSACTION_ID"}' # Crear movimiento 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"}' # Actualizar movimiento kobana finance financial-transactions update \ --params '{"id": "FINANCIAL_TRANSACTION_ID"}' \ --json '{"description": "DESCRIPTION", "bank_description": "BANK_DESCRIPTION", "document": "DOCUMENT"}' # Sumar totales de transacciones del mes kobana finance financial-transactions aggregates get \ --params '{"company_id": "COMPANY_ID", "month": 1, "year": 2026}' # Eliminar movimiento kobana finance financial-transactions delete \ --params '{"id": "FINANCIAL_TRANSACTION_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Cuentas por pagar](https://docs.finance.kobana.com.br/es/es/cli/resources/payables.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Notas fiscales Las notas fiscales (NF-e y NFS-e) **recibidas** contra las empresas del workspace — por NFE.io, carga de XML o SEFAZ. Son de solo lectura: el producto no emite notas, así que no hay `create` ni cancelación. El listado viene ordenado por la emisión más reciente. | Comando | HTTP | Descripción | | ----------------------- | ------------------------------- | -------------------------- | | `fiscal-documents list` | `GET /v1/fiscal-documents` | Listar notas fiscales | | `fiscal-documents get` | `GET /v1/fiscal-documents/{id}` | Obtener nota fiscal por ID | Los filtros incluyen `kind` (`service` para NFS-e, `product` para NF-e), `situation` (`authorized`, `cancelled`, `unknown`), `source` (`nfe_io`, `xml_upload`, `sefaz`), `access_key`, `number`, `issuer_document` (CNPJ/CPF del emisor, solo dígitos) e intervalos en `issued_at`, `created_at` y `updated_at` (`[gte]`, `[lte]`…) — `updated_at` es la ventana de sincronización incremental. El XML no viene aquí: sigue `xml_download_url`, que es del recurso [Adjuntos](https://docs.finance.kobana.com.br/es/es/cli/resources/attachments.md) y pide el scope `finance/attachments`. El scope de este recurso es `finance/fiscal_documents` con lectura. ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar notas de servicio autorizadas kobana finance fiscal-documents list \ --params '{"kind": "service", "situation": "authorized"}' \ --fields "id,number,issued_at,issuer_name,issuer_document,total_amount" # Notas de un proveedor emitidas en enero kobana finance fiscal-documents list \ --params '{"issuer_document": "12345678000190", "issued_at[gte]": "2026-01-01", "issued_at[lte]": "2026-01-31"}' # Obtener nota fiscal por ID kobana finance fiscal-documents get \ --params '{"id": "FISCAL_DOCUMENT_ID"}' \ --fields "id,access_key,number,situation,total_amount,payable_count,xml_download_url" ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Adjuntos](https://docs.finance.kobana.com.br/es/es/cli/resources/attachments.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Identidad del token Quién está detrás del token: la persona (`user`, nulo en un token de integración), la organización y los detalles del propio token. Sirve para probar que el token configurado vale — es el primer comando a ejecutar después de definir `KOBANA_TOKEN`. El token en sí nunca vuelve en la respuesta. | Comando | HTTP | Descripción | | -------- | ------------ | ------------------------------ | | `me get` | `GET /v1/me` | Obtener la identidad del token | La ruta es de **nivel de organización**: no lleva `X-Workspace-Id`, así que `KOBANA_WORKSPACE_ID` no hace falta aquí. Cualquier token válido sirve — no se exige scope. ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Obtener la identidad del token kobana finance me get # Solo la organización y el token kobana finance me get \ --fields "organization,token" ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Autenticación](https://docs.finance.kobana.com.br/es/es/cli/overview/authentication.md) — cómo obtener el token y elegir el workspace. * [Organización](https://docs.finance.kobana.com.br/es/es/cli/resources/organization.md) --- # Organización El perfil de la organización del token, en la cima de la jerarquía: vale para todos los workspaces. El recurso es **singular** — no hay `list` ni `id`, porque un token siempre alcanza una sola organización, la suya. | Comando | HTTP | Descripción | | --------------------- | ------------------------ | --------------------------------------- | | `organization get` | `GET /v1/organization` | Obtener la organización del token | | `organization update` | `PATCH /v1/organization` | Actualizar el perfil de la organización | Las dos rutas son de **nivel de organización**: no llevan `X-Workspace-Id`, así que `KOBANA_WORKSPACE_ID` no hace falta aquí. El `get` pide el scope `finance/settings` con lectura; el `update` pide escritura y, como el perfil vale para todos los workspaces, el dueño de la organización o acceso a todos ellos. El `update` solo cambia `trade_name`, `website`, `addresses` y `custom_metadata`. Nombre, e-mail y teléfono vienen de la Cuenta Kobana y la identidad fiscal (`document_type`, `document_number`) no cambia por la API: enviar cualquiera de ellos — o cualquier clave desconocida — da `422`, y un campo comercial (`courtesy`, `entitlements`…) da `403`. `custom_metadata: null` mantiene el valor guardado. ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Obtener la organización del token kobana finance organization get \ --fields "id,name,trade_name,document_number,website,created_at" # Actualizar el perfil de la organización kobana finance organization update \ --json '{"trade_name": "Acme", "website": "https://acme.com.br", "custom_metadata": {"crm_id": "CRM_ID"}}' ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Autenticación](https://docs.finance.kobana.com.br/es/es/cli/overview/authentication.md) — el scope `finance/settings` y el workspace de las demás rutas. * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Recursos Todo recurso de `finance` abajo se genera a partir de la misma spec OpenAPI documentada en la [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api/v1) — el CLI llama exactamente a los mismos endpoints, así que filtros, validación y comportamiento de borrado son idénticos. Recurre a la [introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) siempre que los parámetros exactos de un comando no sean obvios en los ejemplos de estas páginas. ``` kobana finance [flags] ``` ## Cómo leer estas páginas[​](#cómo-leer-estas-páginas "Enlace directo al Cómo leer estas páginas") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. Mira [Autenticación](https://docs.finance.kobana.com.br/es/es/cli/overview/authentication.md) para las credenciales propias de `finance`. Un subcamino que solo acepta `POST` es una acción del recurso, con el nombre del último segmento — `kobana finance automatic-rules reorder` y `kobana finance receivables charge cancel`. La forma antigua, terminada en `create`, sigue funcionando. ## El catálogo[​](#el-catálogo "Enlace directo al El catálogo") | Recurso | Comando | Métodos | | ------------------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | [Cuentas financieras](https://docs.finance.kobana.com.br/es/es/cli/resources/financial-accounts.md) | `financial-accounts` | list, create, get, update, delete, adjust-balance, balances list, balances create, balances latest get, balances delete | | [Movimientos](https://docs.finance.kobana.com.br/es/es/cli/resources/financial-transactions.md) | `financial-transactions` | list, create, get, update, delete, aggregates get, ids list | | [Cuentas por pagar](https://docs.finance.kobana.com.br/es/es/cli/resources/payables.md) | `payables` | list, create, get, update, delete, cancel-dispatch, send-to-bank, aggregates get, ids list | | [Cuentas por cobrar](https://docs.finance.kobana.com.br/es/es/cli/resources/receivables.md) | `receivables` | list, create, get, update, delete, aggregates get, charge create, charge cancel, ids list | | [Flujo de caja](https://docs.finance.kobana.com.br/es/es/cli/resources/cash-flow.md) | `cash-flow` | get | | [Conciliaciones](https://docs.finance.kobana.com.br/es/es/cli/resources/reconciliations.md) | `reconciliations` | create, get, delete | | [Categorías](https://docs.finance.kobana.com.br/es/es/cli/resources/categories.md) | `categories` | list, create, get, update, delete | | [Centros de clasificación](https://docs.finance.kobana.com.br/es/es/cli/resources/classification-centers.md) | `classification-centers` | list, create, get, update, delete | | [Clasificadores personalizados](https://docs.finance.kobana.com.br/es/es/cli/resources/custom-classifiers.md) | `custom-classifiers` | list, create, get, update, delete, values create, values update, values delete | | [Reglas automáticas](https://docs.finance.kobana.com.br/es/es/cli/resources/automatic-rules.md) | `automatic-rules` | list, create, get, update, delete, reorder | | [Personas](https://docs.finance.kobana.com.br/es/es/cli/resources/people.md) | `people` | list, create, get, update, delete, ids list | | [Empresas](https://docs.finance.kobana.com.br/es/es/cli/resources/companies.md) | `companies` | list, create, get, update, delete | | [Impuestos](https://docs.finance.kobana.com.br/es/es/cli/resources/taxes.md) | `taxes` | list, create, get, update, delete | | [Adjuntos](https://docs.finance.kobana.com.br/es/es/cli/resources/attachments.md) | `attachments` | list, create, get, delete, download, links, unlink | | [Comprobantes](https://docs.finance.kobana.com.br/es/es/cli/resources/receipts.md) | `receipts` | list, get | | [Notas fiscales](https://docs.finance.kobana.com.br/es/es/cli/resources/fiscal-documents.md) | `fiscal-documents` | list, get | | [Transferencias](https://docs.finance.kobana.com.br/es/es/cli/resources/transfers.md) | `transfers` | create, get | | [Bancos](https://docs.finance.kobana.com.br/es/es/cli/resources/banks.md) | `banks` | list | | [Agentes de IA](https://docs.finance.kobana.com.br/es/es/cli/resources/ai-agents.md) | `ai-agents` | list, create, get, update, delete, triggers get, triggers create, triggers update, triggers delete, triggers token | | [Habilidades de IA](https://docs.finance.kobana.com.br/es/es/cli/resources/ai-skills.md) | `ai-skills` | list, create, get, update, delete | | [Organización](https://docs.finance.kobana.com.br/es/es/cli/resources/organization.md) | `organization` | get, update | | [Identidad del token](https://docs.finance.kobana.com.br/es/es/cli/resources/me.md) | `me` | get | --- # Cuentas por pagar Las obligaciones por vencer y ya pagadas, con aprobación de pago, envío al banco y prorrateo por centro de clasificación. Las cuentas pendientes de aprobación solo aparecen en el listado si filtras por `payment_approval=pending_approval`. | Comando | HTTP | Descripción | | -------------------------- | ---------------------------------------- | -------------------------------------- | | `payables list` | `GET /v1/payables` | Listar cuentas por pagar | | `payables create` | `POST /v1/payables` | Crear cuenta por pagar | | `payables get` | `GET /v1/payables/{id}` | Obtener cuenta por pagar por ID | | `payables update` | `PATCH /v1/payables/{id}` | Actualizar o liquidar cuenta por pagar | | `payables delete` | `DELETE /v1/payables/{id}` | Eliminar cuenta por pagar | | `payables cancel-dispatch` | `POST /v1/payables/{id}/cancel-dispatch` | Cancelar el envío al banco | | `payables send-to-bank` | `POST /v1/payables/{id}/send-to-bank` | Enviar cuenta por pagar al banco | | `payables aggregates get` | `GET /v1/payables/aggregates` | Sumar totales de cuentas por pagar | | `payables ids list` | `GET /v1/payables/ids` | Listar IDs de cuentas por pagar | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar cuentas por pagar kobana finance payables list \ --fields "id,company_id,description,amount,interest_amount" # Obtener cuenta por pagar por ID kobana finance payables get --params '{"id": "PAYABLE_ID"}' # Crear cuenta por pagar kobana finance payables create \ --json '{"company_id": "COMPANY_ID", "description": "DESCRIPTION", "amount": "1500.00", "due_date": "2026-01-31T12:00:00Z"}' # Actualizar o liquidar cuenta por pagar kobana finance payables update \ --params '{"id": "PAYABLE_ID"}' \ --json '{"description": "DESCRIPTION", "amount": "1500.00", "due_date": "2026-01-31T12:00:00Z"}' # Cancelar el envío al banco kobana finance payables cancel-dispatch --params '{"id": "PAYABLE_ID"}' # Sumar totales de cuentas por pagar del mes kobana finance payables aggregates get \ --params '{"company_id": "COMPANY_ID", "month": 1, "year": 2026}' # Eliminar cuenta por pagar kobana finance payables delete --params '{"id": "PAYABLE_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Cuentas por cobrar](https://docs.finance.kobana.com.br/es/es/cli/resources/receivables.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Personas Clientes y proveedores — la contraparte de cualquier título. `ids` devuelve solo los identificadores, útil para no llenar la ventana de contexto de un agente. | Comando | HTTP | Descripción | | ----------------- | ------------------------ | ---------------------------------------- | | `people list` | `GET /v1/people` | Listar personas (clientes / proveedores) | | `people create` | `POST /v1/people` | Crear persona (cliente / proveedor) | | `people get` | `GET /v1/people/{id}` | Obtener persona por ID | | `people update` | `PATCH /v1/people/{id}` | Actualizar persona | | `people delete` | `DELETE /v1/people/{id}` | Eliminar persona | | `people ids list` | `GET /v1/people/ids` | Listar IDs de personas | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar personas (clientes / proveedores) kobana finance people list --fields "id,company_id,name,legal_name,nickname" # Obtener persona por ID kobana finance people get --params '{"id": "PEOPLE_ID"}' # Crear persona (cliente / proveedor) kobana finance people create \ --json '{"company_id": "COMPANY_ID", "name": "NAME"}' # Actualizar persona kobana finance people update \ --params '{"id": "PEOPLE_ID"}' \ --json '{"name": "NAME", "legal_name": "LEGAL_NAME", "nickname": "NICKNAME"}' # Eliminar persona kobana finance people delete --params '{"id": "PEOPLE_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Empresas](https://docs.finance.kobana.com.br/es/es/cli/resources/companies.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Comprobantes Los comprobantes de pago generados por la plataforma. Solo lectura. | Comando | HTTP | Descripción | | --------------- | ----------------------- | ---------------------------------- | | `receipts list` | `GET /v1/receipts` | Listar comprobantes de pago | | `receipts get` | `GET /v1/receipts/{id}` | Obtener comprobante de pago por ID | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar comprobantes de pago kobana finance receipts list \ --fields "id,company_id,payable_id,payable_status,financial_account_id" # Obtener comprobante de pago por ID kobana finance receipts get --params '{"id": "RECEIPT_ID"}' ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Transferencias](https://docs.finance.kobana.com.br/es/es/cli/resources/transfers.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Cuentas por cobrar Lo que tienes por cobrar, con emisión y cancelación de cobro por el Gateway Bancario desde el propio título. Para mover el dinero, el comando es `charge` — el registro en sí queda aquí. | Comando | HTTP | Descripción | | ---------------------------- | ----------------------------------------- | ------------------------------------------ | | `receivables list` | `GET /v1/receivables` | Listar cuentas por cobrar | | `receivables create` | `POST /v1/receivables` | Crear cuenta por cobrar | | `receivables get` | `GET /v1/receivables/{id}` | Obtener cuenta por cobrar por ID | | `receivables update` | `PATCH /v1/receivables/{id}` | Actualizar o liquidar cuenta por cobrar | | `receivables delete` | `DELETE /v1/receivables/{id}` | Eliminar cuenta por cobrar | | `receivables aggregates get` | `GET /v1/receivables/aggregates` | Sumar totales de cuentas por cobrar | | `receivables charge create` | `POST /v1/receivables/{id}/charge` | Generar el cobro de una cuenta por cobrar | | `receivables charge cancel` | `POST /v1/receivables/{id}/charge/cancel` | Cancelar el cobro de una cuenta por cobrar | | `receivables ids list` | `GET /v1/receivables/ids` | Listar IDs de cuentas por cobrar | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar cuentas por cobrar kobana finance receivables list \ --fields "id,company_id,description,amount,interest_amount" # Obtener cuenta por cobrar por ID kobana finance receivables get --params '{"id": "RECEIVABLE_ID"}' # Crear cuenta por cobrar kobana finance receivables create \ --json '{"company_id": "COMPANY_ID", "description": "DESCRIPTION", "amount": "1500.00", "due_date": "2026-01-31T12:00:00Z"}' # Actualizar o liquidar cuenta por cobrar kobana finance receivables update \ --params '{"id": "RECEIVABLE_ID"}' \ --json '{"description": "DESCRIPTION", "amount": "1500.00", "due_date": "2026-01-31T12:00:00Z"}' # Sumar totales de cuentas por cobrar del mes kobana finance receivables aggregates get \ --params '{"company_id": "COMPANY_ID", "month": 1, "year": 2026}' # Eliminar cuenta por cobrar kobana finance receivables delete --params '{"id": "RECEIVABLE_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Flujo de caja](https://docs.finance.kobana.com.br/es/es/cli/resources/cash-flow.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Conciliaciones El vínculo entre un movimiento del extracto y el título que liquida. Crear la conciliación liquida el título; eliminarla deshace la liquidación. | Comando | HTTP | Descripción | | ------------------------ | --------------------------------- | --------------------------- | | `reconciliations create` | `POST /v1/reconciliations` | Crear conciliación | | `reconciliations get` | `GET /v1/reconciliations/{id}` | Obtener conciliación por ID | | `reconciliations delete` | `DELETE /v1/reconciliations/{id}` | Eliminar conciliación | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Obtener conciliación por ID kobana finance reconciliations get --params '{"id": "RECONCILIATION_ID"}' # Crear conciliación kobana finance reconciliations create \ --json '{"billings": [], "transaction_ids": []}' # Eliminar conciliación kobana finance reconciliations delete \ --params '{"id": "RECONCILIATION_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Categorías](https://docs.finance.kobana.com.br/es/es/cli/resources/categories.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Impuestos Los tributos retenidos o por recaudar vinculados a un título. | Comando | HTTP | Descripción | | -------------- | ----------------------- | ----------------------- | | `taxes list` | `GET /v1/taxes` | Listar impuestos | | `taxes create` | `POST /v1/taxes` | Crear impuesto | | `taxes get` | `GET /v1/taxes/{id}` | Obtener impuesto por ID | | `taxes update` | `PATCH /v1/taxes/{id}` | Actualizar impuesto | | `taxes delete` | `DELETE /v1/taxes/{id}` | Eliminar impuesto | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar impuestos kobana finance taxes list \ --fields "id,name,default_rate,default_withholding,active" # Obtener impuesto por ID kobana finance taxes get --params '{"id": "TAXE_ID"}' # Crear impuesto kobana finance taxes create --json '{"name": "IRRF"}' # Actualizar impuesto kobana finance taxes update \ --params '{"id": "TAXE_ID"}' \ --json '{"name": "IRRF", "default_rate": "1.50", "default_withholding": true}' # Eliminar impuesto kobana finance taxes delete --params '{"id": "TAXE_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Adjuntos](https://docs.finance.kobana.com.br/es/es/cli/resources/attachments.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Transferencias Movimientos entre dos cuentas financieras tuyas. Genera los dos movimientos — salida y entrada — en una sola llamada. | Comando | HTTP | Descripción | | ------------------ | ------------------------ | ---------------------------- | | `transfers create` | `POST /v1/transfers` | Crear transferencia | | `transfers get` | `GET /v1/transfers/{id}` | Obtener transferencia por ID | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") `--params` lleva parámetros de query y de ruta (id, página, filtros); `--json` lleva el cuerpo de la solicitud; `--fields` limita los campos que vuelven — vale la pena en todo `list`/`get`, para ahorrar contexto. Mira [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Obtener transferencia por ID kobana finance transfers get --params '{"id": "TRANSFER_ID"}' # Crear transferencia kobana finance transfers create \ --json '{"from_account_id": "FROM_ACCOUNT_ID", "to_account_id": "TO_ACCOUNT_ID", "amount": "1500.00", "occurred_at": "2026-01-31T12:00:00Z", "description": "Aporte para conta pagamentos"}' ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Bancos](https://docs.finance.kobana.com.br/es/es/cli/resources/banks.md) * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Flags globales | Flag | Descripción | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `--params ''` | Parámetros de query y de URL (id, página, filtros) | | `--json ''` | Cuerpo de la solicitud (POST/PUT/PATCH) | | `--file ` | Envía un archivo como parte de un cuerpo `multipart/form-data` (repetible; los campos de `--json` pasan a ser partes de texto) | | `--fields ''` | Limita los campos que vuelven en la respuesta | | `--dry-run` | Muestra la solicitud sin ejecutarla | | `--page-all` | Paginación automática, con salida NDJSON | | `--page-limit ` | Máximo de páginas (por defecto: 10) | | `--page-delay ` | Intervalo entre páginas (por defecto: 100ms) | | `--env ` | Ambiente: `production` (por defecto), `sandbox`, `development` | | `--verbose` | Detalles de la solicitud en stderr | | `--output ` | Guarda la respuesta en un archivo | | `--output-format ` | Formato: `json`, `table`, `csv` | | `--idempotency-key ` | Clave de idempotencia personalizada | | `--lang ` | Idioma de los mensajes: `pt`, `en` o `es` (predeterminado: el del sistema) | ## Envío de archivos[​](#envío-de-archivos "Enlace directo al Envío de archivos") `--file campo=ruta` cambia el cuerpo JSON por `multipart/form-data`: cada `--file` pasa a ser una parte de archivo con el nombre del campo, y los campos de `--json` van como partes de texto. Repita la flag para enviar más de un archivo. El tipo de cada parte sale de la extensión (un `.eml` va como `message/rfc822`), y `--dry-run` muestra el `content_type` y la lista `files` antes de enviar. Los nombres de los campos son los del cuerpo `multipart/form-data` del endpoint en la [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api/v1). ``` kobana finance attachments create \ --file file=nota-junho.pdf \ --json '{"title": "Nota fiscal de junho"}' \ --dry-run ``` ## Idioma[​](#idioma "Enlace directo al Idioma") El CLI habla portugués, inglés o español: ayuda, mensajes, errores y las descripciones de los comandos. El idioma viene, en este orden, de `--lang`, de la variable `KOBANA_LANG`, de las variables de idioma de la terminal (`LC_ALL`, `LC_MESSAGES`, `LANG`) y, por último, del idioma del sistema. ``` kobana --lang en finance --help export KOBANA_LANG=pt ``` Los nombres de comandos y flags, las claves del JSON y los códigos de salida no cambian con el idioma. Disponible desde la versión 0.6.0. ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Uso](https://docs.finance.kobana.com.br/es/es/cli/usage/overview.md) — sintaxis, recursos, ejemplos. * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — parámetros, campos obligatorios, tipos y respuestas. --- # Helpers Los helpers son comandos con prefijo `+` que entregan flujos de varios pasos que los comandos dinámicos por sí solos no dan: interfaces simplificadas, operaciones en lote o llamadas compuestas por varios endpoints. No envuelven una única llamada de API ya disponible por los comandos dinámicos — cada flag de helper controla lógica de orquestación, no una versión remodelada de `--params`/`--json`. Los helpers de hoy son del **Gateway Bancario**, y están disponibles desde el mismo binario uses el producto que uses: | Helper | Descripción | | ---------------- | -------------------------------------------------------- | | `+emitir` | Emisión simplificada de boleto, con flags con nombre | | `+cancelar-lote` | Cancelación en lote de varios boletos por id | | `+cobrar` | Creación simplificada de cobro Pix, con flags con nombre | ``` # Emitir un boleto kobana +emitir --valor 150.50 --vencimento 2026-05-01 \ --nome "Maria Silva" --cpf-cnpj "012.345.678-90" --carteira 1 # Crear un cobro Pix kobana +cobrar --valor 99.90 --conta-pix "UID" \ --nome "João" --cpf-cnpj "012.345.678-90" # Cancelar boletos en lote kobana +cancelar-lote --ids "123,456,789" ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Uso](https://docs.finance.kobana.com.br/es/es/cli/usage/overview.md) — los comandos dinámicos junto a los que viven estos helpers. * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — inspecciona los endpoints que un helper llama por debajo. --- # Uso ## Sintaxis[​](#sintaxis "Enlace directo al Sintaxis") ``` kobana [flags] ``` * **``** — `banking`, `finance`, `billing` o `inbox`. * **``** — puede ser anidado: `payables`, `receivables`, `attachments links`. * **``** — la acción: `list`, `get`, `create`, `update`, `delete`, o una acción específica del recurso. La versión de la API nunca entra en el comando — el CLI resuelve la URL a partir de la spec OpenAPI embebida. Los parámetros de URL y de query van en `--params`; el cuerpo de la solicitud va en `--json`. Toda la superficie se descubre con `--help`, en cualquier nivel: ``` kobana --help # productos kobana finance --help # recursos de Finanzas Inteligentes kobana finance financial-accounts --help # métodos de un recurso ``` ## Recursos de `finance`[​](#recursos-de-finance "Enlace directo al recursos-de-finance") | Recurso | Descripción | | ------------------------ | ------------------------ | | `financial-accounts` | Cuentas financieras | | `financial-transactions` | Movimientos | | `payables` | Cuentas por pagar | | `receivables` | Cuentas por cobrar | | `cash-flow` | Flujo de caja | | `reconciliations` | Conciliaciones | | `categories` | Categorías | | `classification-centers` | Centros de clasificación | | `automatic-rules` | Reglas automáticas | | `people` | Personas | | `companies` | Empresas | | `taxes` | Impuestos | | `attachments` | Adjuntos | | `receipts` | Comprobantes | | `transfers` | Transferencias | | `banks` | Bancos | Cada recurso tiene su propia página, con la tabla completa de comandos y ejemplos — mira el [catálogo](https://docs.finance.kobana.com.br/es/es/cli/resources/overview.md). ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") ``` # Cuentas por pagar abiertas kobana finance payables list \ --params '{"status": "pending"}' \ --fields "id,description,amount,due_date" # Totales agregados en vez de la lista entera kobana finance payables aggregates get --params '{"month": 1, "year": 2026}' # Enviar una cuenta al banco para pago kobana finance payables send-to-bank --dry-run --params '{"id": "PAYABLE_ID"}' # Flujo de caja del mes kobana finance cash-flow get \ --params '{"from": "2026-01-01", "to": "2026-01-31"}' # Conciliar un movimiento con un título kobana finance reconciliations create \ --json '{"financial_transaction_id": "TRANSACTION_ID", "payable_id": "PAYABLE_ID"}' # Listar con paginación automática (NDJSON) kobana finance financial-transactions list --page-all --fields "id,amount,date" # Salida en tabla kobana finance financial-accounts list --output-format table # Guardar la respuesta en un archivo kobana finance payables get --params '{"id": "PAYABLE_ID"}' --output conta.json ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Introspección de schema](https://docs.finance.kobana.com.br/es/es/cli/usage/schema.md) — inspecciona parámetros y cuerpo de cualquier endpoint. * [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) — todas las flags que acepta un comando. * [Helpers](https://docs.finance.kobana.com.br/es/es/cli/usage/helpers.md) — atajos `+verbo` para flujos comunes. * [Recursos](https://docs.finance.kobana.com.br/es/es/cli/resources/overview.md) — el catálogo completo, recurso por recurso. --- # Introspección de schema ``` # Listar todos los productos y sus recursos kobana schema --list # Ver el schema de un endpoint específico kobana schema finance.payables.list kobana schema finance.payables.create kobana schema finance.cash-flow.list ``` Devuelve parámetros, campos obligatorios, tipos y respuestas — todo derivado de la spec OpenAPI embebida, así que siempre está sincronizado con lo que el comando de hecho acepta. La ruta sigue la misma forma del comando: `..`. Este es el primer paso recomendado para un agente de IA que aún no conoce el formato exacto de un payload: inspecciona el schema antes de disparar una llamada que altera datos, en vez de adivinar. ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Flags globales](https://docs.finance.kobana.com.br/es/es/cli/usage/global-flags.md) — `--params`, `--json`, `--dry-run` y las demás. * [Uso](https://docs.finance.kobana.com.br/es/es/cli/usage/overview.md) — sintaxis, recursos, ejemplos. --- # Comprobantes **Financiero > Comprobantes** (`/receipts`) reúne los comprobantes de pago del espacio de trabajo. Cada pago enviado al banco y confirmado genera un comprobante aquí **automáticamente** — y lo que se pagó por fuera (aplicación del banco, débito automático) lo subes a mano. En ambos casos, quien necesita recibir el comprobante es [avisado por correo](#qui%C3%A9n-recibe-por-correo). nota **El comprobante es del dinero que SALE.** Esta pantalla pertenece al lado de cuentas por pagar. Del lado de cuentas por cobrar el equivalente es el cobro que paga tu cliente — ver [Cobro por boleto y Pix](https://docs.finance.kobana.com.br/es/es/contas-a-receber/cobranca-kobana.md). ## De dónde viene cada comprobante[​](#de-dónde-viene-cada-comprobante "Enlace directo al De dónde viene cada comprobante") | Origen | Cómo aparece | ¿Se puede eliminar? | | ----------------- | ----------------------------------------------------- | ------------------- | | **Banco** | solo, cuando un pago enviado al banco se **confirma** | ❌ no | | **Subida manual** | subes el archivo en **"Subir comprobante"** | ✅ sí | info **El comprobante capturado no se puede eliminar.** Es la prueba de un pago que realmente ocurrió, y la siguiente captura lo traería de vuelta — borrarlo sería una promesa que el banco deshace. En cambio, lo que subiste es tu archivo, y se va junto con el adjunto. ## La franja de números[​](#la-franja-de-números "Enlace directo al La franja de números") Sobre la tabla, cinco números del período filtrado: | Número | Qué cuenta | | ----------------- | ------------------------------------------------------------------------------------------------------------ | | **Comprobantes** | cuántos existen en el recorte | | **Disponible** | con el documento ya guardado — el desenlace feliz | | **Sin vínculo** | sin cuenta por pagar asociada | | **Con error** | la captura no logró traer el documento | | **Importe total** | la suma de los importes — separado de los demás por una línea, porque es el único que no cuenta comprobantes | nota **Estos números ignoran la búsqueda y la pestaña.** Responden *"¿cuántos existen allí?"*, no *"cuántos quedaron de lo que estoy viendo"* — si no, el contador de la pestaña se encogería mientras escribes. ## Las cuatro pestañas[​](#las-cuatro-pestañas "Enlace directo al Las cuatro pestañas") * **Todos** — todo lo del período. * **Sin vínculo** — comprobantes que todavía no apuntan a ninguna cuenta por pagar. Solo la subida manual los produce: por el camino del banco la cuenta siempre se conoce. * **Cuenta abierta** — el comprobante apunta a una cuenta por pagar que nadie registró como pagada. Ver [El comprobante no registra el pago de la cuenta](#el-comprobante-no-registra-el-pago-de-la-cuenta). * **Con error** — la captura no consiguió el documento. Cada fila muestra el motivo. ## Situación de un comprobante[​](#situación-de-un-comprobante "Enlace directo al Situación de un comprobante") | Situación | Qué significa | | --------------- | --------------------------------------------------------------- | | **Descargando** | el comprobante fue identificado y se está buscando el documento | | **Disponible** | listo para abrir y descargar | | **Con error** | no fue posible traer el documento; usa **"Intentar de nuevo"** | info **Unos instantes en "Descargando" es normal.** La búsqueda del documento ocurre en segundo plano y se hace con parsimonia — el banco limita cuántas consultas caben por hora, y esas consultas se comparten con las sincronizaciones y con el seguimiento del estado de los pagos. ## Filtros y búsqueda[​](#filtros-y-búsqueda "Enlace directo al Filtros y búsqueda") La búsqueda de arriba mira el **beneficiario** (nombre o documento) y la **descripción de la cuenta**. La **Búsqueda avanzada** recorta por: * **Fecha de pago** (período) * **Empresa** — solo en la vista consolidada; con una empresa elegida arriba, ella es el alcance de toda la pantalla * **Cuenta financiera** — de dónde salió el dinero * **Liquidación** — boleto, Pix, tributo, transferencia… * **Origen** — banco o subida manual ## Qué se puede hacer en cada fila[​](#qué-se-puede-hacer-en-cada-fila "Enlace directo al Qué se puede hacer en cada fila") | Acción | Cuándo aparece | | ---------------------------- | --------------------------------------------------- | | **Descargar comprobante** | con el documento disponible | | **Abrir la cuenta** | cuando hay cuenta por pagar vinculada | | **Vincular a una cuenta** | cuando no la hay, y solo en los subidos manualmente | | **Desvincular de la cuenta** | cuando la hay, y solo en los subidos manualmente | | **Pagar** | cuando la cuenta vinculada sigue abierta | | **Intentar de nuevo** | solo en los capturados que fallaron | | **Eliminar** | solo en los subidos manualmente | Al hacer clic en el documento se abre la **vista previa**. Las **imágenes** se muestran ahí mismo; el **PDF se abre en una pestaña nueva** — la política de seguridad del sistema no permite mostrarlo dentro de la pantalla, y la propia vista previa lo avisa en vez de enseñar un marco vacío. nota **Algunos bancos solo entregan el comprobante como página web, no como archivo.** En ese caso no hay nada que guardar aquí: el comprobante sigue accesible por el botón **"Abrir en el origen"**, y la fila permanece **Disponible** — no es un error. ## Vincular a una cuenta por pagar[​](#vincular-a-una-cuenta-por-pagar "Enlace directo al Vincular a una cuenta por pagar") **"Vincular a una cuenta"** asocia el comprobante a una cuenta por pagar. **El adjunto va junto**: el comprobante pasa a aparecer también en la pantalla de la cuenta, sin que tengas que adjuntarlo otra vez. Desvincular quita esa asociación. Es el camino para el pago que hiciste desde la aplicación del banco: sube el comprobante y vincúlalo a la cuenta correspondiente — al subirlo o después, desde el menú de la propia fila. tip **¿No encuentras la cuenta en la lista? Escribe.** Sin nada escrito la lista muestra las cuentas que vencen **cerca de la fecha del pago**, que es donde casi siempre está la correspondiente — y marca con **"Mismo monto"** y **"Misma fecha"** las que coinciden con el comprobante. En cuanto escribes, la búsqueda pasa a valer para **todo el período**: así se encuentra la cuenta de un pago hecho con dos meses de atraso. La línea debajo del campo siempre dice qué recorte está vigente y cuántas cuentas quedaron fuera. nota **Vincular y desvincular solo existen en la subida manual.** En el comprobante capturado la cuenta viene del propio pago, y la siguiente captura la traería de vuelta — tocarla ahí sería una promesa que el banco deshace. ## El comprobante no registra el pago de la cuenta[​](#el-comprobante-no-registra-el-pago-de-la-cuenta "Enlace directo al El comprobante no registra el pago de la cuenta") **Vincular un comprobante no marca la cuenta por pagar como pagada.** Son dos hechos distintos: el comprobante es la *prueba* de que el dinero salió; el registro del pago es lo que queda en el sistema y crea el movimiento en la cuenta financiera. Cuando el pago sale por el banco, ese registro ya ocurre solo en la confirmación. En la subida manual, no — y por eso una cuenta puede aparecer como **Vencida** aun con el comprobante adjunto. La pantalla te avisa en vez de decidir por ti: la cuenta vinculada recibe la marca **"Cuenta abierta"** debajo de la descripción, la pestaña del mismo nombre las reúne todas, y la acción **"Pagar"** abre la confirmación de pago de siempre — ya rellenada con la fecha y la cuenta del comprobante. info **¿Por qué no automático?** El importe del comprobante no siempre es el de la cuenta: intereses, descuentos y pagos parciales hacen que difieran. Registrarlo solo guardaría el importe equivocado justo en los casos que más importan — así que la confirmación queda contigo, que sabes lo que pasó. ## Subir un comprobante a mano[​](#subir-un-comprobante-a-mano "Enlace directo al Subir un comprobante a mano") **"Subir comprobante"** abre el formulario. Obligatorios: el **archivo**, la **fecha de pago** y el **importe**. Opcionales: **cuenta por pagar**, beneficiario, cuenta financiera y forma de liquidación — puedes vincular la cuenta ahora o después. La empresa no se elige aquí: vale la que esté seleccionada en la parte superior de la pantalla. nota **El archivo tiene que ser PDF o imagen** (`pdf`, `png`, `jpg`). Hojas de cálculo y extractos — `xlsx`, `csv`, `xml`, `ofx` — se aceptan en **[Adjuntos](https://docs.finance.kobana.com.br/es/es/anexos/.md)**, porque sirven a otros fines, pero ninguno de ellos prueba un pago. El límite de tamaño es el mismo que el de los adjuntos. ## Quién recibe por correo[​](#quién-recibe-por-correo "Enlace directo al Quién recibe por correo") El aviso sale para **dos listas**, que conviven: | Lista | Dónde se configura | Quién puede entrar | Qué recibe | | -------------------------- | ----------------------------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------- | | **Del espacio de trabajo** | **"Configurar envío"**, en esta pantalla | solo miembros del espacio | un aviso, con enlace a la cuenta y los [archivos adjuntos](#qu%C3%A9-va-adjunto) | | **De la cuenta** | en el formulario de la cuenta por pagar, en **"Envío del comprobante"** | cualquier correo | **los [archivos adjuntos](#qu%C3%A9-va-adjunto)**, sin enlace | ### La lista del espacio de trabajo[​](#la-lista-del-espacio-de-trabajo "Enlace directo al La lista del espacio de trabajo") **"Configurar envío"** abre la lista de quién recibe aviso de **todos** los comprobantes del espacio. info **Aquí solo aparecen miembros del espacio de trabajo.** En esta lista no existe un campo de correo libre: una dirección suelta que valiera para todo el espacio sería un registro paralelo, sin dueño y sin forma de revocarlo. Quitar a la persona del espacio de trabajo ya la saca de los envíos; no hace falta desmarcarla aquí también. ### La lista de la cuenta[​](#la-lista-de-la-cuenta "Enlace directo al La lista de la cuenta") En el formulario de la cuenta por pagar, **"Envío del comprobante"** acepta **cualquier dirección** — el contador del proveedor, el propio beneficiario. Esas personas reciben **el comprobante y los demás adjuntos de la cuenta** en el correo, y ningún enlace al sistema: son personas de fuera, y un botón hacia una pantalla donde no entran sería una puerta cerrada. info **¿Por qué aquí se permite correo libre y en la otra lista no?** Un comprobante es un documento que se manda hacia fuera — exigir que el contador del proveedor se vuelva miembro de tu espacio de trabajo para recibir uno no es control, es un muro. Lo que mantiene esta lista bajo control es su alcance: pertenece a **esa cuenta**, se edita en su formulario y se va con ella, así que no queda ninguna dirección heredada que nadie recuerde quitar. La lista **se repite en la serie**: al crear un plan de cuotas o una recurrencia, cada cuota y cada ocurrencia nace con los mismos destinatarios, porque cada una genera su propio comprobante. Cambiarla después afecta solo a la cuenta editada. ### Cuándo sale el correo[​](#cuándo-sale-el-correo "Enlace directo al Cuándo sale el correo") En cualquiera de las tres formas en que un comprobante llega a una cuenta: * la **captura automática**, cuando el banco confirma el pago; * la **subida manual ya vinculada** a una cuenta por pagar; * **"Vincular a una cuenta"**, en un comprobante que estaba sin vínculo. Sin nadie en las dos listas, no se envía ningún correo — y nada falla por eso. El aviso en la **campana** ocurre de todas formas. Quien está en las dos listas lo recibe **una sola vez**. nota **El correo sale siempre en el idioma predeterminado del producto.** El aviso de la campana, ese sí, aparece en el idioma de cada persona. ### Qué va adjunto[​](#qué-va-adjunto "Enlace directo al Qué va adjunto") El correo lleva el **comprobante** y, junto con él, **todos los adjuntos de la cuenta** — la factura, el boleto, el contrato —, porque quien necesita el comprobante casi siempre los necesita también. El comprobante va primero; los demás, en el orden en que se adjuntaron a la cuenta. **Los otros comprobantes de la misma cuenta no van.** Una cuenta puede tener más de uno (cuotas, una nueva subida), y cada correo habla de un solo pago — los anteriores ya tuvieron su aviso. nota **El correo tiene límite de tamaño.** Si los archivos suman más de **25 MB**, los que no quepan quedan fuera, y el propio correo dice cuáles — mejor que llegue el resto que no llegue nada. nota **Un comprobante que el banco solo entrega como página no tiene archivo que adjuntar.** El correo sale igual, solo con los demás adjuntos de la cuenta. ## Comprobantes de pagos antiguos[​](#comprobantes-de-pagos-antiguos "Enlace directo al Comprobantes de pagos antiguos") La captura la dispara la confirmación del pago, así que no alcanza al pasado: los pagos confirmados **antes** de que existiera la función no tienen comprobante aquí. Quien administra el entorno puede ejecutar un barrido único para buscarlos — es lento a propósito, para no consumir el límite de consultas del banco. ## Relacionado[​](#relacionado "Enlace directo al Relacionado") * [Cuentas por pagar — envío al banco](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md) — lo que produce la confirmación que genera el comprobante * [Adjuntos](https://docs.finance.kobana.com.br/es/es/anexos/.md) — la biblioteca donde se guarda el documento capturado * [Integración Gateway Bancario](https://docs.finance.kobana.com.br/es/es/integracoes/kobana.md) — la conexión que hace posible la captura * [Cuentas por pagar — el formulario](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/.md#env%C3%ADo-del-comprobante) — donde se registran los destinatarios de una cuenta * [API — Comprobantes](https://docs.finance.kobana.com.br/es/es/api/v1/list-receipts) — para leer los comprobantes desde fuera del sistema (solo lectura) * [API — Actualizar cuenta por pagar](https://docs.finance.kobana.com.br/es/es/api/v1/update-payable) — el campo `receipt_emails`, para registrar los destinatarios desde fuera del sistema --- # Conciliación La pantalla **Conciliación** (`/conciliacao`) cierra las líneas del extracto bancario de una cuenta. Cada línea es dinero que ya salió o entró; conciliar es decir a qué **cuenta por pagar o por cobrar** corresponde o, cuando no la hay (una comisión, un alquiler que nadie registró, dinero que solo cambió de cuenta), registrar lo que falta en ese momento. ## Concepto[​](#concepto "Enlace directo al Concepto") * **Transacción** — la línea del extracto, tal como la envió el banco (Open Finance, el Gateway Bancario Kobana, un archivo OFX/QIF o la importación de Fintera o de Nibo). Ya es una transacción de la cuenta, normalmente clasificada por las [reglas automáticas](https://docs.finance.kobana.com.br/es/es/regras-automaticas/.md) cuando llega. * **Cuenta por pagar o por cobrar** — el compromiso registrado. Una línea está **abierta** mientras no tiene cuenta por pagar o por cobrar, no forma parte de un grupo de conciliación y no es un tramo de una transferencia. Solo las líneas abiertas aparecen en la pantalla; la línea conciliada sale de ella. Lo que no es un movimiento del banco nunca aparece: una línea de valor cero, un **ajuste de saldo** hecho en la cuenta y el saldo inicial que graba la importación de Nibo. Cuando Nibo liquidó un compromiso en varias líneas del extracto, la importación ya las concilia todas con el título: esas líneas no aparecen aquí, y el título las muestra todas en su conciliación. Cuando la liquidación ocurre desde la propia cuenta por pagar o por cobrar (**"Pagar"** / **"Cobrar"**), el sistema crea una transacción vinculada. Si después llega la línea del extracto, la conciliación cambia esa transacción automática por la línea del banco. ## Requisitos[​](#requisitos "Enlace directo al Requisitos") * **Una cuenta elegida.** La conciliación se hace cuenta por cuenta: con **Todas las cuentas** arriba de la pantalla, te pide *"Elige una cuenta"*. * **Una cuenta que concilia.** La cuenta tiene que estar activa y con la conciliación habilitada; si no, la pantalla muestra *"Conciliación desactivada en esta cuenta"* (o *"No hay cuentas disponibles"* cuando ninguna concilia). * **Una cuenta con empresa.** Las cuentas por pagar y por cobrar son por empresa: una cuenta sin empresa muestra *"La cuenta no tiene empresa"*. ## La parte superior[​](#la-parte-superior "Enlace directo al La parte superior") * **Manual** / **En lote** — los dos modos. La elección queda guardada. * **Volver al extracto** — el extracto de la cuenta, donde también se deshace una conciliación. * **Reglas automáticas** — la pantalla de [reglas](https://docs.finance.kobana.com.br/es/es/regras-automaticas/.md). * **Importar** — **Archivo OFX o QIF**, **Planilla** o **Extractos importados**, en la página de la cuenta. * **El bloque de la cuenta** — banco, agencia y cuenta, la etiqueta **Conectada por Open Finance** cuando corresponde, **Cambiar cuenta** y cuándo se leyó el extracto por última vez: la última lectura de Open Finance o del Gateway Bancario, o la última importación de archivo en una cuenta manual. ### Filtros y orden[​](#filtros-y-orden "Enlace directo al Filtros y orden") Los dos modos filtran por **Período**, **Descripción o nombre**, **Valor** (Mín y Máx) y **Tipo** (Entradas o Salidas). Los filtros se aplican al hacer clic en **Filtrar** y quedan guardados. El período empieza vacío: todas las líneas abiertas de la cuenta. El orden puede ser **por fecha** (el predeterminado, de la más antigua a la más nueva), **por descripción**, **por valor** o **por relevancia**. La **relevancia** de una línea es cuántas líneas abiertas de la cuenta tienen el mismo texto del banco: ordenar por ella trae primero lo que más se repite — comisiones, alquiler, nómina. ## Manual[​](#manual "Enlace directo al Manual") Una tarjeta por línea. A la izquierda, lo que envió el banco: fecha, valor (flecha hacia la izquierda y verde en una entrada, hacia la derecha y roja en una salida, como en Transacciones), el texto del banco y la contraparte, cuando se conoce. Abajo, **Crear regla** y la papelera. A la derecha, tres pestañas y el botón **OK**. La tarjeta se abre en **Sugerencia** cuando hay una; si no, en **Nueva transacción**. ### Sugerencia[​](#sugerencia "Enlace directo al Sugerencia") La cuenta por pagar o por cobrar que cierra la línea: * **mismo valor**, siempre; * de la **misma empresa** y del sentido correcto (una salida con una cuenta por pagar, una entrada con una cuenta por cobrar); * **pendiente o vencida**, o ya **liquidada por la transacción automática** y todavía sin conciliar; * elegida por la **contraparte** — el documento de la persona de la cuenta escrito en la línea, la persona que una regla ya puso en la línea, el nombre — y por la **cercanía de la fecha**, hasta 45 días. Sin ninguna señal de contraparte, la sugerencia solo aparece para un título solo a hasta 7 días. Cuando dos títulos empatan, no hay sugerencia: la elección es tuya, en **Buscar / Crear varios**. La sugerencia también puede ser la **otra punta de una transferencia**: la única línea abierta de otra cuenta del espacio, en el sentido opuesto, con el mismo valor y hasta 3 días de distancia — *"Transferencia a (cuenta)"* en una salida, *"Transferencia de (cuenta)"* en una entrada. **OK** concilia: el título queda pagado o cobrado con la línea del extracto. La misma sugerencia puede aparecer en varias líneas iguales; después del OK, la otra línea pasa a la sugerencia siguiente. ### Nueva transacción[​](#nueva-transacción "Enlace directo al Nueva transacción") Cuando nada cierra la línea, se convierte en una cuenta nueva, **ya liquidada** con el valor, la fecha y la cuenta de la línea: * **Tipo** — **Pago** en una salida, **Cobro** en una entrada, o **Transferencia**. * **Proveedor** o **Cliente**, **Descripción**, **Categoría** y **Centro de clasificación**. La descripción viene con el texto del banco. * El **clip** adjunta un archivo a la cuenta creada. * **Abrir formulario completo** abre el formulario completo de la cuenta por pagar o por cobrar, completado con lo que está en la tarjeta (un contacto **Nuevo** y el adjunto no se llevan). Al guardarlo, vuelve conciliado. La cuenta creada aquí no pasa por la aprobación de pagos ni va al banco: nace pagada. Su clasificación también va a la línea del extracto; lo que la cuenta no trae, la línea lo conserva. El proveedor o cliente, la categoría y el centro deben ser de la empresa de la cuenta. #### Sugerencias de llenado[​](#sugerencias-de-llenado "Enlace directo al Sugerencias de llenado") Con **Mostrar predicciones** activado (junto a *"Extracto en Finanzas Inteligentes"*), el formulario viene completado, con la franja **predicción**: 1. lo que la línea ya trae — la persona, la categoría y el centro que una regla automática puso en ella; 2. si no, la última clasificación usada para el **mismo texto del banco**, en la misma empresa y el mismo sentido, en el último año; 3. si no, la persona cuyo CPF/CNPJ está escrito en la línea y la categoría de su última cuenta. Cuando la línea trae un **CNPJ que no es de nadie registrado** (el pagador o receptor de Open Finance, o el documento en el texto del banco), el proveedor o cliente viene con la etiqueta **Nuevo** y la razón social registrada en la Receita Federal. El OK crea la persona junto con la cuenta. Desactivar **Mostrar predicciones** deja contacto, categoría y centro en blanco. La elección queda guardada. #### Transferencia[​](#transferencia "Enlace directo al Transferencia") Con **Tipo** = **Transferencia**, el formulario pide la **Cuenta de destino** y la descripción. La línea se convierte en un tramo de la transferencia: * si la cuenta de destino tiene una línea abierta en el sentido opuesto, con el mismo valor y hasta 3 días de distancia, las dos se emparejan; * si no, el otro tramo se escribe en la cuenta de destino. Nunca nacen dos tramos nuevos. Las cuentas de tarjeta de crédito no aparecen como destino. #### Conciliar todas[​](#conciliar-todas "Enlace directo al Conciliar todas") En el OK de una nueva transacción, si hay otras líneas abiertas de la cuenta con **el mismo valor, sentido y texto del banco**, la pantalla pregunta *"¿Conciliar todas de una vez?"*: * **Solo esta** — concilia solo la línea de la tarjeta; * **Conciliar todas** — crea una cuenta igual para cada línea, en una sola acción. Una línea que no pudo acompañar (alguien la concilió mientras tanto, por ejemplo) queda abierta, y el aviso dice cuántas. ### Buscar / Crear varios[​](#buscar--crear-varios "Enlace directo al Buscar / Crear varios") Para la línea que se cierra con **más de un título** — una transferencia que pagó tres facturas — o con un título que la sugerencia no encontró: Al abrir la pestaña, la búsqueda aparece **debajo de la tarjeta, a todo lo ancho**; en el lugar del formulario queda lo que ya se eligió. 1. **Pagos** (o **Cobros**, en una entrada) y **Transferencias**. 2. Filtros **Nombre**, **Período**, **Descripción o referencia**, **Valor** (exacto) y **Categoría**, y **Filtrar**. Sin filtro, la lista viene por valor, hasta 100 por vez. 3. Marca los títulos. La selección **se acumula entre búsquedas** y sube a la tarjeta, con el clip y la X de cada uno — y el lápiz, cuando hay un solo título pendiente. 4. La tarjeta muestra *"Faltan (valor) para conciliar"* hasta que la suma cierra — o *"Excede en (valor) el valor de esta transacción"*, cuando se pasa. 5. **Crear nueva transacción** (o el enlace *"crea un nuevo pago"*, antes de marcar alguno) abre *"Nuevo pago"* o *"Nuevo cobro"* con el valor que falta: **Descripción**, **Proveedor** o **Cliente**, **Categoría** y **Centro de clasificación**. **Guardar** lo pone en la tarjeta; el **OK** concilia todo junto. El **OK** solo se habilita con la suma exacta. Con un solo título, el lápiz abre **Intereses y descuento**: el valor del título más intereses, menos descuento, tiene que dar el valor de la línea. En **Transferencias**, la lista trae las líneas abiertas de otras cuentas del espacio; emparejar exige el mismo valor. Cuentas por pagar o por cobrar y transferencia no se mezclan en la misma conciliación. ### Crear regla y eliminar[​](#crear-regla-y-eliminar "Enlace directo al Crear regla y eliminar") * **Crear regla** abre una [regla automática](https://docs.finance.kobana.com.br/es/es/regras-automaticas/.md) nueva, completada con la cuenta, el sentido, el texto del banco y la clasificación de la tarjeta. Una vez guardada, vuelve a la conciliación. * La papelera elimina la transacción importada, después de confirmar: *"Sale del extracto de la cuenta y la próxima sincronización o importación no la trae de vuelta."* ## En lote[​](#en-lote "Enlace directo al En lote") Una tabla con una fila por transacción abierta, para registrar **muchas líneas nuevas de una vez** — comisiones, transferencias entre cuentas propias, lo que se repite cada mes: | Lado | Columnas | | ------------------------ | ----------------------------------------------------------- | | **Lo importado** | Fecha, Descripción, Pagador/beneficiario, Valor, Relevancia | | **Lo que se registrará** | Tipo, Descripción, Proveedor/Cliente o cuenta, Categoría | Las columnas Fecha, Descripción, Valor y Relevancia ordenan la tabla; hacer clic de nuevo invierte el orden. La parte derecha viene completada por la predicción, y la descripción, con el texto del banco. * **Lista** — la fila se pone **verde** cuando tiene descripción, contacto y categoría; en una transferencia, descripción y cuenta de destino. Al marcar filas, aparece justo arriba de la tabla la barra de acciones en lote, como en los demás listados: cuántas están seleccionadas, cuántas están listas para conciliar, **Editar** y **Conciliar**. * **Editar** — abre *"Editar N transacciones"*: los campos completados valen para todas las marcadas (**Modificar**), y los vacíos quedan como están. La categoría solo se puede cambiar cuando las marcadas son todas entradas o todas salidas. * **⋮ → Crear regla** — la misma regla completada del Manual. * **Conciliar** — concilia las marcadas que están listas; las otras se quedan. Cada fila va por su cuenta: una que falla (porque alguien la concilió antes, por ejemplo) no impide las otras, y el motivo aparece debajo de su descripción. El filtro **Transacciones conocidas** deja solo las líneas que la predicción conoce: las que ya tienen persona o categoría, o cuyo texto del banco se clasificó en el último año. nota **En lote siempre crea una cuenta nueva** (o una transferencia) por línea, sin centro de clasificación. Una línea que se cierra con una cuenta que ya existe se concilia en **Manual**. ## Deshacer una conciliación[​](#deshacer-una-conciliación "Enlace directo al Deshacer una conciliación") La pantalla no tiene deshacer: la línea conciliada sale de ella. Se deshace desde el extracto de la cuenta (**Volver al extracto**), en el detalle de la transacción: * **Desvincular** — la cuenta vuelve a pendiente y la línea vuelve a estar abierta. En una cuenta creada por la conciliación, eliminar la cuenta también libera la línea. * **Deshacer conciliación** — en la tarjeta de transferencia de una línea que vino del banco: el tramo que escribió la conciliación se elimina; una línea emparejada vuelve a estar abierta. Solo vale para la transferencia de una línea del extracto: la transferencia ingresada a mano se elimina en su propia pantalla. nota **Una conciliación importada no se desvincula.** Una conciliación replicada desde Fintera es de solo lectura: refleja el sistema de origen, y la próxima importación la traería de vuelta. ## Conteos de otras pantallas[​](#conteos-de-otras-pantallas "Enlace directo al Conteos de otras pantallas") El listado de [transacciones](https://docs.finance.kobana.com.br/es/es/lancamentos/.md) tiene el filtro **Conciliado**, que mira solo el vínculo con cuentas por pagar o por cobrar. La Conciliación también da por resuelta la línea que se convirtió en tramo de transferencia — por eso una línea puede estar fuera de la Conciliación y seguir apareciendo como no conciliada en el listado de transacciones. ## Estados vacíos[​](#estados-vacíos "Enlace directo al Estados vacíos") * **"Nada que conciliar"** — todas las líneas de la cuenta, con los filtros aplicados, están conciliadas. Otro período u otro valor pueden traer otras. ## Por la API y por el MCP[​](#por-la-api-y-por-el-mcp "Enlace directo al Por la API y por el MCP") Las mismas acciones existen en la API v1, bajo el alcance `finance/reconciliations`: * [las sugerencias de una línea](https://docs.finance.kobana.com.br/es/es/api/v1/get-reconciliation-suggestions) — la cuenta o la transferencia que la cierra, la predicción y las líneas gemelas; * [la cuenta nueva ya liquidada](https://docs.finance.kobana.com.br/es/es/api/v1/reconcile-with-new-billing), con conciliar todas; * [la transferencia](https://docs.finance.kobana.com.br/es/es/api/v1/reconcile-as-transfer); * [el lote](https://docs.finance.kobana.com.br/es/es/api/v1/reconcile-transactions-batch). Conciliar cuentas que ya existen, incluso varias con varias transacciones, es [crear una conciliación](https://docs.finance.kobana.com.br/es/es/api/v1/create-reconciliation). En el MCP, las mismas acciones son las tools de [transacciones](https://docs.finance.kobana.com.br/es/es/mcp/tools/transactions.md). --- # Cuentas por pagar Cuentas por Pagar (`/payables`) registra los compromisos de salida de la organización: facturas de proveedores, gastos operativos, impuestos, nómina y cualquier obligación de desembolso futura o pasada. ![Lista de cuentas por pagar](/es/assets/images/01-payables-c77351262f78c93637a0ba5fc9c02800.png) ![Detalle de cuenta por pagar](/es/assets/images/02-payable-detail-27842fb266819593b83c6a02ab5648f2.png) ## En esta sección[​](#en-esta-sección "Enlace directo al En esta sección") ## [📄️Ciclo de vida](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/ciclo-de-vida.md) [Estados, transiciones y la puerta de aprobación — Borrador → Pendiente → Pagado.](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/ciclo-de-vida.md) ## [📄️Cuotas y recurrencia](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/parcelas-e-recorrencia.md) [Dividir en cuotas o repetir periódicamente — los tres tipos de cuenta y el comportamiento de las series.](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/parcelas-e-recorrencia.md) ## [📄️Operación y pago](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/operacao-e-pagamento.md) [Tipo de operación, documento (boleto, factura de servicios, tributo, PIX), transferencia (TED, PIX) o débito automático, y las coordenadas de pago.](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/operacao-e-pagamento.md) ## [📄️Tributos](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/tributos.md) [DARF, DARE, GRU, GPS, FGTS, ICMS, ISS, IPTU e ITBI — cómo informar la guía y qué se envía al banco.](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/tributos.md) ## [📄️Envío al banco (Gateway Bancario)](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md) [Enviar al banco las cuentas por pagar aprobadas mediante el Gateway Bancario — prerrequisitos, estado y liquidación automática.](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md) ## [📄️Importación CSV](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/importacao-csv.md) [Importar lotes de cuentas por pagar mediante planilla — columnas aceptadas, formato tolerante y la puerta de aprobación.](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/importacao-csv.md) ## La lista[​](#la-lista "Enlace directo al La lista") El encabezado abre con tres totales del período — **Por pagar**, **Pagado** y **Total** — y un subtítulo accionable: si hay atrasos, *"Tienes 3 facturas vencidas"* trae el fragmento en rojo como botón que aplica el filtro de vencidas; sin atrasos, *"Estás al día con tus facturas."* En el encabezado están el botón de **período**, **"Nueva cuenta por pagar"** y — **solo con el gateway conectado** — **"Enviar pagos"**, que abre la bandeja de envío en lote. El contador rojo a su lado cuenta todo lo que la bandeja va a listar: los títulos **vencidos y los que vencen en los próximos 7 días**, listos o bloqueados. Por ahí sale el lote; desde la lista no hay atajo por fila hacia el banco. A la derecha de los totales, las píldoras **"Importar"** (abre el panel de abajo y limpia la búsqueda y los filtros) e **"Informe"** (se abre en un diálogo). Importar exige una **empresa específica** seleccionada. ### Filtros[​](#filtros "Enlace directo al Filtros") * **Búsqueda** — por descripción o número de documento. * **Filtros rápidos** — **Todos**, **Con adjuntos**, **Pagado**, **Conciliado**, **Borradores**. * **Filtros avanzados** — panel con los criterios combinados, contador de activos y un resumen para limpiar o editar. ### Columnas[​](#columnas "Enlace directo al Columnas") Descripción, Fecha de vencimiento, Categoría, **Estado general**, **Estado en el banco**, Monto y **Liquidación** — más **Empresa**, solo en la vista consolidada. **Impuesto** y **Notas** vienen ocultas; **Liquidación** también. Actívalas desde el menú de columnas. nota **Estado general y Estado en el banco son dos columnas, ordenables, una al lado de la otra** — no un estado con un chip pegado. Una dice lo que Finanzas Inteligentes sabe; la otra, lo que el banco reporta. Ver [Ciclo de vida](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/ciclo-de-vida.md). ### Acciones de fila[​](#acciones-de-fila "Enlace directo al Acciones de fila") Las mismas nueve del lado de cobrar, con las etiquetas de pagar: | Acción | Cuándo aparece | | ---------------- | ------------------------------------------------------------------- | | **Pagar** | Mientras la baja manual sea posible | | **Conciliar** | Ya pagada y todavía no conciliada | | **Cuotas** | Tipo Cuota | | **Recurrencias** | Tipo Recurrente, dentro de una serie | | **Clasificar** | Siempre | | **Editar** | Siempre | | **Deshacer** | Ya pagada | | **Cancelar** | Solo pendiente, y **fuera** del carril del gateway | | **Eliminar** | Fuera del banco: nunca enviado, o con el pago rechazado o cancelado | aviso **Un título ya enviado al banco no ofrece "Pagar", "Cancelar" ni "Eliminar".** Anularlo o eliminarlo aquí dejaría el pago vivo en el gateway, sin el título que lo explica. Una vez pagado también se queda: es el registro de lo que salió de la cuenta. El camino es **"Cancelar envío"**, en la tarjeta del gateway de la pantalla de detalle. Cancelar el envío **no deshace el despacho**: el título sigue en el carril del gateway, ahora con el sello **Cancelado**. Lo que vuelve es solo **"Pagar"** — el envío no se concretó, así que el título sigue pendiente y alguien tiene que cerrarlo por fuera. **"Cancelar" no vuelve:** una vez enviado al banco, el título nunca más se puede cancelar desde la lista. Ver [Envío al banco](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md). ### Acciones en lote[​](#acciones-en-lote "Enlace directo al Acciones en lote") **"Clasificar seleccionados"** (solo con empresa específica), **"Marcar como pagadas"** y **"Eliminar"**, con los totales **Por pagar**, **Pagado** y **Total** de la selección en vivo. **"Marcar como pagadas"** abre un diálogo con la **Fecha de pago** (hoy, por defecto). Cada cuenta se paga por su propio valor, desde la **cuenta de origen** prevista en ella; si alguna seleccionada no tiene una, el diálogo pide la cuenta para esas. Intereses y descuentos quedan fuera — para ellos, confirma el pago de una en una. Lo que la fila no dejaría marcar como pagado (ya pagada, enviada al banco, esperando aprobación) queda fuera, y el diálogo dice cuántas. ## El formulario[​](#el-formulario "Enlace directo al El formulario") **La empresa no es un campo** — viene del selector del encabezado. ### ESENCIALES[​](#esenciales "Enlace directo al ESENCIALES") | Campo | Observaciones | | ------------------------ | ---------------------------------------------------------------------------------- | | **Monto (R$)** | Obligatorio. Campo de moneda con máscara | | **Fecha de vencimiento** | Obligatorio. Al crear, hay atajos de fecha relativa | | **Pagar desde** | Cuenta financiera prevista para la salida | | **Descripción** | Obligatorio | | **Proveedor** | Obligatorio. Elegir un proveedor ya registrado **precarga su información de pago** | | **Mes de competencia** | Obligatorio. Selector de mes | nota **"Pagar desde" es la cuenta prevista, y es el único campo de cuenta del formulario.** La cuenta que **efectivamente** pagó no se escribe aquí: se elige en la baja, en el campo **"Cuenta de origen"** del diálogo "Confirmar pago". ### CLASIFICACIÓN[​](#clasificación "Enlace directo al CLASIFICACIÓN") **Tipo** (obligatorio: **Único**, **Recurrente**, **Cuota**, que revela **Recurrencia** o **Cuotas**), **Categoría** y **Centro de clasificación**, cada uno con el atajo **Distribución**. ### OPERACIÓN Y DOCUMENTO[​](#operación-y-documento "Enlace directo al OPERACIÓN Y DOCUMENTO") El eje que distingue las cuentas por pagar de las cuentas por cobrar: * **Tipo de operación** — **Pago de documento** o **Transferencia**. * El campo siguiente **solo aparece después** de esa elección, y cambia de nombre con ella: **"Documento"** (Boleto bancario, Factura de servicios, Impuesto / tributo, PIX…) o **"Tipo de transferencia"** (**Transferencia bancaria (TED)**, PIX). Cambiar la operación limpia un método incompatible. * **Número de documento** y **Fecha del documento**. La elección destraba las coordenadas de pago — código de barras, PIX, datos bancarios, datos del formulario fiscal. Ver [Operación y pago](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/operacao-e-pagamento.md) e [Tributos](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/tributos.md). ### ENVÍO DEL COMPROBANTE[​](#envío-del-comprobante "Enlace directo al ENVÍO DEL COMPROBANTE") Quién recibe el **comprobante** de este pago por correo, **con el archivo adjunto** — y, junto, los [demás adjuntos de la cuenta](https://docs.finance.kobana.com.br/es/es/comprovantes/.md#qu%C3%A9-va-adjunto) —, en cuanto se adjunte un comprobante a la cuenta. Acepta **cualquier dirección** — el contador del proveedor, el beneficiario —, con una **etiqueta** opcional para identificar a cada uno. La lista vale **para esta cuenta**. Al crear un plan de cuotas o una recurrencia, cada cuota y cada ocurrencia **nace con los mismos destinatarios**, porque cada una genera su propio comprobante — pero cambiar la lista después afecta **solo a la cuenta que estás editando**. **No sustituye** a los miembros marcados en [Comprobantes](https://docs.finance.kobana.com.br/es/es/comprovantes/.md#qui%C3%A9n-recibe-por-correo): esos siguen recibiendo sus avisos. nota **Este bloque no depende de la operación elegida.** A diferencia de las coordenadas de pago, no cambia ni se limpia cuando cambias el documento o el tipo de transferencia — y sigue editable incluso después de que el banco confirme el pago, porque dice a quién avisar, no lo que hizo el banco. ### Impuestos retenidos · Notas e IR[​](#impuestos-retenidos--notas-e-ir "Enlace directo al Impuestos retenidos · Notas e IR") **Impuestos retenidos** (píldoras de tributos en la fuente), la píldora **"Relevante para impuestos"** y **"Agregar nota"**. ### Adjuntos[​](#adjuntos "Enlace directo al Adjuntos") Al crear, es posible adjuntar archivos antes de guardar. ## Confirmar pago[​](#confirmar-pago "Enlace directo al Confirmar pago") Dos pestañas: * **Pagar** — **Fecha de pago** y **Cuenta de origen**. Marca como pagada y crea la transacción de débito. * **Pagar y conciliar** — *"Pague esta cuenta vinculándola a una transacción que ya existe en el extracto — sin duplicados."* En las dos pestañas, la sección **"Ajustes del pago"** (opcional) acepta **Interés** y **Descuento**. Debajo, el **Monto pagado** muestra cuánto sale de la cuenta. En **Pagar**, ese importe, y no el del título, es el que se registra como transacción de débito; en **Pagar y conciliar**, es con él que se compara la transacción elegida, y el interés y el descuento quedan registrados en la cuenta. aviso **Un pago confirmado por el banco traba parte del formulario.** *"Lo que describe el pago — monto, fecha de vencimiento, proveedor y la información de pago — ya no puede modificarse. La clasificación interna (categoría, centro, adjuntos, notas) sigue editable."* Ver [Ciclo de vida](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/ciclo-de-vida.md). --- # Ciclo de vida de las cuentas por pagar Una cuenta por pagar se describe mediante **tres capas independientes**. No se sustituyen entre sí — conviven, y la pantalla las muestra todas: | Capa | Qué responde | Dónde aparece | | --------------------------- | ----------------------------------------------------------------------------- | -------------------------------- | | **1. Estado del título** | Dónde está el título en Finanzas Inteligentes (Borrador → Pendiente → Pagado) | Columna **"Estado general"** | | **2. Aprobación** | ¿Una persona liberó este pago? (puerta de entrada) | Sello al lado del estado general | | **3. Estado en el gateway** | Si fue enviado al banco, en qué punto está **allá** | Columna **"Estado en el banco"** | nota La capa 3 solo existe si el título fue enviado al banco. En la lista tiene **columna propia**: **"Estado general"** y **"Estado en el banco"** van una al lado de la otra, ambas ordenables — el gateway nunca es un chip colgado del estado del título. Son dos señales distintas: una dice lo que Finanzas Inteligentes sabe, la otra lo que el banco reporta. Fuera del carril del gateway, la columna muestra "-". Lo que aparece **al lado** del estado general es la **capa 2**: el sello de aprobación. Y en la pantalla de detalle el estado del gateway no está en el encabezado — vive dentro de la **tarjeta del gateway**. ## Capa 1 — Estado del título[​](#capa-1--estado-del-título "Enlace directo al Capa 1 — Estado del título") | Estado | Descripción | | ------------- | ---------------------------------------------------- | | **Borrador** | Creado pero no publicado. No aparece en los totales. | | **Pendiente** | Confirmado, a la espera de pago. | | **Pagado** | Vinculado a una transacción. | | **Cancelado** | Anulado, no genera movimiento. | La columna muestra además un quinto sello que **no es un estado**: **Vencido** — todo título **Pendiente** cuya fecha de vencimiento ya pasó. Se deriva de la fecha, no se graba: nada "pasa a" vencido, y pagarlo o reprogramarlo lo hace desaparecer solo. * **Publicar** (Borrador → Pendiente): confirma el título — pero todavía pasa por la capa 2. * **Pagar** (Pendiente → Pagado): hay dos caminos — ver "Cómo un título pasa a Pagado", más abajo. * **Cancelar** (Pendiente → Cancelado): anula. Solo aparece en un título pendiente, y **no es irreversible** — el diálogo dice *"Puede reabrirla más tarde editando el estado."* ## Capa 2 — Aprobación de pago[​](#capa-2--aprobación-de-pago "Enlace directo al Capa 2 — Aprobación de pago") Puerta antifraude: un título creado por formulario, CSV o API **no entra en la lista oficial** hasta que una persona lo apruebe en [Aprobar pagos](https://docs.finance.kobana.com.br/es/es/aprovar-pagamentos/.md) (`/payables/approvals`). La puerta es una configuración del espacio de trabajo, **activada por defecto**; desactivada, los títulos creados nacen oficiales y saltan la cola. | Estado | Significado | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Esperando aprobación** | A la espera de que alguien apruebe. **Fuera de la lista oficial** — no cuenta en totales ni en el flujo de caja, y no puede ir al banco. | | **Aprobado** | Liberado — entra en la lista oficial y queda elegible para el envío al banco. | | **Rechazado** | Bloqueado definitivamente. | | *(sin sello)* | Ya nace oficial, sin pasar por la cola. | La puerta vale para quien **entra por la puerta principal**: formulario, importación CSV y API. Nacen **oficiales, sin aprobación**, los títulos que el propio sistema genera a partir de algo que ya se decidió antes — las ocurrencias de una recurrencia ya aprobada y lo que viene importado de Fintera. Las ocurrencias de una recurrencia que todavía espera aprobación nacen esperándola también, con el mismo autor — quien la creó no aprueba ninguna. aviso **Guardar como borrador no escapa de la puerta.** El borrador no tiene sello porque todavía no es ninguna obligación — pero **publicar** es el momento en que se convierte en una, y es ahí donde entra en la cola, como cualquier título creado directamente. El borrador no es un atajo. Mientras espera aprobación, **el "Pagar" manual también desaparece** — el título todavía no es oficial. ## Capa 3 — Estado en el gateway[​](#capa-3--estado-en-el-gateway "Enlace directo al Capa 3 — Estado en el gateway") Solo pasa a existir después del envío al banco. Refleja el estado **real** del pago en el gateway — desde **Pendiente** y **Esperando aprobación del banco** hasta **Confirmado**, pasando por **Programado**, **Esperando saldo** y afines. La lista completa, con lo que significa cada uno, está en [Envío al banco](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md). nota **Dos aprobaciones, sin parentesco.** La de la capa 2 es de una persona de tu espacio de trabajo, y libera la **entrada en la lista**. La del banco es la de la institución, y ocurre solo después del envío. Un título puede estar aprobado aquí y rechazado allá. aviso **"Aprobado" en el gateway no es el final.** Significa que el lote fue aprobado por el banco — la institución **todavía no confirmó**. Quien cierra el ciclo es el **Confirmado**. Los estados finales son Confirmado, Cancelado, Rechazado, Reprobado y Fallido. **"Enviar al banco" no es una acción de fila de la lista.** Existe en dos lugares, los dos en la pantalla de **detalle**: el encabezado y la tarjeta del gateway. Desde la lista, el camino es **"Enviar pagos"**, en el encabezado — la bandeja que despacha en **lote**. ## Cómo un título pasa a Pagado — dos carriles[​](#cómo-un-título-pasa-a-pagado--dos-carriles "Enlace directo al Cómo un título pasa a Pagado — dos carriles") Hay **dos caminos** para que el título sea pagado, y son mutuamente excluyentes. ### Carril manual — el pago ocurrió por fuera[​](#carril-manual--el-pago-ocurrió-por-fuera "Enlace directo al Carril manual — el pago ocurrió por fuera") Pagaste el título **fuera del sistema** (banca por internet, efectivo, caja…). Usa **"Pagar"**: * Informa la fecha de pago y la cuenta financiera utilizada. * El sistema lo marca como **Pagado** y crea la transacción de salida en esa cuenta. * Los intereses y descuentos pueden registrarse en la baja. ### Carril gateway — el envío lo hizo el sistema[​](#carril-gateway--el-envío-lo-hizo-el-sistema "Enlace directo al Carril gateway — el envío lo hizo el sistema") Hiciste clic en **"Enviar al banco"**. A partir de ahí **no das de baja** — el sistema lo hace solo: * Cuando el gateway llega a **Confirmado**, el título se marca **Pagado** **automáticamente** y la transacción de salida se crea en la cuenta de origen. * Por eso, en el carril del gateway, el botón **"Pagar" desaparece** — es lo que evita la baja doble. aviso **Requisito de la baja automática:** la cuenta de origen (**"Pagar desde"**) tiene que estar definida. Sin ella el sistema no tiene desde dónde registrar la salida y **no** liquida — el título queda Confirmado y abierto (ver abajo). ### Cuándo el "Pagar" vuelve a aparecer[​](#cuándo-el-pagar-vuelve-a-aparecer "Enlace directo al Cuándo el \"Pagar\" vuelve a aparecer") Si el envío **terminó** y aun así el título quedó abierto, el botón manual se vuelve a exponer para que lo cierres por fuera: * **Confirmado sin cuenta de origen** — el banco confirmó, pero el sistema no tenía dónde registrar la salida. * **Cancelado, Rechazado, Reprobado o Fallido** — el pago no se concretó; tiene que ocurrir por fuera. ## Flujo completo[​](#flujo-completo "Enlace directo al Flujo completo") **El borrador es un desvío opcional, no la puerta de entrada.** Crear por el formulario, por el CSV o por la API graba el título directamente como Pendiente y esperando aprobación. Solo quien hace clic en **"Guardar borrador"** pasa por ahí — y publicar desde allí cae en la misma puerta, no la esquiva. ## Crear una cuenta por pagar[​](#crear-una-cuenta-por-pagar "Enlace directo al Crear una cuenta por pagar") 1. Accede a `/payables/new`. 2. Completa los campos obligatorios: **Monto (R$)**, **Fecha de vencimiento**, **Descripción**, **Proveedor**, **Mes de competencia** y **Tipo**. 3. Define el tipo de operación y el documento — ver [Operación y pago](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/operacao-e-pagamento.md). La categoría y el centro de clasificación son opcionales. 4. Termina con **Agregar cuenta**, **Agregar y crear otro** o **Guardar borrador**. **El proveedor no es opcional.** Sin él el formulario no se envía: *"Selecione ou crie um fornecedor"*. Puedes elegir un proveedor que ya existe **o escribir un nombre nuevo** — en ese caso queda registrado junto con la cuenta. La **Empresa** también es obligatoria, pero no es un campo del formulario: viene del selector del encabezado. nota **"Publicar" no existe en la pantalla de creación.** Los botones de ahí son los tres de arriba. **Publicar** aparece solo en el **detalle**, y solo mientras la cuenta es un borrador. En ambos casos el título entra bajo aprobación (capa 2) antes de contar en los números. ## Editar[​](#editar "Enlace directo al Editar") **Una cuenta pagada no es de solo lectura.** No hay traba por estado: el formulario abre normalmente en cualquier estado, incluso Pagado. La traba real es otra, y viene del banco — no del estado del título. **Cuando el gateway llega a Confirmado**, parte del formulario se cierra, y la pantalla avisa: > *"Pago confirmado por el banco. Lo que describe el pago — monto, fecha de vencimiento, proveedor y la información de pago — ya no puede modificarse. La clasificación interna (categoría, centro, adjuntos, notas) sigue editable."* Es decir: **la traba es parcial y tiene un motivo**. Congela lo que describe una transacción bancaria **ya ejecutada** — monto, fecha de vencimiento, proveedor, "Pagar desde", tipo de operación, documento y las coordenadas de pago. Sigue abierto lo que describe **cómo clasificas** eso: categoría, centro, competencia, descripción, adjuntos, notas y los destinatarios del **envío del comprobante** — ese último porque dice a quién avisar, no lo que hizo el banco. Clasificar es trabajo contable que sigue después de que el dinero sale. aviso **La traba no es solo visual.** El servidor rechaza el cambio de esos campos incluso por API — que la pantalla deshabilite los campos es la cortesía; la regla vale desde cualquier puerta. Esa traba **no existe en cuentas por cobrar** — no pasan por el envío al banco. Al editar una cuenta que forma parte de un grupo, el sistema ofrece **"Aplicar a otras cuotas"**, mostrando antes qué va a cambiar exactamente. Son **todas** las cuotas del grupo — incluidas las **anteriores** a la que estás editando, no solo las siguientes. Quedan fuera únicamente las ya liquidadas y la propia cuota editada. La selección viene marcada por completo; desmarca lo que no debe heredar — o guarda solo en la cuota abierta, con **"Solo esta cuota"** (en una recurrencia, **"Solo esta ocurrencia"**). nota **Los destinatarios del comprobante no entran en ese "aplicar a las demás".** Se copian a todas las cuotas **al crear** la serie; cambiarlos después vale solo para la cuota que estás editando. Si necesitas cambiarlos en todas, edítalas una por una. ## Eliminar[​](#eliminar "Enlace directo al Eliminar") En una cuenta que forma parte de un grupo — **en cuotas o recurrente** —, la eliminación pregunta el alcance: * **Eliminar solo esta** * **Eliminar esta y las futuras** El mismo selector cubre los dos casos: lo que mira es el grupo, no el tipo. En una cuenta suelta no aparece. nota El selector aparece **en la lista y en el detalle** de la cuenta. --- # Envío de pagos al banco Finanzas Inteligentes envía cuentas por pagar al banco a través del **Gateway Bancario**. El envío es una acción **manual** — la hace una persona, título a título o en lote desde la bandeja — **nunca** un disparador automático, salvo que el envío automático después de la aprobación esté activado en la [Configuración de Aprobación](https://docs.finance.kobana.com.br/es/es/aprovar-pagamentos/.md#activar-o-desactivar). El seguimiento del estado corre en segundo plano. Antes de cualquier envío, valen las reglas de [Seguridad](https://docs.finance.kobana.com.br/es/es/seguranca/.md) del espacio de trabajo — límites, cuentas, beneficiarios, tipos de operación, canales y horario nocturno. Ver [Bloqueos de seguridad](#bloqueos-de-seguridad). ## Prerrequisitos[​](#prerrequisitos "Enlace directo al Prerrequisitos") 1. [Gateway Bancario](https://docs.finance.kobana.com.br/es/es/integracoes/kobana.md) conectado y activo, con la cuenta de origen ya sincronizada. 2. Título **oficial**: solo se puede enviar después de pasar por la [aprobación de pago](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/ciclo-de-vida.md) — o si ya nace oficial, como las ocurrencias de una recurrencia aprobada y los títulos importados de Fintera. Un título que espera esa aprobación o que fue rechazado queda bloqueado. No lo confundas con la aprobación **del banco**, que solo existe después del envío. 3. **Tipo de operación** definido y las coordenadas de pago completas — código de barras, clave PIX, datos bancarios. Ver [Operación y pago](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/operacao-e-pagamento.md). 4. **"Pagar desde"** definida — es de ahí de donde sale el dinero. 5. Permitido por [Seguridad](https://docs.finance.kobana.com.br/es/es/seguranca/.md): canal, tipo de operación, cuenta, beneficiario, horario y límites. ## Flujo de envío[​](#flujo-de-envío "Enlace directo al Flujo de envío") nota **No existe "programar" en la pantalla.** El envío es siempre tu clic — nada sale solo, en ninguna fecha. Lo que el sistema manda al banco, junto con el pago, es la fecha en la que debe liquidar: el **vencimiento** del título. Si el título ya está vencido, va **hoy** — el gateway no paga con fecha retroactiva. ## Bloqueos de seguridad[​](#bloqueos-de-seguridad "Enlace directo al Bloqueos de seguridad") Las reglas de [Seguridad](https://docs.finance.kobana.com.br/es/es/seguranca/.md) se comprueban en cada envío — por el botón, en lote o en el envío automático. **Nada se reprograma**: un título frenado queda con el motivo a la vista y debe enviarse de nuevo cuando la regla lo permita. ### Motivos en la lista de envío[​](#motivos-en-la-lista-de-envío "Enlace directo al Motivos en la lista de envío") ![Lista de envío con bloqueos y aviso de límite de Seguridad](/es/assets/images/29-dispatch-inbox-373839bc3518d3690ca66f16100bc330.png) En el diálogo **Enviar pagos al banco**, un título frenado por una regla que solo depende de él aparece **deshabilitado**, con el motivo — pasa el mouse para leer el mensaje completo: | Motivo | Dónde se resuelve | | ----------------------------------------- | ----------------------------------------------- | | **Canal sin permiso de envío** | Seguridad → Canales (Pagar) | | **Tipo de operación desactivado** | Seguridad → Tipos de operaciones | | **Cuenta bloqueada para esta operación** | Seguridad → Cuentas | | **Beneficiario no habilitado** | Seguridad → Beneficiarios (solo transferencias) | | **Envío nocturno bloqueado** | Esperar el período diurno | | **Por encima del límite por transacción** | Seguridad → Límites | Los límites que dependen de lo que **ya se envió** aparecen como **aviso**, y la fila sigue seleccionable: * *Superaría el límite del período* * *Superaría el límite diario de la cuenta* * *Superaría el límite diario del beneficiario* * *Superaría el límite mensual del beneficiario* El aviso es una previsión: la cuenta final se hace en el momento del envío. En un envío en lote, los títulos van en orden de vencimiento, y cuando se alcanza un límite los siguientes que lo superarían **no se envían**. El resultado lista cada título no enviado con su motivo. Si una regla rechazó el envío automático después de la aprobación, la fila lleva la etiqueta **Envío automático bloqueado** — el título vuelve a la lista y espera un envío manual. nota **Forzar el reenvío no escapa de las reglas.** Reenviar y reenviar un cancelado pasan por las mismas comprobaciones, y el envío anterior sigue contando en el límite mientras no haya prueba de que no existe en el banco. ### Envío nocturno desactivado[​](#envío-nocturno-desactivado "Enlace directo al Envío nocturno desactivado") Con **Permitir el envío al banco en el período nocturno** desactivado en Seguridad, nada va al banco entre el inicio de la noche y el inicio del día. La lista muestra el aviso **"Envío al banco bloqueado hasta las 06:00"** (con el horario de tu espacio de trabajo). **Nada se reprograma para la mañana.** Lo aprobado de noche — incluso con el envío automático activado — queda en la lista y debe enviarse de nuevo en el período diurno. ### Retenidos en el banco[​](#retenidos-en-el-banco "Enlace directo al Retenidos en el banco") Un pago creado al final del día puede tener la aprobación automática del lote cayendo ya en el período nocturno. Con el envío nocturno desactivado, el lote **no se aprueba** y queda **retenido en el banco**: * la tarjeta del pago, en el título, muestra la etiqueta **"Retenido en el banco: envío nocturno bloqueado"**; * la lista de envío gana la sección **Retenidos en el banco**; * el botón **Aprobar en el banco** (en la tarjeta y en la sección) solo funciona en el período diurno: vuelve a comprobar las reglas, aprueba el lote y retoma el seguimiento. **"Actualizar estado"** y el seguimiento automático no aprueban un lote retenido. ## Estado del gateway[​](#estado-del-gateway "Enlace directo al Estado del gateway") El estado refleja la situación **real** del pago en el gateway: | Estado | Qué significa | | ----------------------------------------------- | ------------------------------------------ | | **Pendiente** | Creado en el gateway, todavía sin procesar | | **Esperando aprobación del banco** | En la cola de aprobación de la institución | | **Aprobado** | Aprobado — pero **todavía no liquidado** | | **Programado** · **Esperando fecha programada** | Marcado para una fecha futura | | **Esperando saldo** | Sin fondos en la cuenta para liquidar | | **Vencido** | Pasó la fecha y no se liquidó | | **Finalizando** | En procesamiento final | | **Confirmado** | Liquidado — el dinero salió | | **Reprobado** · **Rechazado** | Rechazado por la institución | | **Fallido** | Error en el procesamiento | | **Cancelado** | Envío cancelado | aviso **"Aprobado" no es el final.** Es el estado que más engaña: el lote fue aprobado, pero la institución **todavía no liquidó**. Quien cierra el ciclo es el **Confirmado**. Los estados finales son Confirmado, Cancelado, Rechazado, Reprobado y Fallido. ## Liquidación automática[​](#liquidación-automática "Enlace directo al Liquidación automática") La baja ocurre cuando el gateway llega a **Confirmado** — y no en Aprobado, que todavía es intermedio. Al llegar ahí, el sistema marca la cuenta como pagada y crea la transacción de salida en la cuenta de origen. aviso **Sin "Pagar desde" definida, no hay baja automática.** El sistema no tendría desde dónde registrar la salida: el título queda Confirmado y abierto. Ver [Ciclo de vida](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/ciclo-de-vida.md). El botón **"Actualizar estado"** busca la situación actual bajo demanda, sin esperar al seguimiento automático. ## Comprobante[​](#comprobante "Enlace directo al Comprobante") Al llegar a **Confirmado**, el comprobante del pago se **captura solo**: queda guardado en los [Adjuntos](https://docs.finance.kobana.com.br/es/es/anexos/.md) del título y se lista en [Comprobantes](https://docs.finance.kobana.com.br/es/es/comprovantes/.md). Quien esté marcado para recibirlos recibe un correo, y las direcciones registradas en **"Envío del comprobante"** en el formulario de la cuenta reciben el **archivo adjunto**; la campana avisa de todas formas. Ver [Quién recibe por correo](https://docs.finance.kobana.com.br/es/es/comprovantes/.md#qui%C3%A9n-recibe-por-correo). Mientras se busca, la situación es **Descargando** — normal, y toma unos instantes. ## Cancelar envío[​](#cancelar-envío "Enlace directo al Cancelar envío") **"Cancelar envío"** deshace el envío mientras el pago **no haya llegado a un estado final**. El título sigue en el carril del gateway, ahora con el sello **"Cancelado"**, y el **"Pagar"** vuelve a aparecer — para que cierres el título por fuera, si el pago termina ocurriendo de otra manera. Por eso un título ya enviado **no** ofrece "Cancelar": anularlo por aquí dejaría el pago vivo en el gateway. El camino es cancelar el envío primero. ## Editar después del envío[​](#editar-después-del-envío "Enlace directo al Editar después del envío") Una vez iniciado el envío, **monto, beneficiario, cuenta y datos de pago quedan bloqueados**: *"Título ya enviado al banco — el monto, el beneficiario, la cuenta y los datos de pago ya no se pueden modificar."* El título tiene que seguir correspondiendo a lo que se pagó. Antes del envío, cambiar esos campos en un título aprobado lo devuelve a la [aprobación](https://docs.finance.kobana.com.br/es/es/aprovar-pagamentos/.md#editar-un-t%C3%ADtulo-aprobado). --- # Importación CSV — Cuentas por pagar Importa lotes de cuentas por pagar mediante un archivo CSV. ## Dónde está[​](#dónde-está "Enlace directo al Dónde está") **No existe "Importación" en el menú**, ni una pantalla de importación. El camino es: **Cuentas por Pagar** → píldora **Importar**, en la propia lista. Sin ninguna cuenta registrada todavía, la lista muestra el estado vacío con el botón **Importar** junto a **Nueva cuenta por pagar**, que abre el mismo panel. Hace falta tener una **empresa específica** seleccionada en el encabezado. En "todas las empresas", el panel solo avisa: *"Selecciona una empresa específica para importar cuentas por pagar."* El botón **Descargar plantilla** entrega un CSV de ejemplo con el encabezado correcto — es el punto de partida más seguro, porque ya viene en la codificación adecuada. ## Columnas del CSV[​](#columnas-del-csv "Enlace directo al Columnas del CSV") | Columna | Obligatorio | Descripción | | ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `description` | ✅ | Descripción de la cuenta por pagar | | `amount` | ✅ | Monto en reales (ej.: `3500,00`) | | `due_date` | ✅ | Fecha de vencimiento (`dd/MM/yyyy`) | | `competence_date` | — | Fecha de competencia (`dd/MM/yyyy`) | | `document` | — | Identificador del documento | | `document_date` | — | Fecha de emisión (`dd/MM/yyyy`) | | `document_number` | — | Número de la factura | | `person_name` | — | Nombre del proveedor (si todavía no existe, la vista previa pregunta si crearlo) | | `category_name` | — | Nombre de la categoría (si todavía no existe, la vista previa pregunta si crearlo) | | `cost_center_name` | — | Nombre del centro de clasificación (si todavía no existe, la vista previa pregunta si crearlo) | | `payment_method` | — | Método: `bank_billet`, `utility`, `tribute`, `ted`, `pix`, `credit_card`, `debit_card`, `cash`, `check`, `direct_debit`, `other` o `none` (los alias en portugués — `boleto`, `dinheiro`, … — también valen) | | `notes` | — | Notas | | `ir_relevant` | — | `true` o `false` | | `operation_kind` | — | `pagamento` o `transferencia` | | `barcode` | — | Código de barras (boleto o factura de servicios) | | `pix_copia_e_cola` | — | Payload PIX Copia e Cola | | `pix_key` | — | Clave PIX | | `pix_key_type` | — | Tipo de clave: `cpf`, `cnpj`, `email`, `phone`, `random` | | `bank_code` | — | Código COMPE del banco (TED) | | `bank_ispb` | — | ISPB del banco (TED) | | `agency` | — | Agencia bancaria | | `agency_digit` | — | Dígito de la agencia | | `account_number` | — | Número de cuenta | | `account_digit` | — | Dígito de la cuenta | | `transfer_purpose` | — | Propósito de la transferencia (TED) | | `tax_kind` | — | Tipo de tributo: `darf`, `gru`, `gps`, `fgts`, `icms`, `iss`, `iptu`, `itbi` o `dare` | | `beneficiary_name` | — | Nombre del beneficiario (envío al banco) | | `beneficiary_document` | — | CPF o CNPJ del beneficiario | | `scheduled_to` | — | Fecha/hora de programación del envío al banco | Los nombres de arriba son los canónicos, pero **todo encabezado acepta su equivalente en portugués** — `descricao`, `valor`, `vencimento`, `fornecedor`, `categoria`, `observacao` y así sucesivamente. Las planillas de otros sistemas también sirven para proveedor, centro de clasificación y categoría: `contraparte` vale como `person_name`; `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` valen como `cost_center_name`, y `plano_de_contas`, `categoria_financeira`, `category` como `category_name`. Si el espacio tiene un clasificador con el mismo nombre que una de estas columnas (ej.: *Centro de Resultado*), la columna va al clasificador. Si la planilla tiene más de una columna para el mismo campo (p. ej.: `Centro de Custo` y `Centro de Receita`), cada línea usa la primera que esté completa. Además de esos nombres, un encabezado con la palabra **centro** se lee como centro de clasificación; uno con **categoria** o **plano de contas**, como categoría (por ejemplo, `Centro de Lucro`, `Categoria DRE`); y uno con **pessoa**, **cliente** o **fornecedor** acompañada solo de palabras de nombre, como persona (por ejemplo, `Nome do Fornecedor`, `Cliente / Fornecedor` — pero no `CNPJ do Fornecedor`). Las columnas que el sistema no conoce se **ignoran en silencio**. ## Formato[​](#formato "Enlace directo al Formato") El parser es más tolerante de lo que parece. No hace falta normalizar el archivo de antemano: * **Encabezado** — mayúsculas, acentos y espacios no importan: `Descrição`, `DESCRICAO` y `descricao` son la misma columna. * **Separador** — `,` o `;`, detectado **por la línea de encabezado**. En caso de empate, `;`. * **Fechas** — `31/12/2026`, `31-12-2026` o `2026-12-31`. * **Montos** — `1234.56`, `1.234,56`, `1234,56`, con o sin `R$`. El monto tiene que ser **mayor que cero**. * **`ir_relevant`** — `true`/`false`, `sim`/`nao`, `yes`/`no`, `1`/`0`, `s`/`y`/`n`. Sin acento, en mayúscula o minúscula. Vacío deja el campo en blanco. aviso **La codificación tiene que ser UTF-8, y es aquí donde tropieza la mayoría de los archivos.** Excel en portugués guarda el CSV en Windows-1252 por defecto, y el sistema lo rechaza con un mensaje que permanece en portugués: *"Arquivo não está em UTF-8. Salve novamente em UTF-8 e tente novamente."* ("El archivo no está en UTF-8. Guárdalo de nuevo en UTF-8 e inténtalo otra vez.") En Excel, usa **Guardar como → CSV UTF-8**; o parte de la plantilla descargada. Otros rechazos del archivo entero: extensión distinta de `.csv`, tamaño superior a **5 MB**, archivo vacío, y **columna obligatoria ausente** — *"Colunas obrigatórias ausentes: amount"* ("Faltan columnas obligatorias: amount"). En esos casos no hay vista previa: el problema es del archivo, no de una fila. ## Importar[​](#importar "Enlace directo al Importar") 1. Sube el archivo. El sistema lo lee y muestra la vista previa. 2. **Las filas válidas ya vienen marcadas.** Haz clic en una fila para desmarcarla. 3. Haz clic en **Importar N líneas**. ### Filas con error[​](#filas-con-error "Enlace directo al Filas con error") Las filas inválidas aparecen en la vista previa con un marcador rojo, **y no pueden seleccionarse ni editarse ahí**. No hay corrección dentro del sistema. La propia pantalla indica el camino: *"Desmarca las filas con errores o corrígelas en el archivo y vuelve a subirlo."* El número en **Fila N** es el número de la línea **en el archivo**, contando el encabezado — la primera línea de datos es la 2. ### La grabación corre en segundo plano[​](#la-grabación-corre-en-segundo-plano "Enlace directo al La grabación corre en segundo plano") Al confirmar, recibes *"Importación iniciada en segundo plano"* y un diálogo de progreso. **Puedes cerrar el diálogo** — la importación continúa, y el progreso queda visible en la esquina inferior derecha. ### Vínculos[​](#vínculos "Enlace directo al Vínculos") **Los proveedores, categorías y centros de clasificación aparecen en la vista previa**, cada uno con lo que hará la importación: los que ya existen se vinculan; los nuevos vienen marcados para **crear** (o para **dejar en blanco**, si no tienes permiso para crearlos); un nombre que solo cambia en acentos, mayúsculas o espacios respecto de uno existente viene marcado para **usar el existente**; y un centro de clasificación que solo existe del otro lado (ej.: uno del tipo Ingresos en una cuenta por pagar) viene marcado para dejar en blanco. El proveedor se busca solo por el nombre: una persona ya registrada como cliente también sirve, y pasa a ser proveedor también. Las grafías del mismo nombre que solo cambian acento, mayúscula o espacio (p. ej.: *Água e Luz* y *agua e luz*) cuentan como un solo nombre. Puedes cambiar cualquier elección antes de importar. Las [reglas automáticas](https://docs.finance.kobana.com.br/es/es/regras-automaticas/.md) se aplican a los registros importados. ## Historial[​](#historial "Enlace directo al Historial") Debajo del panel, la sección **Historial** lista las importaciones con fecha, archivo, estado (**En cola**, **En progreso**, **Completado**, **Fallido**, **Cancelado**), cuántas filas entraron del total y quién la pidió. ## Aprobación[​](#aprobación "Enlace directo al Aprobación") Las cuentas por pagar importadas entran bajo la **puerta de aprobación de pagos**: nacen **esperando aprobación** y **no aparecen en la lista oficial** (ni en totales/flujo de caja) hasta ser aprobadas por una persona en [Aprobar pagos](https://docs.finance.kobana.com.br/es/es/aprovar-pagamentos/.md). Solo después de aprobadas pueden enviarse al banco. Esto aplica con la puerta **activada** (el valor por defecto); desactivada, las filas importadas entran ya oficiales. Ver [Ciclo de vida](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/ciclo-de-vida.md). --- # Operación y pago El formulario de cuenta por pagar separa **dos cosas distintas**, en dos bloques: | Bloque | Responde | | ------------------------- | ------------------------------------------------------------------------------------------- | | **OPERACIÓN Y DOCUMENTO** | Qué es esta obligación y qué documento la representa | | **INFORMACIÓN DE PAGO** | Las coordenadas para ejecutarla (código de barras, Pix, datos bancarios, formulario fiscal) | nota **No existe un campo genérico "Método de pago" en la cuenta por pagar.** El segundo campo lo **etiqueta la operación** elegida — y la lista de opciones cambia junto con ella. ## OPERACIÓN Y DOCUMENTO[​](#operación-y-documento "Enlace directo al OPERACIÓN Y DOCUMENTO") ### Tipo de operación[​](#tipo-de-operación "Enlace directo al Tipo de operación") El eje primario. Tres opciones: | Opción | Qué significa | | --------------------- | ------------------------------------------------------------------------------------------------------ | | **Pago de documento** | Saldar un documento que ya existe: boleto, factura de servicios, formulario de impuesto o un cobro Pix | | **Transferencia** | Enviar dinero a un beneficiario | | **Débito automático** | El banco debita la cuenta por sí solo en la fecha, sin nada que enviar | Mientras no se elija el tipo de operación, **el segundo campo ni siquiera aparece**. ### Débito automático[​](#débito-automático "Enlace directo al Débito automático") Para la cuenta que el banco debita por su cuenta: un financiamiento, una tarifa, una factura de servicios en débito en cuenta. **No hay segundo campo ni panel de pago**, y la cuenta **nunca se envía al banco** — no aparece en la bandeja de envío ni ofrece "Enviar al banco". Cuando ocurra el débito, dale de baja: en la fila o en lote, con **"Marcar como pagadas"** (ver [Acciones en lote](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/.md#acciones-en-lote)). ### El segundo campo cambia de nombre según la operación[​](#el-segundo-campo-cambia-de-nombre-según-la-operación "Enlace directo al El segundo campo cambia de nombre según la operación") | Tipo de operación | Etiqueta del campo | Opciones | | --------------------- | ------------------------- | ----------------------------------------------------------------- | | **Pago de documento** | **Documento** | Boleto bancario · Factura de servicios · Impuesto / tributo · PIX | | **Transferencia** | **Tipo de transferencia** | Transferencia bancaria (TED) · PIX | * Cambiar el tipo de operación **resetea** el segundo campo cuando la opción elegida no pertenece a la nueva operación. * **Un tributo es un documento, no una "forma de pago"** — por eso aparece bajo *Documento*, y nunca en una lista de métodos. * **PIX aparece en los dos ejes**, con sentidos distintos: en *Pago de documento* es el **copia y pega** de un cobro; en *Transferencia* es **clave o datos bancarios** de un beneficiario. ### Documento[​](#documento "Enlace directo al Documento") Todavía en este bloque: **Número de documento** y **Fecha del documento** — la identificación de la factura o del boleto. ## INFORMACIÓN DE PAGO[​](#información-de-pago "Enlace directo al INFORMACIÓN DE PAGO") Este panel solo aparece cuando la combinación *operación × documento* tiene coordenadas que informar. El título es **"INFORMACIÓN DE PAGO"** — o **"DATOS DEL FORMULARIO FISCAL"** cuando el documento es un tributo. | Operación → Documento | Qué pide el panel | | ------------------------------- | ------------------------------------------------------------------------------------------ | | Pago → **Boleto bancario** | Código de barras | | Pago → **Factura de servicios** | Código de barras | | Pago → **Impuesto / tributo** | **Tipo de impuesto** + **Cómo ingresar**: **Código de barras** o **Campos del formulario** | | Pago → **PIX** | **Código Pix** (copia y pega) | | Transferencia → **PIX** | Pestañas **Clave Pix** o **Datos bancarios** — eliges un camino | | Transferencia → **TED** | **Datos bancarios**: banco, agencia + dígito, cuenta + dígito | ### Beneficiario (solo en transferencia)[​](#beneficiario-solo-en-transferencia "Enlace directo al Beneficiario (solo en transferencia)") Las dos transferencias — TED y PIX — llevan además **quién recibe**: | Campo | Obligatorio para enviar al banco | | --------------------------------- | -------------------------------- | | **Nombre del beneficiario** | Sí | | **CPF/CNPJ del beneficiario** | Sí | | **Propósito de la transferencia** | No | aviso **Sin esos dos campos el [envío al banco](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md) no sale.** La institución exige nombre y documento de quien recibe en cualquier transferencia, y la bandeja de envío rechaza la fila hasta que estén completos. **En PIX, el beneficiario es siempre el proveedor.** Por clave o por datos bancarios, los dos campos aparecen **solo de lectura**, con el nombre y el CPF/CNPJ del registro del proveedor, y la nota *"En Pix, el beneficiario es siempre el proveedor de la cuenta por pagar. Para cambiarlo, elige otro proveedor o corrige su registro."* El envío al banco usa ese registro, aunque la cuenta guarde otro beneficiario de antes. Un proveedor sin CPF/CNPJ traba el envío hasta que se complete su registro. Por la API, un PIX con el CPF/CNPJ de otra persona como beneficiario se rechaza. **En TED, elegir un proveedor completa el beneficiario por ti** — nombre y CPF/CNPJ vienen de la persona, junto con los datos bancarios de su cuenta principal. Esto ocurre en el momento en que seleccionas la persona en el campo Proveedor, y **sustituye lo que ya estuviera completado**. Los campos siguen siendo editables: en la TED el beneficiario puede legítimamente ser otro (un empleado del proveedor, un tercero autorizado). nota **Este panel no paga nada.** Solo guarda las coordenadas en el registro. El pago ocurre de dos formas — por fuera (y tú das de baja) o por el [envío al banco](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md). Ver [Ciclo de vida](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/ciclo-de-vida.md). ### PIX — copia y pega[​](#pix--copia-y-pega "Enlace directo al PIX — copia y pega") Al pegar el código, el sistema **dibuja el código QR** al instante — se puede escanear en la app del banco y pagar por fuera. **"Consultar datos del QR"** va más allá: busca el cobro y muestra **Beneficiario**, **Monto del QR**, **Fecha de vencimiento** y si **puede pagarse**. Es solo lectura — sirve para verificar antes de enviar. Con los datos en pantalla, **"Rellenar con estos datos"** los trae al formulario: | Del QR | Va a | | ------------ | ------------------------------------------------------------------------- | | Monto | **Monto (R$)** | | Vencimiento | **Fecha de vencimiento** | | Descripción | **Descripción** — solo si está vacía; lo que escribiste no se sobrescribe | | Beneficiario | **Proveedor** | **El beneficiario del QR se convierte en el Proveedor.** Aquí no hay campo "Beneficiario" — ese solo existe en transferencia. El sistema busca un proveedor ya registrado **por el documento** del beneficiario (CPF o CNPJ); si lo encuentra, lo selecciona. Si no, deja el **nombre** completado como proveedor nuevo, que se registra al guardar. ### PIX — clave[​](#pix--clave "Enlace directo al PIX — clave") El **tipo de clave** (CPF, CNPJ, correo electrónico, teléfono, aleatoria) se **detecta automáticamente** a partir de la clave escrita — es un campo de solo lectura; no lo seleccionas. ### Impuesto / tributo — código o datos[​](#impuesto--tributo--código-o-datos "Enlace directo al Impuesto / tributo — código o datos") Son **nueve** tipos: DARF, GRU, GPS, FGTS, DARE, ICMS, ISS, IPTU e ITBI. nota **Solo cuatro aceptan el formulario estructurado.** **DARF, GRU, GPS y FGTS** ganan el campo **"Cómo ingresar"**, para elegir entre **Código de barras** (predeterminado) y **Campos del formulario** — y ahí los campos varían por tipo. Los otros cinco aceptan **solo el código de barras**; para ellos, el "Cómo ingresar" ni siquiera aparece. Esto **no** limita el envío al banco: los nueve se pueden enviar. Ver [Tributos](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/tributos.md). ### Bloqueo tras la confirmación[​](#bloqueo-tras-la-confirmación "Enlace directo al Bloqueo tras la confirmación") Después de que el banco confirma el pago, el panel entero queda de **solo lectura**: las coordenadas pasan a describir una transacción bancaria ya ejecutada y no pueden cambiar más. ## ¿Y el efectivo, la tarjeta, el cheque?[​](#y-el-efectivo-la-tarjeta-el-cheque "Enlace directo al ¿Y el efectivo, la tarjeta, el cheque?") Efectivo, tarjeta de crédito, tarjeta de débito, cheque y "otro" existen en el sistema y pueden llegar por **importación de CSV** o por la **API** — pero **ningún formulario los ofrece**. No hay ese campo en cuentas por pagar, ni en cuentas por cobrar, ni en transacciones. El **débito automático** es la excepción: tiene opción propia en **Tipo de operación** (ver arriba). Donde sí aparecen es **en la lectura**: la lista de cuentas por pagar tiene la columna **Liquidación** y la de transacciones tiene **Método de pago**, ambas ocultas por defecto y activables desde el selector de columnas. Un título importado con "efectivo" muestra "efectivo" ahí — lo que no puedes es escribirlo. Si la obligación no es un documento ni una transferencia, **deja el tipo de operación sin completar**: cómo salió efectivamente el dinero se registra en la baja (cuenta financiera + fecha), no aquí. El select abre vacío en un título nuevo — pero solo tiene las tres opciones, sin un "Ninguno": una vez elegida una operación, no se puede volver al vacío desde la pantalla. --- # Cuotas y recurrencia Las cuentas por pagar admiten dos modos además del pago simple: cuotas y recurrencia. ## Los tres tipos[​](#los-tres-tipos "Enlace directo al Los tres tipos") El campo **Tipo**, obligatorio, ofrece: | Tipo | Qué es | | -------------- | -------------------------------------------------- | | **Único** | Cuenta única, sin repetición | | **Cuota** | Dividida en N cuotas con vencimientos secuenciales | | **Recurrente** | Se repite sola en un intervalo fijo | ## Cuota[​](#cuota "Enlace directo al Cuota") Elegido el tipo, aparece el campo **Cuotas**: de **2** a **120**. aviso **El monto es por cuota, no el total.** En **Monto (R$)** informas cuánto vale **cada** cuota — 12 × R$ 100 se registra como monto 100 y 12 cuotas, no como 1.200. El resumen junto al formulario muestra los dos: **Valor de cada cuota** y **Total en 12 cuotas**. Al guardar, el sistema crea las N cuentas de una vez, con **vencimientos mensuales a partir del primer vencimiento** (un mes por cada cuota) y numeración secuencial — **Cuota 1/12**, **Cuota 2/12**… Cuando el día no existe en el mes (el 31 en febrero), la cuota cae en el último día de ese mes. Cada cuota es una cuenta independiente: puede pagarse por separado, y su vencimiento o monto se ajustan después, una por una. info **Las cuotas se eligen al crear.** En una cuenta que ya forma parte de una serie, **Tipo** y **Cuotas** quedan bloqueados — *"Forma parte de una serie: el tipo y el número de cuotas no cambian."* Una cuenta **Único** ya guardada puede pasar a **Recurrente**, pero no a **Cuota**. ### Navegar entre cuotas[​](#navegar-entre-cuotas "Enlace directo al Navegar entre cuotas") En el detalle de una cuota, las flechas llevan a la anterior y a la siguiente de la misma serie. La acción **Cuotas**, en el menú de la fila, lista la serie entera. ## Recurrente[​](#recurrente "Enlace directo al Recurrente") Elegido el tipo, aparece el campo **Recurrencia**, obligatorio, con cinco períodos: | Opción | Intervalo | | -------------------- | --------- | | **Cada semana** | 7 días | | **Cada dos semanas** | 14 días | | **Cada mes** | 1 mes | | **Cada 3 meses** | 3 meses | | **Cada año** | 12 meses | **En las listas el rótulo se acorta** — la misma recurrencia aparece como **Semanal**, **Quincenal**, **Mensual**, **Trimestral** o **Anual**. Es lo mismo, escrito corto para que entre en la fila. ### Las próximas quedan registradas con antelación[​](#las-próximas-quedan-registradas-con-antelación "Enlace directo al Las próximas quedan registradas con antelación") nota **Una recurrencia nace con los próximos meses ya registrados.** Al crearla, el sistema graba las ocurrencias hasta **12 meses adelante** (el valor por defecto), y la ventana avanza sola: cada día las series se completan hasta el nuevo límite. Cada ocurrencia es una cuenta de verdad — entra en el flujo de caja, su monto puede cambiarse y puede liquidarse **antes** que la anterior. El plazo está en **Configuración de recurrencia**, en el engranaje del listado de cuentas por pagar o por cobrar: **Meses de aprovisionamiento**, de 0 a 36. Aumentarlo completa las series en el momento; disminuirlo no borra lo ya registrado, solo deja de registrar más allá del nuevo plazo. Con **0**, cada serie mantiene solo la próxima cuenta abierta, y la siguiente nace cuando esta se liquida. Con la [aprobación de pago](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/ciclo-de-vida.md) activada, todas las ocurrencias de una serie nueva entran en la cola de aprobación. **Las ocurrencias se cuentan desde la primera.** Una serie mensual que empieza un día 31 cae en el último día de los meses más cortos y vuelve al 31 cuando el mes tiene 31 días. Cambiar el vencimiento de una ocurrencia afecta solo a esa: las siguientes siguen en el día original de la serie. **Cada ocurrencia registrada copia la última de la serie** — monto, categoría, centro de clasificación, forma de pago, impuestos y retenciones, documento y observaciones. Una cuenta **Único** ya guardada puede pasar a **Recurrente**: al cambiar el tipo y elegir la recurrencia, el sistema empieza la serie a partir de ella. **Repetir hasta** (opcional, junto a la recurrencia) es el último vencimiento de la serie; vacío, la serie no tiene fin. La fecha vale para toda la serie: acortarla elimina las cuentas abiertas después del nuevo fin, y extenderla vuelve a registrar. No puede quedar antes del vencimiento de la cuenta que estás editando. En una serie importada (Fintera, Nibo), el fin es el del origen y el campo no aparece. Para cambiar el monto de los próximos meses, edita una ocurrencia: el diálogo de propagación permite elegir qué otras de la serie heredan el cambio — o ninguna, con **"Solo esta ocurrencia"**. Las ocurrencias registradas desde entonces siguen el valor de la última. Más allá del plazo, la proyección del flujo de caja continúa la serie al mostrarla, sin grabarla. Ver [Dashboard](https://docs.finance.kobana.com.br/es/es/dashboard/.md). La acción **Recurrencias**, en el menú de la fila, lista las ocurrencias registradas de la serie. En el detalle de la cuenta, **Fecha de vencimiento anterior** y **Próxima fecha de vencimiento** las recorren. ### Eliminar[​](#eliminar "Enlace directo al Eliminar") Al eliminar una cuenta que pertenece a un grupo, el sistema ofrece: * **Eliminar solo esta** — quita únicamente la ocurrencia actual. En una recurrencia no vuelve a registrarse: la serie sigue desde la siguiente. * **Eliminar esta y las futuras** — quita la actual y todas las siguientes del grupo. En una recurrencia también cierra la serie ahí: las cuentas eliminadas no vuelven a registrarse. nota **Lo ya pagado se queda.** *"Las ocurrencias ya pagadas o conciliadas se mantienen."* Si alguna de las siguientes no se puede eliminar, el aviso dice cuántas quedaron. **Una serie importada no se elimina desde aquí.** En una serie que vino de una integración (Fintera, Nibo), **Eliminar esta y las futuras** se rechaza — *"Esta serie viene de una integración; elimínala en el origen"*. Su fin también es el del origen. **El alcance no es exclusivo de las recurrencias.** El selector mira el **grupo**, así que **cuotas y recurrentes** se comportan igual. En una cuenta suelta no aparece. El selector está **en la lista**. Al eliminar desde el detalle, se borra siempre solo esa cuenta. --- # Tributos Una cuenta por pagar cuyo **documento es un Impuesto / tributo** representa una guía de tributo federal, estatal o municipal. En el formulario: **Tipo de operación = Pago de documento** → **Documento = Impuesto / tributo** (el tributo es un documento, no una "forma de pago" — ver [Operación y pago](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/operacao-e-pagamento.md)). El campo **Tipo de impuesto** determina los campos específicos de la guía. ## Tipos de tributo[​](#tipos-de-tributo "Enlace directo al Tipos de tributo") Nueve, tal como aparecen en el selector **"Tipo de impuesto"**: | Tributo | ¿Guía estructurada? | | --------------------------------------------------------------- | ------------------- | | **ITBI** — Impuesto sobre Transmisión de Bienes Inmuebles | No | | **ICMS** — Impuesto sobre Circulación de Mercancías y Servicios | No | | **ISS** — Impuesto sobre Servicios | No | | **IPTU** — Impuesto Predial y Territorial Urbano | No | | **FGTS** — Fondo de Garantía por Tiempo de Servicio | **Sí** | | **DARE** — Documento de Recaudación de Ingresos Estaduales | No | | **DARF** — Documento de Recaudación de Ingresos Federales | **Sí** | | **GRU** — Guía de Recaudación Federal | **Sí** | | **GPS** — Guía de la Previsión Social | **Sí** | ## Cómo informar la guía[​](#cómo-informar-la-guía "Enlace directo al Cómo informar la guía") Elegido el tipo, **DARF, GRU, GPS y FGTS** ganan un segundo campo — **"Cómo ingresar"** — con dos opciones: * **Código de barras** (opción por defecto) — un solo campo: **"Código de barras / línea digitada"**. * **Campos del formulario** — abre las secciones estructuradas del documento, descritas más abajo. nota **Los otros cinco tipos no tienen esa elección.** ICMS, ISS, IPTU, ITBI y DARE aceptan **solamente el código de barras** — el campo "Cómo ingresar" ni siquiera aparece para ellos. ## Campos de la guía[​](#campos-de-la-guía "Enlace directo al Campos de la guía") Solo en el modo **Campos del formulario**, y solo en los cuatro tipos de arriba. Cada guía se organiza en secciones que reproducen el documento oficial. ### DARF[​](#darf "Enlace directo al DARF") | Sección | Campos | | ------------------------------------ | ----------------------------------------------------------------------------------------- | | **Identificación del contribuyente** | Tipo de contribuyente · CPF/CNPJ del contribuyente · Nombre del contribuyente | | **Datos del formulario** | Código de ingreso / pago · Número de referencia · Fecha de cálculo · Fecha de vencimiento | | **Cargos e ingresos** | Multa · Interés · Ingreso bruto | El **Tipo de contribuyente** del DARF es el más amplio: CNPJ, CPF, NIT, PIS, PASEP, CEI, NB, N.º de título, DEBCAD y Referencia. ### GRU[​](#gru "Enlace directo al GRU") | Sección | Campos | | ------------------------------- | ------------------------------------------------------------------------- | | **Vencimiento y referencia** | Fecha de vencimiento · Número de referencia · Monto total | | **Ajustes de valor (opcional)** | Descuento · Otras deducciones · Otras adiciones · **Multa** · **Interés** | ### GPS[​](#gps "Enlace directo al GPS") | Sección | Campos | | ------------------------------------ | ------------------------------------------------------------------------------- | | **Identificación del contribuyente** | Tipo de contribuyente · CPF/CNPJ del contribuyente · Nombre del contribuyente | | **Datos del formulario** | Código de ingreso / pago · Competencia · Fecha de vencimiento · Otras entidades | | **Cargos (opcional)** | Actualización monetaria · Multa · Interés | El **Tipo de contribuyente** de la GPS es más corto que el del DARF: CNPJ, CPF, NIT, PIS, PASEP y CEI. ### FGTS[​](#fgts "Enlace directo al FGTS") | Sección | Campos | | ------------------ | ------------------------------------------------------------------- | | **Identificación** | Código del contribuyente · Número PIS/PASEP · Código de recaudación | | **Datos FGTS** | Código FGTS · Porcentaje JAM (%) · Sello de conectividad | El FGTS no tiene sección de contribuyente ni de cargos — la identificación se hace mediante los códigos. ## Envío por el Gateway Bancario[​](#envío-por-el-gateway-bancario "Enlace directo al Envío por el Gateway Bancario") nota **Los nueve tipos pueden enviarse al banco.** El ruteo mira la combinación **operación × documento** — "Pago de documento" + "Impuesto / tributo" resuelve al recurso de tributo del gateway, **sea cual sea el tipo de tributo**. Un IPTU informado por código de barras sale tan bien como un DARF. Lo que es exclusivo de DARF, GRU, GPS y FGTS **no es el envío, es el modo de informar**: solo ellos aceptan la guía estructurada. Los demás viajan por el código de barras. **El envío no es automático.** Nada sale por sí solo: eres tú quien hace clic — **"Enviar al banco"**, en la pantalla de detalle, o **"Enviar pagos"**, para despachar en lote desde la lista. Ver [Envío al banco](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md) y [Ciclo de vida](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/ciclo-de-vida.md). --- # Cuentas por cobrar Cuentas por Cobrar (`/receivables`) registra los compromisos de entrada de la organización: mensualidades de clientes, ventas, servicios prestados y cualquier importe a cobrar. ![Lista de cuentas por cobrar](/es/assets/images/03-receivables-f5d856e6cf1a2f8a8496fc14184d10a6.png) ![Detalle de cuenta por cobrar](/es/assets/images/04-receivable-detail-cb9a871abf0c1701b513d89996320959.png) ## En esta sección[​](#en-esta-sección "Enlace directo al En esta sección") ## [📄️Ciclo de vida](https://docs.finance.kobana.com.br/es/es/contas-a-receber/ciclo-de-vida.md) [Estados, transiciones y cobro — Borrador → Pendiente → Recibido.](https://docs.finance.kobana.com.br/es/es/contas-a-receber/ciclo-de-vida.md) ## [📄️Cuotas y recurrencia](https://docs.finance.kobana.com.br/es/es/contas-a-receber/parcelas-e-recorrencia.md) [Dividir en cuotas o repetir periódicamente — mismo comportamiento que las cuentas por pagar.](https://docs.finance.kobana.com.br/es/es/contas-a-receber/parcelas-e-recorrencia.md) ## [📄️Cobro por boleto y Pix](https://docs.finance.kobana.com.br/es/es/contas-a-receber/cobranca-kobana.md) [Generar boleto o Pix desde una cuenta por cobrar mediante el Gateway Bancario — requisitos, estados y cancelación.](https://docs.finance.kobana.com.br/es/es/contas-a-receber/cobranca-kobana.md) ## [📄️Importación CSV](https://docs.finance.kobana.com.br/es/es/contas-a-receber/importacao-csv.md) [Importar lotes de cuentas por cobrar vía planilla — columnas aceptadas y formato tolerante.](https://docs.finance.kobana.com.br/es/es/contas-a-receber/importacao-csv.md) ## La lista[​](#la-lista "Enlace directo al La lista") El encabezado abre con tres totales del período — **Por cobrar** (lo que sigue pendiente), **Recibido** y **Total** — y un subtítulo que resume la situación. Es **accionable**: cuando hay atraso, la frase *"Tienes 3 facturas vencidas"* trae el fragmento en rojo como botón, y al hacer clic se aplica el filtro de vencidas. Sin atraso, pasa a ser *"Estás al día con tus cobros."* El botón de **período** está en el encabezado, junto a **"Nueva cuenta por cobrar"**. A la derecha de los totales hay dos píldoras de acción: **"Importar"** (abre el panel de importación abajo, y limpia la búsqueda y los filtros para dejar la lista en un estado limpio) e **"Informe"** (se abre en un diálogo, sin tocar la lista). Importar exige una **empresa específica** seleccionada — en la vista consolidada la píldora avisa en lugar de abrirse. ### Filtros[​](#filtros "Enlace directo al Filtros") * **Búsqueda** — por descripción o número de documento. * **Filtros rápidos** — **Todos**, **Con adjuntos**, **Recibido**, **Conciliado**, **Borradores**. * **Filtros avanzados** — panel con los criterios combinados; un contador muestra cuántos están activos, y un resumen permite limpiarlos o editarlos sin volver a abrir el panel. ### Columnas[​](#columnas "Enlace directo al Columnas") Descripción, Fecha de vencimiento, Categoría, Estado, Monto — más **Empresa**, que solo aparece en la vista consolidada (con una empresa seleccionada, todas las filas tendrían el mismo valor). **Impuesto** y **Notas** existen, pero vienen **ocultas**; actívalas desde el menú de columnas. **"Estado en el banco"** muestra el estado del [cobro](https://docs.finance.kobana.com.br/es/es/contas-a-receber/cobranca-kobana.md) — Registrando, Registrado, Vencido, Pagado, Cancelado — y trae **"-"** para el título que nunca se cobró. nota **"Liquidación" es exclusiva de cuentas por pagar** — aquí la forma de cobro se materializa en la transacción, al dar de baja. Y la columna de estado general se llama solo **"Estado"**, no "Estado general": las cuentas por cobrar no pasan por aprobación. ### Acciones de fila[​](#acciones-de-fila "Enlace directo al Acciones de fila") Nueve acciones, varias condicionadas al estado de la fila: | Acción | Cuándo aparece | | ---------------- | ------------------------------------ | | **Cobrar** | Mientras la baja manual sea posible | | **Conciliar** | Ya cobrada y aún no conciliada | | **Cuotas** | Tipo Cuota | | **Recurrencias** | Tipo Recurrente, dentro de una serie | | **Clasificar** | Siempre | | **Editar** | Siempre | | **Deshacer** | Ya cobrada | | **Cancelar** | Solo pendiente | | **Eliminar** | Siempre | **Editar** y **Eliminar** aparecen siempre, pero con un cobro en pie la operación es limitada: los campos que describen lo que fue cobrado quedan bloqueados y la eliminación se bloquea — ver [Cobro](https://docs.finance.kobana.com.br/es/es/contas-a-receber/cobranca-kobana.md). ### Acciones en lote[​](#acciones-en-lote "Enlace directo al Acciones en lote") Al seleccionar filas, la barra ofrece **"Clasificar seleccionados"**, **"Marcar como cobradas"** y **"Eliminar"**, y muestra en vivo los totales **Por cobrar**, **Recibido** y **Total** **de la selección**. "Clasificar seleccionados" solo existe con una **empresa específica** seleccionada: crear un cliente o una categoría nueva por el nombre necesita una empresa sin ambigüedad. **"Marcar como cobradas"** abre un diálogo con la **Fecha de cobro** (hoy, por defecto). Cada cuenta se cobra por su propio valor, en la **cuenta de destino** prevista en ella; si alguna seleccionada no tiene una, el diálogo pide la cuenta para esas. Intereses y descuentos quedan fuera — para ellos, confirma el cobro de una en una. Lo que la fila no dejaría marcar como cobrado (ya cobrada, cancelada) queda fuera, y el diálogo dice cuántas. ## El formulario[​](#el-formulario "Enlace directo al El formulario") Los campos están agrupados en secciones. **La empresa no es un campo** — viene del selector del encabezado, y la pantalla te devuelve allí si no hay ninguna elegida. ### ESENCIALES[​](#esenciales "Enlace directo al ESENCIALES") | Campo | Observaciones | | ------------------------ | --------------------------------------------------------------------------------------------------------------- | | **Monto (R$)** | Obligatorio. Campo de moneda, con máscara — escribes el importe, no una cadena decimal | | **Fecha de vencimiento** | Obligatorio. Al crear, hay atajos de fecha relativa | | **Cobrar en** | Cuenta financiera esperada para la entrada | | **Descripción** | Obligatorio | | **Cliente** | Obligatorio. Busca entre las personas marcadas como cliente, y permite **registrarlo por el nombre** al guardar | | **Mes de competencia** | Obligatorio. Selector de mes, no de día | ### CLASIFICACIÓN[​](#clasificación "Enlace directo al CLASIFICACIÓN") * **Tipo** (obligatorio) — **Único**, **Recurrente** o **Cuota**. La elección revela el campo siguiente: **Recurrencia** (el período) para recurrente, **Cuotas** (cuántas) para cuota. * **Categoría** — categoría de ingreso; también acepta registrarla por el nombre. Tiene el atajo **Distribución** al lado, para dividir la cuenta entre categorías. Ver [Categorías](https://docs.finance.kobana.com.br/es/es/categorias/.md#distribuci%C3%B3n). * **Centro de clasificación** — con el atajo **Distribución** al lado. Al marcarlo, se abre el diálogo de prorrateo y el campo único da lugar al resumen del reparto. Ver [Centros de clasificación](https://docs.finance.kobana.com.br/es/es/centros-de-classificacao/.md). ### DOCUMENTO Y PAGO[​](#documento-y-pago "Enlace directo al DOCUMENTO Y PAGO") **Número de documento** (factura, boleto…) y **Fecha del documento**. Nada más — pese al nombre, la sección no tiene campos de pago del lado de cobrar. ### Impuestos retenidos · Notas e IR[​](#impuestos-retenidos--notas-e-ir "Enlace directo al Impuestos retenidos · Notas e IR") Dos secciones lado a lado. **Impuestos retenidos** es el editor de tributos retenidos en la fuente, en píldoras. Al lado, la píldora **"Relevante para impuestos"** (activa/desactiva) y **"Agregar nota"**, que abre el campo de texto libre. ### Adjuntos[​](#adjuntos "Enlace directo al Adjuntos") Al **crear**, puedes adjuntar archivos antes de guardar — se vinculan junto con el registro en el momento de guardarlo. ## Confirmar cobro[​](#confirmar-cobro "Enlace directo al Confirmar cobro") El diálogo **"Confirmar cobro"** tiene dos pestañas: * **Cobrar** — indica la **Fecha de cobro** y la **Cuenta de destino**. El sistema marca la cuenta como cobrada y crea la transacción de **entrada**. * **Cobrar y conciliar** — *"Cobre esta cuenta vinculándola a una transacción que ya existe en el extracto — sin duplicados."* Elige la transacción; los candidatos traen la pista **"mismo monto"** / **"monto aproximado"**. En las dos pestañas, la sección **"Ajustes del cobro"** (opcional) acepta **Interés** y **Descuento**. Debajo, el **Monto cobrado** muestra cuánto entra en la cuenta. En **Cobrar**, ese importe, y no el del título, es el que se registra como transacción de entrada; en **Cobrar y conciliar**, es con él que se compara la transacción elegida, y el interés y el descuento quedan registrados en la cuenta. ## Diferencias con cuentas por pagar[​](#diferencias-con-cuentas-por-pagar "Enlace directo al Diferencias con cuentas por pagar") | | Cuentas por cobrar | Cuentas por pagar | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Estado final** | **Recibido** | **Pagado** | | **Puerta de aprobación** | No pasa — no existe aprobación del lado de cobrar | Todo título nuevo espera la [aprobación](https://docs.finance.kobana.com.br/es/es/aprovar-pagamentos/.md) cuando la puerta está activada (el valor por defecto) | | **Tipo de operación y documento** | No hay — el modo de cobro se materializa en la transacción, cuando ocurre la baja | Definen cómo se pagará el título y desbloquean las coordenadas | | **Coordenadas de pago y datos de la guía** | No hay. **"Impuestos retenidos"** existe, pero es otra cosa: lo que la fuente retiene de lo que tienes por cobrar, no una guía a pagar | Código de barras, Pix, datos bancarios, datos de la guía | | **Gateway bancario** | [Generar cobro](https://docs.finance.kobana.com.br/es/es/contas-a-receber/cobranca-kobana.md) — boleto o Pix para que el cliente pague | [Envío al banco](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md) — el pago sale de tu cuenta | | **Comprobante** | No hay: el comprobante es del dinero que sale | Capturado solo en la confirmación — ver [Comprobantes](https://docs.finance.kobana.com.br/es/es/comprovantes/.md) | --- # Ciclo de vida de las cuentas por cobrar ## Estados[​](#estados "Enlace directo al Estados") | Estado | Descripción | | ------------- | -------------------------------------------------------- | | **Borrador** | Creado pero aún no publicado. No aparece en los totales. | | **Pendiente** | A la espera del cobro. | | **Recibido** | Vinculado a una transacción de entrada. | | **Cancelado** | Anulado, sin movimiento financiero. | Además de esos cuatro, la lista muestra dos distintivos que **no son estados**, sino derivados: * **Vencido** — una cuenta **Pendiente** cuyo vencimiento ya pasó. * **Conciliado** — el cobro está ligado a una transacción del extracto. Cuando aparece, sustituye al distintivo "Recibido": es la información más fuerte. ## Transiciones[​](#transiciones "Enlace directo al Transiciones") * **Publicar** (Borrador → Pendiente) — pasa a contar en los totales. * **Cobrar** (Pendiente → Recibido) — registra el cobro y genera la transacción de entrada. * **Cancelar** (Pendiente → Cancelado) — anula la cuenta. ## Crear[​](#crear "Enlace directo al Crear") 1. Entra en `/receivables/new`. 2. Completa los campos obligatorios: **Monto (R$)**, **Fecha de vencimiento**, **Descripción**, **Cliente**, **Mes de competencia** y **Tipo**. 3. Termina con **Agregar cuenta**, **Agregar y crear otro** o **Guardar borrador**. **El cliente no es opcional.** Sin él el formulario no se envía: pide que selecciones o crees un cliente. Puedes elegir un cliente que ya existe **o escribir un nombre nuevo** — en ese caso se registra junto con la cuenta. La **Empresa** también es obligatoria, pero no es un campo del formulario: viene del selector del encabezado. nota **"Publicar" no existe en la pantalla de creación.** Los botones de allí son los tres de arriba. **Publicar** aparece solo en el **detalle**, y solo mientras la cuenta es un borrador. El camino es: guardar borrador → abrir la cuenta → Publicar. ## Cobrar[​](#cobrar "Enlace directo al Cobrar") En la lista o en el detalle, usa **Cobrar**. El diálogo **Confirmar cobro** tiene dos pestañas: * **Cobrar** — indica la fecha y la **Cuenta de destino**. El sistema crea la transacción de entrada. * **Cobrar y conciliar** — liga la cuenta a una transacción que **ya existe** en el extracto, sin generar un duplicado. Las dos pestañas también traen **Ajustes del cobro**, opcionales: **Interés** y **Descuento**. Debajo, el **Monto cobrado** muestra cuánto entra en la cuenta, con el cálculo detallado. ## Deshacer y conciliar[​](#deshacer-y-conciliar "Enlace directo al Deshacer y conciliar") * **Deshacer** — disponible en una cuenta cobrada. Vuelve a pendiente; si la transacción fue generada por el cobro, se elimina con ella. * **Conciliar** — disponible en una cuenta cobrada que aún no fue conciliada. ## Cancelar[​](#cancelar "Enlace directo al Cancelar") **Cancelar solo aparece en cuentas pendientes** — no es una salida disponible desde cualquier estado. Y **no es irreversible**: el propio diálogo dice *"Puede reabrirla más tarde editando el estado."* La cuenta deja de aparecer entre las pendientes; las transacciones automáticas vinculadas se eliminan, y las transacciones importadas del extracto permanecen — solo se deshace el vínculo. nota La acción existe **en la lista**. Si abres el detalle directamente, ese camino no está allí. ## Editar[​](#editar "Enlace directo al Editar") **Una cuenta cobrada no es de solo lectura.** No hay traba por estado: el formulario abre normalmente y es editable en cualquier estado, incluidos **Recibido** y **Cancelado**. La única traba viene de un [cobro en pie](https://docs.finance.kobana.com.br/es/es/contas-a-receber/cobranca-kobana.md), que congela lo que describe lo que fue cobrado. Esta es una **diferencia con cuentas por pagar**: allí existe una traba — parcial — cuando el banco confirma el pago. Las cuentas por cobrar no pasan por el envío al banco, así que no tienen qué trabar. Al editar una cuenta que forma parte de un grupo, el sistema ofrece **"Aplicar a otras cuotas"**, mostrando antes qué es exactamente lo que va a cambiar. Son **todas** las cuotas del grupo — incluidas las **anteriores** a la que estás editando, no solo las siguientes. Quedan fuera únicamente las ya liquidadas y la propia cuota editada. La selección viene marcada por completo; desmarca lo que no debe heredar — o guarda solo en la cuota abierta, con **"Solo esta cuota"** (en una recurrencia, **"Solo esta ocurrencia"**). ## Eliminar[​](#eliminar "Enlace directo al Eliminar") En una cuenta que forma parte de un grupo — **en cuotas o recurrente** —, la eliminación pregunta el alcance: * **Eliminar solo esta** * **Eliminar esta y las futuras** El mismo selector cubre los dos casos: lo que mira es el grupo, no el tipo. En una cuenta suelta, no aparece. nota El selector aparece **en la lista y en el detalle** de la cuenta. --- # Cobro por boleto y Pix Desde una cuenta por cobrar, Finanzas Inteligentes genera un **cobro** mediante el [Gateway Bancario](https://docs.finance.kobana.com.br/es/es/integracoes/kobana.md) — un **boleto** o un **Pix** — para que el cliente pague. Es el espejo del [envío de pagos](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md), en la dirección del dinero que entra. La acción es **"Generar cobro"**, en la pantalla de detalle del título. ## Requisitos[​](#requisitos "Enlace directo al Requisitos") | Exigencia | Boleto | Pix | | ---------------------------------------------------------------------------------- | ------ | --- | | Gateway Bancario conectado | ✅ | ✅ | | Cliente vinculado al título | ✅ | ✅ | | CPF/CNPJ del cliente | ✅ | ✅ | | Fecha de vencimiento en el título | ✅ | ✅ | | **Dirección completa del cliente** (código postal, calle, barrio, ciudad y estado) | ✅ | — | | **Convenio de boleto** registrado en la cuenta del gateway | ✅ | — | | **Cuenta Pix de cobro** registrada en la cuenta del gateway | — | ✅ | nota **Los dos caminos no son el mismo cobro con otro botón.** Cambian lo que recibe el cliente y lo que hay que tener registrado antes — por eso la elección se hace con **dos tarjetas**, cada una indicando su requisito. Si algo falta, el sistema **dice exactamente qué**, en vez de dar un error genérico: *"El cliente necesita CPF o CNPJ"*, *"El boleto exige la dirección completa del cliente"*, *"No hay ninguna cuenta Pix de cobro registrada"*, y así. ## Flujo[​](#flujo "Enlace directo al Flujo") aviso **Un cobro recién generado todavía no puede entregarse al cliente.** El registro en la institución financiera es asíncrono: mientras el estado sea **Registrando**, el boleto aún no existe en el banco y el Pix aún no tiene código QR. Espera a que llegue a **Registrado**. ## Estados del cobro[​](#estados-del-cobro "Enlace directo al Estados del cobro") Aparecen en la tarjeta del cobro y en la columna **Estado en el banco** del listado de cuentas por cobrar. | Estado | Qué significa | | ------------------------------------------------------------------------ | -------------------------------------------------- | | **Registrando** | creado; la institución aún no confirmó el registro | | **Registrado** | registrado — puede entregarse al cliente | | **Vencido** | pasó el vencimiento sin pago | | **Pagado** | el cliente pagó | | **Registro rechazado** · **Error en el registro** · **Error al generar** | la institución no lo aceptó; el cobro no vale | | **Cancelado** | deshecho | El botón **"Actualizar"** consulta el estado actual bajo demanda, sin esperar al seguimiento automático. ## Baja automática[​](#baja-automática "Enlace directo al Baja automática") Cuando el cobro llega a **Pagado**, el título se liquida por sí solo: pasa a **Recibido**, con la fecha de hoy, y se crea la transacción de entrada. aviso **Sin "Cobrar en" definido, no hay baja automática.** Es ese campo el que dice en qué cuenta entró el dinero — sin esa información el sistema no lo adivina, y la baja te queda a ti para hacerla a mano. El cobro sigue marcado como Pagado. ## Mientras el cobro está en pie, el título no cambia[​](#mientras-el-cobro-está-en-pie-el-título-no-cambia "Enlace directo al Mientras el cobro está en pie, el título no cambia") Con un cobro **Registrando**, **Registrado**, **Vencido** o **Pagado**, alguien allá afuera puede pagarlo — o ya lo pagó. Por eso el título queda bloqueado en todo lo que describe el cobro: **importe, vencimiento, cliente y similares no pueden alterarse**, y el título **no puede eliminarse**. info **Editar aquí no volvería a emitir nada.** El boleto que el cliente tiene en la mano seguiría siendo el mismo — el sistema es el que pasaría a mentir sobre lo que se cobró. Para corregirlo, **cancela primero el cobro**. Los cobros **rechazados** o **cancelados** no bloquean nada: no existen para nadie. ## Cancelar el cobro[​](#cancelar-el-cobro "Enlace directo al Cancelar el cobro") **"Cancelar cobro"** deshace el cobro en el gateway. Los dos caminos se comportan distinto, y la diferencia le importa a tu cliente: * **Boleto** — deja de valer en cuanto el gateway lo confirme, y el cliente ya no puede pagarlo. * **Pix** — la cancelación la confirma la **institución financiera**. **Hasta que llegue esa confirmación, el cliente todavía puede pagar.** Por eso la respuesta distingue **"Cobro cancelado"** de **"Cancelación solicitada — esperando la confirmación de la institución"**. En el segundo caso, sigue el estado hasta que diga **Cancelado**. Un cobro **pagado**, **ya cancelado** o **con error** no tiene nada que cancelar. ## Relacionado[​](#relacionado "Enlace directo al Relacionado") * [Cuentas por cobrar — ciclo de vida](https://docs.finance.kobana.com.br/es/es/contas-a-receber/ciclo-de-vida.md) — los estados del título en sí * [Integración Gateway Bancario](https://docs.finance.kobana.com.br/es/es/integracoes/kobana.md) — conectar, sincronizar y hacer seguimiento * [Personas](https://docs.finance.kobana.com.br/es/es/pessoas/.md) — donde están el documento y la dirección que el cobro exige --- # Importación CSV — Cuentas por cobrar Importa lotes de cuentas por cobrar vía archivo CSV. ## Dónde está[​](#dónde-está "Enlace directo al Dónde está") **No existe "Importación" en el menú**, ni una pantalla de importación. El camino es: **Cuentas por Cobrar** → píldora **Importar**, en la propia lista. Sin ninguna cuenta registrada todavía, la lista muestra el estado vacío con el botón **Importar** junto a **Nueva cuenta por cobrar**, que abre el mismo panel. Hace falta tener una **empresa específica** seleccionada en el encabezado. En "todas las empresas", el panel solo avisa: *"Selecciona una empresa específica para importar cuentas por cobrar."* El botón **Descargar plantilla** entrega un CSV de ejemplo con el encabezado correcto — es el punto de partida más seguro, porque ya viene en la codificación adecuada. ## Columnas del CSV[​](#columnas-del-csv "Enlace directo al Columnas del CSV") | Columna | Obligatorio | Descripción | | ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `description` | ✅ | Descripción de la cuenta por cobrar | | `amount` | ✅ | Importe en reales (ej.: `299,00`) | | `due_date` | ✅ | Fecha de vencimiento (`dd/MM/yyyy`) | | `competence_date` | — | Fecha de competencia (`dd/MM/yyyy`) | | `document` | — | Identificador del documento (el campo **Documento** del formulario) | | `document_date` | — | Fecha de emisión (`dd/MM/yyyy`) | | `document_number` | — | Número de la factura (el campo **Número de documento**) | | `person_name` | — | Nombre del cliente (si todavía no existe, la vista previa pregunta si crearlo) | | `category_name` | — | Nombre de la categoría (si todavía no existe, la vista previa pregunta si crearlo) | | `cost_center_name` | — | Nombre del centro de clasificación (si todavía no existe, la vista previa pregunta si crearlo) | | `payment_method` | — | Método: `pix`, `bank_billet`, `ted`, `credit_card`, `debit_card`, `cash`, `check`, `direct_debit`, `other` o `none` (los alias en portugués — `boleto`, `dinheiro`, … — también valen) — aceptado y guardado en el título, aunque el formulario de cuentas por cobrar no expone el campo | | `notes` | — | Observaciones | | `ir_relevant` | — | `true` o `false` | Los nombres de arriba son los canónicos, pero **todo encabezado acepta el equivalente en portugués** — `descricao`, `valor`, `vencimento`, `cliente`, `categoria`, `observacao` y así sucesivamente. Las planillas de otros sistemas también sirven para cliente, centro de clasificación y categoría: `contraparte` vale como `person_name`; `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` valen como `cost_center_name`, y `plano_de_contas`, `categoria_financeira`, `category` como `category_name`. Si el espacio tiene un clasificador con el mismo nombre que una de estas columnas (ej.: *Centro de Resultado*), la columna va al clasificador. Si la planilla tiene más de una columna para el mismo campo (p. ej.: `Centro de Custo` y `Centro de Receita`), cada línea usa la primera que esté completa. Además de esos nombres, un encabezado con la palabra **centro** se lee como centro de clasificación; uno con **categoria** o **plano de contas**, como categoría (por ejemplo, `Centro de Lucro`, `Categoria DRE`); y uno con **pessoa**, **cliente** o **fornecedor** acompañada solo de palabras de nombre, como persona (por ejemplo, `Nome do Fornecedor`, `Cliente / Fornecedor` — pero no `CNPJ do Fornecedor`). Las columnas que el sistema no conoce se **ignoran en silencio**. El archivo de cuentas por cobrar acepta las mismas columnas que el de pagar, excepto las de pago (código de barras, Pix, datos bancarios, tributo, programación) — esas existen solo del lado de pagar, que es quien envía dinero al banco. ## Formato[​](#formato "Enlace directo al Formato") El parser es más tolerante de lo que parece. No necesitas normalizar el archivo antes: * **Encabezado** — mayúsculas, acentos y espacios no importan: `Descrição`, `DESCRICAO` y `descricao` son la misma columna. * **Separador** — `,` o `;`, detectado **por la línea de encabezado**. En caso de empate, `;`. * **Fechas** — `31/12/2026`, `31-12-2026` o `2026-12-31`. * **Importes** — `1234.56`, `1.234,56`, `1234,56`, con o sin `R$`. El importe tiene que ser **mayor que cero**. * **`ir_relevant`** — `true`/`false`, `sim`/`nao`, `yes`/`no`, `1`/`0`, `s`/`y`/`n`. Sin acento, en mayúscula o minúscula. Vacío deja el campo en blanco. aviso **La codificación tiene que ser UTF-8, y es aquí donde tropieza la mayoría de los archivos.** Excel en portugués guarda el CSV en Windows-1252 por defecto, y el sistema lo rechaza con un mensaje que permanece en portugués: *"Arquivo não está em UTF-8. Salve novamente em UTF-8 e tente novamente."* ("El archivo no está en UTF-8. Guárdalo de nuevo en UTF-8 e inténtalo otra vez.") En Excel, usa **Guardar como → CSV UTF-8**; o parte de la plantilla descargada. Otros rechazos del archivo entero: una extensión distinta de `.csv`, un tamaño superior a **5 MB**, un archivo vacío, y **columna obligatoria ausente** — *"Colunas obrigatórias ausentes: amount"* ("Faltan columnas obligatorias: amount"). En esos casos no hay vista previa: el problema es del archivo, no de una línea. ## Importar[​](#importar "Enlace directo al Importar") 1. Sube el archivo. El sistema lo lee y muestra la vista previa. 2. **Las filas válidas ya vienen marcadas.** Haz clic en una fila para desmarcarla. 3. Haz clic en **Importar N líneas**. ### Filas con error[​](#filas-con-error "Enlace directo al Filas con error") Las filas inválidas aparecen en la vista previa con un marcador rojo, **y no se pueden seleccionar ni editar allí**. No hay corrección dentro del sistema. La propia pantalla dice el camino: *"Desmarca las filas con errores o corrígelas en el archivo y vuelve a subirlo."* El número en **Fila N** es el número de la línea **en el archivo**, contando el encabezado — la primera línea de datos es la 2. ### La grabación corre en segundo plano[​](#la-grabación-corre-en-segundo-plano "Enlace directo al La grabación corre en segundo plano") Al confirmar, recibes *"Importación iniciada en segundo plano"* y un diálogo de progreso. **Puedes cerrar el diálogo** — la importación continúa, y el progreso queda visible en la esquina inferior derecha. ### Vínculos[​](#vínculos "Enlace directo al Vínculos") **Los clientes, categorías y centros de clasificación aparecen en la vista previa**, cada uno con lo que hará la importación: los que ya existen se vinculan; los nuevos vienen marcados para **crear** (o para **dejar en blanco**, si no tienes permiso para crearlos); un nombre que solo cambia en acentos, mayúsculas o espacios respecto de uno existente viene marcado para **usar el existente**; y un centro de clasificación que solo existe del otro lado (ej.: uno del tipo Costo en una cuenta por cobrar) viene marcado para dejar en blanco. El cliente se busca solo por el nombre: una persona ya registrada como proveedor también sirve, y pasa a ser cliente también. Las grafías del mismo nombre que solo cambian acento, mayúscula o espacio (p. ej.: *Água e Luz* y *agua e luz*) cuentan como un solo nombre. Puedes cambiar cualquier elección antes de importar. Las [reglas automáticas](https://docs.finance.kobana.com.br/es/es/regras-automaticas/.md) se aplican a los registros importados. ## Historial[​](#historial "Enlace directo al Historial") Debajo del panel, la sección **Historial** lista las importaciones con fecha, archivo, estado (**En cola**, **En progreso**, **Completado**, **Fallido**, **Cancelado**), cuántas filas entraron del total y quién la pidió. ## Aprobación[​](#aprobación "Enlace directo al Aprobación") nota **Las cuentas por cobrar importadas no pasan por aprobación.** La puerta de aprobación de pagos existe solo del lado de **pagar**, porque es allí donde sale dinero. Un cobro importado entra directamente en la lista normal y en los totales. --- # Cuotas y recurrencia — Cuentas por cobrar El comportamiento es el mismo que en [Cuentas por pagar](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/parcelas-e-recorrencia.md): mismos tipos, mismos períodos, mismo agrupamiento. ## Tipos[​](#tipos "Enlace directo al Tipos") El campo **Tipo** ofrece tres opciones: | Tipo | Descripción | | -------------- | --------------------------------------------- | | **Único** | Cuenta única | | **Cuota** | N cuotas con vencimientos secuenciales | | **Recurrente** | Generada automáticamente en un intervalo fijo | ## Cuotas[​](#cuotas "Enlace directo al Cuotas") Informa el monto **de cada cuota** y el número de **Cuotas**, de **2** a **120**. El sistema genera N cuentas unidas por el mismo grupo, con **vencimientos mensuales a partir del primer vencimiento**, y **cada cuota se cobra individualmente**. Una vez creadas, vencimiento y monto se ajustan una por una. En una cuenta que ya forma parte de una serie, **Tipo** y **Cuotas** quedan bloqueados. Una cuenta **Único** ya guardada puede pasar a **Recurrente**, pero no a **Cuota**. ## Recurrencia[​](#recurrencia "Enlace directo al Recurrencia") El campo **Recurrencia** aparece cuando el tipo es **Recurrente** y es obligatorio. Son **cinco** períodos: | Opción | Intervalo | | -------------------- | --------- | | **Cada semana** | 7 días | | **Cada dos semanas** | 14 días | | **Cada mes** | 1 mes | | **Cada 3 meses** | 3 meses | | **Cada año** | 12 meses | tip **No existen períodos bimestral ni semestral.** Si necesitas un intervalo fuera de esa lista, el camino son las cuotas: nacen mensuales, y ajustas el vencimiento de cada una después. Las ocurrencias se cuentan desde la primera: cambiar el vencimiento de una no toca las siguientes, que siguen en el día original de la serie. Cada ocurrencia registrada copia la última — monto, categoría, impuestos y retenciones, observaciones. En la lista, la recurrencia aparece abreviada junto al vencimiento — *Semanal*, *Quincenal*, *Mensual*, *Trimestral*, *Anual*. Es lo mismo, escrito corto para que entre en la columna. ## Eliminar[​](#eliminar "Enlace directo al Eliminar") Al eliminar una cuenta que pertenece a un grupo, se pregunta el alcance: * **Eliminar solo esta** * **Eliminar esta y las futuras** — *"Las ocurrencias ya cobradas o conciliadas se mantienen."* En una serie importada (Fintera, Nibo), **Eliminar esta y las futuras** se rechaza: *"Esta serie viene de una integración; elimínala en el origen"*. **El alcance no es exclusivo de las recurrencias.** El selector mira el **grupo**, así que **cuotas y recurrentes** se comportan igual. En una cuenta suelta no aparece. El selector está **en la lista**. Al eliminar desde el detalle, se borra siempre solo esa cuenta. --- # Cuentas financieras Las cuentas financieras (`/financial-accounts`) representan las cuentas bancarias y de efectivo de las empresas del espacio de trabajo. El saldo de cada cuenta se calcula a partir de las transacciones registradas. Dos operaciones viven **dentro** de la cuenta, y están documentadas aparte: ## [📄️Extractos bancarios](https://docs.finance.kobana.com.br/es/es/extratos-bancarios/.md) [Importar OFX y QIF en la cuenta financiera — deduplicación, historial y deshacer.](https://docs.finance.kobana.com.br/es/es/extratos-bancarios/.md) ## [📄️Transferencias](https://docs.finance.kobana.com.br/es/es/transferencias/.md) [Mover dinero entre cuentas del espacio de trabajo — dos transacciones espejadas.](https://docs.finance.kobana.com.br/es/es/transferencias/.md) ![Lista de cuentas financieras](/es/assets/images/07-accounts-1e379ebb52cba5bfeaf3e91e378aa544.png) ![Detalle de cuenta financiera](/es/assets/images/08-account-detail-c614eeade50b5d7cfe108dfd47acb7e7.png) ## Tipos de cuenta[​](#tipos-de-cuenta "Enlace directo al Tipos de cuenta") **Cuenta corriente** · **Ahorros** · **Efectivo** · **Inversión** · **Crédito** El tipo elegido cambia el formulario: **Efectivo no tiene datos bancarios** — la sección entera desaparece, y lo que ya estaba completado se borra. **Una cuenta de Crédito puede convertirse en tarjeta.** En [Tarjetas](https://docs.finance.kobana.com.br/es/es/cartoes/.md) pasa a tener resúmenes, límite y compras en cuotas — y cada tarjeta nueva crea aquí su propia cuenta de Crédito. En el selector **Cuenta** del encabezado, la cuenta de una tarjeta lleva la etiqueta **Tarjeta**; su saldo es la deuda de la tarjeta y queda fuera de la caja (ver [Cerrar, revisar y pagar](https://docs.finance.kobana.com.br/es/es/cartoes/fechar-conferir-pagar.md#en-el-flujo-de-caja)). ## Campos[​](#campos "Enlace directo al Campos") ### Esencial[​](#esencial "Enlace directo al Esencial") | Campo | Obligatorio | Observación | | ----------------- | ----------- | -------------------------------------- | | **Nombre** | Sí | Ej.: "Cuenta corriente principal" | | **Tipo** | Sí | — | | **Saldo inicial** | Sí | **Solo en la creación** | | **Empresa** | **No** | Vincularla permite filtrar por empresa | ### Banco — no aparece en cuentas de tipo Efectivo[​](#banco--no-aparece-en-cuentas-de-tipo-efectivo "Enlace directo al Banco — no aparece en cuentas de tipo Efectivo") | Campo | Obligatorio | | -------------------------- | ----------- | | **Banco** | **Sí** | | **Agencia** | **Sí** | | **Dígito** (de la agencia) | No | | **Número de cuenta** | **Sí** | | **Dígito** (de la cuenta) | No | ### Estado[​](#estado "Enlace directo al Estado") Una sola opción: **Deshabilitar conciliación**, para cuentas que no deben entrar en la conciliación (una caja chica manual, por ejemplo). aviso **Atención a lo que es obligatorio, que suele leerse al revés:** la **Empresa es opcional** — una cuenta puede existir sin empresa. En cambio el **Banco es obligatorio** en Cuenta corriente, Ahorros, Inversión y Crédito; la agencia y el número de cuenta, en Cuenta corriente, Ahorros e Inversión — una cuenta de **Crédito** no tiene agencia ni número. Solo en **Efectivo** no existe ninguno de ellos. ## Saldo[​](#saldo "Enlace directo al Saldo") El **Saldo inicial** se informa **solo en la creación**. Después de eso el campo desaparece del formulario, que pasa a mostrar el aviso *"El saldo se actualiza automáticamente con las transacciones."* Para corregir el saldo de una cuenta que ya existe, usa **Ajustar saldo** — haz clic sobre el valor del saldo, en el detalle de la cuenta. Informas el saldo real y la fecha, y el sistema crea **una transacción de ajuste** que iguala la cuenta al valor informado. nota **Un ajuste no se puede editar después — solo eliminar.** Para corregir un ajuste equivocado, registra uno nuevo. ## Listado[​](#listado "Enlace directo al Listado") Columnas: **Nombre** (con el banco en la línea de abajo), **Tipo**, **Empresa** (solo en el modo "Consolidado"), **Sucursal**, **Cuenta**, **Transacciones** y **Saldo**. La flecha al final lleva a las transacciones de la cuenta. Filtros: búsqueda **por nombre**, pestañas por tipo (**Todas** · **Cuenta corriente** · **Ahorros** · **Efectivo** · **Inversión** · **Crédito**) y el filtro **Estado** (**Activo** / **Archivado**). El encabezado tiene **Nueva cuenta** y **Nueva transferencia**. ## Archivar[​](#archivar "Enlace directo al Archivar") Una cuenta archivada **sigue en el listado**, con el distintivo **Archivado**. El filtro **Estado** nace **sin selección** — es decir, ves las activas y las archivadas juntas hasta que elijas. Archivar y desarchivar son acciones del menú de la fila (**Archivar** / **Desarchivar**), no un campo del formulario. El menú también trae **Editar** y **Eliminar**. ## Detalle de la cuenta[​](#detalle-de-la-cuenta "Enlace directo al Detalle de la cuenta") Además de las transacciones, el detalle trae tres acciones: **Extractos bancarios**, **Importar** e **Informe**. Aparecen cuando la cuenta ya tiene transacciones. **Extractos bancarios** e **Importar** exigen una **empresa específica** seleccionada en el encabezado — en "Consolidado" el panel solo avisa de eso. ## Gerentes[​](#gerentes "Enlace directo al Gerentes") La sección **Gerentes**, en el detalle de la cuenta, guarda los gerentes del banco que atienden la cuenta — **con historial**. Puede haber más de un gerente activo al mismo tiempo. * **Agregar gerente** tiene dos pestañas, con la fecha de **Inicio** en común. En **Gerente registrado** eliges quién atiende la cuenta entre las personas de la empresa de la cuenta con el rol **Gerente de cuenta**. En **Nuevo gerente** completas nombre, correo, teléfono y observaciones, y **Registrar y agregar** crea a la persona ya como gerente — también pasa a existir en [Personas](https://docs.finance.kobana.com.br/es/es/pessoas/.md), donde completas el resto del registro. * Cada gerente activo aparece en una tarjeta con sus teléfonos y correos y los atajos **Conversar por WhatsApp** (solo celular), **Llamar** y **Enviar correo**. * **Finalizar** registra la fecha de **Salida**: el gerente deja los activos y pasa al **Historial de gerentes**, plegado debajo de las tarjetas. * **Editar fechas** corrige inicio y salida. **Eliminar** borra el registro — úsalo solo para deshacer un registro hecho por error. nota **El gerente es una persona de la empresa de la cuenta.** Una cuenta sin empresa no tiene gerentes — la sección pide vincular la cuenta a una empresa. Si el mismo gerente atiende dos empresas, se registra en cada una. Eliminar a la persona finaliza sus períodos activos en la fecha del día; siguen en el historial. ## Accesos[​](#accesos "Enlace directo al Accesos") La sección **Accesos**, también en el detalle de la cuenta, registra quién del equipo opera la cuenta en el banco y con qué nivel — **Propietario**, **Administrador**, **Gestor**, **Visualizador** o **Sin acceso**. **Sin acceso** es un nivel registrado a propósito, distinto de que la persona no esté en la lista. * **Agregar acceso** elige una persona de la empresa de la cuenta (o registra una nueva por el nombre) y el **Nivel de acceso**. La persona recibe el rol **Equipo**. * Cada persona tiene **un** nivel por cuenta — para cambiarlo, cambia el nivel directamente en la lista. * **Quitar acceso** saca a la persona de la lista. Los accesos **no tienen historial**: lo que se quita no se guarda. Como con los gerentes, solo personas de la empresa de la cuenta, y una cuenta sin empresa no tiene accesos. ## Integración con el Gateway Bancario[​](#integración-con-el-gateway-bancario "Enlace directo al Integración con el Gateway Bancario") Las cuentas **corrientes** y de **ahorros** pueden sincronizarse con el Gateway Bancario, habilitando la sincronización de extractos bancarios y el envío de pagos. Las cuentas de tipo Efectivo, Inversión y Crédito no son compatibles y quedan fuera. Hay dos caminos para el vínculo, y se encuentran en el mismo lugar: * **De allá para acá** — el botón **Sincronizar cuentas bancarias**, en la pantalla de integración, importa las cuentas registradas en el gateway y vincula solo las que ya existen aquí. Ver [Gateway Bancario](https://docs.finance.kobana.com.br/es/es/integracoes/kobana.md). * **De aquí para allá** — la cuenta que solo existe aquí gana el botón **Agregar al gateway bancario** en su propia página. Tú eliges cuál enviar; el envío crea la cuenta en el gateway con el banco, la sucursal y el número registrados aquí, y pide una confirmación antes. nota **Nada se duplica.** El encuentro es por **banco, número de sucursal y número de cuenta**. Si la cuenta que envías ya existe en el gateway con esas mismas coordenadas, solo se **vincula**, no se crea de nuevo. Los **dígitos verificadores quedan fuera de la comparación**: salen del propio número, así que un lado tenerlos y el otro no — o registrarlos pegados, como `5555-0` — no la convierte en otra cuenta. De la sucursal valen los **cuatro primeros dígitos**, así que `1234-5`, `12345` y `1234` son la misma sucursal. La misma regla vale para la [importación de Fintera](https://docs.finance.kobana.com.br/es/es/integracoes/fintera.md): una cuenta que ya existe aquí (creada a mano o traída del gateway) se vincula a la cuenta de Fintera, no se importa de nuevo. Y si el propio gateway tiene dos cuentas con el mismo banco, sucursal y número, solo se trae la primera — la otra aparece en la vista previa como **Duplicada en el gateway**. Una cuenta ya vinculada muestra un distintivo **Kobana** en el listado y en su propia página, y el botón de enviar desaparece — no hay adónde mandarla. --- # Dashboard **Dashboard** (`/dashboard`) es la pantalla de inicio de Finanzas Inteligentes. Consolida la salud financiera de la organización en dos pestañas: **Desempeño** (lo que ya ocurrió) y **Flujo de caja** (la proyección de lo que está por venir). ![Dashboard — panel general](/es/assets/images/00-dashboard-f815aae0c12e278a85cd7bda0af85964.png) ## Filtros[​](#filtros "Enlace directo al Filtros") * **Período** — selector de rango de fechas, en el encabezado. Cada pestaña abre con su preajuste predeterminado. * **Empresa** — viene del selector superior, o consolida todas las empresas del espacio de trabajo. * **Granularidad** — **Día**, **Semana**, **Mes** o **Año**, en la parte superior de la pestaña. Cada pestaña tiene la suya. * **Cuenta** — **solo en la pestaña Flujo de caja**, para proyectar sobre una cuenta específica. ## Pestaña Desempeño[​](#pestaña-desempeño "Enlace directo al Pestaña Desempeño") Mira hacia atrás: los números del período ya efectuado. ### Tarjetas de métricas[​](#tarjetas-de-métricas "Enlace directo al Tarjetas de métricas") Cuatro indicadores, cada uno con un **minigráfico** de tendencia: | Métrica | Descripción | Variación % | | -------------------------- | --------------------------------------- | ----------- | | **Saldo total** | Saldo sumado de las cuentas financieras | — | | **Ingresos en el período** | Entradas realizadas | **Sí** | | **Gastos en el período** | Salidas realizadas | **Sí** | | **Margen operativo** | (ingresos − gastos) / ingresos | — | **Solo Ingresos y Gastos se comparan con el período anterior.** El distintivo de variación porcentual existe en esos dos. Saldo total y Margen operativo muestran el minigráfico, pero no traen distintivo de variación — no hay con qué compararlos de forma honesta. ### Flujo realizado[​](#flujo-realizado "Enlace directo al Flujo realizado") Gráfico del **saldo** a lo largo del período, con el histograma de entradas y salidas ya efectuadas debajo y las pestañas **Día**, **Semana**, **Mes** y **Año** para elegir el tamaño del bloque. El pico y el saldo mínimo quedan marcados en el propio punto, y al pasar el mouse se ven los mayores movimientos de ese punto. **Las opciones que no tienen sentido para el período quedan deshabilitadas.** Una granularidad que produciría una sola barra no se ofrece: en "Este mes", **Mes** sale (se volvería un único bloque) y la vista abre en **Semana**. En "Hoy", queda **Día**. Es la misma regla de la pestaña Flujo de caja. ### Principales gastos[​](#principales-gastos "Enlace directo al Principales gastos") Las **4 mayores categorías de gasto** del período, con acceso directo al listado de gastos. ### Análisis a corto plazo[​](#análisis-a-corto-plazo "Enlace directo al Análisis a corto plazo") Compara **Esta semana** con los **Últimos 30 días**, y muestra el valor promedio por transacción en el período de 30 días. aviso **Este panel ignora el selector de período.** Las ventanas son fijas — esta semana y los últimos 30 días corridos — y no cambian cuando cambias el período en el encabezado. Es la fuente de confusión más común de la pantalla: sus números no "cuadran" con las tarjetas a propósito, porque miden otra cosa. ## Pestaña Flujo de caja[​](#pestaña-flujo-de-caja "Enlace directo al Pestaña Flujo de caja") Mira hacia adelante. La antigua ruta `/cash-flow` **redirige** hacia aquí (`/dashboard?tab=cash-flow`). Además de la granularidad, esta pestaña tiene el selector de **Cuenta**, para proyectar sobre una cuenta específica. ### Las cuatro tarjetas[​](#las-cuatro-tarjetas "Enlace directo al Las cuatro tarjetas") | Tarjeta | Qué trae | | ------------------------ | ----------------------------------------------------------------------------------------------------------- | | **Saldo actual** | Saldo de hoy, con el conteo de cuentas | | **Entradas proyectadas** | Lo que hay por cobrar en la ventana | | **Salidas proyectadas** | Lo que hay por pagar en la ventana | | **Saldo proyectado** | El saldo al final del período, con el **menor saldo proyectado de aquí en adelante** y la variación vs. hoy | **En una ventana sin futuro, los títulos cambian.** Mirando solo hacia el pasado, los tres últimos se vuelven **"Entradas realizadas"**, **"Salidas realizadas"** y **"Saldo final"** — dejan de prometer proyección cuando no hay nada que proyectar. El menor saldo es una alerta sobre lo que **viene por delante**: recorre solo los períodos futuros, porque un valle que ya pasó no avisa de nada. Y solo aparece cuando queda **por debajo** del saldo del final del período — si el peor momento es el último, repetir el número no diría nada. nota **"Saldo proyectado" no es "saldo de fin de mes".** Es el saldo de cierre del **último período del rango elegido**. En un rango de 90 días, es el saldo al final de los 90 días — no del mes en curso. ### Qué entra en la proyección[​](#qué-entra-en-la-proyección "Enlace directo al Qué entra en la proyección") Cuatro fuentes sumadas: 1. **Cuentas pendientes** — cuentas por pagar y por cobrar, por la **fecha de vencimiento**. Las cuentas por pagar entran solo después de aprobadas, cuando la aprobación está activada (el valor por defecto). 2. **Transacciones previstas** — las marcadas como provisionales, por la fecha. 3. **Ocurrencias virtuales de recurrencias** — este es el punto sutil. Una recurrencia queda registrada solo hasta el plazo de aprovisionamiento (12 meses por defecto; ver [Cuotas y recurrencia](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/parcelas-e-recorrencia.md)). En una proyección que va más allá, el sistema continúa la serie **en la lectura**, generando las ocurrencias que aún no existen como registro. No se graban — existen solo en la proyección. 4. **Resúmenes de tarjeta** — el resumen abierto y los futuros de cada tarjeta de crédito, por el total previsto, en el vencimiento, en la cuenta que paga la tarjeta. Cerrado, el resumen entra como cuenta por pagar. Las compras con tarjeta no entran una por una: la tarjeta no es caja (ver [Tarjetas](https://docs.finance.kobana.com.br/es/es/cartoes/fechar-conferir-pagar.md#en-el-flujo-de-caja)). nota **Lo vencido no desaparece: se empuja hacia hoy.** Una cuenta con vencimiento la semana pasada y aún pendiente no se queda en el pasado ni desaparece — entra en el grupo de **hoy**, porque sigue siendo dinero que va a salir o a entrar. El detalle lo marca: *"Incluye R$ 1.200,00 en cuentas vencidas"*. ### Vencidas y Por vencer[​](#vencidas-y-por-vencer "Enlace directo al Vencidas y Por vencer") **Dos** paneles, no uno: **"Vencidas"** y **"Por vencer (30 días)"**. Cada uno separa lo que es por pagar y lo que es por cobrar, y dice hace cuántos días venció o en cuántos vence. ### Gráfico, detalle y escenarios[​](#gráfico-detalle-y-escenarios "Enlace directo al Gráfico, detalle y escenarios") * **Gráfico** del saldo por período: la línea es el saldo (sólida en lo realizado, discontinua a partir de **Hoy**), con el pico y el saldo mínimo marcados en el punto y la línea del cero destacada; debajo, el histograma de Entradas y Salidas del mismo período. Al pasar el mouse se ven entradas, salidas, saldo y los mayores movimientos de ese punto. Encima quedan las pestañas **Resumen** y **Por categoría**, que **comandan el gráfico y la tabla al mismo tiempo** — no son de la tabla, aunque sea allí donde más se nota la diferencia. En **Por categoría** el gráfico cambia la curva del saldo por una línea por categoría, con las **entradas por encima del cero y las salidas por debajo**: los dos lados aparecen juntos, y la línea del cero es la línea de flotación. La leyenda de abajo separa las categorías de cada lado. * **"Detalle por período"** — tabla con Saldo inicial, Entradas, Salidas, Saldo del período y Saldo final. Esas cinco filas son la pestaña **Resumen**: en **Por categoría** las filas de saldo **salen**, y quedan solo Entradas y Salidas, abiertas por categoría — es una lectura de flujo, no de saldo. Al hacer clic en un período se abren las transacciones que lo componen, marcando lo que es **Realizado**, **Proyectado**, **Vencido** y lo que vino de **recurrencia**. * **Escenario** — simulación what-if: **Aplazar** o **Quitar** cuentas de la proyección para ver el efecto en el **Saldo proyectado** y en el **Peor saldo proyectado**, sin alterar nada de verdad. **Limpiar** lo deshace. --- # MCP de la Documentación Esta documentación tiene **su propio servidor MCP**. Con él, un asistente de IA (Claude, ChatGPT, Cursor, VS Code, Claude Code) busca y lee las páginas de este sitio sin que tengas que copiar y pegar nada. Así, las respuestas sobre Finanzas Inteligentes salen del contenido publicado, en el idioma que elijas. ``` https://docs.finance.kobana.com.br/mcp ``` > **No es el MCP del producto:** El MCP de la Documentación solo **lee la documentación**. No accede a tu cuenta, no ve cuentas por pagar, cuentas por cobrar ni transacciones y no cambia nada. Para que un agente opere Finanzas Inteligentes, usa el **MCP del producto** (`mcp.finance.kobana.com.br`), que pide inicio de sesión y respeta tus permisos. Consulta [MCP › Clientes](https://docs.finance.kobana.com.br/es/es/mcp/overview/clients.md). ## Cómo funciona[​](#cómo-funciona "Enlace directo al Cómo funciona") * **Público y de solo lectura:** no pide inicio de sesión ni token. Expone el mismo contenido que cualquier persona ve en el sitio. * **Siempre actualizado:** lee la versión publicada de la documentación. Una página nueva o modificada aparece en el MCP en cuanto se publica el sitio. * **Tres idiomas:** portugués (`pt`), inglés (`en`) y español (`es`). Si no se indica idioma, usa el portugués. * **Transporte:** Streamable HTTP, sin sesión. Funciona con cualquier cliente MCP que se conecte a un servidor remoto por URL. ## Tools[​](#tools "Enlace directo al Tools") | Tool | Qué hace | Parámetros | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `search_docs` | Busca páginas por palabras clave en el título, la ruta y el resumen, sin distinguir acentos ni mayúsculas. Devuelve las mejores páginas con ruta y resumen | `query` (obligatorio), `locale`, `limit` (1 a 25, por defecto 8) | | `get_page` | Devuelve el contenido completo de una página en Markdown | `path`: la ruta que devolvió `search_docs` o `list_pages` (por ejemplo, `/es/conciliacao`) o la URL completa | | `list_pages` | Lista todas las páginas, con ruta y resumen | `locale` | | `search_openapi` | Busca operaciones (endpoints) de la API REST por palabras clave en el resumen, la ruta y la descripción. Devuelve las mejores operaciones con método, ruta y `operationId` | `query` (obligatorio), `version`, `locale`, `limit` (1 a 25, por defecto 8) | | `get_operation` | Devuelve una operación de la API completa: descripción, parámetros, cuerpo de la solicitud y respuestas con sus schemas | `operation_id`, o `method` y `path`; `version`, `locale` | El asistente decide solo cuándo llamar a cada tool. Normalmente busca con `search_docs` y lee con `get_page` las páginas que le interesan. ## Cómo instalarlo[​](#cómo-instalarlo "Enlace directo al Cómo instalarlo") La forma más rápida es el menú **Copiar página**, arriba de cada página de este sitio. En **MCP de la Documentación** encontrarás: * **Conectar a Cursor** y **Conectar a VS Code:** instalan el servidor con un clic. * **Copiar config del MCP:** copia el bloque JSON para clientes configurados por archivo. * **Copiar comando del MCP:** copia el comando de instalación para la terminal. Si prefieres configurarlo a mano, los pasos de cada cliente están abajo. ### Cualquier cliente, desde la terminal[​](#cualquier-cliente-desde-la-terminal "Enlace directo al Cualquier cliente, desde la terminal") [`add-mcp`](https://www.npmjs.com/package/add-mcp) detecta los clientes instalados en tu equipo y les agrega el servidor: ``` npx add-mcp "https://docs.finance.kobana.com.br/mcp" ``` ### Claude Code[​](#claude-code "Enlace directo al Claude Code") ``` claude mcp add --transport http kobana-finance-docs https://docs.finance.kobana.com.br/mcp ``` ### Cursor[​](#cursor "Enlace directo al Cursor") Usa **Conectar a Cursor** en el menú de la página, o agrega esto a `~/.cursor/mcp.json` (para todos los proyectos) o al `.cursor/mcp.json` del proyecto: ``` { "mcpServers": { "kobana-finance-docs": { "url": "https://docs.finance.kobana.com.br/mcp" } } } ``` ### VS Code[​](#vs-code "Enlace directo al VS Code") Usa **Conectar a VS Code** en el menú de la página, o crea `.vscode/mcp.json` en el proyecto. En VS Code la clave es `servers`, no `mcpServers`: ``` { "servers": { "kobana-finance-docs": { "type": "http", "url": "https://docs.finance.kobana.com.br/mcp" } } } ``` ### Claude y ChatGPT[​](#claude-y-chatgpt "Enlace directo al Claude y ChatGPT") En **Configuración › Conectores**, agrega un conector personalizado y pega la URL `https://docs.finance.kobana.com.br/mcp`. No hay inicio de sesión. ### Otros clientes configurados por archivo[​](#otros-clientes-configurados-por-archivo "Enlace directo al Otros clientes configurados por archivo") ``` { "mcpServers": { "kobana-finance-docs": { "type": "http", "url": "https://docs.finance.kobana.com.br/mcp" } } } ``` ## Ejemplos de preguntas[​](#ejemplos-de-preguntas "Enlace directo al Ejemplos de preguntas") Con el servidor conectado, pregunta con normalidad. El asistente consulta la documentación antes de responder: * "¿Cómo concilio una transacción del extracto con una cuenta por pagar?" * "¿Cómo registro una cuenta por pagar en cuotas o recurrente?" * "¿Cómo creo reglas automáticas para clasificar las transacciones?" * "Arma un ejemplo de llamada a la API para crear una cuenta por cobrar, según la documentación." ## Probar sin cliente[​](#probar-sin-cliente "Enlace directo al Probar sin cliente") ``` curl -s https://docs.finance.kobana.com.br/mcp \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"conciliación","locale":"es"}}}' ``` ## Límites[​](#límites "Enlace directo al Límites") * Las páginas de referencia de cada endpoint de la API no forman parte de `search_docs`/`get_page`: se generan a partir de la especificación OpenAPI, así que el MCP la lee directamente, con `search_openapi` y `get_operation`. La especificación completa sigue en [API › OpenAPI](https://docs.finance.kobana.com.br/es/es/api/overview/openapi.md). * La búsqueda es por palabras clave, no semántica. Si no encuentras nada, prueba otros términos o pide al asistente que use `list_pages`. * También puedes leer cualquier página en Markdown agregando `.md` a su URL, o descargar toda la documentación en [`llms-full.txt`](https://docs.finance.kobana.com.br/es/llms-full.txt). --- # Empresas Las empresas (`/companies`) representan las entidades jurídicas (CNPJ) administradas dentro del espacio de trabajo. Finanzas Inteligentes es multiempresa: un solo espacio de trabajo puede llevar el back-office financiero de varias empresas a la vez. ![Lista de empresas](/es/assets/images/17-companies-00692188753d23fa420c7c59a95f92f3.png) ## Registro[​](#registro "Enlace directo al Registro") El formulario tiene **dos campos**, y el segundo depende del primero: | Campo | Obligatorio | Descripción | | ---------- | ----------- | ------------------------------------------------------------------------------- | | **CNPJ** | Sí | El CNPJ de la empresa. En cuanto está completo, el sistema consulta la Receita. | | **Nombre** | Sí | Lo completa la consulta. Solo acepta escritura cuando la consulta no responde. | **Activo** y **Cuentas financieras** aparecen **solo en la edición** — una empresa nueva nace activa, y al momento de crearla todavía no hay cuentas que vincular. El flujo es crear la empresa y después crear las cuentas. ### El CNPJ acepta letras[​](#el-cnpj-acepta-letras "Enlace directo al El CNPJ acepta letras") nota **El CNPJ tiene 14 caracteres, no 14 dígitos.** En el formato alfanumérico de la Receita Federal, los 12 primeros caracteres (raíz y orden del establecimiento) aceptan **letras y números**; solo los 2 dígitos verificadores del final son exclusivamente numéricos. La máscara del campo lo contempla, y las letras que escribas pasan a mayúsculas automáticamente. El CNPJ se valida en el propio campo antes de cualquier consulta: un dígito verificador inválido ni siquiera llega a consultar la Receita. ### Consulta automática a la Receita[​](#consulta-automática-a-la-receita "Enlace directo al Consulta automática a la Receita") **En cuanto el CNPJ está completo** — escrito o pegado, sin necesidad de salir del campo —, el sistema consulta la Receita Federal y usa la respuesta para completar el resto: * **Razón social completada y bloqueada.** El campo **Nombre** empieza bloqueado, con el aviso *"Ingrese el CNPJ arriba"* — existe para recibir la razón social, no para que escribas en él. Cuando la consulta responde, el nombre llega listo. * **Aviso de estado en el registro.** Si la empresa no está **ATIVA** en la Receita, aparece una alerta con el estado encontrado — *"Estado en la Receita Federal: SUSPENSA."*, por ejemplo. Es **solo un aviso**: no impide el registro. * **Un CNPJ duplicado bloquea.** Si el CNPJ ya pertenece a otra empresa **activa de este espacio de trabajo**, aparece el aviso *"CNPJ ya registrado."* y el botón Guardar no concluye. Esta verificación es local: el CNPJ de una empresa **inactiva no reserva el lugar**, y la unicidad rige por espacio de trabajo, no globalmente. Si la Receita no localiza el CNPJ (*"CNPJ no encontrado en la Receita — ingrese el nombre manualmente."*) o la consulta falla (*"No se pudo consultar la Receita — ingrese el nombre manualmente."*), el campo **Nombre** se desbloquea y lo escribes tú. Una consulta que no responde nunca bloquea el registro. ### El tipo (sede o sucursal) no es un campo[​](#el-tipo-sede-o-sucursal-no-es-un-campo "Enlace directo al El tipo (sede o sucursal) no es un campo") No lo eliges. El tipo se **deduce del propio CNPJ**, por los cuatro caracteres de la orden del establecimiento — el `0001` en `12.345.678/0001-95`. `0001` es **sede**; cualquier otro valor es **sucursal**. El tipo aparece como distintivo en el listado y como filtro (**Todas** · **Sede** · **Sucursal**), nunca como campo editable. Si corriges el CNPJ de una empresa ya registrada, el tipo se recalcula también. ## Cuentas financieras[​](#cuentas-financieras "Enlace directo al Cuentas financieras") Cada empresa puede tener varias cuentas financieras, vinculadas en la sección **Cuentas financieras** del formulario de edición (**Agregar cuenta** vincula una cuenta que ya existe). **La empresa es opcional en la cuenta financiera**, no obligatoria. Una cuenta puede existir sin empresa. Vincularla es lo que permite filtrar el Dashboard y los informes por empresa — es útil, pero el sistema no lo exige. ## Filtro por empresa[​](#filtro-por-empresa "Enlace directo al Filtro por empresa") El selector de empresa en el encabezado de la aplicación persiste entre pantallas y filtra los datos que se muestran. Solo lista **empresas activas**. ## Desactivar[​](#desactivar "Enlace directo al Desactivar") Desactivar **no** saca a la empresa de la pantalla de Empresas. Sigue en el listado, con el distintivo **Inactivo** en la columna Estado. Lo que hace la desactivación es **sacar a la empresa del selector del encabezado y de los formularios** — deja de ser una opción en registros nuevos, y el historial permanece intacto. * **Para desactivar:** abre **Editar** en la fila de la empresa y apaga el interruptor **Activo**. * **Para reactivar:** el mismo camino, volviendo a encenderlo. * **Para ver las inactivas:** ya aparecen por defecto. El filtro **Estado** (**Activo** / **Inactivo**) sirve para restringir — fijarlo en **Activo** es lo que las oculta. ## Eliminar[​](#eliminar "Enlace directo al Eliminar") La eliminación es permanente y no se puede deshacer. El diálogo avisa: *"¿Está seguro de que desea eliminar esta empresa? Todas las cuentas financieras asociadas serán eliminadas."* nota **El movimiento financiero bloquea la eliminación.** Si la empresa tiene **transacciones**, **cuentas por pagar**, **cuentas por cobrar** o **personas registradas**, el sistema se niega y dice qué encontró: *"No se pudo eliminar esta empresa porque tiene 3 transacciones, 1 cuenta por pagar vinculados. Elimine esos registros primero e inténtelo de nuevo."* No bloquean — **se eliminan junto** con la empresa: * **Cuentas financieras** (es lo que avisa el diálogo) * **Categorías** y **centros de clasificación** de la empresa En la práctica el bloqueo casi siempre gana: una cuenta financiera con movimiento implica transacciones, y una transacción bloquea. Si la empresa tiene historial y solo quieres sacarla de circulación, **desactívala** en lugar de eliminarla. ## Integración WhatsApp[​](#integración-whatsapp "Enlace directo al Integración WhatsApp") Cada empresa puede tener su propia configuración de WhatsApp (vía Evolution API) para mostrar las fotos de perfil de clientes y proveedores. Consulta [WhatsApp](https://docs.finance.kobana.com.br/es/es/integracoes/whatsapp.md). --- # Extractos bancarios Los extractos bancarios importan el extracto de una cuenta y crean transacciones a partir de él. Los formatos aceptados son OFX y QIF. ## Dónde está[​](#dónde-está "Enlace directo al Dónde está") Los extractos bancarios **no son una pantalla propia** y no tienen ítem de menú. Son una pestaña dentro de la cuenta: **Cuentas financieras** → abre la cuenta → pestaña **Extractos bancarios**. Por eso no existe el paso de "elegir la cuenta de destino": **la cuenta es aquella en la que ya estás**. Hace falta tener una **empresa específica** seleccionada en el encabezado — en "todas las empresas" el panel solo avisa de eso. ## Formatos aceptados[​](#formatos-aceptados "Enlace directo al Formatos aceptados") | Formato | Extensión | Descripción | | ------- | --------- | ----------------------------------------------------------------------------- | | OFX | `.ofx` | Open Financial Exchange — estándar de la mayoría de los bancos | | QIF | `.qif` | Quicken Interchange Format — formato legado, todavía usado por algunos bancos | El botón **Descargar ejemplo** ofrece un archivo de cada formato. Son **ejemplos para que conozcas el formato**, no plantillas para completar — un extracto se exporta desde el banco, no se escribe a mano. ## Importar[​](#importar "Enlace directo al Importar") 1. Exporta el extracto de tu banco en OFX o QIF. 2. En la pestaña **Extractos bancarios** de la cuenta, sube el archivo. 3. El sistema lee el archivo y muestra lo que encontró: cuántas transacciones son importables y cuántas se ignoraron. 4. **Todas las filas vienen ya marcadas.** Haz clic en una fila para desmarcarla si no quieres importarla. 5. Haz clic en **Importar N transacciones**. La importación **corre en segundo plano**: recibes el aviso *"Importación iniciada en segundo plano"* y la sigues por un diálogo de progreso — la pantalla no se queda bloqueada esperando. Las transacciones importadas entran **sin conciliar**. Para vincularlas con las cuentas por pagar y por cobrar, usa la [Conciliación](https://docs.finance.kobana.com.br/es/es/conciliacao/.md). ### Qué se ignora[​](#qué-se-ignora "Enlace directo al Qué se ignora") Tres casos se descartan en la lectura y se **cuentan**, con el resumen en pantalla — *"Ignoradas: 2 con fecha futura, 1 con monto cero, 0 con fecha inválida."*: * **Fecha futura** * **Monto cero** * **Fecha inválida** (un valor ilegible también cae aquí) ## Deduplicación[​](#deduplicación "Enlace directo al Deduplicación") nota **La deduplicación identifica la fila por el identificador que le da el banco (el FITID del OFX) — no por "mismo monto, fecha y descripción".** Cuando el archivo no trae ese identificador (lo que siempre ocurre en QIF), el sistema genera una clave a partir de la fecha, el monto y la descripción **más el orden de aparición**, justamente para que dos filas idénticas **no** se confundan. **Lo que garantiza la deduplicación:** volver a subir **el mismo archivo** a **la misma cuenta** no duplica nada. Las filas ya conocidas se saltan, y el historial informa cuántas fueron. **La transacción que el ERP ya trajo tampoco se duplica.** Si la cuenta tiene el historial importado de Fintera o de Nibo, la fila del archivo que es el mismo movimiento — misma dirección, mismo valor, mismo día — no crea otra transacción: se une a la que vino del ERP, que conserva la descripción y la clasificación del equipo financiero y gana el texto del banco. **Lo que no garantiza — y conviene saber:** * **Dos transacciones genuinamente iguales entran las dos.** Dos retiros de R$ 50 el mismo día, con la misma descripción, son dos transacciones reales. El sistema las preserva a propósito. * **No hay deduplicación entre orígenes de extracto.** La misma transacción que llega por OFX, por QIF y por la sincronización del Gateway Bancario cuenta como **tres** — cada origen genera su propia clave. (Entre el extracto y el ERP sí la hay, ver arriba.) * **La deduplicación es por cuenta**, no por espacio de trabajo. * **Nada se marca en pantalla.** La verificación ocurre en el servidor, **al momento de importar** — no cuando revisas la lista. ## Historial[​](#historial "Enlace directo al Historial") Debajo del panel de importación, la sección **Historial** lista los archivos ya importados: fecha, archivo, estado, cuántas transacciones entraron del total, y quién lo pidió. La sección solo aparece cuando hay historial. Los estados son **En cola**, **En progreso**, **Completado**, **Fallido** y **Cancelado**. ### Deshacer[​](#deshacer "Enlace directo al Deshacer") La acción **Deshacer** elimina **las transacciones que creó ese archivo** y saca el extracto del historial. El diálogo avisa: *"Esto elimina las N transacciones importadas desde este extracto. Esta acción no se puede deshacer."* Si alguna de esas transacciones ya estaba conciliada, **deshacer también deshace la conciliación**. La transacción que vino del ERP y recibió una fila del archivo **no se elimina**: deshacer solo la desvincula del extracto. Volver a subir el archivo une la fila a ella otra vez. La acción no aparece mientras el extracto está **En cola** o **En progreso** — espera a que termine. Tampoco aparece en extractos que vienen de Fintera: *"Extratos vindos do Fintera não podem ser desfeitos aqui — desfaça no Fintera."* ### Eliminar una transacción del extracto[​](#eliminar-una-transacción-del-extracto "Enlace directo al Eliminar una transacción del extracto") Eliminar **una transacción** que vino de un extracto es distinto de deshacer el extracto entero, y la diferencia se ve en la siguiente importación: * **Eliminaste la transacción** — **no vuelve**. Importar el mismo archivo de nuevo, o volver a sincronizar el Gateway Bancario, no la trae de vuelta: el sistema recuerda que la quitaste. * **Deshiciste el extracto** — ahí sí, importar el archivo de nuevo trae todo. Es el camino para empezar de cero. **Por eso eliminar la fila resuelve, incluso sin Deshacer.** El extracto del Gateway Bancario no tiene lote que deshacer, y la sincronización trae el historial entero de la cuenta cada vez. Sin esa garantía, la fila que eliminaras volvería en la siguiente sincronización — y si ya hubieras registrado la corrección a mano, el monto aparecería **dos veces**. ## Otros orígenes de extracto[​](#otros-orígenes-de-extracto "Enlace directo al Otros orígenes de extracto") Además del archivo, el extracto puede venir de: * **Gateway Bancario** — el botón **Sincronizar extracto bancario**, en la pantalla de integración, trae las transacciones de las cuentas vinculadas de la empresa seleccionada. * **Fintera** — importa el extracto reflejado de la plataforma. **Ninguna de las dos corre sola.** No hay programación: las dos son un botón que aprietas. nota **El extracto del Gateway Bancario no aparece en el Historial de esta pestaña.** No es un archivo — el gateway devuelve una lista de transacciones, sin el concepto de "extracto importado". Las **transacciones** aparecen normalmente en la cuenta; el **lote** no, y por eso **no hay Deshacer** para él. Para quitar una fila, elimina la transacción: no vuelve en la siguiente sincronización (ver [Eliminar una transacción del extracto](#eliminar-una-transacci%C3%B3n-del-extracto)). El registro de esas ejecuciones queda en la propia pantalla del [Gateway Bancario](https://docs.finance.kobana.com.br/es/es/integracoes/kobana.md). --- # Impuestos La sección de Impuestos (`/taxes`) gestiona el catálogo de tasas y tributos que pueden **vincularse a cuentas por pagar y por cobrar** (retenciones/impuestos sobre el título). ![Lista de impuestos](/es/assets/images/13-taxes-08bc9b34740cd76da4ef2e5821e11a6b.png) ## Campos[​](#campos "Enlace directo al Campos") | Campo | Descripción | | ---------------------------- | ------------------------------------------------------------------------------------------------- | | **Nombre** | Identificación del tributo (ej.: "INSS Patronal", "ISS Municipal") — único por espacio de trabajo | | **Alícuota por defecto (%)** | Porcentaje sugerido del tributo | | **Retenido** | Marca el impuesto como retenido en la fuente. Por defecto: sí | | **Activo** | Si el impuesto aparece para selección | ## Uso[​](#uso "Enlace directo al Uso") Los impuestos registrados pueden **asignarse como gravamen** a una cuenta por pagar o por cobrar — el título guarda qué impuestos inciden sobre él. nota **Registrar un impuesto no es pagar una guía (la boleta de pago brasileña).** Para registrar el **pago** de una guía específica (DARF, GPS, GRU, FGTS…), usa una cuenta por pagar con **Documento = Tributo** — ver [Tributos en Cuentas por pagar](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/tributos.md). ## API[​](#api "Enlace directo al API") El recurso de impuestos está disponible en la [API pública](https://docs.finance.kobana.com.br/es/es/api.md), con el scope `finance/taxes` y el nivel de acceso `read` para leer, `write` para crear y modificar y `delete` para eliminar. --- # Integraciones **Integraciones** (`/settings/integrations`) conecta la organización a servicios externos. Es un elemento del grupo **Sistema** del menú. ![Pantalla de integraciones](/es/assets/images/19-integrations-20822a25a14cf35d67e4b7a81c4aeede.png) ## Integraciones disponibles[​](#integraciones-disponibles "Enlace directo al Integraciones disponibles") ## [📄️Gateway Bancario](https://docs.finance.kobana.com.br/es/es/integracoes/kobana.md) [Envío de pagos al banco y sincronización de cuentas, extractos y personas vía Kobana.](https://docs.finance.kobana.com.br/es/es/integracoes/kobana.md) ## [📄️Open Finance](https://docs.finance.kobana.com.br/es/es/integracoes/open-finance.md) [Conecta las cuentas bancarias de la empresa por Open Finance y recibe saldos y extractos automáticamente.](https://docs.finance.kobana.com.br/es/es/integracoes/open-finance.md) ## [📄️Fintera](https://docs.finance.kobana.com.br/es/es/integracoes/fintera.md) [Importación de datos financieros de Fintera — once recursos, vínculo de empresas y programaciones.](https://docs.finance.kobana.com.br/es/es/integracoes/fintera.md) ## [📄️WhatsApp](https://docs.finance.kobana.com.br/es/es/integracoes/whatsapp.md) [Fotos de perfil de clientes y proveedores vía Evolution API — configuración por empresa.](https://docs.finance.kobana.com.br/es/es/integracoes/whatsapp.md) Cada tarjeta lleva a la página de la integración, con las instrucciones de conexión. ## Estado[​](#estado "Enlace directo al Estado") El sello de estado aparece junto al nombre de la integración, y **solo se muestra en dos casos**: | Situación | Lo que ves | | ------------------ | --------------------------------------------------------------------------------------------------------------------- | | **Conectado** | Un **ícono redondo verde**. El texto "Conectado" no se escribe en la pantalla — está en el tooltip, al pasar el mouse | | **Error** | Un **sello rojo con el texto "Error"** — credencial inválida o fallo de conexión | | **No configurado** | **Nada.** El sello simplemente no se dibuja | nota **La ausencia del sello es la información.** Una integración que aún no se ha conectado no muestra "No configurado": el espacio queda vacío. El texto existe en el sistema, pero ninguna pantalla lo muestra. **La tarjeta de WhatsApp no tiene ningún sello**, ni siquiera cuando está configurada. El estado solo se calcula para el Gateway Bancario y Fintera — la conexión de WhatsApp es por empresa y vive en otro lugar. Para saber si está en pie, abre su página. --- # Integración Fintera **Sistema > Integraciones > Fintera** (`/settings/integrations/fintera`). Importa datos de una cuenta Fintera hacia Finanzas Inteligentes — para quien está migrando o mantiene las dos plataformas en paralelo. ## Conectar[​](#conectar "Enlace directo al Conectar") La franja superior muestra el **Estado**, el **Token** y cuántas **Empresas** están vinculadas. Sin conexión, **"Conectar"**: pega el token de API de Fintera. Una vez conectado, el diálogo "Gestionar la conexión con Fintera" muestra el token como *"Almacenado cifrado"* — nunca se exhibe de vuelta. Conectado, el botón pasa a **"Gestionar la conexión"** — y es dentro de ese diálogo donde están el **vínculo de empresas**, **Actualizar** el token y **Desconectar**. ## Vínculo de empresas[​](#vínculo-de-empresas "Enlace directo al Vínculo de empresas") **Fintera trae las empresas, no las cuentas.** *"Estas empresas vienen de Fintera (por tu token). Aquí solo eliges a qué empresa registrada en Finanzas Inteligentes le envía los datos cada una."* ## Dos requisitos[​](#dos-requisitos "Enlace directo al Dos requisitos") Las importaciones quedan bloqueadas hasta que ambos estén satisfechos: 1. **Token válido** — *"Guarda un token válido de Fintera para habilitar las importaciones."* 2. **Al menos una empresa vinculada** — *"Vincula al menos una entidad de Fintera a una empresa de Finanzas Inteligentes para habilitar las importaciones."* ## Qué se importa[​](#qué-se-importa "Enlace directo al Qué se importa") **Once recursos**, en dos grupos. El orden importa: **Movimientos** *"dependen de los registros de arriba"*. ### Registros base[​](#registros-base "Enlace directo al Registros base") | Recurso | Observaciones | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Categorías** | Replicadas por empresa; las categorías bidireccionales generan un **par** (ingreso + gasto) | | **Centros de clasificación** | Para todas las empresas vinculadas | | **Personas** | Clientes y proveedores | | **Impuestos** | Catálogo del espacio de trabajo. **Precede** a las cuentas por pagar/cobrar, cuyos impuestos por título se resuelven contra él | | **Cuentas financieras** | Cuentas bancarias de Fintera. Una cuenta que ya existe aquí con el mismo banco, sucursal y número (a mano o desde el Gateway Bancario) se **vincula**, no se duplica | ### Movimientos[​](#movimientos "Enlace directo al Movimientos") | Recurso | Depende de | | ----------------------- | ----------------------------------------------------------------------------------------------------- | | **Cuentas por Pagar** | Personas + categorías + centros | | **Cuentas por Cobrar** | Personas + categorías + centros | | **Transacciones** | — (la primera importación de cada cuenta trae todo el historial; las siguientes, los últimos 90 días) | | **Conciliaciones** | Títulos + transacciones | | **Adjuntos** | Títulos + transacciones | | **Extractos bancarios** | Transacciones | nota **Extractos bancarios no descarga el archivo OFX.** La importación *"refleja el historial de importación de extractos bancarios de Fintera y vincula cada transacción con su extracto"* — pero **el archivo en sí no viene**: la API de Fintera no lo expone. Recibes la estructura y los vínculos, no el documento. **Conciliaciones preserva el n:m.** El vínculo de Fintera entre títulos y transacciones se refleja tal como está. Ver [Conciliación](https://docs.finance.kobana.com.br/es/es/conciliacao/.md) — una conciliación importada es de solo lectura. **Las cuentas por pagar traen los datos de pago.** Lo que está en *Dados de Pagamento* en Fintera — boleto, TED o Pix (clave, datos bancarios o copia y pega) — llega a **Información de pago** del título. El beneficiario no viene: vacío, el envío al banco usa el proveedor. Cuando el título en Fintera no tiene datos de pago, la importación no toca lo que completaste aquí. Y, después de que alguien cambia los datos de pago aquí o el título se envía al banco, la importación ya no los reemplaza. **Lo que haces aquí la importación no lo deshace.** Solo actualiza lo que sigue tal como Fintera lo envió la última vez. La clasificación que tú, una [regla automática](https://docs.finance.kobana.com.br/es/es/regras-automaticas/.md) o la [conciliación](https://docs.finance.kobana.com.br/es/es/conciliacao/.md) le diste a una transacción se mantiene; la línea conciliada aquí como transferencia sigue siendo transferencia; y el título liquidado aquí sigue pagado, aunque esté abierto en Fintera. La conciliación que viene de Fintera deja fuera lo que ya se concilió aquí, y la transacción eliminada aquí no vuelve. ## Importar[​](#importar "Enlace directo al Importar") **"Importar todo"** ejecuta los once en secuencia, respetando la dependencia. Cada línea también tiene su **"Importar"**, para ejecutar un recurso aislado. Las importaciones **se ejecutan en segundo plano** y siguen los vínculos de empresa. Cada línea muestra el progreso y el resultado — cuántos creados, actualizados, con error, o *"sin cambios"* / *"nada que importar"*. **Cuentas por pagar y por cobrar traen solo lo que cambió.** Después de la primera importación de cada empresa, las siguientes piden a Fintera solo los títulos creados o modificados desde la anterior — nunca todo el histórico de nuevo. Cuando Fintera no informa cuándo cambió un título, piden los que vencen o se pagaron en los últimos 90 días (o desde la importación anterior, si es más antigua). Por eso el total de una reimportación suele ser pequeño: son los cambios. **Un título eliminado en Fintera queda cancelado aquí.** En cada importación, Finanzas Inteligentes compara cuántos títulos tiene Fintera con los de aquí — sin traer el histórico — y, cuando sobra alguno, confirma uno por uno antes de marcarlo como cancelado: sale de los totales, informes y del flujo de caja, pero no se borra. Si vuelve a aparecer en Fintera, la importación siguiente lo restaura. Los títulos ya enviados al banco o conciliados no se tocan. Para importar desde un día específico, algunas líneas tienen un ícono de calendario junto al botón de importar: * **Cuentas por Pagar** y **Cuentas por Cobrar** — los títulos creados o modificados desde la fecha (o, cuando Fintera no informa los cambios, los que vencen o se pagaron desde ella). En la primera importación de una empresa también evita traer todo el histórico: la importación empieza en ese día. * **Transacciones** — las transacciones ocurridas desde la fecha hasta hoy, en todas las cuentas. * **Extractos** — los extractos de las transacciones ya importadas de ese período. * **Adjuntos** — solo los adjuntos enviados a Fintera desde la fecha. Los que ya están aquí no se descargan de nuevo. Los registros, las cuentas financieras y las conciliaciones no tienen el calendario: Fintera no filtra esos recursos por fecha, y se leen completos en cada importación. **No existe un botón "Importar datos" con selector de período.** Son los once recursos, cada uno con el suyo, más el "Importar todo". ## Modo token del módulo Financeiro[​](#modo-token-del-módulo-financeiro "Enlace directo al Modo token del módulo Financeiro") Un token restringido al módulo Financeiro de Fintera no lista empresas. En ese caso no hay nada que vincular, y la pantalla avisa: *"Las importaciones disponibles se aplican a las empresas activas del espacio de trabajo."* Solo un subconjunto de los recursos queda habilitado. ## Programaciones[​](#programaciones "Enlace directo al Programaciones") *"Configura ejecuciones automáticas para importaciones."* Con **"Nueva programación"**, una importación pasa a ejecutarse sola en la frecuencia elegida. Cada línea muestra el recurso, la frecuencia, la **próxima ejecución** y el resultado de la última, con el sello **Activo** o **Deshabilitado** y las acciones **Editar**, **Pausar** / **Reanudar** y **Eliminar**. Es lo que diferencia a Fintera de las herramientas de [Mantenimiento](https://docs.finance.kobana.com.br/es/es/manutencao/.md): aquí **existe** programación. ## Historial de importaciones[​](#historial-de-importaciones "Enlace directo al Historial de importaciones") Registro de las ejecuciones, en cuatro columnas: **Fecha**, **Importaciones**, **Resultado** y **Usuario** — quién la disparó. ## Desconectar[​](#desconectar "Enlace directo al Desconectar") Dentro de **"Gestionar la conexión"**. Los datos ya importados permanecen. --- # Integración Gateway Bancario (Kobana) **Sistema > Integraciones > Kobana** (`/settings/integrations/kobana`). La integración permite: 1. **Envío de pagos al banco** — despachar cuentas por pagar aprobadas, título a título o en lote. 2. **Sincronización de cuentas bancarias** — entre Kobana y Finanzas Inteligentes. 3. **Sincronización de extracto bancario** — traer las transacciones de las cuentas vinculadas. 4. **Sincronización de personas** — mantener el registro igual de los dos lados. Trae todo lo que hay en Kobana; desde aquí, envía solo los clientes. 5. **Liquidación automática** — confirmado el pago, la cuenta se liquida y se crea la transacción. Depende de que el título tenga definido el **"Pagar desde"**: sin saber de qué cuenta salió el dinero, el sistema no lo adivina, y la baja te queda a ti para hacerla a mano. 6. **Generación de cobros** — emitir un **boleto o un Pix** desde una cuenta por cobrar, para que el cliente pague. 7. **Comprobantes de pago** — capturar automáticamente el comprobante de cada pago confirmado. ## Conectar[​](#conectar "Enlace directo al Conectar") La franja superior muestra el **Estado** — **Conectado**, **No conectado** o **Error de conexión** — y el token. Sin conexión, el botón es **"Conectar"**: pega el token de API generado en el panel de Kobana. *"El token se almacena cifrado."* El sistema lo valida e informa cuántas cuentas están visibles. Ya conectado, el botón pasa a **"Gestionar conexión"**. **"Desconectar" no está en la página.** Vive dentro del diálogo **"Gestionar conexión con Kobana"**, junto a "Actualizar". La confirmación tranquiliza: *"Solo se elimina la conexión. Las cuentas y datos ya sincronizados permanecen en Finanzas Inteligentes."* ## Sincronizaciones[​](#sincronizaciones "Enlace directo al Sincronizaciones") nota **Las sincronizaciones exigen una empresa específica** en el selector del encabezado: *"Selecciona una empresa específica en el selector del encabezado, no 'Todas las empresas'. Las cuentas sincronizadas se asignan a la empresa que elijas."* ### Cuentas bancarias[​](#cuentas-bancarias "Enlace directo al Cuentas bancarias") No existe un listado para vincular cuentas a mano. Hay **un botón** — **"Sincronizar cuentas bancarias"** — que hace todo el trabajo y vincula por sí solo. **Esta sincronización solo trae.** La tarjeta lleva el sello **"Desde el gateway"**: importa las cuentas registradas en Kobana y **no crea nada allá**. Aun así hay una confirmación, porque la ejecución puede **reescribir cuentas que ya existen aquí** — y el modal muestra exactamente cuáles, y qué campos cambian, antes de que la autorices. **El camino de vuelta es cuenta por cuenta.** Para enviar una cuenta de aquí a Kobana, abre la cuenta y usa **"Agregar al gateway bancario"** — mira [Cuentas financieras](https://docs.finance.kobana.com.br/es/es/contas-financeiras/.md). Crear una cuenta en el gateway modifica el sistema externo, así que eres tú quien elige qué va, una cuenta a la vez, y no una ejecución en masa. ### Extracto bancario[​](#extracto-bancario "Enlace directo al Extracto bancario") **"Sincronizar extracto bancario"** *"importa el extracto bancario de las cuentas vinculadas (en la empresa seleccionada): trae las transacciones de Kobana a Finanzas Inteligentes, sin duplicar las ya importadas."* **El botón es uno solo y cubre todas las cuentas vinculadas de la empresa** — no hay un botón por cuenta. Las líneas importadas alimentan la [Conciliación](https://docs.finance.kobana.com.br/es/es/conciliacao/.md). ### Personas[​](#personas "Enlace directo al Personas") **"Enviar personas"** sincroniza el registro en ambos sentidos: trae de Kobana a quien solo existe allá y envía desde aquí los **clientes** de la empresa seleccionada que aún no están en Kobana. La tarjeta también lleva el sello **"Bidireccional"**. info **Los proveedores no se envían.** El registro en Kobana es de quien paga: un proveedor ocuparía un lugar allá sin ser cobrado nunca. Quien es cliente **y** proveedor se envía normalmente, por ser cliente también. A la vuelta no hay ese filtro, porque Kobana no separa el papel: **quien viene de allá entra aquí como cliente**. Si la persona importada es en realidad un proveedor tuyo, marca el papel en su ficha — esa marca es tuya y las sincronizaciones siguientes no la deshacen. aviso **También ESCRIBE en Kobana**, y por eso pide confirmación: *"Crear registros en Kobana modifica el sistema externo."* **Nadie se duplica.** El cotejo es por **CPF/CNPJ** — y, para quien ya fue enviado desde aquí antes, por el vínculo guardado en ese envío. Quien ya existe en ambos lados simplemente queda vinculado; los datos que registraste aquí **no se sobrescriben**. info **Una persona sin CPF/CNPJ no se envía.** Sin el documento no hay forma de saber si ya está allá, y el envío prefiere dejarla fuera antes que arriesgar un registro repetido. Al final la sincronización indica cuántas quedaron así — completa el documento y vuelve a ejecutar. La **importación** no tiene ese límite. Cada ejecución envía hasta **200 personas**. Si tu base es mayor, ejecútala de nuevo: lo que ya se envió no se reenvía. ## Aprobación de pagos[​](#aprobación-de-pagos "Enlace directo al Aprobación de pagos") Cuando la aprobación está **activada** (el valor por defecto del espacio de trabajo), un título creado por formulario, CSV o API **no** queda disponible para el envío hasta que **una persona lo apruebe** en [Aprobar pagos](https://docs.finance.kobana.com.br/es/es/aprovar-pagamentos/.md). Con la aprobación desactivada, el título nace oficial y listo para enviar. Ver [Ciclo de vida](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/ciclo-de-vida.md). ## Envío de pagos[​](#envío-de-pagos "Enlace directo al Envío de pagos") Con la integración activa y el título aprobado, usa **"Enviar al banco"** — acción **manual**, en la pantalla de detalle. Desde el listado, el camino es **"Enviar pagos"**, que despacha en lote. Ver [Envío al banco](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/disparo-kobana.md). ## Generación de cobros[​](#generación-de-cobros "Enlace directo al Generación de cobros") La integración también funciona en la dirección del dinero que **entra**: desde una cuenta por cobrar, **"Generar cobro"** emite un **boleto** o un **Pix** para que el cliente pague, y el cobro pagado liquida el título automáticamente. Cada camino tiene su requisito en la cuenta del gateway — el boleto necesita un **convenio**, el Pix una **cuenta Pix de cobro** — y el boleto exige además la **dirección completa** del cliente. Ver [Cobro por boleto y Pix](https://docs.finance.kobana.com.br/es/es/contas-a-receber/cobranca-kobana.md). ## Comprobantes[​](#comprobantes "Enlace directo al Comprobantes") Confirmado un pago enviado al banco, el comprobante se **captura automáticamente**: queda guardado en la biblioteca de [Adjuntos](https://docs.finance.kobana.com.br/es/es/anexos/.md), aparece en la pantalla del título y se lista en [Comprobantes](https://docs.finance.kobana.com.br/es/es/comprovantes/.md). Quien esté marcado en **"Configurar envío"** recibe un correo, y las direcciones registradas en la propia cuenta reciben el comprobante **adjunto**; la campana avisa de todas formas. Ver [Quién recibe por correo](https://docs.finance.kobana.com.br/es/es/comprovantes/.md#qui%C3%A9n-recibe-por-correo). ## Sincronización automática[​](#sincronización-automática "Enlace directo al Sincronización automática") nota **Esta sección solo aparece si el servidor tiene configurada una dirección pública de webhook.** Sin eso no hay forma de que el gateway avise de nada, y ni ella ni las dos secciones siguientes se dibujan. Un interruptor: *"Mantiene al día el estado de los pagos enviados por sí solo, sin hacer clic en 'Actualizar estado'."* **Es opcional, y apagada no te quedas sin información** — solo tienes que buscar el estado a mano, con el **"Actualizar estado"** de cada título. ## Notificaciones[​](#notificaciones "Enlace directo al Notificaciones") Otro interruptor: *"Recibe un aviso en la campana cuando cambie el estado de un pago (confirmado, programado, rechazado…)."* Los dos interruptores conversan: sin la sincronización automática activada, *"los avisos pueden llegar con retraso"* — la campana solo avisa cuando el sistema descubre el cambio. ## Entregas del webhook[​](#entregas-del-webhook "Enlace directo al Entregas del webhook") Tabla de diagnóstico: *"Registro de cada evento de cambio de estado que envía el gateway de pagos de Kobana. Si alguno falla, puedes reenviarlo."* Tiene **"Actualizar"** y, por línea, el reenvío. Es donde mirar cuando un pago parece trabado: si el evento no llegó, el estado de aquí se queda atrás del banco. **Esta tabla solo existe con la sincronización automática activada.** Es ella la que hace que el gateway mande los eventos — apagada, no hay entrega que registrar, y la sección desaparece de la página. ## Historial[​](#historial "Enlace directo al Historial") Registro de las sincronizaciones ejecutadas, por **Fecha**, **Tipo** (**Cuentas**, **Extracto bancario** o **Personas**) y **Resultado** — con cuántas fueron creadas, actualizadas, enviadas u omitidas. En la sincronización de personas, que corre en los dos sentidos, el resultado los separa: lo que **vino** de Kobana aparece como creado o actualizado, y lo que **fue** desde aquí aparece como enviado. Las personas dejadas fuera por no tener CPF/CNPJ se cuentan como omitidas. La de cuentas solo trae, así que allí solo hay creadas y actualizadas. --- # Open Finance **Sistema > Integraciones > Open Finance** (`/settings/integrations/open-finance`). Conecta las cuentas bancarias de tus empresas por **Open Finance**, el sistema de compartir datos regulado por el Banco Central de Brasil, y Finanzas Inteligentes empieza a recibir solo: 1. **Saldos** — varias veces al día, registrados en la pestaña **Saldos** de la cuenta con el origen **Open Finance**. 2. **Extracto** — los movimientos efectivados entran como movimientos de la cuenta, clasificados por tus [reglas automáticas](https://docs.finance.kobana.com.br/es/es/regras-automaticas/.md). Nada aquí mueve dinero: Open Finance solo **lee** las cuentas que autorices. ## Conectar un banco[​](#conectar-un-banco "Enlace directo al Conectar un banco") Haz clic en **"Conectar banco"**. Son dos pasos: 1. **Empresa** — elige la empresa e informa el **CPF de quien autorizará en el banco**. Para cuentas de empresa, el banco pide el CPF de una persona con acceso a la cuenta. El CPF no se guarda. Haz clic en **"Continuar"**. 2. **Autorización** — se abre la ventana de autorización, ya con la empresa y el CPF: elige el banco, revisa los datos que se compartirán, la finalidad y el plazo, y confirma. Si la ventana no se abre sola, haz clic en **"Elegir el banco"**. Te llevamos **al propio banco**, ingresas con tus datos de acceso y eliges allí qué cuentas compartir. Nadie más que el banco ve tu contraseña. Al terminar, el banco te trae de vuelta a Financeiro Inteligente. nota El plazo para compartir aparece en la revisión, antes de confirmar, y se confirma en el banco. Puedes finalizarlo antes, aquí o en tu banco. ## Elegir qué hacer con cada cuenta[​](#elegir-qué-hacer-con-cada-cuenta "Enlace directo al Elegir qué hacer con cada cuenta") Al volver del banco, la pantalla muestra las cuentas compartidas. Para cada una: | Opción | Qué sucede | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Vincular a una cuenta existente** | La cuenta que ya tienes aquí empieza a recibir saldo y extracto. El sistema sugiere la correcta por agencia y número | | **Crear una cuenta nueva** | Se crea una cuenta nueva en la empresa, ya vinculada | | **Ignorar esta cuenta** | No se importa nada de ella | Y, para cada cuenta, **"Importar extracto"** con la fecha **"desde"**. aviso **La fecha de inicio evita movimientos repetidos.** Si la cuenta ya tiene extracto aquí — importado por OFX o digitado —, empieza después del último movimiento. El sistema ya sugiere esa fecha. Una cuenta que ya recibe extracto por el [Gateway Bancario](https://docs.finance.kobana.com.br/es/es/integracoes/kobana.md) llega con el extracto **desactivado**. Activándolo aquí, el extracto pasa a venir solo por Open Finance — nunca por los dos, para que el mismo movimiento no entre dos veces. Los saldos de los dos orígenes conviven. ## Seguir las conexiones[​](#seguir-las-conexiones "Enlace directo al Seguir las conexiones") Cada conexión (empresa × banco) aparece con su estado: | Estado | Significado | | ---------------------- | -------------------------------------------------------- | | **Esperando al banco** | La autorización en el banco aún no terminó | | **Conectado** | Saldos y extractos se están actualizando | | **No autorizado** | La autorización fue rechazada o no terminó a tiempo | | **Finalizado** | El compartir fue finalizado — por ti, aquí o en el banco | | **Vencido** | El plazo terminó | En el menú de cada conexión: **Actualizar ahora**, **Revisar cuentas**, **Renovar** (antes de vencer), **Desconectar** y, ya finalizada, **Quitar de la lista**. Recibes un aviso en la central de notificaciones cuando la conexión es autorizada, cuando las cuentas están listas para importar, cerca del vencimiento y cuando finaliza. **Desconectar no borra nada.** Los movimientos y saldos ya importados siguen en las cuentas. ## Programar la sincronización y ver el historial[​](#programar-la-sincronización-y-ver-el-historial "Enlace directo al Programar la sincronización y ver el historial") En la misma pantalla, **Programación de la sincronización** define cuándo se actualizan solas las conexiones de una empresa (saldos, extractos, tarjetas e inversiones). Selecciona la empresa arriba y usa **Nueva programación**; hay una por empresa. Sin programación, el sistema actualiza cada 6 horas y cada vez que el banco avisa de datos nuevos. El **Historial de sincronizaciones** lista las últimas ejecuciones — banco, origen (aviso del banco, programada, manual o nueva conexión) y qué cambió. ## En la cuenta[​](#en-la-cuenta "Enlace directo al En la cuenta") Una cuenta vinculada muestra la insignia **Open Finance**. En la pestaña **Saldos**: * **"Actualizar por Open Finance"** lee el saldo en el momento; * **"Extracto por Open Finance"** activa o desactiva el extracto y cambia la fecha de inicio. Un movimiento importado que borres **no vuelve** en la próxima actualización. --- # Integración WhatsApp (Evolution API) **Sistema > Integraciones > WhatsApp** (`/settings/integrations/whatsapp`). Con Evolution conectado, la herramienta **Obtener fotos** (en [Mantenimiento](https://docs.finance.kobana.com.br/es/es/manutencao/.md)) pasa a intentar la foto de WhatsApp de los contactos. ## Qué hace — y qué no hace[​](#qué-hace--y-qué-no-hace "Enlace directo al Qué hace — y qué no hace") nota **Esta integración no muestra ninguna foto por sí sola.** Es una **fuente** para la búsqueda de fotos, no un recurso autónomo. Sin ella, la búsqueda usa **solo Gravatar** — *"y raramente tiene una foto para un número brasileño"*, que es justamente el motivo por el que la integración existe. La foto encontrada se **guarda** en el registro de la persona. No se busca en cada visita, ni a escondidas: solo cuando alguien ejecuta **Obtener fotos**. **La foto aparece en [Personas](https://docs.finance.kobana.com.br/es/es/pessoas/.md)** — en el listado y en el detalle. **No** aparece en las pantallas de cuentas por pagar o por cobrar. ## Configuración por empresa[​](#configuración-por-empresa "Enlace directo al Configuración por empresa") Las credenciales son **por empresa**, no por espacio de trabajo — cada una puede tener su propia instancia. Sin una empresa seleccionada, la página no muestra la configuración: se queda en **"Selecciona una empresa"**. **La empresa viene del selector del encabezado**, no de un paso dentro de la página. Son **tres** campos, y el botón solo se habilita con los tres completos: | Campo | Ejemplo | | ------------------------ | -------------------------------------------------------------------------------------- | | **URL de Evolution API** | `https://evolution.example.com` | | **Nombre de instancia** | `mi-instancia` | | **Clave API** | La clave de la instancia. *"La clave se almacena cifrada y nunca se devuelve en GET."* | El botón es **"Conectar"** — o **"Actualizar"**, si ya hay credenciales. ## Privacidad y seguridad[​](#privacidad-y-seguridad "Enlace directo al Privacidad y seguridad") * La **Clave API se cifra** en reposo y nunca se devuelve en la lectura. * El sistema **rechaza destinos privados**: direcciones de loopback, redes internas y link-local están bloqueadas, lo que impide usar la integración para alcanzar servicios de la infraestructura. aviso **No es obligatorio que sea HTTPS.** `http://` se acepta — lo que el sistema rechaza es el **destino**, no el protocolo. Aun así, un endpoint en HTTP transporta la Clave API en claro: prefiere HTTPS. ## Obtener fotos[​](#obtener-fotos "Enlace directo al Obtener fotos") La búsqueda es **manual**, en [Mantenimiento](https://docs.finance.kobana.com.br/es/es/manutencao/.md) → **Obtener fotos**. No hay worker periódico. Cada ejecución: * Intenta **Gravatar primero** (por el correo) y **WhatsApp después** (por el teléfono), parando en la primera fuente que responda. * Recorre **solo a quien todavía no tiene foto** — a quien ya la tiene se lo omite. * Procesa como máximo **100 personas por vez**. * Espera **30 días** antes de reintentar con quien falló. ## Eliminar[​](#eliminar "Enlace directo al Eliminar") El botón es **"Eliminar"**. La confirmación dice el efecto exacto: *"Las credenciales de la empresa serán eliminadas. La próxima ejecución de 'Obtener Fotos' para esta empresa omitirá WhatsApp — solo Gravatar."* Las fotos **ya obtenidas continúan** en el registro: eliminar la credencial no borra lo que se encontró. --- # Transacciones Las transacciones (`/financial-transactions`) son los movimientos de las cuentas financieras: entradas y salidas de dinero. Son la base de la conciliación con cuentas por pagar y por cobrar. ![Lista de transacciones](/es/assets/images/05-transactions-edd1f19f02ac46e2bfe2e53b685183a0.png) ![Detalle de transacción](/es/assets/images/06-transaction-detail-e0d47adc5b4e4cd931f285fb4a753356.png) ## En esta sección[​](#en-esta-sección "Enlace directo al En esta sección") ## [📄️Importación CSV](https://docs.finance.kobana.com.br/es/es/lancamentos/importacao-csv.md) [Importar transacciones en lote desde una planilla — dentro de la cuenta financiera, con encabezado en portugués.](https://docs.finance.kobana.com.br/es/es/lancamentos/importacao-csv.md) ## La lista[​](#la-lista "Enlace directo al La lista") El encabezado trae tres totales — **Entradas**, **Salidas** y **Neto** — con flecha verde para la entrada y roja para la salida. nota **Los totales son del encabezado, no del pie, y tienen su propio alcance.** Suman **empresa + período** y nada más: buscar por texto o aplicar filtros **no los acota**. Filtrar por una categoría y ver que el total sigue igual no es un defecto — la franja responde "cuánto entró y salió en el período", no "cuánto muestra la lista". ### Filtros[​](#filtros "Enlace directo al Filtros") * **Búsqueda** — por descripción o documento. * **Filtros rápidos** — **Todos**, **Con adjuntos**, **Conciliado**, **Transferencias**. * **Filtros avanzados** — aceptan cláusulas **negativas**, no solo positivas. Son de dos tipos: píldoras que existen en las dos formas (**Conciliado** / **No conciliado**, **Transferencias** / **Sin transferencias**, **Con adjuntos** / **Sin adjuntos**), y la opción **Sin categoría** dentro del selector de categorías — lo mismo vale para **Sin cliente / proveedor** y **Sin centro de clasificación**. Elegir categorías siempre **incluye**: no hay forma de excluir una categoría específica. Al lado de la franja de totales está además **Exportar** — que no es un filtro, sino una acción: genera el archivo de exportación de las transacciones. ### Columnas[​](#columnas "Enlace directo al Columnas") Descripción, Fecha, Categoría, Cuenta y Monto — más **Empresa**, solo en la vista consolidada. **Método de pago** existe como columna activable, y la última columna es una **ficha** de la transacción (vínculos, persona, documento, competencia, distribución, notas), visible en el escritorio. **Método de pago es de solo lectura.** Ese campo no existe en el formulario: la columna solo muestra lo que llegó por **CSV o API**. Al crear una transacción desde la pantalla, queda vacía. ### Las etiquetas de la columna Descripción[​](#las-etiquetas-de-la-columna-descripción "Enlace directo al Las etiquetas de la columna Descripción") No existe un campo "Origen". La procedencia es **derivada** y aparece como iconos al lado de la descripción: | Etiqueta | Significa | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | **Conciliado** | Vinculada a una cuenta por pagar o por cobrar | | **Generado por liquidación de…** | Creada por la liquidación de una cuenta por pagar o por cobrar | | **Transferencia** | Una de las patas de una transferencia | | **Provisional** | Todavía no efectivada | | **Clip** | Tiene adjuntos | | **Tarjeta** | Una compra de [tarjeta](https://docs.finance.kobana.com.br/es/es/cartoes/.md), con el proveedor y el resumen debajo | | **Pago de resumen** · **Recarga** | Las puntas de la transferencia que paga el resumen de una tarjeta o recarga una prepago | ### Acciones[​](#acciones "Enlace directo al Acciones") Por fila: **Clasificar**, **Conciliar**, **Editar** y **Eliminar**. En lote: **Conciliar seleccionados**, **Clasificar seleccionados** y **Eliminar**. nota **Conciliar y Clasificar en lote exigen una sola empresa.** Las categorías y las cuentas por pagar/cobrar son por empresa, así que una selección que mezcla empresas no puede abrir el diálogo — en la vista consolidada, el sistema avisa y cancela en vez de elegir una empresa por su cuenta. **Clasificar** pide además que la selección sea toda del mismo tipo: entradas y salidas juntas también se rechazan, porque las categorías de unas no sirven para las otras. **Eliminar** no tiene ninguna de esas trabas — borra la selección tal como esté. ## Campos[​](#campos "Enlace directo al Campos") | Campo | Observaciones | | ------------------------------------------- | ----------------------------------------------------- | | **Monto (R$)** | Obligatorio | | **Fecha** | Obligatorio | | **Cuenta financiera** | Obligatorio — donde ocurrió el movimiento | | **Descripción** | Obligatorio | | **Mes de competencia** | Selector de mes | | **Tipo de registro** | Crédito o débito | | **Categoría** · **Centro de clasificación** | Clasificación, cada una con el atajo **Distribución** | | **Cliente / Proveedor** | Persona asociada | | **Número de documento** · **Fecha doc.** | El documento externo | | **Provisional** | Marca la transacción como una previsión | | **Notas** | Texto libre | | **Adjuntos** | Archivos ligados a la transacción | ### Provisional[​](#provisional "Enlace directo al Provisional") La píldora **"Provisional"** marca la transacción como una previsión, todavía no efectivada. **Aparece en la lista con su etiqueta, pero no entra en el saldo de la cuenta ni en los números realizados de la visión general** — cuenta en la **proyección** del flujo de caja, no en lo realizado. ## Creación automática[​](#creación-automática "Enlace directo al Creación automática") Algunas transacciones no las escribes tú — las crea el sistema: * **Liquidación de una cuenta por pagar** → salida en la cuenta elegida. * **Liquidación de una cuenta por cobrar** → entrada en la cuenta elegida. * **Transferencia** → salida en el origen y entrada en el destino. * **Extracto bancario importado**, al confirmar la importación. * **Sincronización del Gateway Bancario**. * **Compra con tarjeta** → salida en la cuenta de la tarjeta, en la fecha de la compra, cuando el movimiento de la tarjeta se realiza. La gestiona la tarjeta: editar, clasificar, conciliar y eliminar quedan deshabilitados aquí, con el motivo, y **"Abrir en la tarjeta"** lleva a su resumen. Lo mismo vale para el pago del resumen y la recarga — ver [Tarjetas](https://docs.finance.kobana.com.br/es/es/cartoes/.md#la-tarjeta-y-tus-cuentas). ## Conciliación[​](#conciliación "Enlace directo al Conciliación") Una transacción puede vincularse con cuentas por pagar y por cobrar. El vínculo aparece en el detalle de la transacción y en la pantalla de [Conciliación](https://docs.finance.kobana.com.br/es/es/conciliacao/.md), que cierra, línea a línea, lo que llegó del extracto. --- # Importación CSV — Transacciones Importa transacciones en lote desde un archivo CSV. ## Dónde está[​](#dónde-está "Enlace directo al Dónde está") **No existe "Importación" en el menú**, ni una pantalla de importación. Y, al contrario de lo que cabría esperar, **la pantalla de Transacciones no importa** — la importación vive dentro de la cuenta: **Cuentas financieras** → abre la cuenta → píldora **Importar**. nota **No hay selector de cuenta de destino.** La cuenta es aquella en la que ya estás: todas las transacciones del archivo entran en ella. Para importar en dos cuentas, son dos importaciones. Hace falta tener una **empresa específica** seleccionada en el encabezado, y **la cuenta tiene que estar vinculada a una empresa**. En los dos casos el panel avisa: *"Selecciona una empresa específica para importar transacciones."* El botón **Descargar plantilla** entrega un CSV de ejemplo con el encabezado correcto — es el punto de partida más seguro, porque ya viene con la codificación correcta. ## Columnas del CSV[​](#columnas-del-csv "Enlace directo al Columnas del CSV") | Columna | Obligatorio | Descripción | | -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | ✅ | Fecha de la transacción | | `descricao` | ✅ | Descripción de la transacción | | `valor` | ✅ | Monto en reales, siempre positivo | | `tipo` | ✅ | `entrada` (crédito) o `saida` (débito) | | `categoria` | — | Nombre de la categoría (si todavía no existe, la vista previa pregunta si crearla). También acepta: `plano_de_contas`, `categoria_financeira`, `category` | | `pessoa` | — | Nombre de la persona (si todavía no existe, la vista previa pregunta si crearla). También acepta: `cliente_fornecedor`, `cliente`, `fornecedor`, `favorecido`, `contraparte` | | `centro_custo` | — | Nombre del centro de clasificación (si todavía no existe, la vista previa pregunta si crearlo). También acepta: `centro_de_custo`, `centro_de_receita`, `centro_de_classificacao`, `centro_de_resultado`, `centro`, `cost_center` | | `documento` | — | Identificador del documento | | `observacao` | — | Notas | aviso **El encabezado de este archivo es en portugués, y solo en portugués.** A diferencia del CSV de cuentas por pagar y por cobrar — que acepta tanto `description` como `descricao` —, aquí los nombres canónicos **ya son** los portugueses y **las columnas obligatorias no tienen equivalente en inglés**. Un archivo con `description`, `amount` y `date` se rechaza entero, por falta de una columna obligatoria. Mayúsculas, acentos y espacios en el encabezado no importan: `Centro de Receita` vale como `centro_de_receita`. Si el espacio tiene un clasificador con el mismo nombre que una de estas columnas (ej.: *Centro de Resultado*), la columna va al clasificador. Si la planilla tiene más de una columna para el mismo campo (p. ej.: `Centro de Custo` y `Centro de Receita`), cada línea usa la primera que esté completa. Además de esos nombres, un encabezado con la palabra **centro** se lee como centro de clasificación; uno con **categoria** o **plano de contas**, como categoría (por ejemplo, `Centro de Lucro`, `Categoria DRE`); y uno con **pessoa**, **cliente** o **fornecedor** acompañada solo de palabras de nombre, como persona (por ejemplo, `Nome do Fornecedor`, `Cliente / Fornecedor` — pero no `CNPJ do Fornecedor`). Las columnas que el sistema no conoce se **ignoran en silencio**. ## Formato[​](#formato "Enlace directo al Formato") * **Encabezado** — las mayúsculas, los acentos y los espacios no importan: `Descrição`, `DESCRICAO` y `descricao` son la misma columna. * **Separador** — `,` o `;`, detectado **por la línea de encabezado**. En caso de empate, `;`. * **Fechas** — `31/12/2026`, `31-12-2026` o `2026-12-31`. * **Montos** — `1234.56`, `1.234,56`, `1234,56`, con o sin `R$`. El monto tiene que ser **mayor que cero**: quien decide si es entrada o salida es la columna `tipo`, nunca el signo del monto. aviso **La codificación tiene que ser UTF-8, y es aquí donde tropieza la mayoría de los archivos.** Excel en portugués guarda el CSV en Windows-1252 por defecto, y el sistema lo rechaza con un mensaje que permanece en portugués: *"Arquivo não está em UTF-8. Salve novamente em UTF-8 e tente novamente."* ("El archivo no está en UTF-8. Guárdalo de nuevo en UTF-8 e inténtalo otra vez.") En Excel, usa **Guardar como → CSV UTF-8**; o parte de la plantilla descargada. Otros rechazos del archivo entero: una extensión distinta de `.csv`, un tamaño superior a **5 MB**, un archivo vacío, y **columna obligatoria ausente** — *"Colunas obrigatórias ausentes: tipo"* ("Faltan columnas obligatorias: tipo"). En esos casos no hay vista previa: el problema es del archivo, no de una línea. ## Importar[​](#importar "Enlace directo al Importar") 1. Sube el archivo. El sistema lo lee y muestra la vista previa. 2. **Las líneas válidas ya vienen marcadas.** Haz clic en una línea para desmarcarla. 3. Haz clic en **Importar N líneas**. ### Líneas con error[​](#líneas-con-error "Enlace directo al Líneas con error") Las líneas inválidas aparecen en la vista previa con un marcador rojo, **y no se pueden seleccionar ni editar ahí**. No hay corrección dentro del sistema. La propia pantalla indica el camino: *"Desmarca las filas con errores o corrígelas en el archivo y vuelve a subirlo."* El número en **Fila N** es el número de la línea **en el archivo**, contando el encabezado — la primera línea de datos es la 2. ### La grabación corre en segundo plano[​](#la-grabación-corre-en-segundo-plano "Enlace directo al La grabación corre en segundo plano") Al confirmar, recibes *"Importación iniciada en segundo plano"* y un diálogo de progreso. **Puedes cerrar el diálogo** — la importación continúa, y el progreso queda visible en la esquina inferior derecha. ### Vínculos[​](#vínculos "Enlace directo al Vínculos") **Las personas, categorías y centros de clasificación aparecen en la vista previa**, cada uno con lo que hará la importación: los que ya existen se vinculan; los nuevos vienen marcados para **crear** (o para **dejar en blanco**, si no tienes permiso para crearlos); un nombre que solo cambia en acentos, mayúsculas o espacios respecto de uno existente viene marcado para **usar el existente**; y un centro de clasificación que solo existe del otro lado (ej.: uno del tipo Costo en un crédito) viene marcado para dejar en blanco. La persona se busca solo por el nombre, sea cliente o proveedor, y pasa a tener el papel de las líneas en que aparece (cliente en los créditos, proveedor en los débitos); una persona nueva usada en créditos y débitos se crea una sola vez, como cliente y proveedor. Un centro de clasificación nuevo usado en créditos y débitos se crea una sola vez, del tipo Ambos. Las grafías del mismo nombre que solo cambian acento, mayúscula o espacio (p. ej.: *Água e Luz* y *agua e luz*) cuentan como un solo nombre. Puedes cambiar cualquier elección antes de importar. Las [reglas automáticas](https://docs.finance.kobana.com.br/es/es/regras-automaticas/.md) se aplican a los registros importados. ## Historial[​](#historial "Enlace directo al Historial") Debajo del panel, la sección **Historial** lista las importaciones con fecha, archivo, estado (**En cola**, **En progreso**, **Completado**, **Fallido**, **Cancelado**), cuántas filas entraron del total y quién la pidió. --- # Mantenimiento **Mantenimiento** (`/settings/maintenance`) reúne las herramientas de higiene de los datos de **personas**: estandarizar teléfonos y nombres, encontrar duplicados, limpiar registros vacíos y obtener fotos. Y una de **movimientos**: unir los que una importación registró dos veces. ## Alcance[​](#alcance "Enlace directo al Alcance") nota **Las herramientas actúan sobre una empresa a la vez.** El alcance viene del selector superior, y la pantalla avisa: *"Aplicado solo a la empresa seleccionada."* En **"Consolidado"**, te pide elegir una antes de ejecutar cualquier cosa. ## Las seis herramientas[​](#las-seis-herramientas "Enlace directo al Las seis herramientas") | Herramienta | Qué hace | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Ajustar teléfonos** | Clasifica cada teléfono como móvil o fijo según las reglas de Anatel — 11 dígitos con el tercero igual a 9 es móvil; 10 dígitos con el tercero entre 2 y 5 es fijo. Lo que no encaja queda como no clasificable | | **Normalizar nombres** | Convierte los nombres de las personas a mayúsculas, **preservando los acentos** | | **Detectar duplicados** | Busca registros repetidos por **Mismo nombre**, **Nombre + apellido**, **Mismo email**, **Mismo teléfono** o **Mismo documento**, y los agrupa para que los fusiones | | **Limpiar personas vacías** | Lista las personas **sin CPF/CNPJ, sin correo, sin teléfono y sin transacciones vinculadas**, para eliminarlas | | **Obtener fotos** | Busca la foto de cada persona en **Gravatar** (por el correo) y en **WhatsApp** (cuando el número es público y la empresa tiene credenciales de Evolution). **Quien ya tiene foto se omite** | | **Deduplicar movimientos** | En una cuenta, une los movimientos que la importación del ERP (Fintera, Nibo) y el extracto del banco (Gateway Bancario, Open Finance o un OFX subido) registraron dos veces | | **Eliminar movimientos de una fuente** | Elimina los movimientos que trajo una integración — Fintera, Nibo, Conta Azul, Open Finance o Gateway Bancario —, en toda la empresa o en una cuenta, para reiniciar la importación | ## Nada corre solo[​](#nada-corre-solo "Enlace directo al Nada corre solo") **Estas herramientas no son programables: corren cuando haces clic, y solo entonces.** No hay ejecución periódica ni disparador automático — ninguna de ellas se lanza al crear una persona o al importar un archivo. Eso no quiere decir que la pantalla se bloquee mientras trabajan: una vez iniciadas, algunas **se ejecutan en segundo plano y muestran el progreso ahí mismo**. Las dos cosas conviven — lo que no existe es la **programación**, no la asincronía. ## Fusionar duplicados[​](#fusionar-duplicados "Enlace directo al Fusionar duplicados") Detectados los grupos, eliges cuáles fusionar. En cada grupo, un registro queda marcado como **Sobreviviente** — es el que se queda, recibiendo los datos y los vínculos de los demás. El botón es **"Fusionar seleccionados"**, y la confirmación dice cuántos grupos se van a procesar y cuántas personas se fusionarán en el sobreviviente. nota **Fusionar no toca las reglas de [Seguridad](https://docs.finance.kobana.com.br/es/es/seguranca/.md#beneficiarios).** Las listas de beneficiarios liberados y bloqueados, y los límites de cada uno, son por **CPF/CNPJ**, no por registro: el documento bloqueado sigue bloqueado y el liberado sigue liberado después de la fusión. Si los registros fusionados tenían documentos distintos, revisa en Seguridad cuál de ellos está en la regla. ## Limpiar personas vacías[​](#limpiar-personas-vacías "Enlace directo al Limpiar personas vacías") La lista muestra cada persona vacía y cuándo fue registrada, con **"Seleccionar todo"** y **"Eliminar seleccionados"**. peligro **La eliminación es la misma de [Personas](https://docs.finance.kobana.com.br/es/es/pessoas/.md), y es irreversible.** La confirmación es explícita — *"Esta acción no se puede deshacer desde la interfaz."* Los registros desaparecen de las pantallas, su historial financiero permanece, y el CPF/CNPJ queda liberado. ## Obtener fotos[​](#obtener-fotos "Enlace directo al Obtener fotos") Ver [Personas](https://docs.finance.kobana.com.br/es/es/pessoas/.md) para saber cómo se elige la foto y dónde aparece. En resumen: **Gravatar primero, WhatsApp como respaldo**, tope de 100 personas por ejecución, y quien falló espera **30 días** antes del siguiente intento. ## Deduplicar movimientos[​](#deduplicar-movimientos "Enlace directo al Deduplicar movimientos") Cuando la misma cuenta recibe el historial del ERP **y** el extracto del banco — automático o por archivo OFX/QIF —, cada movimiento puede haber entrado dos veces — una copia clasificada, del ERP, y una cruda, del extracto. Las importaciones de hoy ya reconocen el mismo movimiento y no lo duplican más; esta herramienta limpia lo que entró dos veces antes de eso. Elige la **cuenta** y haz clic en **"Buscar duplicados"**. La pantalla dice cuántos movimientos se unirán y lista los pares: el que **queda** y el que **sale**, con el origen de cada uno. **Es el mismo movimiento** cuando los dos están en la misma cuenta, con la misma dirección, el mismo valor y el mismo día, y los documentos (el código del banco) no se contradicen. **Queda la copia del ERP**, con la descripción y la clasificación que hizo el equipo financiero. **La del extracto sale**, y antes le pasa a la que queda: * el vínculo con el banco — la próxima lectura del extracto encuentra la línea que quedó y no crea otra; * el título pagado o cobrado, la conciliación, los adjuntos y los elementos de la bandeja de entrada; * lo que a la que queda le faltaba: texto y código del banco, categoría, persona, centro, observación, prorrateos. nota **Un par cuyos dos lados ya están vinculados a cosas distintas** — dos títulos, dos conciliaciones o dos transferencias — **queda fuera** y aparece marcado en la lista. Elegir uno perdería el otro; resuélvelo a mano. peligro **La unión elimina el movimiento del extracto y no se puede deshacer.** Revisa los pares antes de confirmar. ## Eliminar movimientos de una fuente[​](#eliminar-movimientos-de-una-fuente "Enlace directo al Eliminar movimientos de una fuente") Para reiniciar la importación de una integración, o limpiar lo que una fuente registró dos veces. Elige la **fuente** (Fintera, Nibo, Conta Azul, Open Finance o Gateway Bancario) y, si quieres, una **cuenta** — sin cuenta, vale para toda la empresa — y haz clic en **"Buscar movimientos"**. La pantalla dice cuántos se eliminarán, el período y cuántos por cuenta. Un movimiento es de la fuente cuando vino de ella. **Se quedan, y la pantalla dice cuántos:** * los que **también vinieron de otra fuente** (el mismo movimiento reconocido en el extracto y en el ERP): eliminarlo se llevaría los datos de la otra; * los **ligados a un título** (pago), a una **conciliación**, a una **transferencia**, a una **tarjeta** o generados por un pago. Cada uno se deshace por su propio flujo. Lo que se elimina se lleva su clasificación y sus adjuntos, y **no se puede deshacer**. La eliminación **no impide** que la integración traiga los movimientos de nuevo: en la próxima lectura vuelven, y así se reinicia. Corre en lotes de 500, con el avance en pantalla. ## ¿Y la configuración de la cuenta?[​](#y-la-configuración-de-la-cuenta "Enlace directo al ¿Y la configuración de la cuenta?") No existe una pantalla única de "Configuración" en el producto — cada configuración tiene su propio ítem en el grupo **Sistema** del menú, como **Integraciones**, **Seguridad** y **Mantenimiento**. * Los datos de tu cuenta y cómo funciona el inicio de sesión: [Mi perfil](https://docs.finance.kobana.com.br/es/es/meus-dados/.md). * Conexiones con plataformas externas: [Integraciones](https://docs.finance.kobana.com.br/es/es/integracoes/.md). * Reglas antifraude para pagos y transferencias: [Seguridad](https://docs.finance.kobana.com.br/es/es/seguranca/.md). --- # Autenticación El servidor MCP acepta un **Bearer token** en el encabezado `Authorization`, y nada más — sin cookie, sin certificado de cliente, **sin token en la URL**. Una solicitud con `?access_token=` (o `?token=`, `?api_key=` y similares) se rechaza con `401` y `error="invalid_request"`, incluso junto a un encabezado válido: en la URL el token se filtra a logs, historial del navegador e intermediarios. Ese token es un **access token OAuth 2.1 emitido por el Authorization Server de Kobana** (`https://account.kobana.com.br`), un JWT firmado en RS256 y emitido **para este recurso**: su `aud` es `https://mcp.finance.kobana.com.br`. Llega por uno de dos caminos — el flujo OAuth, que hace el propio cliente, o un **token personal** que creas en tu Cuenta Kobana — y se verifica de la misma forma en los dos casos. ``` Authorization: Bearer eyJhbGciOiJSUzI1NiIs… ``` :::info Cada superficie tiene su audience Un token emitido para el MCP **no vale** en la API REST (`api.finance.*`), y un token de la API no vale aquí. Es lo que impide que el token entregado a un asistente se reutilice contra la API — y al revés. ::: ## Dos formas de conectar[​](#dos-formas-de-conectar "Enlace directo al Dos formas de conectar") | | Flujo OAuth | Token personal | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Cómo lo obtienes | Pegas la URL en el cliente; abre el login de Kobana y autorizas | Lo creas en **Cuenta Kobana → Tokens y Acceso → Nuevo Token Personal**: app **Finanzas Inteligentes**, uso **MCP**, recursos y accesos, validez | | Cómo lo usa el cliente | Solo, después de la autorización | Lo pegas en el cliente como `Authorization: Bearer ` | | Validez | Corta, renovada por el cliente | De 7 días a 1 año, elegida por ti | | Scope | Los recursos de Finanzas Inteligentes y los niveles de acceso que apruebas, uno a uno, en la pantalla de consentimiento | Los recursos y accesos que marcaste | | Bueno para | Claude, ChatGPT, IDEs y cualquier cliente con OAuth | Clientes sin soporte a OAuth y scripts | El token personal tiene que crearse con el uso **MCP**. Un token creado para **API REST** tiene la audience de la API y aquí se rechaza con `401` — y lo contrario también vale. ## El workspace[​](#el-workspace "Enlace directo al El workspace") El `org` del token indica la organización; el **workspace** en el que actúa cada tool se decide **en cada llamada**, en este orden: | Orden | De dónde viene | | ----- | ------------------------------------------------------------------ | | 1 | El argumento `workspace_id` de la tool, cuando viene en la llamada | | 2 | El workspace predeterminado de la conexión (abajo) | | — | Ninguno de los dos: la tool devuelve el error `workspace_required` | La URL del servidor no necesita workspace — `https://mcp.finance.kobana.com.br` basta —, y conectarse nunca falla por falta de uno. Para saber dónde puede actuar, el agente llama a `finance_workspaces_list`, sin argumentos: lista los workspaces de la organización que alcanza la persona del token. ``` { "data": [ { "id": "2b93f876-769a-4bdc-b23e-304957f313b4", "name": "Matriz", "default": true }, { "id": "7c1d0e52-…", "name": "Filial Sul", "default": false } ] } ``` Todas las demás tools — salvo `finance_me`, `finance_organization_get`/`_update` (de nivel de organización: valen para toda la organización), `finance_schemas_get` y la propia `finance_workspaces_list` — aceptan el argumento opcional `workspace_id` (uuid): ``` { "name": "finance_payables_list", "arguments": { "workspace_id": "2b93f876-769a-4bdc-b23e-304957f313b4", "limit": 10 } } ``` ### El workspace predeterminado[​](#el-workspace-predeterminado "Enlace directo al El workspace predeterminado") Es el que vale cuando la llamada no trae `workspace_id`, y es el que aparece marcado `default: true` en `finance_workspaces_list`: | Dónde | Ejemplo | | ------------------------------------------- | --------------------------------------------------------------------- | | Encabezado `X-Workspace-Id` (opcional) | `X-Workspace-Id: 2b93f876-769a-4bdc-b23e-304957f313b4` | | Parámetro en la URL del servidor (opcional) | `https://mcp.finance.kobana.com.br/?workspace_id=2b93f876-…` | | Ninguno de los dos | El único workspace que alcanza la persona, si alcanza exactamente uno | El encabezado y el parámetro de URL se siguen aceptando, pero ahora son **opcionales y solo definen el predeterminado**: el argumento `workspace_id` siempre les gana. En cualquier caso el valor es **selector, no concesión** — se verifica contra la organización del token y el acceso de la persona: * Sin `workspace_id` y sin predeterminado — la persona alcanza varios workspaces —, la tool devuelve `workspace_required`. Es un resultado de tool con `isError: true`, no un error HTTP: ``` { "error": { "code": "workspace_required", "message": "…" } } ``` * Un `workspace_id` que la persona no alcanza, o que no existe, devuelve el error de tool `workspace_access_denied` — la misma respuesta en ambos casos. * Un encabezado o parámetro de URL con un workspace de otra organización sigue rechazado con HTTP `403` `UNKNOWN_WORKSPACE`. * Un predeterminado de la conexión que es de la organización, pero que la persona no alcanza, no bloquea nada: `tools/list` sigue listando lo que puede ejecutar en algún workspace, y una llamada con un `workspace_id` válido se ejecuta. Solo la llamada que depende de ese predeterminado devuelve `workspace_access_denied`. Los resources (`kobana://finance/…`) y las completions no tienen argumento de workspace: usan el predeterminado de la conexión. Sin él, leer un resource de registro falla con `workspace_required` — usa las tools —, y las completions no sugieren nada. Ver [Resources y prompts](https://docs.finance.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md). ## El flujo OAuth[​](#el-flujo-oauth "Enlace directo al El flujo OAuth") No ejecutas ninguno de estos pasos: el cliente MCP (Claude, ChatGPT, un IDE) lo hace todo solo a partir de la URL. Están aquí para cuando algo falle a mitad de camino. 1. **Desafío.** Una solicitud sin token recibe `401` con el desafío que todo resource server OAuth 2.1 debe enviar ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)): ``` WWW-Authenticate: Bearer realm="kobana-finance-mcp", error="invalid_token", resource_metadata="https://mcp.finance.kobana.com.br/.well-known/oauth-protected-resource" ``` 2. **Metadata del recurso.** El cliente lee el documento apuntado. Es público y no lleva ningún secreto — solo punteros: ``` 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` es exactamente lo que el cliente pide en la pantalla de consentimiento: un `finance/{recurso}` por recurso de Finanzas Inteligentes — los de dinero incluidos (`finance/payable_dispatches`, `finance/receivable_charges`) — y todo nivel de acceso que emite la Cuenta Kobana: `read`, `write`, `delete`, `import` y `export`. Tú decides, nivel a nivel, qué conceder. El token que el cliente recibe lleva los recursos aprobados, así que son ellos los que definen el alcance (ver el eje 1 abajo). Queda fuera solo el comodín de recurso, `finance/all` o `all` (los dos son lo mismo). `resource_name` es el nombre del producto y `kobana_scopes` da, para cada scope de recurso de Finanzas Inteligentes (`finance/all` incluido), el texto que la Cuenta Kobana muestra en la pantalla de consentimiento, en portugués. El cliente MCP no necesita leer estos dos miembros. 3. **Metadata del Authorization Server** ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)), en `https://account.kobana.com.br/.well-known/oauth-authorization-server`. 4. **Registro dinámico del cliente** ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)). El cliente se registra solo; la pantalla de consentimiento avisa que no es una app verificada. 5. **Autorización con PKCE y `resource`** ([RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707)). Inicias sesión en Kobana, eliges la organización (si tienes más de una) y autorizas. 6. **Token.** El cliente cambia el código por un access token de vida corta y pasa a enviarlo en cada solicitud, renovándolo cuando expira. El token lleva quién eres (`sub`) y la organización que autorizaste (`org`); el workspace viene de cada llamada, como arriba. Ninguna tool acepta organización como argumento. ## Dos ejes de autorización[​](#dos-ejes-de-autorización "Enlace directo al Dos ejes de autorización") Lo que ve un llamador es **más estrecho** que el catálogo, por dos filtros independientes. Ninguno de los dos puede *ampliar* la superficie. ### Eje 1 — el scope del token[​](#eje-1--el-scope-del-token "Enlace directo al Eje 1 — el scope del token") El techo del cliente, en el claim `scope`. Cada tool exige **un** nivel de acceso — el mismo que exige el endpoint de la API que llama: la lectura (tool de lectura, resource, prompt y completion) exige `read`; las tools de eliminación (`*_delete`) exigen `delete`; todo lo demás que altera datos exige `write` — incluso `finance_attachments_unlink`, que deshace un vínculo y no borra nada, y las tools que mueven dinero. Ningún nivel sustituye a otro: `write` no elimina, y `delete` no escribe. **Token con recursos** — el caso del token del flujo OAuth y del token personal. Los recursos definen hasta dónde llega el token, y los niveles valen solo dentro de ellos: | Scope del token | Resultado | | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance/payables finance/people read write` | Lee y escribe cuentas por pagar y personas — no elimina, y no alcanza nada más | | `finance/payables read write delete` | Lee, escribe y elimina cuentas por pagar | | `finance/payables read` | Solo lee cuentas por pagar | | `finance/all read` | Lee todo, no escribe nada | | `finance/all write` | Lee y escribe todo, incluidos enviar al banco y cobrar (el comodín alcanza los recursos de dinero) — pero no elimina | | `finance/payables finance/payable_dispatches read write` | Escribe cuentas por pagar y las envía al banco — por el MCP, solo con un token de hasta 24 horas: ver [Mover dinero por el MCP](#mover-dinero-por-el-mcp) | Enviar al banco y cobrar son `write` en su propio recurso — `finance/payable_dispatches` y `finance/receivable_charges`; `finance/payables write` no basta. **Token sin recursos** — un token que solo lleva el nivel de acceso, sin ningún scope `finance/…` ni `all` (o solo con recursos de otra app), **no alcanza nada**: solo responde `finance_me`. `all` no es un nivel: es el comodín de recurso, como `finance/all` — solo lee, y los verbos vienen explícitos (`all write`). :::info Los clientes conectados por el flujo OAuth alcanzan lo que aprobaste El documento `/.well-known/oauth-protected-resource` anuncia todos los recursos de Finanzas Inteligentes y todos los niveles de acceso, y es lo que el cliente (Claude, ChatGPT, el MCP Inspector, IDEs) pide en la pantalla de consentimiento; el token que recibe lleva los recursos y los niveles que aprobaste. El MCP lista solo las tools que el token alcanza; una tool fuera de él vuelve `insufficient_scope`, y la salida es autorizar de nuevo concediendo el acceso que faltó — `delete` para eliminar, el recurso de dinero para enviar al banco o cobrar. ::: La misma regla vale en la API REST — ver [Alcances](https://docs.finance.kobana.com.br/es/es/api/overview/authentication.md#alcances-scopes). ### Eje 2 — los permisos de la persona del token[​](#eje-2--los-permisos-de-la-persona-del-token "Enlace directo al Eje 2 — los permisos de la persona del token") El `sub` del token es la persona que consintió. **En el MCP, las tools se estrechan a lo que esa persona puede hacer en el panel de la organización**, resuelto en cada solicitud — las mismas funciones y permisos de la pantalla **Miembros**. | Situación | Resultado | | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | La persona nunca entró a Finanzas Inteligentes, o no es miembro de la organización | **Niega todas las tools.** Quien no es miembro no alcanza nada por el MCP. | | Miembro activo, con acceso al workspace | Sus permisos, tool por tool. El dueño (`*`) libera todo; `payables.*` libera la familia. | | Miembro activo **sin acceso al workspace** | **Niega todas las tools** de ese workspace. | | Miembro suspendido, con invitación pendiente, eliminado o sin ningún permiso | **Niega todas las tools.** Un token que sobrevive al acceso de la persona es justo el caso a cerrar. | | La consulta de permisos falla | **Niega todas las tools.** Falla cerrada. | Los permisos se leen en cada llamada: quitar un permiso en el panel vale desde la siguiente tool, sin esperar a que el token expire. :::tip Postura recomendada para agentes Conecta el asistente con una cuenta que solo tiene los permisos que el agente necesita y, en un token personal, marca solo los recursos y accesos que va a usar. Los dos ejes se suman: el token de un analista de solo lectura expone solo las tools de lectura, haga lo que haga el modelo del otro lado. ::: ### Cómo se componen los dos[​](#cómo-se-componen-los-dos "Enlace directo al Cómo se componen los dos") El conjunto final es la **intersección**: `tools ∩ scopes del token ∩ permisos de la persona`. Una tool que el llamador no puede ejecutar **no se lista**. Cuando `tools/call` rechaza, el código dice **quién lo resuelve**: | Código | Quién lo resuelve | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `insufficient_scope` | Usar un token que alcance el recurso con el acceso pedido — por ejemplo, un token personal con escritura en ese recurso. | | `insufficient_permission` | Un admin de la organización, concediendo el permiso (el error lo nombra). | | `workspace_required` | El agente pasa `workspace_id` — uno de los `id` de `finance_workspaces_list` —, o la conexión define un [workspace predeterminado](#el-workspace-predeterminado). | | `workspace_access_denied` | Un admin concede el workspace a la persona, o el agente pasa otro `workspace_id`. | | `membership_inactive` | Incluir a la persona en la organización o reactivarla — ningún permiso arregla una membresía que no existe o está inactiva. | | `token_not_accepted` | La tool mueve dinero y el token vive más de 24 horas (todo token personal): conecta por el flujo OAuth, o mueve dinero por la API REST o por la app — ver [Mover dinero por el MCP](#mover-dinero-por-el-mcp). O la llamada es destructiva y el token fue verificado por la clave fija provisional: conecta por el flujo OAuth o con un token personal. | :::caution Lo que el eje 2 no cubre El estrechamiento por permiso vale **solo para el MCP**. Un token de la API, llamado directo en `api.finance.*`, sigue limitado solo por sus scopes. ::: ### Seguridad › Canales[​](#seguridad--canales "Enlace directo al Seguridad › Canales") Las reglas de la pestaña [Seguridad › Canales](https://docs.finance.kobana.com.br/es/es/seguranca/.md#canales) siguen valiendo por encima de los dos ejes — las aplica el propio endpoint. Un agente de IA actúa por el canal **MCP - Inteligencia Artificial**, donde, por defecto, **enviar al banco empieza cerrado**: `finance_payables_send_to_bank` solo funciona después de que la solicitud sea aprobada. **Cobrar** — emitir boleto o Pix a un cliente — también empieza cerrado en el MCP. Y un título que el agente crea, o cuyo monto, beneficiario, cuenta o datos de pago cambia, va a la cola de **aprobación de pagos** aunque la aprobación esté desactivada en el workspace: una instrucción escondida en una factura o en un e-mail no se vuelve un pago oficial sin que una persona lo apruebe. ## Revocación del token personal[​](#revocación-del-token-personal "Enlace directo al Revocación del token personal") Revocar un token personal en tu Cuenta Kobana **no corta el acceso en el momento**: Finanzas Inteligentes verifica el token por sí mismo, sin consultar a Kobana en cada llamada, y el token sigue aceptado hasta su validez. Por eso: * elige la **validez más corta** que el uso permita; * marca solo los **recursos y accesos** que el agente necesita; * para cortar un agente de inmediato, suspende o elimina a la persona en la organización, o quítale el acceso al workspace — los permisos se leen en cada llamada y valen al instante. ### Mover dinero por el MCP[​](#mover-dinero-por-el-mcp "Enlace directo al Mover dinero por el MCP") Como la revocación no llega aquí antes del vencimiento, las tools que mueven dinero — `finance_payables_send_to_bank`, `finance_payables_cancel_dispatch`, `finance_receivables_charge` y `finance_receivables_charge_cancel` — solo aparecen y solo se ejecutan con un token de **vida corta**: como máximo **24 horas** entre la emisión y el vencimiento. Además exigen `write` en el recurso de dinero (`finance/payable_dispatches`, `finance/receivable_charges`), o el nivel `write` en un token sin scopes por recurso. En la práctica: un cliente conectado por el **flujo OAuth** (token de vida corta, renovado por el cliente) mueve dinero si aprobaste el recurso de dinero y `write` en el consentimiento — y cada llamada pasa igual por la confirmación del servidor y por las reglas de [Seguridad › Canales](#seguridad--canales). Un **token personal** vive como mínimo 7 días y nunca mueve dinero por el MCP (la tool vuelve `token_not_accepted`): usa el flujo OAuth, la [API REST](https://docs.finance.kobana.com.br/es/es/api/overview/authentication.md#alcances-scopes) o la app. ## Modos de falla[​](#modos-de-falla "Enlace directo al Modos de falla") | HTTP | `code` | Causa | | ---- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `-32022` (JSON-RPC) | Versión del protocolo no soportada, en el encabezado `MCP-Protocol-Version` o en el `_meta`; `data.supported` lista las que sí. Ver [Transporte](https://docs.finance.kobana.com.br/es/es/mcp/overview/transport.md#versiones-del-protocolo). | | 401 | `invalid_token` / `token_expired` / `token_revoked` | Token ausente, malformado, inválido, emitido para otro recurso (la API, por ejemplo) o para más de una audience (`invalid_token`); expirado (`token_expired`); revocado (`token_revoked`). | | 401 | `invalid_request` | Credencial en la URL (`?access_token=`, `?token=`, `?api_key=` y similares), incluso junto a un encabezado válido. | | 403 | `UNKNOWN_ORGANIZATION` / `UNKNOWN_WORKSPACE` | El `org` del token no es un cliente, o el workspace de `X-Workspace-Id` / `?workspace_id=` no es de la organización. | | 403 | `ORGANIZATION_SUSPENDED` | La organización del token está suspendida o inactiva. Nada pasa, ni siquiera lecturas, hasta que Kobana la reactive. | | 403 | `FORBIDDEN` | `Origin` fuera de la allowlist (`origin_not_allowed`). | | 404 | `NOT_FOUND` | La solicitud llegó por un host que no sirve MCP, o pidió un camino que no existe en el servidor. | | 429 | `RATE_LIMITED` | Límite de solicitudes alcanzado — ver [Límite de solicitudes](https://docs.finance.kobana.com.br/es/es/mcp/overview/rate-limit.md). | | 503 | `SERVICE_UNAVAILABLE` | La Cuenta Kobana no respondió para validar el token. No es un problema del token: inténtalo de nuevo después del `Retry-After`. | Todo `401` lleva el desafío `WWW-Authenticate` de arriba, que manda al cliente de vuelta al flujo OAuth. En el desafío, toda falla de token aparece como `error="invalid_token"` — es el `code` del cuerpo el que distingue el token expirado del revocado —, y la credencial en la URL como `error="invalid_request"`. Las negativas de scope y de permiso **no** son errores HTTP: vuelven como resultado de tool marcado `isError`, para que el modelo las lea y reaccione — ver [Errores](https://docs.finance.kobana.com.br/es/es/mcp/overview/errors.md). ## Host y borde[​](#host-y-borde "Enlace directo al Host y borde") El endpoint solo es alcanzable por `mcp.finance.*` — nunca por el host de la app ni por el de la API, que apuntan al mismo origen. Cualquier otro camino responde `404`, siempre en JSON y para cualquier método — `{ "error": { "code": "NOT_FOUND", "message": "Not found." } }`, nunca una página HTML. El identificador de recurso OAuth se deriva de la **configuración del servidor**, nunca del `Host` de la solicitud, para que un `Host` falsificado no pueda apuntar un cliente a otro identificador. --- # Clientes Cualquier cliente que hable **Streamable HTTP** MCP y sepa hacer el flujo **OAuth 2.1** del MCP puede conectarse. Solo indicas la URL y el cliente descubre solo dónde autenticarse, abre el login de Kobana en el navegador y guarda el token. Ver [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). Un cliente sin soporte a OAuth también se conecta, con un **token personal**: créalo en **Cuenta Kobana → Tokens y Acceso → Nuevo Token Personal**, con la app **Finanzas Inteligentes** y el uso **MCP**, y configura el cliente para enviarlo en el encabezado `Authorization: Bearer `. La URL no lleva workspace. El agente elige dónde actuar en cada llamada: `finance_workspaces_list` lista los workspaces que alcanzas, y las demás tools aceptan `workspace_id` (salvo las de nivel de organización, como `finance_me` y `finance_organization_get`/`_update`, que no llevan workspace). Si alcanzas uno solo, ni eso hace falta. Para fijar un **workspace predeterminado** en la conexión, agrega `?workspace_id=` a la URL o, cuando el cliente lo permite, el encabezado `X-Workspace-Id` — los dos son opcionales. Ver [Autenticación → El workspace](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md#el-workspace). ## Claude Code[​](#claude-code "Enlace directo al Claude Code") ``` claude mcp add --transport http kobana-finance https://mcp.finance.kobana.com.br ``` Después, ejecuta `/mcp` en una sesión y elige **Authenticate** para iniciar sesión en Kobana. Para definir un workspace predeterminado — opcional —, usa la URL con él: ``` claude mcp add --transport http kobana-finance \ "https://mcp.finance.kobana.com.br/?workspace_id=$WORKSPACE_ID" ``` Con un token personal, sin flujo OAuth: ``` claude mcp add --transport http kobana-finance https://mcp.finance.kobana.com.br \ --header "Authorization: Bearer " ``` ## Clientes configurados por archivo[​](#clientes-configurados-por-archivo "Enlace directo al Clientes configurados por archivo") Los clientes que leen un archivo JSON de configuración piden la URL y el transporte. Por el flujo OAuth, no hay encabezado de autenticación: ``` { "mcpServers": { "kobana-finance": { "type": "http", "url": "https://mcp.finance.kobana.com.br" } } } ``` En la primera conexión el cliente abre el navegador para que autorices. Eliges la organización en la pantalla de consentimiento, y queda grabada en el token; el workspace viene de cada llamada (o del predeterminado, si pones `?workspace_id=` en la URL). Con un token personal, agrega los encabezados — la organización es la de la cuenta en la que creaste el token: ``` { "mcpServers": { "kobana-finance": { "type": "http", "url": "https://mcp.finance.kobana.com.br", "headers": { "Authorization": "Bearer " } } } } ``` Para un workspace predeterminado, agrega `"X-Workspace-Id": ""` a `headers` — opcional. Trata el archivo como un secreto: quien lo lee usa el token. ## Clientes que se conectan por URL[​](#clientes-que-se-conectan-por-url "Enlace directo al Clientes que se conectan por URL") Claude y ChatGPT conectan un servidor remoto pegando la URL — `https://mcp.finance.kobana.com.br`, nada más — en la configuración de conectores. El flujo OAuth se ejecuta dentro de la propia app, y el asistente descubre los workspaces solo, con `finance_workspaces_list`. ## Usando Billing junto[​](#usando-billing-junto "Enlace directo al Usando Billing junto") Las tools de este servidor empiezan con `finance_`, y las de [Facturación Automática](https://docs.billing.kobana.com.br) con `billing_`; los resources, con `kobana://finance/` y `kobana://billing/`. Los dos servidores conviven en el mismo cliente sin colisión — conecta los dos cuando el agente necesita ambos extremos. ## Postura recomendada para agentes[​](#postura-recomendada-para-agentes "Enlace directo al Postura recomendada para agentes") * **Autoriza con la cuenta correcta.** El MCP estrecha las tools a lo que la persona que autorizó puede hacer en el panel. Un cliente autorizado por un analista de solo lectura expone solo las tools de lectura, haga lo que haga el modelo del otro lado. Es la forma más fuerte de restringir un agente. * **Un token por cliente.** Cada cliente hace su propio flujo y recibe su propio token, que solo vale en el MCP — no sirve para llamar a la API REST. Para desconectar un agente, quita su autorización en Kobana sin afectar tus integraciones. * **Token personal: validez corta y scope mínimo.** Marca solo los recursos y accesos que el agente necesita, y la validez más corta que el uso permita: revocar el token en Kobana no corta el acceso antes de su validez — ver [Revocación del token personal](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md#revocaci%C3%B3n-del-token-personal). Un agente que registra títulos no necesita `finance/payable_dispatches`. Por el MCP, ningún token mueve dinero hoy — ni el personal ni el del flujo OAuth: ver [Mover dinero por el MCP](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md#mover-dinero-por-el-mcp). * **Deja el canal MCP cerrado para pagar y cobrar.** Por defecto, la pestaña [Seguridad › Canales](https://docs.finance.kobana.com.br/es/es/seguranca/.md#canales) no deja que los agentes de IA envíen al banco ni emitan cobros. Ábrelo solo si es intencional. * **Empieza en el sandbox.** El servidor pide confirmación en las tools destructivas, pero la primera exploración no debe ser en producción. * **Las tools destructivas piden un cliente que confirme.** Borrar, enviar al banco, cobrar, transferir, conciliar o ajustar un saldo pide su aprobación: en cualquier cliente, la tool devuelve un enlace que usted abre con sesión iniciada en Kobana Finance para elegir **Continuar** o **Cancelar**. El resto funciona con normalidad. Vea [Confirmación de tools destructivas](https://docs.finance.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md#confirmaci%C3%B3n-de-tools-destructivas). ## Verificando la conexión[​](#verificando-la-conexión "Enlace directo al Verificando la conexión") La forma más simple es preguntarle al asistente: "¿en qué workspaces puedes actuar?" — llama a `finance_workspaces_list`. Después, "¿qué empresas existen en el workspace Matriz?" llama a `finance_companies_list` con su `workspace_id`. Con un token emitido para el MCP — un token personal con uso **MCP**, por ejemplo —, puedes verificarlo con `curl`: ``` # ¿Cuántas tools alcanza este token? 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' # Los workspaces que alcanza la persona del token 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":{}}}' # Las empresas de un 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"]}}}' ``` Si el número de tools es menor de lo que esperabas, son los permisos de quien autorizó o el scope del token — ver [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). No es un error. --- # Endpoints ## Servidor MCP[​](#servidor-mcp "Enlace directo al Servidor MCP") En el mismo dominio que la API, con el prefijo `mcp`: | Entorno | URL del servidor MCP | API REST | | ---------- | ------------------------------------------- | ---------------------------------------------- | | Producción | `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` | La URL del servidor es la **raíz del host** — esa es la dirección que pegas en un cliente MCP, nada más: el workspace se elige en cada llamada, con el argumento `workspace_id` de las tools. `?workspace_id=` se sigue aceptando, pero solo define un workspace predeterminado para la conexión — ver [Autenticación → El workspace](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md#el-workspace). La raíz es también el *resource identifier* OAuth, y por eso no lleva ningún camino. ## Rutas servidas[​](#rutas-servidas "Enlace directo al Rutas servidas") | Método | Camino | Para qué | | -------- | --------------------------------------- | ---------------------------------------------------------------------- | | `POST` | `/` | Un mensaje JSON-RPC por solicitud. Toda la superficie de tools. | | `GET` | `/.well-known/oauth-protected-resource` | Metadata del recurso protegido (RFC 9728). Pública, sin autenticación. | | `GET` | `/` | `405` — este servidor es stateless y no abre stream servidor→cliente. | | `DELETE` | `/` | `204` — no hay sesión que cerrar. | tip Cada entorno tiene base de datos y Authorization Server propios: un token emitido en sandbox no vale en producción. Empieza por el sandbox: las tools destructivas borran títulos y envían pagos al banco de verdad. :::info Host separado, a propósito El servidor MCP tiene host propio en lugar de un camino en el host de la API o de la app. El documento de descubrimiento OAuth tiene que vivir en la raíz del host, y ninguna cookie del panel se envía a este origen — lo que elimina por construcción toda una clase de problemas de *confused deputy*. ::: ## Desarrollo local[​](#desarrollo-local "Enlace directo al Desarrollo local") En desarrollo el endpoint responde en `/mcp` en el host de la app (`http://localhost:3029/mcp`), y el documento de descubrimiento en `/.well-known/oauth-protected-resource`. En sandbox y producción, fuera de `mcp.finance.*`, el endpoint responde `404`. --- # Errores Las fallas llegan por **dos canales distintos**, y la distinción importa: uno es una solicitud rota, el otro es algo que el modelo debe leer y a lo que debe reaccionar. ## Errores de tool[​](#errores-de-tool "Enlace directo al Errores de tool") Todo aquello sobre lo que el llamador puede actuar — validación, no encontrado, scope o permiso insuficiente, un error del endpoint — vuelve como una **respuesta JSON-RPC exitosa** cuyo resultado está marcado `isError`, llevando el envoltorio de error de la propia API como texto: ``` { "jsonrpc": "2.0", "id": 2, "result": { "isError": true, "content": [{ "type": "text", "text": "{ \"error\": { \"code\": \"NOT_FOUND\", \"message\": \"Payable not found.\" } }" }] } } ``` El vocabulario de `code` es el [de la API](https://docs.finance.kobana.com.br/es/es/api/overview/errors.md), sin cambios. Los que más vas a encontrar: | `code` | Cuándo | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `VALIDATION_ERROR` | El cuerpo falló la validación del endpoint; `details.issues[]` nombra cada campo. También cuando los argumentos de la tool (id, filtros) no coinciden con su schema — incluso `limit`, `cursor`, `sort_by` o `fields` dentro de `filters`, que son argumentos nombrados; ahí `details` no trae `issues[]`, sino `{ "formErrors": [...], "fieldErrors": { "": [...] } }` — `formErrors` para lo que no es de un solo argumento (un argumento desconocido, por ejemplo), `fieldErrors` por argumento. | | `BAD_REQUEST` | Filtro, operador o nombre de `fields` desconocido. | | `NOT_FOUND` | No existe ese registro, o es de otro workspace. | | `CONFLICT` | Duplicidad, o un registro todavía en uso. | | `UNPROCESSABLE_ENTITY` | Regla de negocio — borrar una categoría que tiene hijas, liquidar un título sin cuenta. | | `SECURITY_BLOCKED` | La pestaña Seguridad bloqueó la acción en este canal. | | `ENTITLEMENT_REQUIRED` | El espacio no tiene plan contratado y la tool es de uso efectivo (enviar al banco, emitir un cobro); `details.reason` indica `no_plan`. Contratar lo resuelve, reintentar no. | | `RATE_LIMITED` | Se acabó el presupuesto de la API para esta persona en la organización — ver [Límite de solicitudes](https://docs.finance.kobana.com.br/es/es/mcp/overview/rate-limit.md). | Y los cinco que agrega el propio MCP, porque son sobre *autorización*, no sobre el recurso: | `code` | Quién lo resuelve | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `insufficient_scope` | El scope del token no alcanza la tool: el recurso no está en el token, o falta el nivel de acceso que exige — `write` para modificar (mover dinero incluido, en el recurso de dinero), `delete` para eliminar. Usa un token que alcance el recurso con el acceso pedido: por el flujo OAuth, autoriza de nuevo concediendo el acceso que faltó. | | `token_not_accepted` | El token no sirve para esta tool: mueve dinero y el token vive más de 24 horas (todo token personal) — mueve dinero por la API REST o por la app —, o la llamada es destructiva y el token fue verificado por la clave fija provisional — conecta por el flujo OAuth o con un token personal. | | `insufficient_permission` | Un admin de la organización, concediendo el permiso que nombra el error. | | `workspace_access_denied` | El `workspace_id` no es uno que la persona alcanza (o no existe). Un admin concede el workspace a la persona, o el agente pasa otro, de `finance_workspaces_list`. | | `membership_inactive` | Incluir a la persona del token en la organización o reactivarla — ningún permiso arregla una membresía que no existe o está inactiva. | Están separados **a propósito**: cinco conversaciones distintas, con personas distintas. Un error único diría "no puedes" sin decir a quién pedirlo. Ver [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). Hay también `workspace_required`: la llamada no trajo `workspace_id` y la conexión no tiene workspace predeterminado — la persona alcanza varios. El agente llama a `finance_workspaces_list` y repite la llamada con uno de los `id`. Ver [Autenticación → El workspace](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md#el-workspace). Y los de la [confirmación de tools destructivas](https://docs.finance.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md#confirmaci%C3%B3n-de-tools-destructivas) — en todos ellos, no se modificó nada: | `code` | Cuándo | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `confirmation_required` | Tool destructiva llamada por un cliente que no puede confirmar, con un token sin persona detrás — nadie podría abrir un enlace de aprobación. Con una persona, la tool devuelve el enlace (`status: approval_required`) — vea [Aprobación por enlace](https://docs.finance.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md#aprobaci%C3%B3n-por-enlace). | | `USER_DECLINED` | En la era `2026-07-28`, la persona rechazó o canceló la confirmación. | | `confirmation_replayed` | La confirmación reenviada ya ejecutó la tool una vez. Llama de nuevo sin `requestState` para volver a preguntar. | | `confirmation_unavailable` | El servidor no pudo garantizar la confirmación en ese momento. Inténtalo más tarde. | | `confirmation_subject_unreadable` | La tool mueve dinero y la pregunta muestra el registro, pero la persona del token no puede leerlo. Un admin concede el permiso de lectura que el error nombra. | ### `input_required` no es un error[​](#input_required-no-es-un-error "Enlace directo al input_required-no-es-un-error") En la era `2026-07-28`, el primer `tools/call` de una tool destructiva puede volver `resultType: "input_required"` con un pedido de confirmación a la persona. Es el flujo normal, no una falla: el cliente muestra la pregunta y reenvía la misma llamada con la respuesta. Ver [Confirmación de tools destructivas](https://docs.finance.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md#confirmaci%C3%B3n-de-tools-destructivas). ## Errores de protocolo[​](#errores-de-protocolo "Enlace directo al Errores de protocolo") Un mensaje malformado recibe un objeto de error JSON-RPC, no un resultado: | Código | Significado | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `-32700` | Parse error — el cuerpo no es JSON válido | | `-32600` | Invalid request — no es un objeto JSON-RPC, o es un array (el batching no está soportado) | | `-32601` | Method not found | | `-32602` | Invalid params — tool, prompt o argumento inexistente, `name` ausente; en la era `2026-07-28`, también resource no encontrado | | `-32002` | Resource no encontrado — solo en la era 2025 (la `2026-07-28` usa `-32602`) | | `-32603` | Internal error — falla inesperada al ejecutar la tool | | `-32020` | Header mismatch — en la `2026-07-28`, un encabezado `MCP-Protocol-Version`, `Mcp-Method` o `Mcp-Name` que no coincide con el cuerpo (HTTP `400`) | | `-32022` | Unsupported protocol version — la versión pedida no está soportada; `data.supported` lista las que sí (HTTP `400`) | ## Errores de transporte[​](#errores-de-transporte "Enlace directo al Errores de transporte") Los rechazos que ocurren **antes** de leer el mensaje JSON-RPC son respuestas HTTP comunes: token ausente, inválido, expirado, revocado o emitido para otro recurso (`401`, con `code` `invalid_token`, `token_expired` o `token_revoked`), credencial en la URL (`401` `invalid_request`), workspace predeterminado (`X-Workspace-Id` / `?workspace_id=`) de otra organización, `Origin` fuera de la allowlist, límite de solicitudes del protocolo, Cuenta Kobana no disponible para validar el token (`503`), cuerpo por encima de 14 MB (`413`, con el error JSON-RPC `-32600` `Request body too large (limit 14680064 bytes)` e `id: null`). Están listados en [Autenticación → Modos de falla](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md#modos-de-falla). ## Por qué `isError` y no error JSON-RPC[​](#por-qué-iserror-y-no-error-json-rpc "Enlace directo al por-qué-iserror-y-no-error-json-rpc") Un `404` en un título no es un defecto del cliente MCP — es información sobre el mundo, y el modelo del otro lado la necesita para corregirse. Enterrarla en un error de protocolo haría que el cliente la tratara como falla de transporte, escondiera el texto y, en el mejor caso, reintentara idéntico. Por eso la regla: **si el llamador puede actuar, es resultado; si la solicitud está rota, es error.** ## Observabilidad[​](#observabilidad "Enlace directo al Observabilidad") Cada `tools/call` escribe una línea estructurada con la tool, el workspace, la persona, el tipo de token (`oauth` o `personal`), el estado y la duración. Las **escrituras** quedan registradas con el canal **`mcp`** y con la persona del token, así que lo que hizo un agente aparece junto a lo que hizo una persona, en las mismas pantallas. --- # Idempotencia Las tools de creación y modificación aceptan un argumento `idempotency_key`. Se envía al endpoint como el encabezado `X-Idempotency-Key` que la API REST ya respeta — ver [Idempotencia](https://docs.finance.kobana.com.br/es/es/api/overview/idempotency.md) en la API. ``` { "name": "finance_payables_create", "arguments": { "company_id": "…", "description": "Alquiler de noviembre", "amount": 4500, "due_date": "2026-11-10T00:00:00Z", "person": { "name": "Inmobiliaria Centro" }, "idempotency_key": "7c4a8d09-ca37-4f21-b1f0-3d2f2b8c9a11" } } ``` | | | | ---------------------------------- | ------------------------------------------------------------------- | | **Formato** | String opaco, de 1 a 255 caracteres. Un UUID es la elección usual. | | **Repetición con el mismo cuerpo** | Devuelve la respuesta original, sin ejecutar la operación de nuevo. | | **Repetición con cuerpo distinto** | Conflicto (`IDEMPOTENCY_KEY_REUSED`). | Las tools que borran no aceptan el argumento: la ruta no lo lee, y borrar dos veces ya da el mismo resultado. ## Por qué un agente lo necesita más que tu backend[​](#por-qué-un-agente-lo-necesita-más-que-tu-backend "Enlace directo al Por qué un agente lo necesita más que tu backend") Un cliente MCP que da timeout y reintenta, o un modelo que decide "no estoy seguro de que eso funcionó, lo hago de nuevo", es justo el patrón que crea el segundo título y el segundo movimiento. Tu backend tiene un bucle de reintentos que escribiste tú; el agente tiene un criterio. **Envía una clave siempre que la operación cree algo.** Una clave nueva es un intento nuevo; para repetir con seguridad, repite la misma. ## Las que mueven dinero: la clave es obligatoria[​](#las-que-mueven-dinero-la-clave-es-obligatoria "Enlace directo al Las que mueven dinero: la clave es obligatoria") En estas cuatro la clave **no es opcional** — la tool rechaza la llamada sin ella, como la ruta: | Tool | Qué hace | | ----------------------------------- | --------------------------------- | | `finance_payables_send_to_bank` | Envía el pago al banco por Kobana | | `finance_payables_cancel_dispatch` | Cancela el envío al banco | | `finance_receivables_charge` | Emite boleto o Pix al cliente | | `finance_receivables_charge_cancel` | Cancela el cobro | Un envío duplicado es un pago duplicado, y un cobro duplicado es una deuda duplicada — ningún `_delete` lo deshace. Son también tools **destructive**: el servidor solo las ejecuta después de confirmar con la persona — vea [Confirmación de tools destructivas](https://docs.finance.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md#confirmaci%C3%B3n-de-tools-destructivas). --- # Introducción El **servidor MCP de Finanzas Inteligentes** es un servidor [Model Context Protocol](https://modelcontextprotocol.io) remoto que expone las operaciones de la API pública — cuentas por pagar y por cobrar, movimientos, conciliaciones, cuentas financieras, flujo de caja y registros — como **tools** que un cliente de IA puede llamar. Lo conectas por URL; no hay nada que instalar. Se sirve en un host propio, `mcp.finance.kobana.com.br`, en el mismo dominio que la API, con transporte **Streamable HTTP** en modo stateless y autenticación por **Bearer token** emitido para el MCP por la Cuenta Kobana. No interviene ningún certificado de cliente. :::info Disponibilidad El servidor, sus **96 tools**, los resources y los prompts están implementados, y la autenticación es por el Authorization Server de Kobana: por el flujo **OAuth 2.1**, en el que el cliente recibe solo la URL y hace el login por sí mismo, o por un **token personal** creado en tu Cuenta Kobana. El endpoint se sirve por el borde dedicado `mcp.finance.*`, con distribution, WAF y DNS propios. ::: ## Cuándo usarlo[​](#cuándo-usarlo "Enlace directo al Cuándo usarlo") | | API REST (`/v1`) | Servidor MCP (este) | | ------------- | ---------------------------------------- | ---------------------------------------------------------------------------------- | | Consumidor | tu backend | un cliente de IA (Claude, ChatGPT, un IDE) | | Configuración | token y `X-Workspace-Id`, fuera de banda | solo una URL; el workspace va en cada llamada | | Transporte | HTTPS/REST | Streamable HTTP (JSON-RPC 2.0) | | Autenticación | Bearer token emitido para la API | OAuth 2.1 o token personal, siempre emitido para el MCP | | Autorización | scope del token | scope del token **y** permisos de la persona | | Superficie | los endpoints de `/v1` | 96 tools, una por operación de esos endpoints, más resources y prompts sobre ellas | El servidor MCP **no reemplaza** la API REST. Cada tool despacha in-process al endpoint que implementa la operación, así que filtros, validación, reglas de liquidación, prorrateo y aislamiento por workspace son exactamente los mismos. Si estás escribiendo código, usa la [API REST](https://docs.finance.kobana.com.br/es/es/api/overview/introduction.md). Si estás conectando un asistente, usa esto. ## El principio[​](#el-principio "Enlace directo al El principio") **Una capacidad solo existe en el MCP si existe en la API pública.** Nada se implementa dos veces. La tool llama al handler del endpoint con la identidad que el token del llamador ya probó — la misma persona, la misma organización, el mismo workspace —, así que se ejecuta, verifica el scope y audita como lo haría con cualquier solicitud HTTP. Una tool hace lo que el endpoint hace por REST — nunca más. En la práctica: lo que hoy solo existe en el panel (aprobar pagos, importar extractos, gestionar miembros) no se convierte en tool antes de convertirse en endpoint. ## Lo que ves es más estrecho que el catálogo[​](#lo-que-ves-es-más-estrecho-que-el-catálogo "Enlace directo al Lo que ves es más estrecho que el catálogo") `tools/list` devuelve solo las tools que **este llamador puede ejecutar**: las que alcanzan los scopes del token **y** que la persona del token tiene permiso para hacer en la organización. Un agente no se entera de capacidades que solo le serían negadas. Los dos ejes están en [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). ## Primeros pasos[​](#primeros-pasos "Enlace directo al Primeros pasos") 1. **Apunta tu cliente a la URL del servidor** — `https://mcp.finance.kobana.com.br`, nada más. Ver [Endpoints](https://docs.finance.kobana.com.br/es/es/mcp/overview/endpoints.md) y [Clientes](https://docs.finance.kobana.com.br/es/es/mcp/overview/clients.md). 2. **Autoriza.** El cliente abre el login de Kobana; entra con una cuenta de la organización y autoriza el acceso. Ver [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). 3. **Elige el workspace.** El agente llama a `finance_workspaces_list` y pasa el `id` elegido como `workspace_id` a las demás tools. Si alcanzas un solo workspace, ese es el predeterminado y el argumento se puede omitir. Ver [Autenticación → El workspace](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md#el-workspace). 4. **Lista las tools** para confirmar lo que alcanza tu acceso — pídeselo al asistente o, con un token emitido para el MCP en mano: ``` 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. **Explora el catálogo** en [Tools](https://docs.finance.kobana.com.br/es/es/mcp/tools/overview.md). ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md) — el flujo OAuth, el token personal, el workspace, el scope y los permisos aplicados, y los modos de falla. * [Endpoints](https://docs.finance.kobana.com.br/es/es/mcp/overview/endpoints.md) — URLs por entorno y rutas servidas. * [Transporte](https://docs.finance.kobana.com.br/es/es/mcp/overview/transport.md) — JSON-RPC, encabezados y métodos. * [Clientes](https://docs.finance.kobana.com.br/es/es/mcp/overview/clients.md) — cómo conectar Claude Code y clientes por archivo. * [Listado, filtros y campos](https://docs.finance.kobana.com.br/es/es/mcp/overview/pagination.md) — `cursor`, `filters`, `sort_by`, `fields`. * [Idempotencia](https://docs.finance.kobana.com.br/es/es/mcp/overview/idempotency.md) — y las acciones que mueven dinero. * [Resources y prompts](https://docs.finance.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md) — documentos por URI, guiones listos, autocompletado y la confirmación de tools destructivas. * [Errores](https://docs.finance.kobana.com.br/es/es/mcp/overview/errors.md) — los dos canales de falla, y por qué importa la distinción. * [Tools](https://docs.finance.kobana.com.br/es/es/mcp/tools/overview.md) — el catálogo completo. --- # Listado, Filtros y Campos Las tools `*_list` usan la misma paginación que la API REST: **por cursor**. | Argumento | Predeterminado | Máximo | | --------- | -------------- | ------------------------------------ | | `limit` | `25` | `100` (`10000` en las tools `*_ids`) | | `cursor` | — | — | ``` { "name": "finance_payables_list", "arguments": { "limit": 50 } } ``` El resultado trae el envoltorio de siempre: ``` { "data": [ /* ... */ ], "meta": { "next_cursor": "eyJpZCI6Mn0" } } ``` Para la página siguiente, envía el `meta.next_cursor` como `cursor`, **con los mismos filtros**. `next_cursor: null` significa que esta es la última página. Ver [Listado y paginación](https://docs.finance.kobana.com.br/es/es/api/overview/pagination.md) en la API. ## Filtros[​](#filtros "Enlace directo al Filtros") `filters` es un objeto con **exactamente** los filtros que acepta el listado — el `inputSchema` de la tool los enumera, con los operadores de cada uno. Un filtro u operador fuera de la lista se rechaza antes de llegar al endpoint. Paginación, orden y columnas (`limit`, `cursor`, `sort_by`, `sort_order`, `fields` — y `page`, `per_page` y `sort`, de otras APIs) son **argumentos nombrados**: dentro de `filters` se rechazan con `VALIDATION_ERROR`, que nombra las claves, y nunca sobrescriben el argumento. | Forma | Significa | Se convierte en | | --------------------------------------------------------- | ---------- | --------------------------------- | | `"status": "pending"` | igual a | `?status=pending` | | `"status": ["pending", "paid"]` | está en | `?status[in]=pending,paid` | | `"due_date": { "gte": "2026-11-01", "lt": "2026-12-01" }` | operadores | `?due_date[gte]=…&due_date[lt]=…` | ``` { "name": "finance_payables_list", "arguments": { "filters": { "company_id": "…", "status": "pending", "due_date": { "lte": "2026-11-30" } }, "sort_by": "due_date", "sort_order": "asc" } } ``` La gramática completa está en [Filtros y ordenación](https://docs.finance.kobana.com.br/es/es/api/overview/filtering.md). ## Ordenación[​](#ordenación "Enlace directo al Ordenación") | Argumento | Valores | Predeterminado | | ------------ | ------------------------------------------------------------------------------ | ----------------- | | `sort_by` | Una de las columnas por las que ordena el listado (el `inputSchema` las lista) | varía por recurso | | `sort_order` | `asc` o `desc` | `asc` | ## Campos (`fields`)[​](#campos-fields "Enlace directo al campos-fields") Las tools de lectura de registros aceptan `fields`, un array de nombres de columna. Omitido, vuelve el registro entero; informado, vuelve solo eso: ``` { "name": "finance_payables_list", "arguments": { "filters": { "status": "pending" }, "fields": ["description", "amount", "due_date"] } } ``` | Regla | Por qué | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **`id` siempre vuelve** | Una proyección que no puedes seguir no sirve, y quitar el `id` en silencio rompería la llamada siguiente, no esta. | | **Solo el primer nivel** | `fields: ["reconciliation"]` devuelve el objeto entero; no existe la sintaxis `reconciliation.kind`. | | **Solo en lectura de registros** | Las escrituras devuelven el registro entero; totales, `*_ids` y descarga no ofrecen el argumento. | | **Un nombre desconocido es error** | `400` con `details.unknown` y `details.available`. Ignorarlo devolvería menos campos que los pedidos, como si el registro no los tuviera. | Es el mismo [`?fields=` de la API](https://docs.finance.kobana.com.br/es/es/api/overview/fields.md). Y es la forma más barata de reducir el contexto que gasta un agente. ## `finance_schemas_get` — el catálogo de campos[​](#finance_schemas_get--el-catálogo-de-campos "Enlace directo al finance_schemas_get--el-catálogo-de-campos") `fields` solo sirve si sabes qué pedir. `finance_schemas_get` responde con los schemas del contrato publicado: ``` { "name": "finance_schemas_get", "arguments": {} } { "name": "finance_schemas_get", "arguments": { "schema": "PayableV1" } } ``` Sin argumento, devuelve el catálogo; con `schema`, los campos de ese schema — nombre, tipo, enum, si acepta nulo y descripción. Es el mismo OpenAPI que genera la [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api/overview/introduction.md). ## Contrato de datos[​](#contrato-de-datos "Enlace directo al Contrato de datos") Lo que vale para la API vale aquí, porque es el mismo código: * **snake\_case en todo**, argumentos y respuestas. * **El dinero es un número en BRL**, con hasta 2 decimales: `1500.5` es R$ 1.500,50. Títulos y movimientos son siempre positivos — la dirección viene del tipo, no del signo. * **Fechas en ISO 8601.** * **Las escrituras aceptan `idempotency_key`** — ver [Idempotencia](https://docs.finance.kobana.com.br/es/es/mcp/overview/idempotency.md). --- # Límite de Solicitudes El servidor MCP gasta **los mismos límites que la API REST**, contados **por persona en la organización** — no por token —, más un límite propio para el protocolo. Generar un token nuevo, o reautorizar el cliente, no reinicia el presupuesto. | Presupuesto | Qué cuenta | Límite (producción) | | -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Protocolo MCP | toda solicitud a `/` (`initialize`, `tools/list`, `ping`, `tools/call`) | 1000/hora por persona en la organización | | Lecturas de la API | cada `tools/call` de una tool **read** | el mismo de la [API](https://docs.finance.kobana.com.br/es/es/api/overview/rate-limit.md) | | Escrituras de la API | cada `tools/call` de una tool **write** o **destructive** | el mismo de la [API](https://docs.finance.kobana.com.br/es/es/api/overview/rate-limit.md) | | Acciones que mueven dinero | `send_to_bank`, `cancel_dispatch`, `charge`, `charge_cancel` | el mismo de la [API](https://docs.finance.kobana.com.br/es/es/api/overview/rate-limit.md) | Una llamada de tool **nunca es más barata que el endpoint que refleja**: se cuenta en el presupuesto del protocolo y, de nuevo, en el presupuesto de la API que gastaría la misma llamada REST — con el mismo tamaño de presupuesto de la API, por persona. Un agente que recorre listados en bucle no esquiva el límite que el mismo recorrido pagaría por REST. Hay también un techo por IP, muy por encima de cualquier uso legítimo. ## Cuando se alcanza el límite[​](#cuando-se-alcanza-el-límite "Enlace directo al Cuando se alcanza el límite") **En el protocolo**, el servidor responde `429` y el mensaje JSON-RPC no llega a procesarse: ``` 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." } } ``` **En el presupuesto de la API**, la tool devuelve un resultado con error, para que el modelo lo lea y espere: ``` { "isError": true, "content": [{ "type": "text", "text": "{ \"error\": { \"code\": \"RATE_LIMITED\", \"details\": { \"retry_after_seconds\": 37 } } }" }] } ``` En ambos casos, espera los segundos indicados antes de intentarlo de nuevo. ## Gastando menos[​](#gastando-menos "Enlace directo al Gastando menos") Un agente consume el mismo presupuesto que tu backend — y, en las lecturas, ese presupuesto es pequeño. Tres hábitos resuelven casi todo: * **Filtra antes de paginar.** `finance_payables_list { filters: { status: "pending", due_date: { lte: "2026-11-30" } } }` cuesta una llamada; traer todo para filtrar en el modelo cuesta decenas. * **Usa los totales listos.** "Cuánto vence este mes" es una llamada a `finance_payables_aggregates`, no un recorrido de `finance_payables_list`. * **Pide solo las columnas que interesan.** `fields` no reduce el número de llamadas, pero reduce mucho el contexto gastado — ver [Listado, filtros y campos](https://docs.finance.kobana.com.br/es/es/mcp/overview/pagination.md). --- # Resources y prompts Además de las tools, el servidor ofrece tres cosas que el **cliente** usa por su cuenta: **resources** (documentos que adjuntas a la conversación), **prompts** (guiones listos que eliges) y **completions** (autocompletado de los argumentos de ambos). En la era `2026-07-28`, también pide **confirmación** antes de ejecutar una tool destructiva — incluidas las que mueven dinero. Nada de esto abre un camino nuevo hasta tus datos: todo pasa por las mismas tools, bajo los mismos permisos y el mismo [nivel de acceso](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). Todo resource y todo prompt de aquí solo lee, así que un token `read` los alcanza a todos — siempre que la persona pueda ejecutar las tools que hay detrás. ## Resources[​](#resources "Enlace directo al Resources") Un resource es un documento identificado por una URI. Eliges, por ejemplo, una cuenta por pagar, y el cliente lee el registro y lo pone en el contexto, sin que el modelo tenga que llamar una tool. Las URIs quedan bajo `kobana://finance/`, así que conviven con las de otros productos Kobana en el mismo cliente. | URI | Qué vuelve | | ------------------------------------------------------------------ | ----------------------------------------------------------- | | `kobana://finance/schemas` | El catálogo de schemas del contrato de la API (JSON) | | `kobana://finance/schemas/{schema}` | Un schema: los campos que una tool devuelve o acepta (JSON) | | `kobana://finance/payables/{id}` | Una cuenta por pagar (JSON) | | `kobana://finance/receivables/{id}` | Una cuenta por cobrar (JSON) | | `kobana://finance/financial-transactions/{id}` | Un movimiento (JSON) | | `kobana://finance/financial-accounts/{account_id}` | Una cuenta financiera (JSON) | | `kobana://finance/financial-accounts/{account_id}/balances/latest` | El saldo registrado más reciente de la cuenta (JSON) | | `kobana://finance/people/{id}` | Una persona — proveedor, cliente o ambos (JSON) | | `kobana://finance/companies/{id}` | Una empresa del workspace (JSON) | | `kobana://finance/fiscal-documents/{id}` | Un documento fiscal recibido (JSON) | | `kobana://finance/attachments/{attachment_id}` | Los datos de un adjunto y a qué está vinculado (JSON) | | `kobana://finance/attachments/{attachment_id}/download` | El archivo del adjunto — comprobante, boleto, XML | `resources/list` trae las URIs fijas y `resources/templates/list` los templates con parámetro. * **Permisos.** Cada resource se lee con la tool correspondiente (`kobana://finance/payables/{id}` es `finance_payables_get`). Solo aparece, y solo se lee, si puedes ejecutar esa tool. * **Archivos.** El archivo de un adjunto vuelve como bytes en base64 (`blob`), o como texto cuando es texto (un XML), hasta **10 MB**. A diferencia de la tool, que solo describe el archivo, aquí el documento es la respuesta: fue el cliente quien lo pidió. * **No encontrado.** Una URI desconocida, o un registro que no existe en este workspace, es `-32002` en la era 2025 y `-32602` en la `2026-07-28` — ver [Errores](https://docs.finance.kobana.com.br/es/es/mcp/overview/errors.md). * **Workspace.** La URI no lleva workspace: el resource se lee en el [workspace predeterminado de la conexión](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md#el-workspace-predeterminado). Sin predeterminado — la persona alcanza varios workspaces y la conexión no fijó uno —, leer un resource de registro falla con el error JSON-RPC `-32602`, con `data.code: "workspace_required"` y una pista; usa las tools, que aceptan `workspace_id`. El catálogo de schemas no depende de un workspace. * **Sin suscripción a cambios.** El servidor es stateless: no hay `resources/subscribe` ni aviso de lista modificada. ## Prompts[​](#prompts "Enlace directo al Prompts") Un prompt es una instrucción lista que eliges en el cliente y que se convierte en el primer mensaje de la conversación. Solo aparece si puedes ejecutar **todas** las tools en las que se apoya. Ninguno mueve dinero, edita ni borra: enviar al banco o cobrar queda para que lo pidas explícitamente. | Prompt | Argumentos | Qué hace | | --------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | | `overdue_payables` | `company_id` (opcional) | Lista las cuentas por pagar vencidas y todavía abiertas, de la más antigua, con el total adeudado. | | `overdue_receivables` | `person_id` (opcional) | Lista las cuentas por cobrar vencidas y las agrupa por cliente, mayores totales primero. | | `cash_flow_outlook` | `until` (opcional, `YYYY-MM-DD`; por defecto: 90 días) | El saldo de hoy y hacia dónde va la caja, semana a semana, con el punto más bajo. | | `monthly_summary` | `month` (opcional, `YYYY-MM`) | Lo que se pagó, se cobró y quedó abierto en el mes. | | `person_overview` | `person_id` | Un proveedor o cliente: sus datos y lo que está abierto de cada lado. | Un argumento obligatorio ausente, o `month`/`until` fuera de formato, es `-32602`. ## Completions[​](#completions "Enlace directo al Completions") `completion/complete` sugiere valores mientras escribes un argumento: * **Ids** (`person_id`, `company_id`, `account_id` y el parámetro de los templates de registro): los registros más recientes del listado correspondiente, por el prefijo escrito, bajo el mismo permiso de ese listado. Si no puedes listar, no hay sugerencia. Los registros salen del workspace predeterminado de la conexión; sin él, la lista vuelve vacía. * **`{schema}` de `kobana://finance/schemas/{schema}`**: los nombres del contrato, por prefijo. * **`month`**: los últimos doce meses. Sin fuente de sugerencias, la respuesta es una lista vacía, y sigues escribiendo. ## Confirmación de tools destructivas[​](#confirmación-de-tools-destructivas "Enlace directo al Confirmación de tools destructivas") Las tools que borran, cancelan, envían un pago al banco, cobran, transfieren entre cuentas, concilian o ajustan un saldo están marcadas con `destructiveHint`. El cliente puede o no pedir confirmación por eso — así que el **servidor** exige tu aprobación, y una tool destructiva solo se ejecuta con ella. En toda revisión del protocolo y en cualquier cliente, la tool destructiva devuelve un **enlace de aprobación** (vea [Aprobación por enlace](#aprobaci%C3%B3n-por-enlace)) — incluso en un cliente que declare elicitation de formulario, porque hay clientes que la declaran y nunca muestran el formulario, y la llamada quedaría detenida sin nada registrado. La pregunta en la conversación es solo el camino de reserva para cuando no hay aprobación que registrar (un token sin persona detrás) y el cliente habla la `2026-07-28` con elicitation de formulario: 1. El primer `tools/call` no ejecuta nada. Vuelve `resultType: "input_required"` con un formulario de una pregunta: ¿ejecutar esta acción, con estos argumentos? 2. El cliente muestra la pregunta y reenvía la misma llamada con tu respuesta. 3. Solo un **sí** explícito ejecuta. Rechazar o cancelar devuelve un resultado `isError` con `USER_DECLINED`, y nada cambia. Dos tools son destructivas solo según los argumentos: `finance_payables_update` pide confirmación cuando la llamada cambia el `status` a `paid` o `cancelled`, y `finance_receivables_update` cuando lo cambia a `received` o `cancelled`. Las dos se anuncian con `destructiveHint`, pero cualquier otro cambio por ellas se ejecuta sin pregunta. En las tools que mueven dinero, la pregunta muestra **el registro sobre el que actúa la acción**, leído por el servidor: monto, vencimiento, beneficiario, clave Pix, cuenta bancaria, código de barras. Si el título cambia entre la pregunta y el **sí** — la clave Pix cambiada, por ejemplo —, el sí no vale y el servidor vuelve a preguntar, con los datos nuevos. Si la persona del token no puede leer el registro, la tool devuelve `confirmation_subject_unreadable` y nada se ejecuta. La confirmación protege contra un agente engañado por texto de terceros — una instrucción escondida en una descripción o en un e-mail. **No** sustituye el scope, la validez del token, los permisos ni la pestaña Canales: quien tiene el token puede escribir un cliente que responda sí por sí solo. La confirmación vale **solo para esa llamada** y **una sola vez**: la misma tool, los mismos argumentos, la misma persona, organización y workspace, durante **5 minutos**. Una respuesta no puede reutilizarse para otro título u otra acción; si algo no coincide, el servidor simplemente vuelve a preguntar. Reenviar una confirmación que ya ejecutó la tool devuelve `confirmation_replayed` — para repetir la acción, llama la tool de nuevo sin `requestState` y confirma otra vez. **Sin aprobación ni pregunta posible, la tool no se ejecuta.** Sin persona detrás del token no hay quien abra el enlace, y el servidor solo puede preguntar en la era `2026-07-28`, a clientes que declaran soporte a formularios de elicitation (`elicitation: {}` o `elicitation: { form: {} }` en `clientCapabilities`). Fuera de eso, un `tools/call` de una tool destructiva devuelve `isError` con `confirmation_required` y nada cambia — las lecturas y escrituras comunes siguen ejecutándose. Si el propio servidor no puede garantizar la confirmación en ese momento, la respuesta es `confirmation_unavailable`, tampoco cambia nada. ## Aprobación por enlace[​](#aprobación-por-enlace "Enlace directo al Aprobación por enlace") Es el camino de toda tool destructiva llamada por un token con persona detrás, en cualquier revisión y en cualquier cliente — con o sin elicitation de formulario. La tool destructiva **no se ejecuta**: el servidor registra la operación como pendiente y responde, como resultado normal (sin `isError`), un texto JSON: ``` { "status": "approval_required", "approval": { "id": "…", "url": "https://app.finance.kobana.com.br/approvals/…", "expires_at": "2026-11-01T12:15:00.000Z" }, "message": "… show them this URL … Do not call the tool again." } ``` El asistente muestra la URL. Usted la abre **con sesión iniciada en Kobana Finance** (sin sesión, la app pide el inicio de sesión y vuelve a ella), revisa lo que va a pasar — monto, beneficiario, cuenta de origen y saldo en las tools de dinero, el registro afectado en las demás y todos los argumentos — y elige: * **Continuar**: la operación se ejecuta en el momento, una sola vez, con los argumentos registrados y **sus permisos actuales**. Si perdió el permiso mientras tanto, o el acceso de la aplicación fue revocado, falla y nada cambia. * **Cancelar**: no se ejecuta nada. El enlace vale **15 minutos** y decide **una sola vez**. Solo usted lo abre: para cualquier otra persona, incluso de su organización, no existe. Sus aprobaciones quedan en **Sistema › Aprobaciones**; al hacer clic en una se abre lo que se pidió, solo para lectura. ### Consultar el resultado[​](#consultar-el-resultado "Enlace directo al Consultar el resultado") El asistente no recibe aviso cuando usted decide. Después de que usted diga que decidió, consulta el resultado con `finance_operation_approvals_get`, pasando el `approval.id` de la respuesta — una vez, sin repetir la llamada. `finance_operation_approvals_list` lista sus aprobaciones en el workspace de la llamada, las más recientes primero (`status`, `created_after`, `created_before`, `page`, `per_page`; devuelve `{ data, meta: { total, page, per_page, total_pages } }`). ``` { "data": { "id": "…", "status": "executed", "action": "finance_categories_delete", "title": "Eliminar la categoría", "resource": "categories", "operation": "delete", "amount": null, "requested_at": "2026-11-01T12:00:00.000Z", "expires_at": "2026-11-01T12:15:00.000Z", "decided_at": "2026-11-01T12:03:10.000Z", "executed_at": "2026-11-01T12:03:11.000Z", "error": null, "result": { "data": { "id": "…", "deleted": true } }, "result_hidden": false } } ``` * `status`: `pending`, `approved` (confirmada, en proceso), `executed`, `failed`, `declined` (cancelada) o `expired` — la pendiente que pasó el plazo ya sale como `expired`. * `title`: lo que hace la operación, en el idioma del encabezado `Accept-Language` de la conexión (portugués, inglés o español; sin él, portugués). * `error`: `{ code, message }` cuando `failed`. `result`: lo que devolvió la operación cuando `executed`, con los secretos (tokens, claves, contraseñas) enmascarados — el valor en claro aparece una sola vez, en la pantalla. * Nunca se devuelven el enlace, su token ni los argumentos. Cualquier token con una persona detrás y algún alcance de recurso de Finanzas (`finance/…` o `all`) consulta sus **propias** aprobaciones; no hay alcance de recurso ni permiso propios. Pero `error`, `result` y el valor leído del registro son datos del recurso de la operación: solo salen cuando el token lee ese recurso y usted **todavía** tiene permiso para leerlo en el workspace (quien perdió el permiso después de la operación deja de ver el retorno) (por ejemplo, `finance/categories` con `read` para la eliminación de una categoría; en las operaciones de dinero — enviar al banco, cobrar — el recurso de dinero y el del título juntos: `finance/payable_dispatches` con `finance/payables`, `finance/receivable_charges` con `finance/receivables`). Sin eso, la aprobación viene con la situación, el título y las fechas, `error` y `result` en `null` y `"result_hidden": true`; el valor que el propio asistente envió en los argumentos sigue apareciendo. La aprobación de otra persona, de otra organización, de otro workspace o un id que no existe devuelven el mismo `NOT_FOUND`. Las dos tools solo leen: ninguna aprueba, cancela ni reabre nada. Un token sin persona detrás no tiene quién abra el enlace y sigue recibiendo `confirmation_required`. --- # Transporte **Streamable HTTP, stateless.** Un mensaje JSON-RPC 2.0 por `POST`, una respuesta JSON. No hay `Mcp-Session-Id`, no hay reanudación y no hay stream servidor→cliente: la aplicación corre varias réplicas, y ninguna operación necesita empujar mensajes al cliente. ## Versiones del protocolo[​](#versiones-del-protocolo "Enlace directo al Versiones del protocolo") El servidor habla dos eras del protocolo en el mismo endpoint: | Versión | Era | Estado | | ------------ | --------------------------------------------------------------------------------------- | --------- | | `2026-07-28` | Stateless, sin handshake — descubrimiento por `server/discover` | Soportada | | `2025-06-18` | Handshake por `initialize` — es la versión en la que el `initialize` cierra por defecto | Soportada | | `2025-03-26` | Handshake por `initialize` | Soportada | La era se decide **por el cuerpo** de la solicitud, con los encabezados como verificación: * **`params._meta` trae `io.modelcontextprotocol/protocolVersion`** → era `2026-07-28` (ver abajo). * **Sin ese envoltorio**, con `MCP-Protocol-Version` de 2025 o sin el encabezado → era 2025, con `initialize`. * **`MCP-Protocol-Version: 2026-07-28` sin el envoltorio** → `400` con `-32602`. El servidor no cae en silencio a la era antigua: pediste la semántica stateless y recibirías la otra. Una versión que el servidor no habla — en el encabezado o en el envoltorio, en cualquier era — se responde con `400` y el error JSON-RPC `-32022`, listando las soportadas: ``` { "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" } } } ``` La versión en uso vuelve en el encabezado `MCP-Protocol-Version` de la respuesta. ### Era `2026-07-28`[​](#era-2026-07-28 "Enlace directo al era-2026-07-28") No hay handshake: **cada** solicitud lleva su propia versión y las capacidades del cliente en `params._meta`, y el servidor no recuerda nada entre una solicitud y otra. | Clave de `params._meta` | Obligatoria | Significado | | -------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `io.modelcontextprotocol/protocolVersion` | sí | `2026-07-28` | | `io.modelcontextprotocol/clientCapabilities` | sí | Capacidades del cliente (un objeto; `{}` sirve). Las tools destructivas devuelven un enlace de aprobación con o sin `elicitation` de formulario — vea [confirmación de tools destructivas](https://docs.finance.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md#confirmaci%C3%B3n-de-tools-destructivas) | | `io.modelcontextprotocol/clientInfo` | recomendada | `name` y `version` del cliente | Los encabezados repiten lo que está en el cuerpo, para que los intermediarios puedan enrutar sin leerlo — y por eso tienen que coincidir con él: | Encabezado | Tiene que ser igual a | | ---------------------- | ------------------------------------------------------------------- | | `MCP-Protocol-Version` | La versión del envoltorio | | `Mcp-Method` | El `method` del mensaje | | `Mcp-Name` | Solo en `tools/call`: el `params.name`, crudo o como `=?base64?…?=` | Cualquier divergencia es `400` con `-32020` (`Header mismatch: …`). Si falta `clientCapabilities`, es `400` con `-32602`. Los resultados de esta era siempre traen `resultType: "complete"` y el servidor en `_meta["io.modelcontextprotocol/serverInfo"]`. `server/discover`, `tools/list`, `resources/list`, `resources/templates/list`, `resources/read` y `prompts/list` traen además `ttlMs: 0` y `cacheScope: "private"`: lo que vuelve está filtrado por el scope y los permisos de quien llama, así que no debe reutilizarse ni compartirse. Un `tools/call` de una tool destructiva puede volver `resultType: "input_required"` — ver [Confirmación de tools destructivas](https://docs.finance.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md#confirmaci%C3%B3n-de-tools-destructivas). ## Encabezados de la solicitud[​](#encabezados-de-la-solicitud "Enlace directo al Encabezados de la solicitud") | Encabezado | Obligatorio | Significado | | ---------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | sí | `Bearer ` emitido para el MCP — ver [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md) | | `X-Workspace-Id` | no | Workspace predeterminado de la conexión, usado cuando la tool no recibe `workspace_id` — lo mismo que `?workspace_id=` en la URL. Ver [Autenticación → El workspace](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md#el-workspace) | | `Content-Type` | sí | `application/json` | | `Accept` | recomendado | `application/json` | | `MCP-Protocol-Version` | sí en la era `2026-07-28`; recomendado en la de 2025 | Revisión del protocolo | | `Mcp-Method` | sí en la era `2026-07-28` | El método del mensaje | | `Mcp-Name` | sí en el `tools/call` de la era `2026-07-28` | El nombre de la tool | | `Origin` | condicional | Lo envían los clientes de navegador; se valida contra una allowlist | ## Encabezados de la respuesta[​](#encabezados-de-la-respuesta "Enlace directo al Encabezados de la respuesta") | Encabezado | Significado | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MCP-Protocol-Version` | Revisión en uso | | `Cache-Control` | `no-store` en toda respuesta, incluidas las de error (`400`, `401`, `403`, `404`, `405`, `413`, `429`, `503`) y el `204` del `DELETE`. Solo el documento `/.well-known/oauth-protected-resource`, público e igual para todos, usa `public, max-age=300` | | `Content-Security-Policy` | `default-src 'none'` en toda respuesta, incluida la del documento de metadata — el servidor solo devuelve JSON | | `Retry-After` | En `429` — ver [Límite de solicitudes](https://docs.finance.kobana.com.br/es/es/mcp/overview/rate-limit.md) — y en `503` | ## Métodos[​](#métodos "Enlace directo al Métodos") | Método | Era `2026-07-28` | Era 2025 | Para qué | | -------------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------- | | `server/discover` | sí | — | Versiones soportadas, capacidades del servidor e instrucciones | | `initialize` | — | sí | Negociación de versión, capacidades del servidor e instrucciones | | `ping` | — | sí | Prueba de vida; responde un resultado vacío | | `tools/list` | sí | sí | Las tools que este llamador puede ejecutar, con JSON Schema y anotaciones | | `tools/call` | sí | sí | Ejecuta una tool | | `resources/list` | sí | sí | Los documentos de URI fija que este llamador puede leer | | `resources/templates/list` | sí | sí | Los templates de URI (`kobana://finance/payables/{id}`, …) que este llamador puede leer | | `resources/read` | sí | sí | Lee un documento por la URI | | `prompts/list` | sí | sí | Los guiones listos que este llamador puede usar | | `prompts/get` | sí | sí | Arma un guion con los argumentos dados | | `completion/complete` | sí | sí | Sugerencias para un argumento de prompt o de template | Resources, prompts y completions están en [Resources y prompts](https://docs.finance.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md). Cualquier otro método es `-32601 Method not found` — en la era `2026-07-28`, con HTTP `404`; en la de 2025, en el cuerpo de un `200`. **El batching JSON-RPC no está soportado** — se eliminó en la revisión `2025-06-18`, y un cuerpo en array se responde con `400`. **El cuerpo tiene un tope de 14 MB** (14.680.064 bytes) — suficiente para la mayor solicitud legítima, un `finance_attachments_upload` de 10 MB en base64 con el envoltorio. Por encima, la respuesta es `413` con `{ "jsonrpc": "2.0", "id": null, "error": { "code": -32600, "message": "Request body too large (limit 14680064 bytes)" } }`: un `Content-Length` declarado por encima del tope se rechaza incluso antes de la autenticación, y un cuerpo sin `Content-Length` (o con uno falso) se corta en el tope durante la lectura. Una **notificación** (mensaje sin `id`, como `notifications/initialized`) se acepta con `202` y cuerpo vacío, en las dos eras. La autenticación viene **antes** de cualquier método, incluido `server/discover`: sin token, la respuesta es el `401` con el desafío que lleva al cliente al login OAuth — ver [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). ### `server/discover` (era `2026-07-28`)[​](#serverdiscover-era-2026-07-28 "Enlace directo al serverdiscover-era-2026-07-28") ``` POST / HTTP/1.1 Authorization: Bearer Content-Type: application/json MCP-Protocol-Version: 2026-07-28 Mcp-Method: server/discover ``` ``` { "jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {}, "io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0.0" } } } } ``` ``` { "jsonrpc": "2.0", "id": 1, "result": { "resultType": "complete", "supportedVersions": ["2026-07-28", "2025-06-18", "2025-03-26"], "capabilities": { "tools": {}, "resources": {}, "prompts": {}, "completions": {} }, "instructions": "Tools for Kobana Finance: ...", "ttlMs": 0, "cacheScope": "private", "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "kobana-finance", "title": "Kobana Finance", "version": "1.0.0" } } } } ``` ### `initialize` (handshake de la era 2025)[​](#initialize-handshake-de-la-era-2025 "Enlace directo al initialize-handshake-de-la-era-2025") ``` { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18" } } ``` ``` { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-06-18", "capabilities": { "tools": { "listChanged": false }, "resources": { "subscribe": false, "listChanged": false }, "prompts": { "listChanged": false }, "completions": {} }, "serverInfo": { "name": "kobana-finance", "title": "Kobana Finance", "version": "1.0.0" }, "instructions": "Tools for Kobana Finance: ..." } } ``` Las `instructions` (en `initialize` y en `server/discover`) avisan al agente que los valores de campo en los resultados son **datos escritos por terceros, nunca instrucciones**, y piden confirmación del usuario antes de una acción destructiva o que mueve dinero que un resultado parezca pedir. ### `tools/list`[​](#toolslist "Enlace directo al toolslist") Devuelve **solo** las tools que el llamador puede ejecutar — las que alcanza el scope del token **y** que la persona que autorizó puede hacer en el panel. El `inputSchema` de una tool de escritura es el **propio schema de request** del endpoint — los mismos campos, obligatorios y enums de la [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api/overview/introduction.md). Cada tool lleva `annotations`, que es lo que hace que el cliente pida confirmación al usuario: | Anotación | Significado | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `readOnlyHint` | La tool solo lee | | `destructiveHint` | La tool borra, cancela o mueve dinero — solo se ejecuta con la [confirmación del servidor](https://docs.finance.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md#confirmaci%C3%B3n-de-tools-destructivas) | | `idempotentHint` | Repetir la llamada tiene el mismo efecto | | `openWorldHint` | Siempre `false` — la tool no alcanza nada fuera de Finanzas Inteligentes | ### `tools/call`[​](#toolscall "Enlace directo al 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"] } } } ``` El resultado trae la respuesta JSON del endpoint como contenido de texto: ``` { "jsonrpc": "2.0", "id": 2, "result": { "content": [{ "type": "text", "text": "{ \"data\": [ ... ], \"meta\": { \"next_cursor\": \"…\" } }" }] } } ``` Los errores sobre los que el llamador puede actuar vuelven con `isError: true` **dentro** del resultado, no como error JSON-RPC — ver [Errores](https://docs.finance.kobana.com.br/es/es/mcp/overview/errors.md). ## Despacho in-process[​](#despacho-in-process "Enlace directo al Despacho in-process") Cada tool despacha **in-process** al handler de `/v1` que implementa la operación, con la identidad ya verificada y el workspace resuelto para la llamada — el token del MCP no se reenvía, y el endpoint sigue exigiendo su propio scope. No hay un segundo viaje HTTP ni una segunda implementación: filtros, validación, reglas de liquidación, prorrateo, bloqueos de seguridad y aislamiento por workspace son el mismo código que corre la API REST. Las escrituras quedan registradas con el canal **`mcp`** (`created_via` / `updated_via`), distinguibles de las hechas por la API o por el panel. ## Archivos[​](#archivos "Enlace directo al Archivos") * **Descarga** — `finance_attachments_download` **no** devuelve los bytes: un PDF en base64 en el contexto de un modelo es caro e inútil. El resultado trae el `content_type`, el tamaño y el camino para descargar el archivo en la API — con un token emitido para la API, ya que el del MCP no vale allí. * **Subida** — `finance_attachments_upload` recibe el archivo en `content_base64` (hasta 10 MB) y lo envía al endpoint como `multipart/form-data`. Después, `finance_attachments_link` lo adjunta a un título o movimiento. --- # Cuentas financieras y flujo de caja Las cuentas financieras, el saldo calculado y los saldos observados de cada fuente, el catálogo de bancos, la proyección del flujo de caja y las tarjetas de crédito con sus resúmenes, movimientos y recurrencias y las alícuotas de IOF. ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | --------------------------------------------------- | ----- | ---- | ----- | ----------- | | `financial_accounts` — Cuentas financieras y saldos | 10 | 4 | 3 | 3 | | `banks` — Bancos | 1 | 1 | 0 | 0 | | `cash_flow` — Flujo de caja | 1 | 1 | 0 | 0 | | `credit_cards` — Tarjetas de crédito | 5 | 2 | 2 | 1 | | `card_statements` — Resúmenes de la tarjeta | 9 | 3 | 2 | 4 | | `card_transactions` — Movimientos de la tarjeta | 8 | 3 | 3 | 2 | | `card_recurrences` — Recurrencias de la tarjeta | 5 | 2 | 2 | 1 | | `iof_rates` — Alícuotas de IOF | 1 | 1 | 0 | 0 | ## `financial_accounts`[​](#financial_accounts "Enlace directo al financial_accounts") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | -------------------------------------------- | ----------- | -------- | ------------------ | ------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `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 "Enlace directo al banks") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | -------------------- | ---- | ------ | --------------- | ----------- | --------------- | ----------------------------------------------------------------------------------------- | | `finance_banks_list` | read | `read` | `finance/banks` | — (ninguno) | `GET /v1/banks` | The Brazilian bank catalog (COMPE/BACEN codes) — use it to find `bank_id` for an account. | ## `cash_flow`[​](#cash_flow "Enlace directo al cash_flow") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ----------------------- | ---- | ------ | ------------------- | ---------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Enlace directo al credit_cards") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ----------------------------- | ----------- | ------- | ---------------------- | --------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `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 "Enlace directo al card_statements") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ----------------------------------------- | ----------- | -------- | ---------------------- | ------------------------ | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Enlace directo al card_transactions") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | -------------------------------------- | ----------- | -------- | ---------------------- | -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Enlace directo al card_recurrences") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | --------------------------------- | ----------- | -------- | ---------------------- | -------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Enlace directo al iof_rates") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ------------------------ | ---- | ------ | ---------------------- | ----------- | ------------------- | ------------------------------------------------------------------------------- | | `finance_iof_rates_list` | read | `read` | `finance/credit_cards` | — (ninguno) | `GET /v1/iof-rates` | List the IOF rates with their validity (global and this workspace's overrides). | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api/overview/introduction.md) y en `finance_schemas_get`. Una tool que no puedes ejecutar no aparece en `tools/list`. Si falta alguna de esta página, ve [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Cuentas por pagar y por cobrar Los títulos: crear, modificar, liquidar, cancelar y borrar cuentas por pagar y por cobrar, los totales por período, enviar un pago al banco y emitir un cobro (boleto o Pix). ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | ---------------------------------- | ----- | ---- | ----- | ----------- | | `payables` — Cuentas por pagar | 10 | 4 | 1 | 5 | | `receivables` — Cuentas por cobrar | 10 | 4 | 1 | 5 | ## `payables`[​](#payables "Enlace directo al payables") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ---------------------------------- | ------------- | -------- | ---------------------------- | ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `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 "Enlace directo al receivables") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ----------------------------------- | ------------- | -------- | ---------------------------- | -------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `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. | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api/overview/introduction.md) y en `finance_schemas_get`. Una tool que no puedes ejecutar no aparece en `tools/list`. Si falta alguna de esta página, ve [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Adjuntos, notas fiscales, esquemas y espacios Los archivos adjuntos a los registros, las notas fiscales recibidas, `finance_schemas_get`, el catálogo de los campos que devuelve cada tool — qué pedir en `fields` —, y `finance_workspaces_list`, los espacios de donde sale el `workspace_id` de las demás tools — y `finance_me`, la identidad detrás del token de la conexión — y `finance_organization_get`/`_update`, la organización del token — y `finance_operation_approvals_get`/`_list`, el resultado de las operaciones que aprobaste por el enlace. ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | ----------------------------------------------- | ----- | ---- | ----- | ----------- | | `attachments` — Adjuntos | 7 | 3 | 2 | 2 | | `fiscal_documents` — Notas fiscales recibidas | 2 | 2 | 0 | 0 | | `schemas` — Catálogo de campos | 1 | 1 | 0 | 0 | | `workspaces` — Espacios | 1 | 1 | 0 | 0 | | `me` — Identidad | 1 | 1 | 0 | 0 | | `organization` — Organización | 2 | 1 | 1 | 0 | | `operation_approvals` — Aprobaciones por enlace | 2 | 2 | 0 | 0 | ## `attachments`[​](#attachments "Enlace directo al attachments") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ------------------------------ | ----------- | -------- | --------------------- | ---------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `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 "Enlace directo al fiscal_documents") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ------------------------------- | ---- | ------ | -------------------------- | ----------------------- | ------------------------------- | ---------------------------------------------------------------------------------- | | `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 "Enlace directo al schemas") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | --------------------- | ---- | ------ | ----- | ----------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `finance_schemas_get` | read | `read` | — | — (ninguno) | — (local) | Describe a schema of the Finance API contract: the fields a tool returns (`PayableDetailV1`, `FinancialTransactionV1`…) or accepts. | ## `workspaces`[​](#workspaces "Enlace directo al workspaces") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ------------------------- | ---- | ------ | ----- | ----------- | --------- | -------------------------------------------------------- | | `finance_workspaces_list` | read | `read` | — | — (ninguno) | — (local) | List the workspaces of this organization you can act on. | ## `me`[​](#me "Enlace directo al me") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ------------ | ---- | ----- | ----- | ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_me` | read | — | — | — (ninguno) | — (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 "Enlace directo al organization") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ----------------------------- | ----- | ------- | ------------------ | ----------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Enlace directo al operation_approvals") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ---------------------------------- | ---- | ------ | ----- | ----------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `finance_operation_approvals_get` | read | `read` | — | — (ninguno) | — (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` | — | — (ninguno) | — (local) | List the operation approvals you asked for in this workspace, most recent first, with the same fields as finance\_operation\_approvals\_get. | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api/overview/introduction.md) y en `finance_schemas_get`. Una tool que no puedes ejecutar no aparece en `tools/list`. Si falta alguna de esta página, ve [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Tools El servidor expone **148 tools** sobre **30 familias de recurso**. Cada una despacha in-process al endpoint de `/v1` que ya implementa la operación, así que filtros, validación, reglas de liquidación y aislamiento por workspace son exactamente los de la API REST — la tool *es* el endpoint. Las excepciones, `finance_schemas_get` (el contrato publicado), `finance_workspaces_list` (los espacios que alcanza la persona), `finance_me` (la identidad del token) y `finance_operation_approvals_get`/`_list` (tus aprobaciones por enlace), responden localmente. `finance_organization_get`/`_update` van al endpoint, pero son de nivel de organización: como `finance_me`, no llevan workspace. Toda otra tool acepta `workspace_id`. ## Cómo leer estas páginas[​](#cómo-leer-estas-páginas "Enlace directo al Cómo leer estas páginas") Cada tool aparece con seis datos: > `finance_payables_send_to_bank` · **destructive** · verbo `write` · scope `finance/payable_dispatches` · permiso `payables.dispatch` · `POST /v1/payables/{id}/send-to-bank` | Campo | Significado | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **read** / **write** / **destructive** | La anotación que lee el cliente MCP. Una `destructive` solo se ejecuta después de que el servidor pide confirmación a la persona — en un cliente que no puede preguntar, la tool devuelve un enlace para que usted confirme en la app. Vea [Confirmación de tools destructivas](https://docs.finance.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md#confirmaci%C3%B3n-de-tools-destructivas). | | **destructive\*** | Destructiva solo en algunas llamadas: el `*_update` que liquida o cancela el título (`status` `paid`/`received`/`cancelled`). Solo esa llamada pide confirmación; las demás modificaciones se ejecutan directamente. | | **verbo** | El nivel de acceso que el token debe tener: `read`, `write`, `delete`, `import` o `export`. Ninguno sustituye a otro — `write` no elimina. `—` cuando la tool no exige scope (solo `finance_me`). | | **scope** | El recurso que el token debe alcanzar: `finance/` o `finance/all` (o `all`, que es lo mismo). Vale para el token que trae scopes `finance/…` (el de un cliente OAuth); un token solo con el nivel de acceso, sin scope `finance/…` ni `all`, no alcanza nada. Enviar al banco y cobrar son `write` en los recursos de dinero (`finance/payable_dispatches`, `finance/receivable_charges`) — vea [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). | | **permiso** | El permiso que la persona del token debe tener en la organización — el mismo que la acción exige en el panel. | | **`MÉTODO /ruta`** | El endpoint de `/v1` al que despacha la tool, para cruzar con la [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api/overview/introduction.md). El token necesita el scope que ese endpoint exige. | ## Argumentos comunes[​](#argumentos-comunes "Enlace directo al Argumentos comunes") Aparecen en muchas tools y siempre significan lo mismo. | Argumento | Tipo | Descripción | | ----------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `limit` | entero | Tamaño de página. Predeterminado `25`, máximo `100` (`10000` en las tools `*_ids`). | | `cursor` | string | El `meta.next_cursor` de la página anterior. `null` ahí significa la última página. | | `filters` | object | Los filtros que acepta el listado: un escalar es igualdad, un array es `in`, un objeto elige operadores (`{ "gte": …, "lt": … }`). | | `sort_by` | enum | Columna de orden, entre las que acepta el listado. | | `sort_order` | `asc` \| `desc` | Dirección. Predeterminado `asc`. | | `fields` | string\[] | Columnas a devolver. Omitido, vuelve el registro entero; `id` siempre vuelve. | | `idempotency_key` | string | Protección contra repeticiones, enviada como `X-Idempotency-Key`. Obligatoria en las acciones que mueven dinero. | | `custom_metadata` | object | JSON libre tuyo, devuelto en cada lectura. | ## El catálogo[​](#el-catálogo "Enlace directo al El catálogo") | Familia | Tools | read | write | destructive | | ----------------------------------------------------------------------------------------------------------------------- | ----- | ---- | ----- | ----------- | | [`payables` — Cuentas por pagar](https://docs.finance.kobana.com.br/es/es/mcp/tools/billings.md) | 10 | 4 | 1 | 5 | | [`receivables` — Cuentas por cobrar](https://docs.finance.kobana.com.br/es/es/mcp/tools/billings.md) | 10 | 4 | 1 | 5 | | [`financial_transactions` — Movimientos](https://docs.finance.kobana.com.br/es/es/mcp/tools/transactions.md) | 11 | 5 | 2 | 4 | | [`transfers` — Transferencias](https://docs.finance.kobana.com.br/es/es/mcp/tools/transactions.md) | 2 | 1 | 0 | 1 | | [`reconciliations` — Conciliaciones](https://docs.finance.kobana.com.br/es/es/mcp/tools/transactions.md) | 3 | 1 | 0 | 2 | | [`receipts` — Comprobantes](https://docs.finance.kobana.com.br/es/es/mcp/tools/transactions.md) | 2 | 2 | 0 | 0 | | [`financial_accounts` — Cuentas financieras y saldos](https://docs.finance.kobana.com.br/es/es/mcp/tools/accounts.md) | 10 | 4 | 3 | 3 | | [`banks` — Bancos](https://docs.finance.kobana.com.br/es/es/mcp/tools/accounts.md) | 1 | 1 | 0 | 0 | | [`cash_flow` — Flujo de caja](https://docs.finance.kobana.com.br/es/es/mcp/tools/accounts.md) | 1 | 1 | 0 | 0 | | [`credit_cards` — Tarjetas de crédito](https://docs.finance.kobana.com.br/es/es/mcp/tools/accounts.md) | 5 | 2 | 2 | 1 | | [`card_statements` — Resúmenes de la tarjeta](https://docs.finance.kobana.com.br/es/es/mcp/tools/accounts.md) | 9 | 3 | 2 | 4 | | [`card_transactions` — Movimientos de la tarjeta](https://docs.finance.kobana.com.br/es/es/mcp/tools/accounts.md) | 8 | 3 | 3 | 2 | | [`card_recurrences` — Recurrencias de la tarjeta](https://docs.finance.kobana.com.br/es/es/mcp/tools/accounts.md) | 5 | 2 | 2 | 1 | | [`iof_rates` — Alícuotas de IOF](https://docs.finance.kobana.com.br/es/es/mcp/tools/accounts.md) | 1 | 1 | 0 | 0 | | [`companies` — Empresas](https://docs.finance.kobana.com.br/es/es/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`people` — Personas](https://docs.finance.kobana.com.br/es/es/mcp/tools/registers.md) | 6 | 3 | 2 | 1 | | [`categories` — Categorías](https://docs.finance.kobana.com.br/es/es/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`classification_centers` — Centros de clasificación](https://docs.finance.kobana.com.br/es/es/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`custom_classifiers` — Clasificadores personalizados](https://docs.finance.kobana.com.br/es/es/mcp/tools/registers.md) | 8 | 2 | 4 | 2 | | [`taxes` — Impuestos](https://docs.finance.kobana.com.br/es/es/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`automatic_rules` — Reglas automáticas](https://docs.finance.kobana.com.br/es/es/mcp/tools/registers.md) | 6 | 2 | 3 | 1 | | [`ai_agents` — Agentes de IA](https://docs.finance.kobana.com.br/es/es/mcp/tools/registers.md) | 9 | 3 | 4 | 2 | | [`ai_skills` — Habilidades de IA](https://docs.finance.kobana.com.br/es/es/mcp/tools/registers.md) | 5 | 2 | 2 | 1 | | [`attachments` — Adjuntos](https://docs.finance.kobana.com.br/es/es/mcp/tools/documents.md) | 7 | 3 | 2 | 2 | | [`fiscal_documents` — Notas fiscales recibidas](https://docs.finance.kobana.com.br/es/es/mcp/tools/documents.md) | 2 | 2 | 0 | 0 | | [`schemas` — Catálogo de campos](https://docs.finance.kobana.com.br/es/es/mcp/tools/documents.md) | 1 | 1 | 0 | 0 | | [`workspaces` — Espacios](https://docs.finance.kobana.com.br/es/es/mcp/tools/documents.md) | 1 | 1 | 0 | 0 | | [`me` — Identidad](https://docs.finance.kobana.com.br/es/es/mcp/tools/documents.md) | 1 | 1 | 0 | 0 | | [`organization` — Organización](https://docs.finance.kobana.com.br/es/es/mcp/tools/documents.md) | 2 | 1 | 1 | 0 | | [`operation_approvals` — Aprobaciones por enlace](https://docs.finance.kobana.com.br/es/es/mcp/tools/documents.md) | 2 | 2 | 0 | 0 | Una tool que no puedes ejecutar no aparece en `tools/list`. Si falta alguna de esta página, ve [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Registros Lo que clasifica títulos y movimientos: empresas, personas, categorías, centros de clasificación, clasificadores personalizados, impuestos y las reglas de clasificación automática — y los agentes de IA, instrucciones que el asistente ejecuta solo en un horario, y las habilidades de IA, instrucciones que carga cuando la tarea las pide. ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | ---------------------------------------------------- | ----- | ---- | ----- | ----------- | | `companies` — Empresas | 5 | 2 | 2 | 1 | | `people` — Personas | 6 | 3 | 2 | 1 | | `categories` — Categorías | 5 | 2 | 2 | 1 | | `classification_centers` — Centros de clasificación | 5 | 2 | 2 | 1 | | `custom_classifiers` — Clasificadores personalizados | 8 | 2 | 4 | 2 | | `taxes` — Impuestos | 5 | 2 | 2 | 1 | | `automatic_rules` — Reglas automáticas | 6 | 2 | 3 | 1 | | `ai_agents` — Agentes de IA | 9 | 3 | 4 | 2 | | `ai_skills` — Habilidades de IA | 5 | 2 | 2 | 1 | ## `companies`[​](#companies "Enlace directo al companies") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | -------------------------- | ----------- | -------- | ------------------- | ------------------ | --------------------------- | -------------------------------------------- | | `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 "Enlace directo al people") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ----------------------- | ----------- | -------- | ---------------- | --------------- | ------------------------ | ---------------------------------------------------------------- | | `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 "Enlace directo al categories") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | --------------------------- | ----------- | -------- | -------------------- | ------------------- | ---------------------------- | ----------------------------------------------------------------- | | `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 "Enlace directo al classification_centers") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | --------------------------------------- | ----------- | -------- | ---------------------- | --------------------- | ---------------------------------------- | ----------------------------------------------------------------------- | | `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 "Enlace directo al custom_classifiers") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ------------------------------------------ | ----------- | -------- | ---------------------------- | --------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `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 "Enlace directo al taxes") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ---------------------- | ----------- | -------- | --------------- | -------------- | ----------------------- | --------------------------------------------------------------- | | `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 "Enlace directo al automatic_rules") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | --------------------------------- | ----------- | -------- | ------------------------- | ------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `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 "Enlace directo al ai_agents") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ---------------------------------- | ----------- | -------- | ------------------- | ------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Enlace directo al ai_skills") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | -------------------------- | ----------- | -------- | ------------------- | ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api/overview/introduction.md) y en `finance_schemas_get`. Una tool que no puedes ejecutar no aparece en `tools/list`. Si falta alguna de esta página, ve [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Movimientos y conciliación El lado realizado: los movimientos de cada cuenta, las transferencias entre cuentas, la conciliación de títulos con movimientos y los comprobantes de pago. ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | -------------------------------------- | ----- | ---- | ----- | ----------- | | `financial_transactions` — Movimientos | 11 | 5 | 2 | 4 | | `transfers` — Transferencias | 2 | 1 | 0 | 1 | | `reconciliations` — Conciliaciones | 3 | 1 | 0 | 2 | | `receipts` — Comprobantes | 2 | 2 | 0 | 0 | ## `financial_transactions`[​](#financial_transactions "Enlace directo al financial_transactions") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ----------------------------------------------------------- | ----------- | -------- | ------------------------- | ------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Enlace directo al transfers") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | -------------------------- | ----------- | ------- | ---------------------- | ------------------- | --------------------------------- | -------------------------------------------------------------------------------------------- | | `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 "Enlace directo al reconciliations") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | -------------------------------- | ----------- | -------- | ------------------------- | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------- | | `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 "Enlace directo al receipts") | Tool | Tipo | Verbo | Scope | Permiso | Endpoint | Qué hace | | ----------------------- | ---- | ------ | ------------------ | --------------- | ----------------------- | ------------------------------------------------------- | | `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. | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api/overview/introduction.md) y en `finance_schemas_get`. Una tool que no puedes ejecutar no aparece en `tools/list`. Si falta alguna de esta página, ve [Autenticación](https://docs.finance.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Mi perfil **Mi perfil** (`/profile`) muestra la información de tu cuenta. Es el **único destino interno del menú de usuario** — el avatar en la esquina superior derecha. ![Mi perfil](/es/assets/images/20-profile-bf68191f3b3efec1ccc30590c033d76b.png) ## Qué muestra la pantalla[​](#qué-muestra-la-pantalla "Enlace directo al Qué muestra la pantalla") Las tarjetas: | Tarjeta | Contenido | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Perfil** | Nombre y correo, tal como vinieron del inicio de sesión, y el espacio de trabajo activo. Sin selección, muestra *"Ningún espacio de trabajo seleccionado"* | | **Preferencias** | Tema (claro, oscuro o el del sistema) e idioma — los mismos controles del encabezado, en un lugar donde puedes ir a buscarlos | | **Organizaciones** | Solo para quien es miembro de dos o más organizaciones: el nombre de cada una en el selector — ver abajo | | **Notificaciones** | **Recibir la Agenda del día** por correo | | **Primeros Pasos** | Activa y desactiva el elemento **Primeros Pasos** del menú lateral | nota **Quién eres no se edita aquí.** El nombre y el correo vienen del inicio de sesión, y no hay contraseña — más abajo verás por qué. Lo que la pantalla sí guarda son preferencias: tema, idioma, el nombre de las organizaciones en el selector, la Agenda del día y la visualización de Primeros Pasos. ## El nombre de las organizaciones en el selector[​](#el-nombre-de-las-organizaciones-en-el-selector "Enlace directo al El nombre de las organizaciones en el selector") Quien es miembro de dos o más organizaciones ve la tarjeta **Organizaciones**. Allí le das a cada organización el nombre que quieres ver en el selector del encabezado y en la elección de organización al entrar — "Samsung" en lugar de la razón social completa, por ejemplo. * **El nombre es solo tuyo.** Los demás miembros siguen viendo el nombre que ellos dieron, o el oficial. * **El nombre oficial no cambia aquí.** Viene de tu cuenta Kobana y aparece como título de cada campo. * **Un campo en blanco vuelve al nombre oficial** — bórralo y haz clic en **Guardar**. * **El selector cambia al instante**, sin salir y volver a entrar. ## Cómo entras[​](#cómo-entras "Enlace directo al Cómo entras") **Este producto no usa contraseña.** Hay dos caminos, y ninguno pide una — pero no son intercambiables: * **Entrar con Kobana** — es la puerta de entrada. Tu cuenta Kobana te autentica, y es por ahí que llega quien todavía no tiene acceso a Finanzas Inteligentes. * **Enlace mágico** — indicas tu correo y recibes un enlace de acceso de un solo uso, válido por **15 minutos**. **Solo funciona para quien ya tiene acceso**: un correo al que no se le ha concedido nada no recibe ningún enlace. nota **El formulario de correo puede no aparecer en la pantalla de inicio de sesión.** Algunos entornos dejan solo **"Entrar con Kobana"**. El enlace mágico sigue valiendo para quien ya lo usa — simplemente deja de ofrecerse. Por eso no existe registro de contraseña, cambio de contraseña ni "olvidé mi contraseña": el correo **es** la identidad. La zona horaria tampoco se configura por aquí. ## Entrar no es lo mismo que tener acceso[​](#entrar-no-es-lo-mismo-que-tener-acceso "Enlace directo al Entrar no es lo mismo que tener acceso") Autenticarse prueba **quién eres**; entrar en el producto depende de que tengas un **espacio de trabajo**. Cuando ambos no coinciden, el inicio de sesión funciona y te detienes en una pantalla que explica por qué: | Pantalla | Cuándo aparece | Qué hacer | | --------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | **Crea el espacio de tu empresa** | Tu cuenta Kobana todavía no tiene un espacio de trabajo aquí | Revisa los datos y haz clic en **Crear espacio de trabajo** | | **Todavía no te han invitado** | Tu empresa ya tiene un espacio de trabajo, y tu correo no es miembro de él | Pide a un administrador que te habilite el acceso | | **Tu acceso está suspendido** | Eras miembro y un administrador pausó tu acceso | Habla con quien administra la cuenta — no es lo mismo que nunca haber sido invitado | | **Registro no disponible** | La creación de nuevos espacios de trabajo está desactivada en el entorno | Si tu empresa ya usa Finanzas Inteligentes, pide una invitación | info **La pantalla de creación no es un formulario.** El nombre de la empresa y el CNPJ (o CPF) vienen del registro de tu cuenta Kobana — tú revisas y confirmas, sin escribir nada. También por eso solo aparece en el inicio de sesión con Kobana: el enlace mágico autentica un correo, no una cuenta, y no lleva esos datos. tip **Si administras la cuenta en Kobana** y el espacio de trabajo de tu empresa ya existe, entras directamente: el inicio de sesión reconoce tu rol de administrador y habilita el acceso sin invitación. La excepción es haber tenido el acceso pausado — en ese caso vale la pausa. El botón **Volver**, en la esquina, regresa a la pantalla anterior. ## Cómo llegar[​](#cómo-llegar "Enlace directo al Cómo llegar") Haz clic en tu avatar, en la esquina superior derecha, y elige **Mi perfil**. La parte de arriba del menú muestra tu correo, tu nombre y el espacio de trabajo activo, con **Gestionar cuenta** — que abre tu cuenta Kobana en otra pestaña, y solo aparece en los entornos donde esa dirección está configurada. Debajo, el menú ofrece además **Política de privacidad**, **Política de seguridad**, **Términos de uso** y **Cerrar sesión** — los tres primeros abren páginas externas. ## Cambiar de espacio de trabajo[​](#cambiar-de-espacio-de-trabajo "Enlace directo al Cambiar de espacio de trabajo") No es aquí. La tarjeta solo **muestra** cuál está activo. Para cambiarlo, usa el selector en el encabezado de la aplicación o la pantalla de [Espacios de trabajo](https://docs.finance.kobana.com.br/es/es/workspaces/.md). --- # Notas fiscales **Documentos > Notas fiscales** (`/fiscal-documents`) reúne las *"Notas recibidas contra las empresas del espacio"* — las NF-e (producto) y NFS-e (servicio) que tus proveedores emitieron contra los CNPJ registrados. Entran solas por las integraciones o a mano, y desde aquí las concilias y las conviertes en cuentas. nota **Aquí está la nota que TÚ recibes, no la que emites.** Finanzas Inteligentes no emite ni cancela notas fiscales — las guarda, las lee y las concilia. Cancelar o reemitir siempre es del lado de quien la emitió. ## De dónde viene cada nota[​](#de-dónde-viene-cada-nota "Enlace directo al De dónde viene cada nota") | Origen | Cómo entra | Cómo aparece | | ---------------------- | ----------------------------------------------------- | ----------------------------------------- | | **nfe.io** | captura automática de las NFS-e de servicio recibidas | notas de **Servicio**, listas en la lista | | **Importación de XML** | envías los archivos en **"Importar XML"** | un XML o un ZIP con el mes entero | | **SEFAZ** | búsqueda por clave de acceso | la nota traída de SEFAZ por su clave | tip **Un ZIP con el mes entero funciona.** En *"Importar XML"* puedes soltar un paquete con varios XML de una vez — lo que ya existe se ignora, y solo lo nuevo entra. ## Encontrar una nota[​](#encontrar-una-nota "Enlace directo al Encontrar una nota") La búsqueda arriba acepta *"Buscar por clave, número o emisor"*. Las pestañas separan por tipo — *Todas*, *Servicio* y *Producto* — y los filtros recortan lo que importa: | Filtro | Qué muestra | | ------------------------- | ------------------------------------------------------------ | | **Sin empresa vinculada** | notas cuyo CNPJ del tomador no coincidió con ninguna empresa | | **Con cuenta generada** | notas que ya se volvieron cuenta por pagar | | **Sin cuenta generada** | notas que aún no se volvieron cuenta | | **Fecha de creación** | cuándo entró la nota al espacio | Cada nota muestra su **situación** — *Autorizada*, *Cancelada* o *Indefinida* — y, cuando solo se conoce el resumen de la nota, el marcador *Resumen*. info **Un resumen es una nota sin el detalle.** SEFAZ entrega al destinatario solo el encabezado de la NF-e hasta que lo manifiestes — sin ítems ni duplicatas. Una nota *Resumen* aparece en la lista, pero no tiene ítems para revisar ni cuotas para generar cuentas. ## La empresa vinculada[​](#la-empresa-vinculada "Enlace directo al La empresa vinculada") La nota se vincula a una empresa del espacio por el **CNPJ del tomador**. Cuando ningún CNPJ registrado coincide, queda *Sin empresa vinculada* — previsto, no un error: la nota puede haberse emitido contra un CNPJ que aún no registraste, o contra un CPF. En la pantalla de la nota, cuando no hay vínculo, el botón **Registrar empresa** abre el registro ya completado con el CNPJ del tomador; al guardarlo, la nota (y las demás que esperaban ese CNPJ) pasa a la empresa nueva. Si ya existe una empresa con ese CNPJ, el mismo botón vincula la nota a ella de inmediato, sin abrir el registro. ## Leer la nota[​](#leer-la-nota "Enlace directo al Leer la nota") Al abrir una nota ves: * **Prestador** y **Tomador** — razón social, CNPJ y dirección de cada lado. * **Valores e impuestos** — valor del servicio, base de cálculo, ISS y los impuestos retenidos (IRRF, PIS, COFINS, CSLL, INSS), con el valor neto. * **Servicio** (NFS-e) o **Ítems** (NF-e) — la descripción y los códigos fiscales, o la lista de productos. * **Duplicatas** y **Cuentas por pagar** — las cuotas de la nota y las cuentas ya generadas a partir de ella. ## Convertir en cuenta por pagar[​](#convertir-en-cuenta-por-pagar "Enlace directo al Convertir en cuenta por pagar") A partir de las duplicatas de la nota **generas las cuentas por pagar** — una por cuota. Las notas sin duplicata usan la fecha de vencimiento que informes al generar. Lo ya generado aparece en la pestaña *Cuentas por pagar* de la nota, y el filtro *Con cuenta generada* separa en la lista lo ya convertido de lo que aún falta. ## Descargar los archivos[​](#descargar-los-archivos "Enlace directo al Descargar los archivos") | Acción | Qué hace | | ------------------- | -------------------------------------------------------------- | | **Copiar XML** | copia el XML de la nota al portapapeles | | **Descargar XML** | descarga el XML guardado de la nota | | **Descargar todas** | genera un ZIP con los XML de todas las notas del filtro actual | aviso **No toda nota tiene XML guardado.** Una nota *Resumen* puede no tener XML — en ese caso *"Descargar XML"* queda no disponible y la etiqueta muestra *"Sin XML guardado"*. ## Por la API[​](#por-la-api "Enlace directo al Por la API") Las notas fiscales también se exponen, **solo lectura**, en la API v1 bajo el scope `finance/fiscal_documents` (nivel de acceso `read`): * [Listar notas fiscales](https://docs.finance.kobana.com.br/es/es/api/v1/list-fiscal-documents) — una página paginada, con filtros por empresa, tipo, situación, origen, clave, número y fecha. * [Obtener nota fiscal por ID](https://docs.finance.kobana.com.br/es/es/api/v1/get-fiscal-document) — la nota individual. El `xml_download_url` que devuelve la API apunta al recurso de adjuntos, así que descargar los bytes del XML exige también el scope `finance/attachments`. ## Relacionado[​](#relacionado "Enlace directo al Relacionado") * [Comprobantes](https://docs.finance.kobana.com.br/es/es/comprovantes/.md) — la prueba del pago que sale * [Adjuntos](https://docs.finance.kobana.com.br/es/es/anexos/.md) — donde se guardan los archivos de las notas * [Cuentas por pagar](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/.md) — en lo que se convierte una nota * [Integraciones](https://docs.finance.kobana.com.br/es/es/integracoes/.md) — la captura de las NFS-e por nfe.io --- # Personas Las personas (`/people`) son los clientes, proveedores y contactos registrados en el espacio de trabajo. Un mismo registro puede acumular roles — cliente, proveedor, ambos o ninguno — sin convertirse en un registro duplicado. ![Lista de personas](/es/assets/images/09-people-0c894746749cdf2fa7331e3817d7868f.png) ![Detalle de persona](/es/assets/images/10-person-detail-98fc5467286089971605c5b72e2b57b9.png) ## El listado[​](#el-listado "Enlace directo al El listado") Columnas: **foto**, **Nombre**, **Rol**, **Documento**, **Correo electrónico** y **Teléfono** — más **Registrado bajo**, que solo aparece en la vista consolidada. Cada rol se muestra como distintivo — **Cliente**, **Proveedor**, **Gerente de cuenta**, **Equipo** — o aparece el texto **Sin rol**. Sobre la tabla están la **búsqueda** (por nombre o documento) y el filtro **Rol**: **Todos**, **Clientes**, **Proveedores**, **Gerentes**, **Equipo** y **Sin rol**. Cada fila tiene dos acciones — **Editar** y **Eliminar**. El botón de creación es **"Nueva persona"**. ## El formulario[​](#el-formulario "Enlace directo al El formulario") Cuatro pestañas: **Identificación**, **Contacto**, **Dirección** y **Datos bancarios**. ### Identificación[​](#identificación "Enlace directo al Identificación") | Campo | Observaciones | | ----------------------- | ------------------------------------------------------------------------------------------------------------- | | **Nombre** | Obligatorio | | **Apodo** | Opcional | | **Razón social** | *"Para personas jurídicas — nombre legal oficial"* | | **Registrar en** | **Obligatorio** — la empresa bajo la cual se registra la persona | | **Rol** | Las casillas **Cliente**, **Proveedor**, **Gerente de cuenta** y **Equipo**. Dejar todas sin marcar es válido | | **Tipo** | **Detectar automáticamente** (por defecto), **Persona física** o **Persona jurídica** | | **CPF** / **CNPJ** | La etiqueta y la máscara siguen al Tipo — CPF por defecto, CNPJ cuando es persona jurídica | | **Fecha de nacimiento** | Opcional | **No hace falta elegir el Tipo.** Por defecto, el sistema lo deduce del documento que escribas. ### Contacto[​](#contacto "Enlace directo al Contacto") **Correos electrónicos** y **Teléfonos**, ambos en forma de lista — puedes agregar tantos como necesites. **Solo el correo lleva etiqueta.** Cada correo acepta una etiqueta libre (financiero, comercial…). El teléfono no tiene ese campo. Y **"correo principal" no es un concepto del sistema**: ningún correo se designa como principal. ### Dirección y Datos bancarios[​](#dirección-y-datos-bancarios "Enlace directo al Dirección y Datos bancarios") Dos pestañas propias. **Datos bancarios** cubre banco, agencia y cuenta (con dígitos), clave PIX y tipo de clave. ## Roles[​](#roles "Enlace directo al Roles") | Combinación | Uso típico | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cliente** | Quien le paga a la empresa | | **Proveedor** | A quien la empresa le paga | | **Cliente + Proveedor** | Socio que compra y vende | | **Gerente de cuenta** | Gerente del banco que atiende una cuenta de la empresa — ver [Gerentes](https://docs.finance.kobana.com.br/es/es/contas-financeiras/.md#gerentes) | | **Equipo** | Gente de la propia empresa: socios, equipo de finanzas — ver [Accesos](https://docs.finance.kobana.com.br/es/es/contas-financeiras/.md#accesos) | | Ninguno | Contacto sin relación financiera activa | El rol decide dónde aparece la persona: el campo **Cliente** de las cuentas por cobrar solo busca entre quienes son clientes; el de **Proveedor** de las cuentas por pagar, solo entre quienes son proveedores. Para quien es o fue gerente, el detalle de la persona muestra **Cuentas que atiende**, con el período de cada una; para quien tiene accesos a cuentas, **Accesos a cuentas**, con el nivel de cada una. ## Búsqueda y creación automática[​](#búsqueda-y-creación-automática "Enlace directo al Búsqueda y creación automática") Al escribir un nombre en los formularios de cuentas por pagar o por cobrar, el sistema busca entre los registros existentes y, si no encuentra ninguno, ofrece **registrarla por el nombre** — la persona se crea al guardar. La importación CSV hace lo mismo. ## Foto de perfil[​](#foto-de-perfil "Enlace directo al Foto de perfil") El sistema busca la foto en **dos** fuentes, en este orden: 1. **Gravatar** — por el correo registrado. Es la fuente primaria. 2. **WhatsApp** — por el teléfono, y solo si la integración está configurada para la empresa. Es el **respaldo**, y se usa cuando Gravatar no devuelve nada. nota **Ninguna foto aparece sola.** La búsqueda no corre en segundo plano ni al guardar la persona: es una herramienta manual, en **Mantenimiento → Obtener fotos**. Cada ejecución recorre **solo las personas que aún no tienen foto**, con un tope de **100 por vez**, y espera **30 días** antes de reintentar con quienes fallaron. La foto encontrada se **guarda** en el registro — no se vuelve a buscar en cada visita. La foto aparece en el listado y en la parte superior del detalle de la persona. ## Transferencias y Seguridad[​](#transferencias-y-seguridad "Enlace directo al Transferencias y Seguridad") La pestaña **Beneficiarios** de [Seguridad](https://docs.finance.kobana.com.br/es/es/seguranca/.md#beneficiarios) decide a qué beneficiarios se pueden enviar al banco las **transferencias (Pix y TED)**. La regla mira el **CPF/CNPJ**, no el registro: * **Una regla por documento.** La misma persona registrada en varias empresas aparece una sola vez en Seguridad, y liberar, bloquear o limitar vale para todos los registros con ese CPF/CNPJ — con los límites diario y mensual sumados entre las empresas. * **Registrar no se bloquea.** En el modo *Bloquear a todos y liberar algunos*, una persona nueva se puede registrar y usar en títulos normalmente; solo el **envío** de transferencias a ella queda frenado (*"Beneficiario no habilitado"*) hasta que alguien pida la liberación del documento y Kobana la apruebe. En el modo *Liberar a todos y bloquear algunos*, entra liberada. * **Boleto, tributo y servicio público no pasan por esta regla** — el dinero va a quien indica el código de barras, y el control está en Tipos de operaciones. * **Eliminar o fusionar registros no cambia la regla.** Un documento bloqueado sigue bloqueado aunque no tenga registro activo (aparece en Seguridad como *"Sin registro activo"*), y uno liberado sigue liberado. ## Eliminación[​](#eliminación "Enlace directo al Eliminación") Un único bloqueo: **una [regla automática](https://docs.finance.kobana.com.br/es/es/regras-automaticas/.md) que apunte a la persona**. Mientras exista una, la eliminación falla — la regla acabaría clasificando contra alguien invisible, y no hay a quién reapuntarla. Edita o elimina la regla antes. **Las cuentas por pagar, las cuentas por cobrar y las transacciones no bloquean.** El diálogo muestra lo que está vinculado, pero deja eliminar. peligro **La eliminación no se puede deshacer — y es intencional.** La persona desaparece de las pantallas, pero su historial financiero permanece intacto, apuntando al registro eliminado. No hay "restaurar": al eliminar, el **CPF/CNPJ queda liberado**, y nada impide que otro registro pase a usarlo. Por eso no se ofrece la vuelta atrás: podría chocar con quien ya ocupó el lugar. --- # Reglas automáticas Las reglas automáticas (`/automatic-rules`) clasifican transacciones automáticamente según criterios registrados, evitando la categorización manual de documentos recurrentes. ![Listado de reglas automáticas](/es/assets/images/14-automatic-rules-959c4feee2f453bde8529144e2adc408.png) ## Alcance de la regla[​](#alcance-de-la-regla "Enlace directo al Alcance de la regla") Cada regla tiene un **alcance fijo** (definido en la creación, **inmutable**) y pertenece a una **entidad**. El alcance es un par de pestañas en la parte superior del formulario, sin etiqueta — las dos opciones son: * **Cuentas Financieras** — se dispara en transacciones recién creadas. * **Cuentas por Pagar / Cobrar** — se dispara en cuentas recién creadas. ## Cómo funciona[​](#cómo-funciona "Enlace directo al Cómo funciona") Al evaluarse un documento, el sistema recorre las reglas **de la misma entidad y del mismo alcance**, en orden de precedencia. La **primera** regla activa cuyos criterios se cumplan todos se aplica — y solo ella. Los campos definidos en la regla **sobrescriben** los valores del documento, aunque ya estén completados. ## Criterios[​](#criterios "Enlace directo al Criterios") La regla combina criterios con lógica **Y** — todos tienen que cumplirse. El editor de la regla tiene dos lados, **CUANDO** (criterios) y **ENTONCES** (acciones), con una vista previa en lenguaje corriente. | Criterio | Cómo compara | | ------------------------ | ------------------------------------------------- | | **Entidad** | Obligatorio — la empresa de la regla | | **Cuenta** | Igualdad (solo en el alcance Cuentas Financieras) | | **Tipo de entrada** | **Pagos** o **Cobros** | | **Cliente/Proveedor** | Igualdad | | **Descripción contiene** | Fragmento del texto, ignorando mayúsculas | | **Notas contienen** | Fragmento del texto, ignorando mayúsculas | aviso **Las mayúsculas se ignoran; los acentos no.** La comparación convierte ambos lados a minúsculas, pero **no** quita el acento: una regla con **"Pao"** no atrapa una descripción escrita **"Pão"**. Escribe el criterio como el texto realmente llega. No existe criterio de **monto o rango**, ni operadores "igual a / comienza con / termina con" — el texto siempre es "contiene". tip El enlace **"Mostrar entradas afectadas por este criterio"** abre la vista previa con lo que la regla atraparía hoy — vale la pena revisarlo antes de guardar. ## Acciones[​](#acciones "Enlace directo al Acciones") | Acción | Descripción | | --------------------------- | ------------------------------------------------------------------------- | | **Descripción** | Reescribe la descripción | | **Cliente/Proveedor** | Asigna la persona | | **Categoría** | Asigna la categoría | | **Centro de clasificación** | Asigna **un** centro | | **Pagar/Cobrar vía** | Define la cuenta prevista (solo en el alcance Cuentas por Pagar / Cobrar) | nota **La acción de centro de clasificación no distribuye.** Asigna un único centro — el selector es de elección única. Para dividir entre centros, usa la **Distribución** en el formulario de la cuenta. Ver [Centros de clasificación](https://docs.finance.kobana.com.br/es/es/centros-de-classificacao/.md). **La regla no deshace una distribución.** En una cuenta ya distribuida entre dos o más categorías, la regla no toca la categoría; lo mismo vale para el centro de clasificación. Las demás acciones de la regla se aplican normalmente, y la vista previa muestra *"distribuido — la regla lo mantiene"* en el campo preservado. Para cambiar la distribución por una sola clasificación, usa **Clasificar seleccionados**. ## Precedencia[​](#precedencia "Enlace directo al Precedencia") Las reglas solo compiten **dentro de su propio grupo: entidad × alcance**. Cada tarjeta trae las flechas **"Mover arriba"** y **"Mover abajo"**, y la regla de menor posición gana primero. **Las flechas se detienen en el borde del grupo.** Aunque haya una tarjeta justo encima en la pantalla, la flecha no pasa por encima de ella si es de otro grupo — el listado muestra todos los grupos en una sola columna, pero el ordenamiento es por grupo. No es un bloqueo: mover para allá no tendría sentido, porque reglas de grupos distintos nunca disputan el mismo documento. * En un grupo de **una sola regla**, las flechas **no aparecen** — no hay contra quién ordenar. * En la primera del grupo, la flecha hacia arriba queda deshabilitada; en la última, la de abajo. * **No hay aviso al mover**: la tarjeta cambiando de lugar es la confirmación. **El orden de los grupos entre sí no significa nada.** Los grupos se listan por identificador interno de la entidad, no por nombre ni por relevancia. Que un grupo aparezca encima de otro no le da precedencia — la disputa nunca cruza grupos. ## Activar y pausar[​](#activar-y-pausar "Enlace directo al Activar y pausar") La píldora al pie de la tarjeta muestra el **estado** — **"Regla activa"** o **"Regla desactivada"** — y el clic hace la **acción opuesta**, que el tooltip anuncia: **"Pausar"** o **"Reanudar"**. Los avisos son **"Regla activada"** y **"Regla desactivada"**. **Una regla pausada nunca se dispara.** No es solo que se ignore en el listado: la evaluación solo considera reglas activas. Pausar es la forma de apagar una regla sin perderla. ## Dónde se disparan las reglas[​](#dónde-se-disparan-las-reglas "Enlace directo al Dónde se disparan las reglas") * **Creación** de transacciones y cuentas (formulario y API). * **Importación CSV** — transacciones, cuentas por pagar y cuentas por cobrar. * **Extractos bancarios**, al confirmar el extracto. * **Cuotas generadas** — cada cuota del grupo se evalúa por su cuenta, porque un criterio de descripción puede depender del sufijo ("1/12"). * **Importación de Fintera** — en los tres importadores: cuentas por pagar, cuentas por cobrar y transacciones. * **Sincronización de extracto del Gateway Bancario**. ## Aplicar a las ya existentes[​](#aplicar-a-las-ya-existentes "Enlace directo al Aplicar a las ya existentes") nota **No es una acción del listado.** Es la casilla **"¿Aplicar regla a entradas existentes?"**, al **pie del formulario**. Marcada, guardar pide confirmación y encola la aplicación retroactiva — que corre en segundo plano (*"Aplicación retroactiva en cola"*). Distinto del diálogo **"Clasificar"** en lote, que define categoría y centro manualmente sobre una selección, sin crear regla. ## Crear una regla[​](#crear-una-regla "Enlace directo al Crear una regla") 1. En `/automatic-rules`, usa **"Nueva Regla"**. 2. Elige la **Entidad** y, en las pestañas superiores, el alcance — **"Cuentas Financieras"** o **"Cuentas por Pagar / Cobrar"**. Solo se puede elegir ahora: después de guardada, la regla no cambia de alcance. 3. Arma los criterios (**CUANDO**) y las acciones (**ENTONCES**), revisando la vista previa. 4. Guarda — la regla vale de inmediato para los **nuevos** documentos. ## Eliminar[​](#eliminar "Enlace directo al Eliminar") El diálogo es **"Eliminar regla automática"**: *"La regla se eliminará permanentemente. Las entradas ya clasificadas no se ven afectadas."* --- # SDKs de Finanzas Inteligentes Los SDKs son las bibliotecas oficiales para llamar a la API REST de Finanzas Inteligentes desde **Node.js / TypeScript**, **Python**, **Ruby** y **PHP**, sin armar solicitudes HTTP, autenticación, paginación y manejo de errores a mano. ## Lenguajes[​](#lenguajes "Enlace directo al Lenguajes") | Lenguaje | Paquete | Registro | Estado | | -------------------- | ------- | --------- | ------------ | | Node.js / TypeScript | — | npm | Próximamente | | Python | — | PyPI | Próximamente | | Ruby | — | RubyGems | Próximamente | | PHP | — | Packagist | Próximamente | :::info Próximamente Los SDKs de Finanzas Inteligentes todavía no se publicaron. Cuando se publiquen, esta página listará el nombre del paquete y el comando de instalación de cada lenguaje. ::: ## Qué esperar[​](#qué-esperar "Enlace directo al Qué esperar") * Clientes generados a partir de la especificación OpenAPI de la API, con los mismos recursos y nombres de la [referencia de la API](https://docs.finance.kobana.com.br/es/es/api/overview/introduction.md). * Autenticación, paginación, reintentos y errores manejados por la biblioteca. * Un paquete por lenguaje, publicado en el registro oficial: npm, PyPI, RubyGems y Packagist. ## Mientras tanto[​](#mientras-tanto "Enlace directo al Mientras tanto") Ya puede integrar Finanzas Inteligentes de otras formas: * [API REST](https://docs.finance.kobana.com.br/es/es/api/overview/introduction.md): la referencia completa de los endpoints. * [MCP](https://docs.finance.kobana.com.br/es/es/mcp/overview/introduction.md): para que los agentes de IA operen el producto. * [CLI](https://docs.finance.kobana.com.br/es/es/cli/overview/introduction.md): el comando `kobana finance` en la terminal. Los SDKs de todos los productos Kobana están en el [catálogo de SDKs](https://www.kobana.com.br/desenvolvedores/sdks). --- # Seguridad **Seguridad** (`/settings/security`) reúne las reglas que protegen el dinero que sale por el banco: **qué se puede enviar, desde qué cuentas, a qué beneficiarios, por qué canales y con qué límites**. Vale solo para **pagos y transferencias** — los cobros quedan fuera. Las reglas son del **espacio de trabajo**: valen para todas sus empresas a la vez, y la pantalla lo avisa arriba (*"Vale para todas las empresas del espacio de trabajo…"*). Sin un espacio seleccionado, pide que elijas uno. ## Dónde está[​](#dónde-está "Enlace directo al Dónde está") ![Pestaña Límites de la pantalla Seguridad](/es/assets/images/21-security-limits-ecfe4d0ac7ca2104bc8ee3acb51e9bc4.png) Menú **Sistema** → **Seguridad**. ## Qué frenan las reglas[​](#qué-frenan-las-reglas "Enlace directo al Qué frenan las reglas") Casi todo aquí actúa **en el envío al banco**. Crear y aprobar títulos sigue libre: un título de un tipo desactivado, de una cuenta bloqueada o para un beneficiario no habilitado se puede registrar y aprobar normalmente — solo no sale al banco. Hay tres excepciones, que actúan antes del envío: * la pestaña **Canales**, que tiene interruptores propios para **Crear** y **Aprobar**; * el interruptor **Permitir aprobaciones en el período nocturno**, en la pestaña Límites; * la [Configuración de Aprobación](https://docs.finance.kobana.com.br/es/es/aprovar-pagamentos/.md#activar-o-desactivar), que también pasa por Kobana (ver [Quién puede pedir cambios](#qui%C3%A9n-puede-pedir-cambios)). nota Un límite **no se libera editando ni eliminando un título**. Lo que ya se envió al banco queda registrado aparte, con el monto del envío: eliminar el título o cambiar después el monto o el beneficiario no devuelve nada al límite. Solo un pago **cancelado, rechazado, reprobado o que falló** en el banco deja de contar. ## Nada vale en el acto[​](#nada-vale-en-el-acto "Enlace directo al Nada vale en el acto") ![Barra de cambios con un cambio listo para enviar](/es/assets/images/27-security-changes-c5e031eb5f8668df908812403f008e12.png) **Ningún cambio de esta pantalla tiene efecto inmediato.** Todo cambio se convierte en una **solicitud**, que **Kobana analiza y aprueba o deniega**. Una regla de seguridad que cualquiera pudiera aflojar en el acto no protegería nada. En la práctica: 1. Cambias lo que quieras, en todas las pestañas que quieras. Los cambios quedan en un borrador hasta el envío; una vez enviados, la pantalla vuelve a mostrar los valores **vigentes**. 2. Cada cambio aparece en la **barra lateral Cambios**, a la derecha, con el valor de antes y el de después y un botón **Deshacer** por ítem. 3. El campo **Justificación (opcional)** explica el pedido a quien lo va a analizar. 4. **Enviar para aprobación** manda todo en una sola solicitud. El botón está siempre visible — fijo arriba de la barra y, en pantallas estrechas, en una barra pegada al pie. aviso **El borrador vive solo en el navegador.** Si sales de la página sin enviar, los cambios se pierden — el navegador avisa antes de salir. Mientras haya pedidos en análisis, la pantalla muestra el aviso *"1 solicitud espera la aprobación de Kobana. Los valores en pantalla son los vigentes ahora."* La regla nueva solo empieza a valer cuando Kobana la aprueba. ### Solicitudes[​](#solicitudes "Enlace directo al Solicitudes") ![Pantalla de solicitudes](/es/assets/images/28-security-requests-4daa6580eb38ca1e6b9ca42568ee2395.png) El botón **Solicitudes**, arriba de la página, muestra cuántas están pendientes y abre la lista de todos los pedidos del espacio de trabajo, con búsqueda por solicitante o justificación y filtro por situación. | Columna | Qué muestra | | ----------------- | ------------------------------------------------------------------------------------------------------- | | **Fecha y hora** | Cuándo se envió el pedido | | **Solicitante** | Quién lo pidió | | **Cambios** | Qué cambia, ítem por ítem | | **Justificación** | El texto enviado junto | | **Situación** | **Pendiente**, **Aprobado**, **Denegado** o **Cancelado** — y, cuando lo hay, el motivo dado por Kobana | | **Acciones** | **Cancelar**, en las pendientes | **Cancelar** retira el pedido del análisis (*"Kobana ya no analizará estos cambios."*). Para pedirlo de nuevo, rehaz los cambios en la pantalla. Puede cancelar quien puede crear ese pedido — no solo el autor. Los pedidos cancelados siguen en la lista, como historial. Los pedidos hechos desde la pantalla de Configuración de Aprobación también aparecen aquí. Puede haber más de un pedido pendiente al mismo tiempo. Si dos tocan el mismo valor, el segundo en analizarse se deniega por conflicto — el valor que esperaba cambiar ya no es el mismo. ## Las pestañas[​](#las-pestañas "Enlace directo al Las pestañas") ### Límites[​](#límites "Enlace directo al Límites") Define **cuándo es día y cuándo es noche** y **cuánto se puede enviar al banco** en cada período. * **Huso horario** — el reloj de todas las reglas: qué es día, noche, "hoy" y "este mes". La búsqueda acepta ciudad, región o UTC; primero vienen los husos de **Brasil**, después **Otros husos**. Predeterminado: São Paulo. * **Horario diurno y nocturno** — arrastra los dos marcadores para definir cuándo empiezan el día y la noche, en pasos de 30 minutos. **El día empieza a las 05:00 como mínimo y termina a las 22:00 como máximo.** Predeterminado: diurno de 06:00 a 20:00, que es también el estándar del Banco Central para Pix. * **Período nocturno**, con dos interruptores: | Interruptor | Activado (predeterminado) | Desactivado | | ----------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | | **Permitir aprobaciones en el período nocturno** | Se aprueba a cualquier hora | Los botones de aprobar quedan bloqueados entre el inicio de la noche y el inicio del día | | **Permitir el envío al banco en el período nocturno** | El envío sigue normalmente, respetando los límites nocturnos | **Nada va al banco de noche** — ver [Envío nocturno desactivado](#env%C3%ADo-nocturno-desactivado) | * **Límites de valor** — una matriz con **Pagos** (boletos, tributos y servicios públicos) y **Transferencias** (Pix y TED) en las filas, y **Límite diurno** y **Límite nocturno** en las columnas, cada uno con: * **Por transacción** — el monto máximo de un único envío; * **Total por día** — la suma de todo lo enviado al banco en el período, **sumando todas las empresas del espacio de trabajo**. Un campo en blanco es **Sin límite**. El límite por transacción no puede superar el total por día. Con el envío nocturno desactivado, los límites nocturnos no tienen efecto. ### Cuentas[​](#cuentas "Enlace directo al Cuentas") ![Pestaña Cuentas](/es/assets/images/22-security-accounts-c28e313c9fd8b85c54c72ed8e8574ace.png) Elige **desde qué cuentas** pueden salir pagos y transferencias, y **cuánto puede enviar cada una por día**. Las cuentas aparecen agrupadas por empresa; cada una tiene un interruptor para **Pagos** y otro para **Transferencias**, cada uno con su **Límite de envío por día**. * **Cuentas nuevas** — la primera fila es el modelo: la configuración que **recibe cada cuenta al integrarse con el banco**. Después se puede ajustar en su propia fila. Cambiar el modelo no altera las cuentas que ya existen. * Las cuentas **Sin integración con el banco** aparecen bloqueadas — no hay nada que enviar por ellas. * **Todas las cuentas habilitadas** aplica el mismo límite a todas las cuentas activadas, de todas las empresas, con **Aplicar a todos**. Un campo en blanco en esa fila **mantiene** el límite actual de cada cuenta. El límite de la cuenta vale junto con los de la pestaña Límites: cuando ambos aplican, vale el menor. ### Beneficiarios[​](#beneficiarios "Enlace directo al Beneficiarios") ![Pestaña Beneficiarios](/es/assets/images/23-security-beneficiaries-10592f0df42080e1cce63548501a0ef5.png) Elige **a qué beneficiarios se pueden enviar transferencias** y cuánto puede recibir cada uno. nota **Solo transferencias — Pix y TED.** Boleto, tributo y servicio público no pasan por esta regla: en esos casos el dinero va a quien indica el código de barras, y una lista de proveedores no protegería nada. Se controlan en [Tipos de operaciones](#tipos-de-operaciones). **Regla general**, con dos modos: | Modo | Quién recibe | Beneficiarios nuevos | | ------------------------------------------------------- | ----------------------------- | -------------------- | | **Liberar a todos y bloquear algunos** (predeterminado) | Todos, menos los que bloquees | Entran liberados | | **Bloquear a todos y liberar algunos** | Solo los que liberes | Entran bloqueados | Cada modo guarda su propia lista: pasar de uno a otro no borra las marcas del otro. **El beneficiario se identifica por el CPF/CNPJ**, no por el registro. Por eso el mismo proveedor registrado en varias empresas aparece **una sola vez** (*"Registrado en 3 empresas"*), y sus límites valen sumados entre las empresas. El documento comparado en el envío es: * el de la **clave Pix**, cuando la clave es CPF o CNPJ; * el **CPF/CNPJ del beneficiario informado en el título**, en los demás casos. aviso En Pix por clave **correo, teléfono o aleatoria**, el sistema no sabe de quién es la clave: vale el documento informado en el título. Quien quiera rigor total desactiva esos tipos de clave en Tipos de operaciones. Por beneficiario, la lista muestra el interruptor **Liberado**, el **Límite diario**, el **Límite mensual** y el **Transferido en el mes**. El mes es el del calendario, en el huso de la pestaña Límites. La búsqueda acepta nombre o CPF/CNPJ, y el filtro separa **Liberados** y **Bloqueados**. Los documentos que la regla cita pero que ya no tienen registro aparecen como **Sin registro activo**. **Todos los liberados** aplica los mismos límites a todos los liberados — de todas las páginas, o solo a los encontrados por la búsqueda. Un campo en blanco en esa fila mantiene el límite actual de cada uno. ### Tipos de operaciones[​](#tipos-de-operaciones "Enlace directo al Tipos de operaciones") ![Pestaña Tipos de operaciones](/es/assets/images/24-security-operation-types-40e7f068ee7a0f6c99249acfbadd41ea.png) Un árbol con todo lo que se puede enviar al banco, con interruptores que activan y desactivan cada tipo: * **Pagos** — Boleto bancario; Servicios públicos; Tributos (Federales: DARF, GPS, GRU y FGTS; Estatales: ICMS y DARE; Municipales: ISS, IPTU e ITBI); Pix copia y pega. * **Transferencias** — Pix por tipo de clave (CPF, CNPJ, correo, teléfono, aleatoria); TED a cuenta de beneficiario o depósito judicial. Desactivar un grupo desactiva todo lo que contiene; un grupo con una parte activada y otra desactivada aparece en amarillo. Los tipos solo se activan y desactivan — no hay límite por tipo. Los tipos desactivados se pueden registrar y aprobar normalmente, pero **no se envían al banco**. ### Canales[​](#canales "Enlace directo al Canales") ![Pestaña Canales](/es/assets/images/25-security-channels-2dc04fc0d937c33e3f3e148230b95912.png) Una matriz con lo que se puede hacer en cada canal: **Crear**, **Aprobar**, **Pagar** (*"Enviar al banco"*) y **Cobrar** (*"Emitir boleto o Pix al cliente"*). **Canales de acceso** — por donde entra una persona o un sistema: | Canal | Observación | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | **Dashboard** | Esta interfaz web | | **Aplicación de escritorio** y **Aplicación móvil** | **En desarrollo** — aparecen bloqueados | | **API** | Integraciones con su sistema | | **MCP - Inteligencia Artificial** | Agentes de IA: **Kadu**, **Kia** y **Otros**. Activar o desactivar el MCP cambia los tres juntos | | **CLI - Línea de comandos** | | **Canales de origen** — de donde viene un título sin que nadie lo escriba. **Solo crean títulos**: Aprobar, Pagar y Cobrar aparecen como *"No aplica"*. | Canal | Qué cubre | | --------------------- | --------------------------------------- | | **Importación** | Planillas CSV | | **Inbox** | Documentos recibidos por correo o carga | | **Facturas fiscales** | Títulos generados a partir de facturas | | **Integraciones** | Nibo, Fintera y las próximas | Cuando una persona genera un título de un canal de origen — por ejemplo, a partir de una factura, en el Dashboard —, **los dos canales deben permitir Crear**. Los títulos recurrentes siguen el canal en que se creó la serie. **Todos los canales** activa o desactiva una acción en todos a la vez, menos los en desarrollo. Las consultas siguen liberadas en todos los canales. aviso **Predeterminado: Pagar activado solo en el Dashboard.** Crear y Aprobar vienen activados en todos los canales de acceso, y Crear en los de origen — pero enviar al banco por la API, la CLI o agentes de IA **exige una solicitud aprobada**. Son los caminos que se pueden automatizar, y por eso empiezan cerrados. **Cobrar** viene activado en el Dashboard, la API y la CLI, y desactivado para agentes de IA: un agente solo emite boleto o Pix en nombre de la organización si alguien lo activa. El envío automático después de la aprobación (ver [Configuración de Aprobación](https://docs.finance.kobana.com.br/es/es/aprovar-pagamentos/.md#activar-o-desactivar)) usa el canal de quien dio la última aprobación. ### Usuarios[​](#usuarios "Enlace directo al Usuarios") ![Pestaña Usuarios](/es/assets/images/26-security-users-f7fa3f9b099e60de14c3d40da8aea506.png) **Solo lectura.** Lista quién tiene acceso al espacio de trabajo, las funciones de cada persona y lo que esas funciones permiten: **Crear**, **Aprobar**, **Pagar** y **Forzar reenvío**. Pasa el mouse sobre una marca para ver qué función concede el permiso. El mismo permiso vale para pagos y transferencias. Para cambiarlo, usa **Cambiar**, que lleva a las funciones de la persona en Miembros — el enlace solo aparece para quien puede ver miembros. Invitaciones pendientes y usuarios suspendidos no operan hasta estar activos. ## Cuando una regla bloquea[​](#cuando-una-regla-bloquea "Enlace directo al Cuando una regla bloquea") Al enviar al banco, las reglas se comprueban en este orden, y la primera que falla decide: canal, tipo de operación, cuenta, beneficiario (solo transferencias), horario nocturno, límite por transacción, total del período, límite diario de la cuenta y límites del beneficiario. **Nada se reprograma.** Un título bloqueado queda donde está, con el motivo a la vista, y debe enviarse de nuevo cuando la regla lo permita. ### En la lista de envío[​](#en-la-lista-de-envío "Enlace directo al En la lista de envío") En el diálogo **Enviar pagos al banco** — la lista "Enviar al banco" de Cuentas por Pagar —, un título frenado por una regla que solo depende de él aparece **deshabilitado**, con el motivo: | Motivo en la lista | Qué hacer | | ----------------------------------------- | -------------------------------------------------- | | **Canal sin permiso de envío** | Pedir Pagar para el canal, en la pestaña Canales | | **Tipo de operación desactivado** | Pedir el tipo, en Tipos de operaciones | | **Cuenta bloqueada para esta operación** | Pedir la operación para la cuenta, en Cuentas | | **Beneficiario no habilitado** | Pedir la liberación del CPF/CNPJ, en Beneficiarios | | **Envío nocturno bloqueado** | Esperar el inicio del período diurno | | **Por encima del límite por transacción** | Pedir un límite mayor, en Límites | Los límites que dependen de lo que **ya se envió** — total del período, límite diario de la cuenta, límites diario y mensual del beneficiario — aparecen como **aviso**, y la fila sigue seleccionable: *"Superaría el límite del período"*, *"Superaría el límite diario de la cuenta"*, *"Superaría el límite diario del beneficiario"*, *"Superaría el límite mensual del beneficiario"*. Pasa el mouse para ver el límite, cuánto ya se envió y cuánto queda. En un envío en lote, los títulos van en orden de vencimiento; cuando se alcanza un límite, los siguientes que lo superarían **no se envían**, y el resultado lista cada uno con su motivo. Si una regla rechazó el envío automático, la fila lleva la etiqueta **Envío automático bloqueado**. ### Envío nocturno desactivado[​](#envío-nocturno-desactivado "Enlace directo al Envío nocturno desactivado") Con **Permitir el envío al banco en el período nocturno** desactivado: * **nada va al banco** entre el inicio de la noche y el inicio del día — ni por el botón ni por el envío automático después de la aprobación; * la lista muestra el aviso **"Envío al banco bloqueado hasta las 06:00"** (con tu horario); * lo aprobado de noche **no se envía solo por la mañana**: queda en la lista y debe enviarse de nuevo en el período diurno. ### Lote retenido en el banco[​](#lote-retenido-en-el-banco "Enlace directo al Lote retenido en el banco") Puede pasar que un pago se cree en el banco al final del día y que la aprobación automática del lote caiga ya en el período nocturno. En ese caso el lote **no se aprueba**: queda **retenido en el banco**. * En el título, la tarjeta del pago muestra la etiqueta **"Retenido en el banco: envío nocturno bloqueado"**. * En la lista de envío, esos títulos aparecen en la sección **Retenidos en el banco**. * El botón **Aprobar en el banco** — en la tarjeta y en la sección — solo funciona en el período diurno. Vuelve a comprobar las reglas, aprueba el lote y retoma el seguimiento del pago. "Actualizar estado" y el seguimiento automático **no** aprueban un lote retenido. ### En la aprobación[​](#en-la-aprobación "Enlace directo al En la aprobación") Con la aprobación nocturna desactivada o con **Aprobar** desactivado en el canal, la pantalla de [Aprobación](https://docs.finance.kobana.com.br/es/es/aprovar-pagamentos/.md) muestra un aviso y deshabilita los botones de aprobar. **Rechazar nunca se bloquea.** La misma pantalla avisa, en cada título, cuando **no se va a poder enviar** tal como está (*"Envío bloqueado por Seguridad"*) — para que quien aprueba sepa que hay que pedir la liberación. ### En la creación[​](#en-la-creación "Enlace directo al En la creación") Con **Crear** desactivado en un canal, el título no se crea: *"El canal … no puede crear títulos. Solicita la habilitación en Seguridad."* En importaciones e integraciones, el motivo queda registrado en el informe de la ejecución, y una recurrencia creada por un canal desactivado deja de generar ocurrencias mientras siga desactivado. ## Quién puede pedir cambios[​](#quién-puede-pedir-cambios "Enlace directo al Quién puede pedir cambios") | Quién | Qué puede pedir | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Propietario** | Cualquier cambio, en todas las pestañas | | Quien tiene el permiso **Configuración de aprobación** | Solo cambios de la configuración de aprobación, por la pantalla [Configuración de Aprobación](https://docs.finance.kobana.com.br/es/es/aprovar-pagamentos/.md#activar-o-desactivar) | | Demás funciones (Administrador, Visualizador…) | Ninguno: ven las reglas, y la barra lateral avisa *"Solo quien puede pedir cambios de seguridad envía solicitudes."* | De forma predeterminada, **solo el Propietario** pide cambios de seguridad — ni siquiera el Administrador. Quien decide es siempre **Kobana**. --- # Transferencias Una transferencia mueve dinero entre dos cuentas financieras del mismo espacio de trabajo, generando **dos transacciones espejadas**: una salida en el origen y una entrada en el destino. ## Dónde está[​](#dónde-está "Enlace directo al Dónde está") nota **La transferencia no es un ítem de menú.** No existe una pantalla de transferencias: es el diálogo **"Nueva transferencia"**, que se abre desde dos lugares, ambos en **Cuentas financieras**: * En el **encabezado de la lista** de cuentas. * En el **detalle de una cuenta** — y ahí el **origen ya viene rellenado** con la cuenta que estás viendo. ## Campos[​](#campos "Enlace directo al Campos") Seis campos, y **cinco son obligatorios**: | Campo | Observaciones | | --------------- | ----------------------------------------------------------------------------------------- | | **De** | Obligatorio — la cuenta que envía | | **A** | Obligatorio — la cuenta que recibe | | **Monto** | Obligatorio — tiene que ser **mayor que cero** | | **Fecha** | Obligatorio — viene rellenada con hoy | | **Descripción** | **Obligatorio** — a diferencia de una transacción común, aquí no se puede dejar en blanco | | **Notas** | Opcional. *"Información adicional — visible en ambas transacciones."* | El botón es **"Crear transferencia"**. **"De" y "A" son los rótulos.** "Cuenta de origen" y "Cuenta de destino" aparecen como texto de apoyo dentro de los campos, no como su nombre. **No existen "Mes de competencia" ni "Provisional" en una transferencia.** Los dos campos existen en la API, pero la pantalla no los ofrece — una transferencia creada por aquí siempre está efectivada, y la competencia acompaña a la fecha. ### Lo que el sistema rechaza[​](#lo-que-el-sistema-rechaza "Enlace directo al Lo que el sistema rechaza") * **Monto cero o negativo** — *"El valor debe ser mayor que cero"*. * **Origen igual al destino** — *"La cuenta de origen y destino deben ser diferentes"*. * **Descripción vacía** — *"Ingresa una descripción"*. ## Las dos transacciones[​](#las-dos-transacciones "Enlace directo al Las dos transacciones") Confirmada la transferencia, nacen dos registros: | Registro | Cuenta | | ----------- | ----------------- | | **Salida** | Cuenta de origen | | **Entrada** | Cuenta de destino | Los dos llevan el mismo identificador de transferencia, lo que los marca como las dos patas del mismo movimiento y evita que la conciliación los trate como dinero nuevo. ## Cómo aparecen después[​](#cómo-aparecen-después "Enlace directo al Cómo aparecen después") En la lista de [Transacciones](https://docs.finance.kobana.com.br/es/es/lancamentos/.md), cada pata recibe la etiqueta de **transferencia** al lado de la descripción, y el filtro rápido **Transferencias** las aísla a todas. Al abrir una pata, la tarjeta de arriba dice **"Transferencia enviada a otra cuenta"** o **"Transferencia recibida de otra cuenta"**, muestra la cuenta del otro lado, la fecha y el monto, y trae el atajo **"Abrir lado opuesto →"**. ## Eliminar[​](#eliminar "Enlace directo al Eliminar") peligro **No hay edición de transferencia, y la eliminación no es en cascada.** Las dos patas son transacciones independientes una vez creadas: borrar una elimina solo esa y **deja la otra huérfana**, con el saldo distorsionado en los dos lados. Para deshacerla por completo, elimina **las dos** — el "Abrir lado opuesto →" es el camino para encontrar la segunda. ## Diferencia con una transacción común[​](#diferencia-con-una-transacción-común "Enlace directo al Diferencia con una transacción común") Una transacción de entrada o salida afecta a **una** cuenta y mueve el saldo total del espacio de trabajo. La transferencia afecta a **dos** y mantiene el total intacto — es el mecanismo correcto para mover saldo entre cuentas sin inventar ingresos ni gastos. --- # Espacios de trabajo Un espacio de trabajo es la caja que guarda todo lo que registras en Finanzas Inteligentes. Cada usuario puede pertenecer a varios espacios de trabajo, y los datos de uno nunca aparecen en el otro. ![Lista de espacios de trabajo](/es/assets/images/18-workspaces-1ad0db6f2334495bd010985dc00cf4b6.png) ## Modelo de aislamiento[​](#modelo-de-aislamiento "Enlace directo al Modelo de aislamiento") ``` Usuario (correo) ├── Espacio de trabajo A │ ├── Empresa 1 (CNPJ) │ ├── Empresa 2 (CNPJ) │ ├── Personas (clientes y proveedores) │ ├── Cuentas financieras │ ├── Categorías │ ├── Centros de clasificación │ ├── Cuentas por Pagar │ ├── Cuentas por Cobrar │ └── Transacciones └── Espacio de trabajo B └── ... ``` Ningún dato cruza la frontera entre espacios de trabajo. Un espacio de trabajo equivale a una organización o a un grupo de empresas administradas por la misma persona. ## La pantalla[​](#la-pantalla "Enlace directo al La pantalla") En `/workspaces` ves **una tarjeta por espacio de trabajo**, no una tabla. Cada tarjeta trae el nombre arriba y, debajo, la lista de las empresas que contiene, bajo la etiqueta **Empresas (N)**. La tarjeta del espacio de trabajo activo aparece destacada con un borde de color. **Hacer clic en la tarjeta cambia a ese espacio de trabajo y te lleva al Dashboard** — el mismo efecto que el selector de la parte superior de la aplicación. ## Crear[​](#crear "Enlace directo al Crear") Haz clic en **Nuevo espacio de trabajo** e informa el **Nombre**. Es el único campo. El espacio de trabajo se crea al instante, pasa a ser el activo y queda disponible en el selector superior. nota **Tu primer espacio de trabajo no nace aquí.** Se crea justo después del primer inicio de sesión con Kobana, en una pantalla de confirmación que ya trae el nombre y el documento de tu empresa — mira [Entrar no es lo mismo que tener acceso](https://docs.finance.kobana.com.br/es/es/meus-dados/.md#entrar-no-es-lo-mismo-que-tener-acceso). Esta pantalla sirve para los **demás**: un segundo espacio de trabajo, creado solo con el nombre. ## Renombrar[​](#renombrar "Enlace directo al Renombrar") En el menú de acciones de la tarjeta (icono de tres puntos), elige **Editar**. Solo cambia el nombre — no hay forma de mover empresas de un espacio de trabajo a otro. ## Alternar[​](#alternar "Enlace directo al Alternar") El selector del encabezado lista todos tus espacios de trabajo. Al alternar, todas las pantallas se recargan con los datos del espacio de trabajo elegido. Si eres miembro de más de una organización, las dos elecciones están en el mismo selector, rotulado **Org / Espacio**: las organizaciones en una columna, los espacios de la organización actual en la otra. Cambiar de organización recarga la aplicación en el **Dashboard**. ## Eliminación[​](#eliminación "Enlace directo al Eliminación") peligro **No existe traba. Eliminar un espacio de trabajo borra todo lo que hay dentro, para siempre.** No importa cuántas empresas, cuentas o transacciones contenga: la eliminación se acepta, el contenido se va con él, y no hay papelera ni forma de deshacer. Esto contradice lo que ocurre un nivel más abajo, y conviene saberlo: una **empresa** con una sola transacción, cuenta por pagar o cuenta por cobrar **no se puede eliminar** — el sistema se niega y pide que quites los registros antes. Pero eliminar el **espacio de trabajo** que contiene esa empresa **funciona**, y se lleva la empresa y todos sus registros. El camino más corto es también el más destructivo. Por eso el diálogo existe para que **revises antes de firmar**. En el menú de acciones de la tarjeta, elige **Eliminar**: 1. El diálogo **cuenta lo que se va a destruir** y cita solo lo que existe de hecho — empresas, cuentas por pagar, cuentas por cobrar, movimientos, personas, cuentas financieras, conciliaciones y registros de auditoría: > Se eliminarán junto con él, para siempre: 2 empresas, 1 cuenta por pagar, 14 movimientos. Si no hay nada vinculado, lo dice: *"Está vacío — no hay nada vinculado a él."* 2. Justo debajo, el recordatorio de lo que se va sin ser contado: **configuraciones, adjuntos, programaciones e historial de importación**. 3. **Para liberar el botón, escribes el nombre del espacio de trabajo.** El texto tiene que coincidir **exactamente**, incluidas mayúsculas y minúsculas. Solo entonces **Eliminar espacio de trabajo** se vuelve clicable. Si el conteo no se puede cargar, el diálogo avisa — *"No pudimos verificar qué se va a eliminar. Revísalo antes de continuar."* — y mantiene la exigencia de escribir el nombre. Eliminar el espacio de trabajo activo limpia la selección; elige otro en el selector superior. --- # Finanzas Inteligentes — Documentación ¡Bienvenido! Finanzas Inteligentes es la plataforma de back-office financiero multi-empresa para el mercado brasileño: cuentas por pagar y por cobrar, transacciones, conciliación, importaciones y envío de pagos al banco — varias empresas, en un solo lugar. Esta documentación describe lo que ves y puedes hacer en las pantallas del producto. Para integrar tus sistemas vía REST, consulta la [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api.md). ## Qué hay en esta documentación[​](#qué-hay-en-esta-documentación "Enlace directo al Qué hay en esta documentación") | Sección | Para quién | Qué encuentras | | ---------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Documentación** (esta sección) | quien usa el panel | cuentas financieras, asientos, cuentas por pagar y por cobrar, conciliación, documentos, clasificación y registros | | [API](https://docs.finance.kobana.com.br/es/es/api/overview/introduction.md) | quien integra otro sistema | la API v1: autenticación, paginación, filtros, idempotencia, errores y la referencia de cada endpoint | | [MCP](https://docs.finance.kobana.com.br/es/es/mcp/overview/introduction.md) | quien usa el producto desde un cliente de IA (Claude, ChatGPT…) | el servidor MCP remoto: autenticación, transporte y la referencia de cada tool | | [CLI](https://docs.finance.kobana.com.br/es/es/cli/overview/introduction.md) | quien opera desde la terminal o un script | `kobana`, la línea de comandos de todos los productos Kobana: instalación, autenticación y uso | ## Primeros pasos[​](#primeros-pasos "Enlace directo al Primeros pasos") Si estás llegando ahora, este es el camino natural: 1. [Crea un espacio de trabajo](https://docs.finance.kobana.com.br/es/es/workspaces/.md) — la caja que aísla los datos de cada organización. 2. [Registra las empresas](https://docs.finance.kobana.com.br/es/es/empresas/.md) — las entidades jurídicas (CNPJ) que administra. 3. [Crea las cuentas financieras](https://docs.finance.kobana.com.br/es/es/contas-financeiras/.md) — corriente, ahorro, caja, inversión y crédito. 4. [Registra cuentas por pagar](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/.md) y [por cobrar](https://docs.finance.kobana.com.br/es/es/contas-a-receber/.md) — al contado, en cuotas o recurrentes — o impórtalas en lote vía CSV. 5. [Importa el extracto](https://docs.finance.kobana.com.br/es/es/extratos-bancarios/.md) y [concilia](https://docs.finance.kobana.com.br/es/es/conciliacao/.md) — cruza lo que ocurrió en el banco con lo que estaba previsto. ## Las secciones[​](#las-secciones "Enlace directo al Las secciones") Las secciones siguientes siguen los **seis grupos del menú** del producto — aquí recorres el mismo árbol que ves en la pantalla. Solo a **Mi perfil** se llega por otro camino en el producto: el menú del avatar. ### Principal[​](#principal "Enlace directo al Principal") * [Dashboard](https://docs.finance.kobana.com.br/es/es/dashboard/.md) — indicadores, flujo de caja realizado y proyectado, próximos vencimientos. * [Espacios de trabajo](https://docs.finance.kobana.com.br/es/es/workspaces/.md) — el aislamiento entre organizaciones: creación, cambio y eliminación. * [Empresas](https://docs.finance.kobana.com.br/es/es/empresas/.md) — registro multi-empresa (CNPJ), matriz y sucursales, consulta a la Receita Federal (el fisco federal brasileño). ### Financiero[​](#financiero "Enlace directo al Financiero") * [Cuentas financieras](https://docs.finance.kobana.com.br/es/es/contas-financeiras/.md) — cuentas corrientes, ahorro, caja, inversión y crédito, con el saldo calculado a partir de las transacciones. * [Extractos bancarios](https://docs.finance.kobana.com.br/es/es/extratos-bancarios/.md) — importación de OFX y QIF en la cuenta. * [Transferencias](https://docs.finance.kobana.com.br/es/es/transferencias/.md) — movimiento entre cuentas del mismo espacio de trabajo. * [Tarjetas](https://docs.finance.kobana.com.br/es/es/cartoes/.md) — tarjetas de crédito, prepago y de beneficio: resúmenes, límite, cuotas, compras internacionales con IOF, recurrencias y el pago del resumen. * [Transacciones](https://docs.finance.kobana.com.br/es/es/lancamentos/.md) — los movimientos de las cuentas financieras; la base de la conciliación. * [Cuentas por pagar](https://docs.finance.kobana.com.br/es/es/contas-a-pagar/.md) — compromisos de salida: cuotas, recurrencia, impuestos y envío al banco. * [Aprobar pagos](https://docs.finance.kobana.com.br/es/es/aprovar-pagamentos/.md) — la puerta que exige el visto bueno de una persona antes de que un título entre en la lista. * [Cuentas por cobrar](https://docs.finance.kobana.com.br/es/es/contas-a-receber/.md) — compromisos de entrada, con cuotas y recurrencia, y el cobro por boleto o Pix. * [Conciliación](https://docs.finance.kobana.com.br/es/es/conciliacao/.md) — cruce entre títulos y transacciones que vienen del extracto. ### Documentos[​](#documentos "Enlace directo al Documentos") * [Comprobantes](https://docs.finance.kobana.com.br/es/es/comprovantes/.md) — la prueba de cada pago: capturada sola cuando el banco confirma, o subida por ti. * [Adjuntos](https://docs.finance.kobana.com.br/es/es/anexos/.md) — la biblioteca de archivos del espacio de trabajo, vinculable a cualquier registro. ### Ejes[​](#ejes "Enlace directo al Ejes") * [Categorías](https://docs.finance.kobana.com.br/es/es/categorias/.md) — clasificación en hasta tres niveles, por ingreso y gasto. * [Centros de clasificación](https://docs.finance.kobana.com.br/es/es/centros-de-classificacao/.md) — asignación por departamento o proyecto, con prorrateo. * [Clasificadores personalizados](https://docs.finance.kobana.com.br/es/es/classificadores-personalizados/.md) — dimensiones de clasificación que creas, con sus propios valores, además de categorías y centros. * [Reglas automáticas](https://docs.finance.kobana.com.br/es/es/regras-automaticas/.md) — clasificación automática según los criterios que definas. ### Registros[​](#registros "Enlace directo al Registros") * [Personas](https://docs.finance.kobana.com.br/es/es/pessoas/.md) — clientes y proveedores (personas físicas y jurídicas), con roles acumulables. * [Impuestos](https://docs.finance.kobana.com.br/es/es/impostos/.md) — el catálogo de tributos vinculables a los títulos. ### Sistema[​](#sistema "Enlace directo al Sistema") * [Integraciones](https://docs.finance.kobana.com.br/es/es/integracoes/.md) — Gateway Bancario (pagos, cuentas, extracto y personas), Fintera (importación de datos) y WhatsApp (fotos de perfil). * [Mantenimiento](https://docs.finance.kobana.com.br/es/es/manutencao/.md) — herramientas de higiene de los registros de personas. * [Mi perfil](https://docs.finance.kobana.com.br/es/es/meus-dados/.md) — la información de tu cuenta y cómo funciona el inicio de sesión. ### API[​](#api "Enlace directo al API") * [Referencia de la API](https://docs.finance.kobana.com.br/es/es/api.md) — REST con autenticación Bearer JWT: endpoints, paginación, filtros, idempotencia y errores. ---