# Faturamento Automático — Documentação > Documentação completa: assinaturas, faturas, pagamentos, NF-e, gateways, dunning e portal do cliente. ## es Bienvenido a la documentación de Facturación Automática, la plataforma B2B2C de facturación, suscripciones y cobro recurrente para el mercado brasileño. - [Facturación Automática — Documentación](https://docs.billing.kobana.com.br/es/index.md): Bienvenido a la documentación de Facturación Automática, la plataforma B2B2C de facturación, suscripciones y cobro recurrente para el mercado brasileño. ### search - [Buscar en la documentación](https://docs.billing.kobana.com.br/es/search.md) ### api - [Referencia de la API](https://docs.billing.kobana.com.br/es/api.md) #### overview - [Autenticación](https://docs.billing.kobana.com.br/es/api/overview/authentication.md): La API de Facturación Automática usa un access token de la Cuenta Kobana para autenticar todas las solicitudes. - [Retención de Datos](https://docs.billing.kobana.com.br/es/api/overview/data-retention.md): Esta página describe por cuánto tiempo se conserva cada tipo de dato en Facturación Automática. - [Endpoints](https://docs.billing.kobana.com.br/es/api/overview/endpoints.md): Plataforma (acceso web) - [Idempotencia](https://docs.billing.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 suscripción que falla por un error de red puede reintentarse con la misma clave, garantizando que solo se cree una suscripción. - [Introducción](https://docs.billing.kobana.com.br/es/api/overview/introduction.md): Si eres dev, ¡diviértete! ✨ - [OpenAPI](https://docs.billing.kobana.com.br/es/api/overview/openapi.md): Mantenemos públicamente los archivos de especificación de la API de Facturación Automática en formato abierto para que puedas descargarlos y usarlos en la herramienta de tu preferencia. - [Listado y Paginación](https://docs.billing.kobana.com.br/es/api/overview/pagination.md): Todos los endpoints GET que devuelven colecciones (/v1/customers, /v1/subscriptions, /v1/invoices, etc.) usan paginación por número de página. - [Postman](https://docs.billing.kobana.com.br/es/api/overview/postman.md): Si prefiere probar la API mediante Postman, descargue la colección en el idioma de su elección e impórtela — o abra la versión online directamente desde el workspace público de Kobana. - [Límite de Solicitudes](https://docs.billing.kobana.com.br/es/api/overview/rate-limit.md): Cuando un cliente excede el límite asociado a él, las solicitudes siguientes se bloquean. - [User-Agent](https://docs.billing.kobana.com.br/es/api/overview/user-agent.md): Puedes incluir el header User-Agent con el nombre de tu aplicación y una dirección de e-mail válida, para que podamos contactarte en caso de que: - [Webhooks](https://docs.billing.kobana.com.br/es/api/overview/webhooks.md): Los webhooks son notificaciones HTTP enviadas por la API de Facturación Automática siempre que ocurre un evento relevante en tu Organización — suscripción creada, factura pagada, NF-e emitida, etc. - [billing_account.suspended](https://docs.billing.kobana.com.br/es/api/overview/webhooks/billing-account-suspended.md): Se dispara cuando una BillingAccount se suspende por morosidad o por una acción manual del operador. - [company.db.updated](https://docs.billing.kobana.com.br/es/api/overview/webhooks/company-updated.md): Se dispara en cada actualización de cualquier campo de una empresa (Company). - [coupon.redeemed](https://docs.billing.kobana.com.br/es/api/overview/webhooks/coupon-redeemed.md): Se dispara cuando un cupón se canjea en una suscripción o factura. - [credit.applied](https://docs.billing.kobana.com.br/es/api/overview/webhooks/credit-applied.md): Se dispara cuando un crédito existente se aplica a una factura, reduciendo el monto adeudado. - [customer.db.created](https://docs.billing.kobana.com.br/es/api/overview/webhooks/customer-created.md): Se dispara cuando un nuevo cliente (persona física o jurídica) se registra en la Organización. - [invoice.paid](https://docs.billing.kobana.com.br/es/api/overview/webhooks/invoice-paid.md): Se dispara cuando una factura tiene su pago confirmado y su estado pasa a paid. - [nfe.issued](https://docs.billing.kobana.com.br/es/api/overview/webhooks/nfe-issued.md): Se dispara cuando la NF-e (factura electrónica brasileña) se emite con éxito en el proveedor fiscal integrado. - [payment_method.expired](https://docs.billing.kobana.com.br/es/api/overview/webhooks/payment-method-expired.md): Se dispara cuando un método de pago expira (tarjeta vencida, mandato cancelado, etc.). - [payment.succeeded](https://docs.billing.kobana.com.br/es/api/overview/webhooks/payment-succeeded.md): Se dispara cuando el gateway confirma un pago con estado succeeded. - [plan.db.updated](https://docs.billing.kobana.com.br/es/api/overview/webhooks/plan-updated.md): Se dispara en cada actualización de cualquier campo de un Plan. - [product.archived](https://docs.billing.kobana.com.br/es/api/overview/webhooks/product-archived.md): Se dispara cuando un producto se archiva y se retira del catálogo activo. - [proposal.accepted](https://docs.billing.kobana.com.br/es/api/overview/webhooks/proposal-accepted.md): Se dispara cuando el cliente acepta una propuesta comercial enviada. - [service_item.db.updated](https://docs.billing.kobana.com.br/es/api/overview/webhooks/service-item-updated.md): Se dispara en cada actualización de ítems de servicio (códigos CNAE, ISS, descripción fiscal). - [subscription.status_changed](https://docs.billing.kobana.com.br/es/api/overview/webhooks/subscription-status-changed.md): Se dispara siempre que cambia el status de una suscripción (active, trialing, past_due, paused, canceled). ### assinaturas - [Suscripciones](https://docs.billing.kobana.com.br/es/assinaturas.md) #### ciclo-de-vida Estados - [Ciclo de Vida de la Suscripción](https://docs.billing.kobana.com.br/es/assinaturas/ciclo-de-vida.md): Estados #### mudanca-de-plano El sistema permite que los clientes cambien el plan de la suscripción con cálculo automático de proration (prorrateo proporcional). - [Cambio de Plan (Upgrade/Downgrade)](https://docs.billing.kobana.com.br/es/assinaturas/mudanca-de-plano.md): El sistema permite que los clientes cambien el plan de la suscripción con cálculo automático de proration (prorrateo proporcional). #### mudancas-de-itens Además de los cambios de plan (upgrade/downgrade), Facturación Automática soporta cambios en los ítems individuales de una suscripción — modificar cantidades, agregar add-ons, cambiar un producto suelto o un ítem metered sin necesidad de cambiar el plan principal. La pantalla /dashboard/subscription-changes agrupa el historial de estos cambios y la configuración predeterminada de proration. - [Cambios de Ítems de la Suscripción](https://docs.billing.kobana.com.br/es/assinaturas/mudancas-de-itens.md): Además de los cambios de plan (upgrade/downgrade), Facturación Automática soporta cambios en los ítems individuales de una suscripción — modificar cantidades, agregar add-ons, cambiar un producto suelto o un ítem metered sin necesidad de cambiar el plan principal. La pantalla /dashboard/subscription-changes agrupa el historial de estos cambios y la configuración predeterminada de proration. #### pausar-assinatura La funcionalidad de pausar suscripciones permite suspender temporalmente el cobro de un cliente sin cancelar la suscripción. Es una herramienta estratégica de retención. - [Pausar Suscripción](https://docs.billing.kobana.com.br/es/assinaturas/pausar-assinatura.md): La funcionalidad de pausar suscripciones permite suspender temporalmente el cobro de un cliente sin cancelar la suscripción. Es una herramienta estratégica de retención. #### termos-de-cobranca Los términos de cobro definen cómo y cuándo se cobra al cliente por la suscripción. - [Términos de Cobro](https://docs.billing.kobana.com.br/es/assinaturas/termos-de-cobranca.md): Los términos de cobro definen cómo y cuándo se cobra al cliente por la suscripción. ### cli #### overview - [Autenticación](https://docs.billing.kobana.com.br/es/cli/overview/authentication.md): KOBANA_TOKEN guarda la credencial de un producto por vez. Un token de Facturación Automática no autentica en ningún otro producto Kobana, y viceversa. - [Variables de ambiente](https://docs.billing.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.billing.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.billing.kobana.com.br/es/cli/overview/installation.md): Homebrew (macOS y Linux) - [Introducción](https://docs.billing.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 — Facturación Automática 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 - [Cuentas de cobro](https://docs.billing.kobana.com.br/es/cli/resources/billing-accounts.md): La cuenta que acumula suscripciones, facturas y créditos de un cliente. Suspender interrumpe el cobro sin terminar la relación; cerrar la termina. - [Certificados digitales](https://docs.billing.kobana.com.br/es/cli/resources/certificates.md): Los certificados A1 usados para firmar la emisión fiscal. El archivo se envía una vez y nunca vuelve en la respuesta. - [Empresas](https://docs.billing.kobana.com.br/es/cli/resources/companies.md): Las empresas emisoras — quién cobra. Llevan el perfil fiscal usado en la emisión de nota, y una de ellas es la predeterminada. - [Cupones](https://docs.billing.kobana.com.br/es/cli/resources/coupons.md): Descuentos con regla de validez y límite de uso. redemptions muestra dónde se aplicó efectivamente cada cupón. - [Créditos](https://docs.billing.kobana.com.br/es/cli/resources/credits.md): Saldo a favor del cliente, aplicable a facturas futuras. Aplicar y quitar créditos son comandos de la propia factura. - [Clientes](https://docs.billing.kobana.com.br/es/cli/resources/customers.md): Quién es cobrado, sus usuarios de portal y el extracto consolidado. recalculate-mrr recalcula el ingreso recurrente del cliente. - [Usuarios del panel](https://docs.billing.kobana.com.br/es/cli/resources/dashboard-users.md): Quién tiene acceso al panel de tu organización — los operadores, no los clientes. - [Facturas](https://docs.billing.kobana.com.br/es/cli/resources/invoices.md): El documento a cobrar, del borrador al pagado. finalize sella el borrador, pay registra la liquidación, void la anula, y las cuotas viven en installments. - [Notas fiscales](https://docs.billing.kobana.com.br/es/cli/resources/nfes.md): La emisión fiscal de una factura: emitir, cancelar, descargar PDF y XML, y seguir cada intento ante la municipalidad. Barueri tiene comandos propios. - [Organización](https://docs.billing.kobana.com.br/es/cli/resources/organization.md): Las configuraciones en la cima de la jerarquía, comunes a todas las empresas de la cuenta. - [Recursos](https://docs.billing.kobana.com.br/es/cli/resources/overview.md): Todo recurso de billing 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. - [Medios de pago](https://docs.billing.kobana.com.br/es/cli/resources/payment-methods.md): Las tarjetas y demás medios guardados de un cliente, y cuál de ellos es el predeterminado. - [Pagos](https://docs.billing.kobana.com.br/es/cli/resources/payments.md): Los intentos de liquidación de una factura: reintento, cambio de tarjeta, cambio de vencimiento, reembolso y reenvío del correo de cobro. - [Cambios de plan](https://docs.billing.kobana.com.br/es/cli/resources/plan-changes.md): Upgrades y downgrades: las reglas que definen qué puede convertirse en qué, la configuración del prorrateo y las estadísticas de lo que se cambió. - [Grupos de planes](https://docs.billing.kobana.com.br/es/cli/resources/plan-groups.md): El estante en que los planes se muestran y ordenan. reorder cambia el orden; archive retira el grupo de circulación sin borrarlo. - [Planes](https://docs.billing.kobana.com.br/es/cli/resources/plans.md): Lo que se suscribe: precio, periodicidad y la lista de ítems que entrega el plan. Las operaciones bulk-* actúan sobre varios planes a la vez. - [Grupos de productos](https://docs.billing.kobana.com.br/es/cli/resources/product-groups.md): La agrupación del catálogo de productos, con ordenación y archivado propios. - [Productos](https://docs.billing.kobana.com.br/es/cli/resources/products.md): El catálogo de lo que se cobra, ítem a ítem, antes de convertirse en plan o ítem de factura. Publicar, archivar y restaurar controlan la visibilidad sin destruir el historial. - [Plantillas de propuesta](https://docs.billing.kobana.com.br/es/cli/resources/proposal-templates.md): Las plantillas de las que nacen las propuestas, con una marcada como predeterminada. - [Propuestas](https://docs.billing.kobana.com.br/es/cli/resources/proposals.md): El presupuesto antes de la suscripción: publicar, enviar, generar PDF y aceptar. Aceptar es lo que convierte la propuesta en suscripción — y undo-accept lo deshace. - [Ítems de servicio](https://docs.billing.kobana.com.br/es/cli/resources/service-items.md): Los servicios de la lista municipal usados para describir qué está cobrando la nota fiscal. - [Cambios de suscripción](https://docs.billing.kobana.com.br/es/cli/resources/subscription-changes.md): La configuración de cómo se aplican los cambios de suscripción — de inmediato, en el próximo ciclo, con o sin prorrateo. - [Cambios de ítems](https://docs.billing.kobana.com.br/es/cli/resources/subscription-item-changes.md): El historial de cambios en los ítems de una suscripción, y la cancelación de un cambio aún agendado. - [Suscripciones](https://docs.billing.kobana.com.br/es/cli/resources/subscriptions.md): El contrato vivo entre un cliente y un plan: activar, pausar, reanudar, cambiar de plan y cancelar. create-invoice fuerza una factura fuera del ciclo. - [Períodos fiscales](https://docs.billing.kobana.com.br/es/cli/resources/tax-periods.md): Los períodos fiscales que agrupan las notas emitidas. - [Reglas de impuesto](https://docs.billing.kobana.com.br/es/cli/resources/tax-rules.md): Qué tributo incide sobre qué, y con qué alícuota — lo que consulta la emisión de nota. - [Roles de equipo](https://docs.billing.kobana.com.br/es/cli/resources/team-roles.md): Los roles que definen qué puede hacer cada usuario del panel. - [Consumo](https://docs.billing.kobana.com.br/es/cli/resources/usage.md): Los eventos de consumo que alimentan el cobro por uso, con instantáneas diarias y mensuales y un resumen consolidado. - [Retenciones](https://docs.billing.kobana.com.br/es/cli/resources/withholdings.md): Los importes retenidos en la fuente por el cliente, que pueden convertirse en crédito. #### usage - [Flags globales](https://docs.billing.kobana.com.br/es/cli/usage/global-flags.md): | Flag | Descripción | - [Helpers](https://docs.billing.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.billing.kobana.com.br/es/cli/usage/overview.md): Sintaxis - [Introspección de schema](https://docs.billing.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: ... ### configuracoes - [Configuraciones](https://docs.billing.kobana.com.br/es/configuracoes.md) #### analytics El área de Analytics (/dashboard/analytics) traduce los datos operativos de la facturación en métricas SaaS que pueden consumir los equipos de finanzas y producto: MRR, ARR, churn, LTV, ARPU, retención por cohorte y embudo de cobro. - [Analytics](https://docs.billing.kobana.com.br/es/configuracoes/analytics.md): El área de Analytics (/dashboard/analytics) traduce los datos operativos de la facturación en métricas SaaS que pueden consumir los equipos de finanzas y producto: MRR, ARR, churn, LTV, ARPU, retención por cohorte y embudo de cobro. #### api-keys En /dashboard/api la organización gestiona las claves de API. Cada clave - [API Keys](https://docs.billing.kobana.com.br/es/configuracoes/api-keys.md): En /dashboard/api la organización gestiona las claves de API. Cada clave #### auditoria La pista de auditoría (/dashboard/audit) registra toda modificación de datos hecha en el dashboard o vía API. Cada entrada captura quién lo hizo, qué se modificó, los valores antes y después, la IP, el User-Agent y el horario, formando un historial inmutable para compliance, depuración y análisis de incidentes. - [Auditoría](https://docs.billing.kobana.com.br/es/configuracoes/auditoria.md): La pista de auditoría (/dashboard/audit) registra toda modificación de datos hecha en el dashboard o vía API. Cada entrada captura quién lo hizo, qué se modificó, los valores antes y después, la IP, el User-Agent y el horario, formando un historial inmutable para compliance, depuración y análisis de incidentes. #### configuracoes-de-cobranca Configuraciones que afectan la fijación de precios y el comportamiento de cobro de la organización. - [Configuraciones de Cobro](https://docs.billing.kobana.com.br/es/configuracoes/configuracoes-de-cobranca.md): Configuraciones que afectan la fijación de precios y el comportamiento de cobro de la organización. #### empresa Las empresas representan las entidades jurídicas que emiten facturas y notas fiscales. Una organización puede tener múltiples empresas (matriz y sucursales). - [Empresa (Entidad Fiscal)](https://docs.billing.kobana.com.br/es/configuracoes/empresa.md): Las empresas representan las entidades jurídicas que emiten facturas y notas fiscales. Una organización puede tener múltiples empresas (matriz y sucursales). #### eventos La pantalla de eventos (/dashboard/events) expone el stream interno de eventos de dominio que genera el sistema cada vez que cambia un estado relevante — invoice.created, payment.succeeded, subscription.canceled, nfe.issued y decenas de otros. Es la misma cola que alimenta los Webhooks y el historial del cliente en el portal. - [Eventos](https://docs.billing.kobana.com.br/es/configuracoes/eventos.md): La pantalla de eventos (/dashboard/events) expone el stream interno de eventos de dominio que genera el sistema cada vez que cambia un estado relevante — invoice.created, payment.succeeded, subscription.canceled, nfe.issued y decenas de otros. Es la misma cola que alimenta los Webhooks y el historial del cliente en el portal. #### feriados Los feriados son los días en que los bancos no operan. Sirven a dos propósitos: - [Feriados](https://docs.billing.kobana.com.br/es/configuracoes/feriados.md): Los feriados son los días en que los bancos no operan. Sirven a dos propósitos: #### membros La página de miembros (/dashboard/members) lista a todas las personas con acceso al dashboard de la organización. Cada miembro tiene un e-mail vinculado a la autenticación Kobana y uno o más roles que definen lo que puede ver y modificar. - [Miembros y Roles](https://docs.billing.kobana.com.br/es/configuracoes/membros.md): La página de miembros (/dashboard/members) lista a todas las personas con acceso al dashboard de la organización. Cada miembro tiene un e-mail vinculado a la autenticación Kobana y uno o más roles que definen lo que puede ver y modificar. #### notificacoes El sistema de notificaciones envía comunicaciones multicanal a clientes sobre eventos importantes. - [Notificaciones](https://docs.billing.kobana.com.br/es/configuracoes/notificacoes.md): El sistema de notificaciones envía comunicaciones multicanal a clientes sobre eventos importantes. #### perfil La página /dashboard/profile reúne las preferencias personales del operador que inició sesión: tema, idioma, zona horaria y configuraciones de notificación. A diferencia de las configuraciones de la organización (que afectan a todos los miembros), las preferencias de perfil son por usuario y se almacenan localmente y en el servidor. - [Perfil del Usuario](https://docs.billing.kobana.com.br/es/configuracoes/perfil.md): La página /dashboard/profile reúne las preferencias personales del operador que inició sesión: tema, idioma, zona horaria y configuraciones de notificación. A diferencia de las configuraciones de la organización (que afectan a todos los miembros), las preferencias de perfil son por usuario y se almacenan localmente y en el servidor. #### rate-limiting El sistema implementa límites de solicitudes de la API para proteger la plataforma y garantizar un uso justo. - [Rate Limiting](https://docs.billing.kobana.com.br/es/configuracoes/rate-limiting.md): El sistema implementa límites de solicitudes de la API para proteger la plataforma y garantizar un uso justo. #### relatorios La central de reportes (/dashboard/reports) es donde los equipos de finanzas, operaciones y atención generan extracciones tabulares de los datos de la organización. A diferencia de Analytics, que agrega métricas, los reportes entregan datos fila por fila listos para conciliar, auditar o armar hojas de cálculo externas. - [Reportes](https://docs.billing.kobana.com.br/es/configuracoes/relatorios.md): La central de reportes (/dashboard/reports) es donde los equipos de finanzas, operaciones y atención generan extracciones tabulares de los datos de la organización. A diferencia de Analytics, que agrega métricas, los reportes entregan datos fila por fila listos para conciliar, auditar o armar hojas de cálculo externas. #### templates-de-email Los templates de e-mail permiten personalizar las comunicaciones transaccionales enviadas a los clientes. - [Templates de E-mail](https://docs.billing.kobana.com.br/es/configuracoes/templates-de-email.md): Los templates de e-mail permiten personalizar las comunicaciones transaccionales enviadas a los clientes. #### uso La pantalla /dashboard/usage consolida el consumo medido (metered) de todos los clientes de la organización: eventos de API, mensajes enviados, transacciones procesadas, almacenamiento — cualquier métrica que el catálogo defina como "uso" y que se cobre por consumo. - [Uso y Consumo](https://docs.billing.kobana.com.br/es/configuracoes/uso.md): La pantalla /dashboard/usage consolida el consumo medido (metered) de todos los clientes de la organización: eventos de API, mensajes enviados, transacciones procesadas, almacenamiento — cualquier métrica que el catálogo defina como "uso" y que se cobre por consumo. #### usuarios La página /dashboard/users lista los usuarios del portal del cliente — personas físicas vinculadas a una cuenta de cobro (BillingAccount) que pueden entrar al portal para ver facturas, pagar boletos, gestionar tarjetas y actualizar datos. - [Usuarios](https://docs.billing.kobana.com.br/es/configuracoes/usuarios.md): La página /dashboard/users lista los usuarios del portal del cliente — personas físicas vinculadas a una cuenta de cobro (BillingAccount) que pueden entrar al portal para ver facturas, pagar boletos, gestionar tarjetas y actualizar datos. ### contas - [Cuentas](https://docs.billing.kobana.com.br/es/contas.md) #### clientes Los clientes son representados por el modelo Persona (Person) con diferentes tipos según el contexto. - [Clientes (Personas)](https://docs.billing.kobana.com.br/es/contas/clientes.md): Los clientes son representados por el modelo Persona (Person) con diferentes tipos según el contexto. #### contas-de-cobranca Las cuentas de cobro (BillingAccount) representan la relación financiera entre una organización y su cliente. Cada cuenta posee suscripciones, facturas, pagos y métodos de pago. - [Cuentas de Cobro](https://docs.billing.kobana.com.br/es/contas/contas-de-cobranca.md): Las cuentas de cobro (BillingAccount) representan la relación financiera entre una organización y su cliente. Cada cuenta posee suscripciones, facturas, pagos y métodos de pago. #### empresas En /dashboard/companies la organización registra las personas jurídicas emisoras — empresas que firman contratos, facturas y NF-e. Una organización puede tener varias empresas (casa matriz, sucursales o CNPJ distintos del mismo grupo) y definir una como predeterminada para los cobros. - [Empresas](https://docs.billing.kobana.com.br/es/contas/empresas.md): En /dashboard/companies la organización registra las personas jurídicas emisoras — empresas que firman contratos, facturas y NF-e. Una organización puede tener varias empresas (casa matriz, sucursales o CNPJ distintos del mismo grupo) y definir una como predeterminada para los cobros. #### organizacoes Las organizaciones son los tenants (inquilinos) de la plataforma. Cada organización es un negocio que usa Facturación Automática para cobrar a sus propios clientes. - [Organizaciones](https://docs.billing.kobana.com.br/es/contas/organizacoes.md): Las organizaciones son los tenants (inquilinos) de la plataforma. Cada organización es un negocio que usa Facturación Automática para cobrar a sus propios clientes. #### portal-do-cliente El portal del cliente permite que los clientes finales de cada organización gestionen sus suscripciones, facturas y métodos de pago de forma autónoma. - [Portal del Cliente](https://docs.billing.kobana.com.br/es/contas/portal-do-cliente.md): El portal del cliente permite que los clientes finales de cada organización gestionen sus suscripciones, facturas y métodos de pago de forma autónoma. ### cupons-e-descontos - [Cupones y Descuentos](https://docs.billing.kobana.com.br/es/cupons-e-descontos.md) #### codigos-de-desconto Los códigos de descuento se aplican directamente a suscripciones en el momento de la creación, ofreciendo descuentos recurrentes o puntuales. - [Códigos de Descuento](https://docs.billing.kobana.com.br/es/cupons-e-descontos/codigos-de-desconto.md): Los códigos de descuento se aplican directamente a suscripciones en el momento de la creación, ofreciendo descuentos recurrentes o puntuales. #### cupons Los cupones son códigos promocionales que los clientes pueden canjear para obtener descuentos en compras y facturas. - [Cupones](https://docs.billing.kobana.com.br/es/cupons-e-descontos/cupons.md): Los cupones son códigos promocionales que los clientes pueden canjear para obtener descuentos en compras y facturas. ### docs-mcp Esta documentación tiene su propio servidor MCP. Con él, un asistente de IA - [MCP de la Documentación](https://docs.billing.kobana.com.br/es/docs-mcp.md): Esta documentación tiene su propio servidor MCP. Con él, un asistente de IA ### exportacao-e-importacao - [Exportación e Importación](https://docs.billing.kobana.com.br/es/exportacao-e-importacao.md) #### exportacoes Exporte datos de la plataforma en diferentes formatos para reportes e integraciones. - [Exportaciones](https://docs.billing.kobana.com.br/es/exportacao-e-importacao/exportacoes.md): Exporte datos de la plataforma en diferentes formatos para reportes e integraciones. #### importacoes Importe datos en masa a la plataforma vía carga de archivos. - [Importaciones](https://docs.billing.kobana.com.br/es/exportacao-e-importacao/importacoes.md): Importe datos en masa a la plataforma vía carga de archivos. ### faturas-e-pagamentos - [Facturas y Pagos](https://docs.billing.kobana.com.br/es/faturas-e-pagamentos.md) #### creditos El sistema de créditos permite agregar saldo en la cuenta del cliente que se aplica automáticamente en facturas futuras. - [Créditos](https://docs.billing.kobana.com.br/es/faturas-e-pagamentos/creditos.md): El sistema de créditos permite agregar saldo en la cuenta del cliente que se aplica automáticamente en facturas futuras. #### faturas Las facturas representan cobros enviados a los clientes. Cada factura contiene line items que detallan los productos y valores cobrados. - [Facturas](https://docs.billing.kobana.com.br/es/faturas-e-pagamentos/faturas.md): Las facturas representan cobros enviados a los clientes. Cada factura contiene line items que detallan los productos y valores cobrados. #### metodos-de-pagamento Cada cuenta de cobro puede tener múltiples métodos de pago almacenados. Uno de ellos se marca como predeterminado para cobros automáticos. - [Métodos de Pago](https://docs.billing.kobana.com.br/es/faturas-e-pagamentos/metodos-de-pagamento.md): Cada cuenta de cobro puede tener múltiples métodos de pago almacenados. Uno de ellos se marca como predeterminado para cobros automáticos. #### pagamentos Los pagos representan intentos de cobro asociados a facturas. Cada pago rastrea el estado, método, gateway utilizado y respuesta del proveedor. - [Pagos](https://docs.billing.kobana.com.br/es/faturas-e-pagamentos/pagamentos.md): Los pagos representan intentos de cobro asociados a facturas. Cada pago rastrea el estado, método, gateway utilizado y respuesta del proveedor. #### parcelamento Las facturas pueden ser divididas en múltiples cuotas con fechas de vencimiento individuales. - [Pagos en Cuotas](https://docs.billing.kobana.com.br/es/faturas-e-pagamentos/parcelamento.md): Las facturas pueden ser divididas en múltiples cuotas con fechas de vencimiento individuales. ### gateways-de-pagamento - [Pasarelas de Pago](https://docs.billing.kobana.com.br/es/gateways-de-pagamento.md) #### callbacks Los proveedores de gateway envían notificaciones al sistema cuando el estado de los pagos cambia. Estas notificaciones se procesan de forma asíncrona. - [Callbacks (Webhooks de los Proveedores)](https://docs.billing.kobana.com.br/es/gateways-de-pagamento/callbacks.md): Los proveedores de gateway envían notificaciones al sistema cuando el estado de los pagos cambia. Estas notificaciones se procesan de forma asíncrona. #### configuracao Cada organización puede configurar múltiples gateways y definir valores predeterminados por método de pago. - [Configuración de Gateways](https://docs.billing.kobana.com.br/es/gateways-de-pagamento/configuracao.md): Cada organización puede configurar múltiples gateways y definir valores predeterminados por método de pago. #### provedores El sistema soporta tres proveedores de pago, cada uno con capacidades específicas. - [Proveedores de Gateway](https://docs.billing.kobana.com.br/es/gateways-de-pagamento/provedores.md): El sistema soporta tres proveedores de pago, cada uno con capacidades específicas. ### gestao-de-inadimplencia - [Gestión de Morosidad](https://docs.billing.kobana.com.br/es/gestao-de-inadimplencia.md) #### configuracao-de-dunning La configuración de dunning define cómo el sistema trata los pagos en atraso: cuántos intentos, el intervalo entre ellos y el comportamiento después de agotarlos. - [Configuración de Dunning](https://docs.billing.kobana.com.br/es/gestao-de-inadimplencia/configuracao-de-dunning.md): La configuración de dunning define cómo el sistema trata los pagos en atraso: cuántos intentos, el intervalo entre ellos y el comportamiento después de agotarlos. #### juros-e-multa Una factura vencida puede acumular multa (cobrada una sola vez) e intereses de mora (que corren por día de atraso). La política de intereses y multas define ambos, vale para toda la organización y puede cambiarse por cliente, por suscripción o por factura. - [Intereses y Multas](https://docs.billing.kobana.com.br/es/gestao-de-inadimplencia/juros-e-multa.md): Una factura vencida puede acumular multa (cobrada una sola vez) e intereses de mora (que corren por día de atraso). La política de intereses y multas define ambos, vale para toda la organización y puede cambiarse por cliente, por suscripción o por factura. #### recuperacao-de-receita El sistema rastrea todos los ingresos recuperados vía dunning para análisis de eficiencia. - [Recuperación de Ingresos](https://docs.billing.kobana.com.br/es/gestao-de-inadimplencia/recuperacao-de-receita.md): El sistema rastrea todos los ingresos recuperados vía dunning para análisis de eficiencia. #### suspensao Las cuentas morosas son automáticamente suspendidas cuando el período de gracia es excedido. - [Suspensión de Cuentas](https://docs.billing.kobana.com.br/es/gestao-de-inadimplencia/suspensao.md): Las cuentas morosas son automáticamente suspendidas cuando el período de gracia es excedido. #### tentativas-de-pagamento El sistema de retry procesa automáticamente intentos de cobro para facturas en atraso. - [Intentos de Pago (Payment Retry)](https://docs.billing.kobana.com.br/es/gestao-de-inadimplencia/tentativas-de-pagamento.md): El sistema de retry procesa automáticamente intentos de cobro para facturas en atraso. ### getting-started La página Getting Started (/dashboard/getting-started) es el punto de partida para las nuevas organizaciones. Presenta una secuencia guiada de las tareas necesarias para empezar a cobrar de forma recurrente: registrar la empresa, configurar gateways y NF-e, crear planes y productos, importar clientes y activar la primera suscripción. - [Primeros Pasos](https://docs.billing.kobana.com.br/es/getting-started.md): La página Getting Started (/dashboard/getting-started) es el punto de partida para las nuevas organizaciones. Presenta una secuencia guiada de las tareas necesarias para empezar a cobrar de forma recurrente: registrar la empresa, configurar gateways y NF-e, crear planes y productos, importar clientes y activar la primera suscripción. ### impostos - [Impuestos](https://docs.billing.kobana.com.br/es/impostos.md) #### motor-de-calculo El motor de cálculo determina todos los impuestos aplicables con base en las reglas fiscales, perfil de la empresa y tipo fiscal del cliente. - [Motor de Cálculo de Impuestos](https://docs.billing.kobana.com.br/es/impostos/motor-de-calculo.md): El motor de cálculo determina todos los impuestos aplicables con base en las reglas fiscales, perfil de la empresa y tipo fiscal del cliente. #### perfil-fiscal El perfil fiscal define la configuración tributaria de cada empresa (entidad jurídica) de la organización. - [Perfil Fiscal](https://docs.billing.kobana.com.br/es/impostos/perfil-fiscal.md): El perfil fiscal define la configuración tributaria de cada empresa (entidad jurídica) de la organización. #### periodos-fiscais Los períodos fiscales agregan las facturas para la liquidación mensual o trimestral de impuestos. - [Períodos Fiscales](https://docs.billing.kobana.com.br/es/impostos/periodos-fiscais.md): Los períodos fiscales agregan las facturas para la liquidación mensual o trimestral de impuestos. #### regras-fiscais Las reglas fiscales permiten configurar alícuotas de impuestos con diferentes niveles de especificidad. - [Reglas Fiscales](https://docs.billing.kobana.com.br/es/impostos/regras-fiscais.md): Las reglas fiscales permiten configurar alícuotas de impuestos con diferentes niveles de especificidad. #### relatorios-fiscais El área de informes fiscales (/dashboard/fiscal/reports) consolida la información necesaria para el cierre contable y la generación de obligaciones accesorias. Los datos se generan a partir de las facturas pagadas, las NF-e emitidas, las retenciones y los períodos fiscales ya cerrados por la organización. - [Informes Fiscales](https://docs.billing.kobana.com.br/es/impostos/relatorios-fiscais.md): El área de informes fiscales (/dashboard/fiscal/reports) consolida la información necesaria para el cierre contable y la generación de obligaciones accesorias. Los datos se generan a partir de las facturas pagadas, las NF-e emitidas, las retenciones y los períodos fiscales ya cerrados por la organización. #### retencoes Las retenciones son impuestos retenidos por el pagador (cliente) que deben ser rastreados, reportados y compensados. - [Retenciones en la Fuente](https://docs.billing.kobana.com.br/es/impostos/retencoes.md): Las retenciones son impuestos retenidos por el pagador (cliente) que deben ser rastreados, reportados y compensados. #### simples-nacional El sistema calcula automáticamente el DAS (Documento de Recaudación del Simples Nacional) con base en los ingresos y el anexo correcto. - [Simples Nacional](https://docs.billing.kobana.com.br/es/impostos/simples-nacional.md): El sistema calcula automáticamente el DAS (Documento de Recaudación del Simples Nacional) con base en los ingresos y el anexo correcto. ### mcp #### overview - [Autenticación](https://docs.billing.kobana.com.br/es/mcp/overview/authentication.md): El servidor MCP acepta un Bearer token en la cabecera Authorization, y nada más — sin cookie, sin certificado de cliente. - [Clientes](https://docs.billing.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; el cliente descubre solo dónde autenticarse, abre el inicio de sesión de Kobana en el navegador y guarda el token — ver Autenticación. - [Endpoints](https://docs.billing.kobana.com.br/es/mcp/overview/endpoints.md): Servidor MCP - [Errores](https://docs.billing.kobana.com.br/es/mcp/overview/errors.md): Los fallos llegan por dos canales distintos, y la diferencia importa: uno es una petición rota, el otro es algo que el modelo debe leer y a lo que debe reaccionar. - [Idempotencia](https://docs.billing.kobana.com.br/es/mcp/overview/idempotency.md): Las tools que crean un recurso o mueven dinero aceptan un argumento opcional idempotency_key. Se envía al endpoint como la cabecera X-Idempotency-Key que la API REST ya honra. - [Introducción](https://docs.billing.kobana.com.br/es/mcp/overview/introduction.md): El servidor MCP de Facturación Automática es un servidor Model Context Protocol remoto que expone las operaciones de la API pública — clientes, suscripciones, facturas, pagos, notas fiscales, propuestas y consumo — como tools que un cliente de IA puede llamar. Lo conectas por URL; no hay nada que instalar. - [Listado, Orden y Campos](https://docs.billing.kobana.com.br/es/mcp/overview/pagination.md): Las tools _list usan la misma paginación de la API REST: por número de página*. - [Límite de Peticiones](https://docs.billing.kobana.com.br/es/mcp/overview/rate-limit.md): El servidor MCP comparte los mismos límites de la API REST, contados por persona y organización — el sub y el org del token, no el token en sí. - [Resources y prompts](https://docs.billing.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 el usuario adjunta a la conversación), prompts (guiones listos que el usuario elige) y completions (autocompletado de sus argumentos). En la era 2026-07-28 también pide confirmación antes de ejecutar una tool destructiva. - [Transporte](https://docs.billing.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 toda operación larga ya responde de inmediato y termina en un worker en segundo plano, no en el canal MCP. #### tools - [Catálogo](https://docs.billing.kobana.com.br/es/mcp/tools/catalog.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} - [Clientes y accesos](https://docs.billing.kobana.com.br/es/mcp/tools/customers.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} - [Fiscal](https://docs.billing.kobana.com.br/es/mcp/tools/fiscal.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} - [Facturas y cobros](https://docs.billing.kobana.com.br/es/mcp/tools/invoices.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} - [Organización y esquemas](https://docs.billing.kobana.com.br/es/mcp/tools/organization.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.billing.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. /} - [Propuestas](https://docs.billing.kobana.com.br/es/mcp/tools/proposals.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} - [Suscripciones](https://docs.billing.kobana.com.br/es/mcp/tools/subscriptions.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} - [Consumo](https://docs.billing.kobana.com.br/es/mcp/tools/usage.md): {/ Página generada a partir del registry de tools. Los nombres, permisos y endpoints de abajo son los mismos que devuelve tools/list. /} ### nota-fiscal - [Nota Fiscal (NF-e)](https://docs.billing.kobana.com.br/es/nota-fiscal.md) #### certificados La página /dashboard/certificates gestiona los certificados digitales A1 usados para firmar NF-e y autenticarse en los webservices de las alcaldías (prefeituras). Cada certificado se vincula a una empresa registrada y se almacena cifrado en reposo. - [Certificados Digitales](https://docs.billing.kobana.com.br/es/nota-fiscal/certificados.md): La página /dashboard/certificates gestiona los certificados digitales A1 usados para firmar NF-e y autenticarse en los webservices de las alcaldías (prefeituras). Cada certificado se vincula a una empresa registrada y se almacena cifrado en reposo. #### configuracao Cada organización puede habilitar y configurar la emisión automática de notas fiscais. - [Configuración de NF-e](https://docs.billing.kobana.com.br/es/nota-fiscal/configuracao.md): Cada organización puede habilitar y configurar la emisión automática de notas fiscais. #### emissao Estados de la NF-e - [Emisión de NF-e](https://docs.billing.kobana.com.br/es/nota-fiscal/emissao.md): Estados de la NF-e #### provedores El sistema abstrae la comunicación con proveedores de NF-e a través de una interfaz común. - [Proveedores de NF-e](https://docs.billing.kobana.com.br/es/nota-fiscal/provedores.md): El sistema abstrae la comunicación con proveedores de NF-e a través de una interfaz común. #### tentativas El sistema implementa reintento automático para emisiones que fallan. - [Intentos y Reintento de NF-e](https://docs.billing.kobana.com.br/es/nota-fiscal/tentativas.md): El sistema implementa reintento automático para emisiones que fallan. ### planos-e-produtos - [Planes y Productos](https://docs.billing.kobana.com.br/es/planos-e-produtos.md) #### grupos-de-planos Los grupos de planes permiten organizar planes relacionados para facilitar la gestión y visualización en el dashboard. - [Grupos de Planes](https://docs.billing.kobana.com.br/es/planos-e-produtos/grupos-de-planos.md): Los grupos de planes permiten organizar planes relacionados para facilitar la gestión y visualización en el dashboard. #### grupos-de-produtos Los grupos de productos permiten categorizar productos para facilitar la organización, los filtros en el dashboard y la vinculación con templates de propuestas. - [Grupos de Productos](https://docs.billing.kobana.com.br/es/planos-e-produtos/grupos-de-produtos.md): Los grupos de productos permiten categorizar productos para facilitar la organización, los filtros en el dashboard y la vinculación con templates de propuestas. #### itens-de-servico Los ítems de servicio (/dashboard/service-items) son el catálogo de descripciones fiscales usadas en facturas y NF-e de servicio. Cada ítem contiene la información que la alcaldía (prefeitura) exige al momento de la emisión: código municipal de servicio, código LC 116, código tributario nacional, alícuotas predeterminadas de ISS, PIS, COFINS, IR, INSS, CSLL. - [Ítems de Servicio](https://docs.billing.kobana.com.br/es/planos-e-produtos/itens-de-servico.md): Los ítems de servicio (/dashboard/service-items) son el catálogo de descripciones fiscales usadas en facturas y NF-e de servicio. Cada ítem contiene la información que la alcaldía (prefeitura) exige al momento de la emisión: código municipal de servicio, código LC 116, código tributario nacional, alícuotas predeterminadas de ISS, PIS, COFINS, IR, INSS, CSLL. #### planos Los planes son los modelos que definen cómo se cobrará a sus clientes. Cada plan agrupa productos con precios específicos y configura el ciclo de cobro, el período de prueba y las funcionalidades incluidas. - [Planes](https://docs.billing.kobana.com.br/es/planos-e-produtos/planos.md): Los planes son los modelos que definen cómo se cobrará a sus clientes. Cada plan agrupa productos con precios específicos y configura el ciclo de cobro, el período de prueba y las funcionalidades incluidas. #### precos Cada producto puede tener múltiples precios, permitiendo variantes por moneda, intervalo de cobro o modelo de fijación de precios. Los precios son en gran parte inmutables después de su creación — solo el nombre y los metadatos pueden modificarse. Para cambiar valores, desactive el precio anterior y cree uno nuevo. - [Precios y Modelos de Fijación de Precios](https://docs.billing.kobana.com.br/es/planos-e-produtos/precos.md): Cada producto puede tener múltiples precios, permitiendo variantes por moneda, intervalo de cobro o modelo de fijación de precios. Los precios son en gran parte inmutables después de su creación — solo el nombre y los metadatos pueden modificarse. Para cambiar valores, desactive el precio anterior y cree uno nuevo. #### produtos Los productos representan los servicios o recursos facturables de su organización. Cada producto puede tener múltiples precios y soporta jerarquía de un nivel (producto raíz con hijos/add-ons). - [Productos](https://docs.billing.kobana.com.br/es/planos-e-produtos/produtos.md): Los productos representan los servicios o recursos facturables de su organización. Cada producto puede tener múltiples precios y soporta jerarquía de un nivel (producto raíz con hijos/add-ons). ### portal - [Portal del Cliente](https://docs.billing.kobana.com.br/es/portal.md) #### assinaturas La página /portal/subscriptions lista las suscripciones vinculadas a la cuenta de cobro autenticada. Cada fila muestra el plan, el status, el valor recurrente, el próximo ciclo y las acciones disponibles. - [Suscripciones](https://docs.billing.kobana.com.br/es/portal/assinaturas.md): La página /portal/subscriptions lista las suscripciones vinculadas a la cuenta de cobro autenticada. Cada fila muestra el plan, el status, el valor recurrente, el próximo ciclo y las acciones disponibles. #### configuracoes La página /portal/settings agrupa las preferencias de la cuenta de cobro que afectan cómo el cliente recibe los cobros y las comunicaciones. - [Configuración](https://docs.billing.kobana.com.br/es/portal/configuracoes.md): La página /portal/settings agrupa las preferencias de la cuenta de cobro que afectan cómo el cliente recibe los cobros y las comunicaciones. #### conta En /portal/account el cliente gestiona los datos de la cuenta de cobro (BillingAccount) — razón social, CNPJ/CPF, inscripción estatal y municipal, dirección, contacto financiero y e-mails para el envío de facturas. - [Cuenta](https://docs.billing.kobana.com.br/es/portal/conta.md): En /portal/account el cliente gestiona los datos de la cuenta de cobro (BillingAccount) — razón social, CNPJ/CPF, inscripción estatal y municipal, dirección, contacto financiero y e-mails para el envío de facturas. #### creditos La página /portal/credits muestra el saldo de créditos de la cuenta de cobro y el historial de aplicaciones. Los créditos surgen por diversos motivos — proration de downgrade, reembolso de factura, ajuste manual de la organización, promoción — y se aplican automáticamente en las próximas facturas. - [Créditos](https://docs.billing.kobana.com.br/es/portal/creditos.md): La página /portal/credits muestra el saldo de créditos de la cuenta de cobro y el historial de aplicaciones. Los créditos surgen por diversos motivos — proration de downgrade, reembolso de factura, ajuste manual de la organización, promoción — y se aplican automáticamente en las próximas facturas. #### faturas La página /portal/invoices lista todas las facturas de la cuenta de cobro, con filtros por status y período. El cliente puede verlas, descargar el PDF, copiar la línea digitable o el código QR PIX, pagar en línea y consultar la NF-e relacionada. - [Facturas](https://docs.billing.kobana.com.br/es/portal/faturas.md): La página /portal/invoices lista todas las facturas de la cuenta de cobro, con filtros por status y período. El cliente puede verlas, descargar el PDF, copiar la línea digitable o el código QR PIX, pagar en línea y consultar la NF-e relacionada. #### metodos-de-pagamento En /portal/payment-methods el cliente gestiona los medios de pago asociados a la cuenta de cobro. La página admite varios métodos a la vez y define cuál es el predeterminado para los cobros automáticos. - [Métodos de Pago](https://docs.billing.kobana.com.br/es/portal/metodos-de-pagamento.md): En /portal/payment-methods el cliente gestiona los medios de pago asociados a la cuenta de cobro. La página admite varios métodos a la vez y define cuál es el predeterminado para los cobros automáticos. #### pagamentos La página /portal/payments presenta el historial de pagos ya procesados en la cuenta de cobro — sin importar el método ni la factura de origen. Es la vista del extracto, útil para la conciliación contable y las dudas sobre cobros. - [Pagos](https://docs.billing.kobana.com.br/es/portal/pagamentos.md): La página /portal/payments presenta el historial de pagos ya procesados en la cuenta de cobro — sin importar el método ni la factura de origen. Es la vista del extracto, útil para la conciliación contable y las dudas sobre cobros. #### perfil La página /portal/profile reúne las preferencias personales del usuario que inició sesión en el portal. A diferencia de Cuenta, que se ocupa de la persona jurídica/física pagadora, el perfil es por cada persona que usa el portal. - [Perfil](https://docs.billing.kobana.com.br/es/portal/perfil.md): La página /portal/profile reúne las preferencias personales del usuario que inició sesión en el portal. A diferencia de Cuenta, que se ocupa de la persona jurídica/física pagadora, el perfil es por cada persona que usa el portal. #### produtos La página /portal/products es la vitrina self-service de los productos y planes que la organización publicó para la venta directa en el portal. El cliente puede contratar nuevos productos sin pasar por el equipo comercial, con un checkout integrado a los métodos de pago ya registrados. - [Productos](https://docs.billing.kobana.com.br/es/portal/produtos.md): La página /portal/products es la vitrina self-service de los productos y planes que la organización publicó para la venta directa en el portal. El cliente puede contratar nuevos productos sin pasar por el equipo comercial, con un checkout integrado a los métodos de pago ya registrados. #### propostas En /portal/proposals el cliente ve las propuestas comerciales enviadas por el equipo de la organización. Cada propuesta detalla planes, ítems, descuentos, plazo y condiciones — y puede aceptarse directamente en el portal, convirtiéndose en una suscripción activa. - [Propuestas](https://docs.billing.kobana.com.br/es/portal/propostas.md): En /portal/proposals el cliente ve las propuestas comerciales enviadas por el equipo de la organización. Cada propuesta detalla planes, ítems, descuentos, plazo y condiciones — y puede aceptarse directamente en el portal, convirtiéndose en una suscripción activa. #### uso La página /portal/usage muestra al cliente el consumo medido acumulado en el ciclo actual — cuántas llamadas a la API, mensajes enviados, eventos procesados o GB almacenados, según las métricas definidas por la organización. - [Uso](https://docs.billing.kobana.com.br/es/portal/uso.md): La página /portal/usage muestra al cliente el consumo medido acumulado en el ciclo actual — cuántas llamadas a la API, mensajes enviados, eventos procesados o GB almacenados, según las métricas definidas por la organización. #### visao-geral La página inicial del portal (/portal) presenta un resumen de la relación financiera del cliente con la organización: suscripción activa, próxima factura, último pago, créditos disponibles y accesos directos a las acciones más comunes. - [Vista General](https://docs.billing.kobana.com.br/es/portal/visao-geral.md): La página inicial del portal (/portal) presenta un resumen de la relación financiera del cliente con la organización: suscripción activa, próxima factura, último pago, créditos disponibles y accesos directos a las acciones más comunes. ### propostas - [Propuestas](https://docs.billing.kobana.com.br/es/propostas.md) #### geracao-de-pdf El sistema genera PDFs de propuestas integrando con Google Docs/Slides vía Google Apps Script. - [Generación de PDF](https://docs.billing.kobana.com.br/es/propostas/geracao-de-pdf.md): El sistema genera PDFs de propuestas integrando con Google Docs/Slides vía Google Apps Script. #### propostas Las propuestas son documentos comerciales enviados a clientes o prospectos con ítems, precios y condiciones de pago. - [Propuestas](https://docs.billing.kobana.com.br/es/propostas/propostas.md): Las propuestas son documentos comerciales enviados a clientes o prospectos con ítems, precios y condiciones de pago. #### templates Los templates definen el modelo de documento usado para generar PDFs de las propuestas. - [Templates de Propuesta](https://docs.billing.kobana.com.br/es/propostas/templates.md): Los templates definen el modelo de documento usado para generar PDFs de las propuestas. ### webhooks - [Webhooks](https://docs.billing.kobana.com.br/es/webhooks.md) #### endpoints Cada organización puede configurar múltiples endpoints para recibir notificaciones de eventos. - [Endpoints de Webhook](https://docs.billing.kobana.com.br/es/webhooks/endpoints.md): Cada organización puede configurar múltiples endpoints para recibir notificaciones de eventos. #### entregas Cada notificación enviada a un endpoint se registra como una entrega, permitiendo monitoreo y reintento. - [Entregas de Webhook](https://docs.billing.kobana.com.br/es/webhooks/entregas.md): Cada notificación enviada a un endpoint se registra como una entrega, permitiendo monitoreo y reintento. #### eventos El sistema emite eventos para todas las operaciones significativas. Cada organización puede suscribirse a los tipos relevantes. - [Eventos de Webhook](https://docs.billing.kobana.com.br/es/webhooks/eventos.md): El sistema emite eventos para todas las operaciones significativas. Cada organización puede suscribirse a los tipos relevantes. --- # 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.billing.kobana.com.br/es/es/.md) [**Facturación Automática**](https://docs.billing.kobana.com.br/es/es/.md) Documentación [Documentación](https://docs.billing.kobana.com.br/es/es/.md)[API](https://docs.billing.kobana.com.br/es/es/api/overview/introduction.md)[MCP](https://docs.billing.kobana.com.br/es/es/mcp/overview/introduction.md)[CLI](https://docs.billing.kobana.com.br/es/es/cli/overview/introduction.md) Preguntar a la IA [](#) * [🇧🇷 Português](https://docs.billing.kobana.com.br/es/pt/search) * [🇺🇸 English](https://docs.billing.kobana.com.br/es/en/search) * [🇪🇸 Español](https://docs.billing.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 --- # Referencia de la API --- # Autenticación La API de Facturación Automática 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. El claim **`org`** identifica tu organización: todos los datos devueltos quedan automáticamente limitados a ella. Requisitos verificados 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.billing[.{env}].kobana.com.br`. Puede ser una **lista** — la regla es *contiene*, no igualdad | | `exp` | **Obligatorio.** 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 auditoría y atribución; no limita nada | | `jti` | Id único del token — base de la auditoría | :::caution Cambio respecto a la clave de API Hasta septiembre de 2026 la credencial era una clave creada en el dashboard (`kb_…`), con prefijo público y secret mostrado una sola vez. La clave era a la vez la credencial y lo que la verificaba — quien leyera el repositorio de claves actuaba como cualquier organización, y cada rotación era una conversación con un cliente. Ahora quien emite es el Authorization Server, y la plataforma solo verifica. **Una clave creada en Configuración → API ya no autentica esta API.** ::: Verifica el ambiente El token es **diferente** entre Sandbox y Producción — el `aud` de uno no vale en el otro. No lo reutilices entre ambientes. ## Cómo enviar el token[​](#cómo-enviar-el-token "Enlace directo al Cómo enviar el token") Incluye el header `Authorization: Bearer ` en cada solicitud. ``` export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx curl -i \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'Content-Type: application/json' \ -H 'User-Agent: Meu Nome (meunome@example.com)' \ -X GET 'https://api.billing.sandbox.kobana.com.br/v1/organization' ``` ## Solicitud válida[​](#solicitud-válida "Enlace directo al Solicitud válida") Con un token válido, la respuesta trae los datos de la Organización autenticada. ``` HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Request-Id: req_01HABCDEF { "id": "org_01HORG", "name": "Minha Empresa", "email": "contato@minhaempresa.com.br", "document_type": "cnpj", "document_number": "12345678000190", "environment": "sandbox", "created_at": "2026-01-01T00:00:00.000Z" } ``` ## Solicitud inválida[​](#solicitud-inválida "Enlace directo al Solicitud inválida") Un token ausente, malformado o expirado devuelve `401 Unauthorized`. ``` curl -i \ -H "Authorization: Bearer tokeninvalido" \ -H 'Content-Type: application/json' \ -H 'User-Agent: Meu Nome (meunome@example.com)' \ -X GET 'https://api.billing.sandbox.kobana.com.br/v1/organization' ``` ``` HTTP/1.1 401 Unauthorized Content-Type: application/json; charset=utf-8 { "error": { "code": "invalid_token", "message": "Token de acesso inválido ou expirado." } } ``` Los códigos específicos ayudan a encontrar el error de inmediato: `invalid_token` (ausente, malformado o con firma inválida), `invalid_audience` (token de otra app Kobana) y `unknown_organization` — este último es `403`: el token es válido, la organización es la que no está aquí. **Si nuestro Authorization Server está fuera de servicio**, la respuesta es `5xx`, no `401`. Es deliberado: un `401` te mandaría a depurar una credencial perfecta durante nuestra caída. Inténtalo de nuevo en unos instantes. :::note `sub` no es el tenant `sub` es la persona y `org` es el cliente — son uuids de tablas diferentes, por lo que intercambiarlos no produce error de formato. Un token sin `org` se rechaza en lugar de caer en `sub`: ese fallback no coincidiría con ninguna organización y respondería `403` en todo, con el síntoma apuntando a permisos y no al claim leído. ::: ## Scopes[​](#scopes "Enlace directo al Scopes") Los scopes se **exigen en cada solicitud**, y cada solicitud requiere **un único nivel de acceso**: el que pide el método (`GET` lee, `DELETE` elimina, `POST`/`PUT`/`PATCH` escriben), o el que declara el endpoint cuando ningún método lo indica (importación y exportación masivas). Hay dos formatos de token, y cada uno se lee de una manera. ### Los seis niveles de acceso[​](#los-seis-niveles-de-acceso "Enlace directo al Los seis niveles de acceso") | Nivel | Concede | | -------- | -------------------------------------------- | | `read` | Lectura (`GET`, `HEAD`) | | `write` | Lectura y escritura (`POST`, `PUT`, `PATCH`) | | `delete` | Eliminación (`DELETE`), individual o en lote | | `import` | Importación masiva | | `export` | Exportación masiva | | `all` | Todo | **Un nivel nunca sustituye a otro.** `write` no elimina, no importa y no exporta; `delete`, `import` y `export` no leen ni escriben. Combina los niveles que necesita la integración — `read delete` lista y elimina, `read write delete` hace las tres cosas. ### El nivel que exige cada endpoint[​](#el-nivel-que-exige-cada-endpoint "Enlace directo al El nivel que exige cada endpoint") | Endpoint | Nivel | | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | `GET` / `HEAD` | `read` | | `POST` / `PUT` / `PATCH` | `write` | | `DELETE` — toda eliminación es un `DELETE`, incluida la de lote (`DELETE /v1/{recurso}/bulk`) y la que solo marca el registro como eliminado | `delete` | | `POST /v1/nfes/import-barueri` | `import` | | Exportación masiva — esta API aún no tiene ninguna; el PDF o el XML de **un** documento (`/invoices/{id}/pdf`, `/nfes/{id}/xml`) es lectura | `export` | | `GET /v1/me` | Cualquier token válido | Todo `DELETE` es una eliminación, y nada más que una eliminación es un `DELETE`: archivar (`POST …/archive`), desarchivar (`POST …/unarchive`), desactivar (`POST …/deactivate`), cerrar (`POST …/close`) y cancelar (`POST …/cancel`) son escrituras. Una eliminación es **soft delete** siempre que el registro tenga historial que preservar: recibe `deleted_at` y desaparece de toda lectura (listados, `GET` por id, filtros), mientras que las facturas, pagos y NFS-e que lo citan conservan la referencia. :::caution Cambio de octubre de 2026 * **`DELETE` exige `delete`** (o `all`). Antes un `DELETE` aceptaba también `write`; un token solo con `write` ahora recibe `403 insufficient_scope` al eliminar. Solicita el nivel `delete` en la Cuenta Kobana para las integraciones que eliminan. * **`POST /v1/nfes/import-barueri` exige `import`** (o `all`); `write` no basta. * **`DELETE` pasó a eliminar** (soft delete, `deleted_at`) donde antes solo cambiaba un estado. Quien usaba `DELETE` para archivar, desactivar o cerrar debe llamar a la ruta propia: | Endpoint | Antes | Ahora | Para el efecto anterior | | ------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `DELETE /v1/products/{id}` | archivaba | elimina | `POST /v1/products/{id}/archive` | | `DELETE /v1/plans/{id}` | archivaba; `?hard=true` eliminaba un borrador | elimina (el parámetro `hard` dejó de existir) | `POST /v1/plans/{id}/archive` (nueva) | | `DELETE /v1/companies/{id}` | desactivaba | elimina | `POST /v1/companies/{id}/deactivate` | | `DELETE /v1/billing_accounts/{id}` | cerraba (`?reason=`) y respondía la cuenta | elimina, con métodos de pago, tarjetas, usuarios del portal y archivos, y responde `{ "deleted": true }` | `POST /v1/billing_accounts/{id}/close` | | `DELETE /v1/customers/{id}/users/{user_id}` | borraba la invitación pendiente; suspendía al usuario activo | elimina ambos | — | | `DELETE /v1/service_items/{id}` | borraba, o solo desactivaba si una regla tributaria lo usaba | elimina | `PATCH` con `is_active=false` | | `DELETE /v1/payment_methods/{id}` | lo marcaba `removed` | elimina (y sigue `removed` donde aparece por relación) | — | | `DELETE /v1/{products,plans}/bulk` | eliminaba definitivamente | elimina (soft delete), mismas reglas que el `DELETE` individual | — | Un registro eliminado ya no aparece en ningún `GET` — ni con filtro de estado. Para seguir consultándolo, archívalo en lugar de eliminarlo. * **Endpoints que cambiaron de método** — mismo cuerpo JSON, misma respuesta; el endpoint anterior dejó de existir: | Antes | Ahora | | ------------------------------------------------------------------------ | ------------------------------------------------ | | `POST /v1/nfes/bulk-delete` | `DELETE /v1/nfes/bulk` | | `POST /v1/plans/bulk-delete` | `DELETE /v1/plans/bulk` | | `POST /v1/products/bulk-delete` | `DELETE /v1/products/bulk` | | `POST /v1/proposals/bulk-delete` | `DELETE /v1/proposals/bulk` | | `DELETE /v1/product_groups/{id}/archive` (desarchivar) | `POST /v1/product_groups/{id}/unarchive` | | `DELETE /v1/subscription_item_changes/{id}` (cancelar cambio programado) | `POST /v1/subscription_item_changes/{id}/cancel` | | ::: | | ### Token solo con nivel de acceso[​](#token-solo-con-nivel-de-acceso "Enlace directo al Token solo con nivel de acceso") Un token sin ningún scope `billing/…` (el de una integración REST) se lee solo por los **niveles de acceso** que lleva, y valen en todos los recursos: `read write` lee y escribe todo, y no elimina nada. ### Token con scopes de recurso[​](#token-con-scopes-de-recurso "Enlace directo al Token con scopes de recurso") Un token que lleva scopes `billing/…` (el token personal creado en el asistente de la Cuenta Kobana, o el de un cliente MCP) tiene **dos ejes ortogonales**: el **recurso**, siempre con el prefijo de la app (`billing/subscriptions`), y el **nivel**, un scope global sin prefijo (`write`, `delete`, `import`, `export`). **Los recursos definen el alcance, y los niveles solo valen dentro de él.** Leer exige el recurso; cualquier otra cosa exige el recurso *y* el nivel. | Grupo | Scopes de recurso | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Clientes y acceso | `billing/customers`, `billing/companies`, `billing/portal_users`, `billing/dashboard_users`, `billing/team_roles` | | Catálogo | `billing/plans`, `billing/plan_groups`, `billing/products`, `billing/product_groups`, `billing/service_items` | | Suscripciones | `billing/subscriptions`, `billing/subscription_changes`, `billing/subscription_item_changes`, `billing/plan_changes` | | Facturación | `billing/invoices`, `billing/payments`, `billing/payment_methods`, `billing/credits`, `billing/coupons` | | Fiscal | `billing/nfes`, `billing/tax_rules`, `billing/tax_periods`, `billing/withholdings`, `billing/certificates` | | Propuestas | `billing/proposals`, `billing/proposal_templates` | | Cuenta y consumo | `billing/organization`, `billing/billing_accounts`, `billing/usage` | | **Comodín del recurso** | `billing/all` — alcanza **todos** los recursos, incluidos los que no están en la lista, y **no concede ningún nivel** | | **Niveles globales** | `write` (`POST`, `PUT`, `PATCH`), `delete` (`DELETE`), `import` (importación masiva), `export` (exportación masiva) — valen en los recursos que el token alcanza; `all` concede todos | Tres ejemplos: `billing/invoices` lee facturas y no escribe; `billing/invoices write` también crea, modifica y cancela, y sigue sin eliminar ni alcanzar suscripciones; `billing/products write delete` mantiene el catálogo de productos, incluida la eliminación en lote. Las cuentas bancarias, bancos, claves Pix, feriados, políticas de multa y compras de crédito (`/bank_accounts`, `/banks`, `/pix_keys`, `/holidays`, `/late_fee_policies`, `/credit_purchases`) no tienen scope de recurso propio: un token con scopes de recurso solo las alcanza con `billing/all`. La forma granular `billing/invoices:write` es una **excepción** de la gramática, no el formato estándar: satisface los dos ejes solo para ese recurso, y existe para "lee un recurso, escribe otro". `billing/*` es un comodín de **registro** y nunca se emite en un token — la comparación aquí es siempre literal. Un token que no trae ningún scope que esta API reconozca — ni nivel de acceso, ni `billing/…` — no alcanza nada más allá de `GET /v1/me`. ### Scope insuficiente[​](#scope-insuficiente "Enlace directo al Scope insuficiente") La falta de scope responde `403 insufficient_scope`, con los niveles que habrían bastado y los scopes que lleva el token: ``` HTTP/1.1 403 Forbidden Content-Type: application/json; charset=utf-8 { "error": { "code": "insufficient_scope", "message": "This token was not granted delete access. Authorize again with delete access to delete data.", "details": { "required": ["delete", "all"], "granted": ["read", "write"] } } } ``` `GET /v1/me` responde a cualquier token válido, sea cual sea el scope — es la forma de comprobar el token que tienes. ## 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 (CRM, ERP, frontend, etc.) — facilita cambiar uno sin tumbar los demás, y la auditoría por `jti` queda legible. * Solicita los scopes mínimos necesarios (principio del menor privilegio) — recurso sin verbo cuando la integración solo lee. * Prefiere tokens de vida corta: esta API no consulta lista de revocación, así que un token filtrado vale hasta su `exp`. Cambia la credencial en la Cuenta Kobana en cuanto sepas de la filtración. * HTTPS obligatorio — las llamadas por HTTP se rechazan. --- # Retención de Datos Esta página describe por cuánto tiempo se conserva cada tipo de dato en Facturación Automática. ## Clientes Activos[​](#clientes-activos "Enlace directo al Clientes Activos") Tiempo de conservación para Organizaciones con suscripciones activas y pagos al día. | Tipo de dato | Tiempo (en meses) | | --------------------------- | ----------------- | | Eventos | 12 | | Entregas de Webhooks | 12 | | Envíos de E-mails | 12 | | Envíos de SMS | 12 | | Logs de Auditoría | 12 | | Requests de la API | 3 | | Facturas | Indefinidamente | | Pagos | Indefinidamente | | Suscripciones | Indefinidamente | | Planes y Productos | Indefinidamente | | Clientes (Billing Accounts) | Indefinidamente | | NF-e emitidas | Indefinidamente | | Cupones y Créditos | Indefinidamente | | Cualquier dato no listado | Indefinidamente | ## Clientes Inactivos[​](#clientes-inactivos "Enlace directo al Clientes Inactivos") Tiempo de conservación para Organizaciones con suscripciones canceladas o suspendidas, o cuentas morosas por encima del período de tolerancia. | Tipo de dato | Tiempo (en meses) | | ------------------------------ | ---------------------- | | Eventos | 1 | | Entregas de Webhooks | 1 | | Envíos de E-mails | 1 | | Envíos de SMS | 1 | | Logs de Auditoría | 3 | | Facturas | 3 | | Pagos | 3 | | Suscripciones | 3 | | Planes y Productos | 3 | | Clientes (Billing Accounts) | 3 | | NF-e emitidas | 60 (obligación fiscal) | | Cupones y Créditos | 3 | | Cualquier otro dato no listado | 3 | La NF-e tiene una retención mínima de 5 años según la legislación fiscal brasileña, incluso después de que la Organización pase a estar inactiva. Los tiempos anteriores pueden modificarse en cualquier momento. ## Sandbox[​](#sandbox "Enlace directo al Sandbox") Los datos en Sandbox pueden eliminarse en cualquier momento sin previo aviso. No dependas del Sandbox para la conservación a largo plazo de datos de prueba. --- # Endpoints ## Plataforma (acceso web)[​](#plataforma-acceso-web "Enlace directo al Plataforma (acceso web)") | Ambiente | URL | | ---------- | ------------------------------------------- | | Sandbox | | | Producción | | ## API (v1)[​](#api-v1 "Enlace directo al API (v1)") | Ambiente | URL | | ---------- | ------------------------------------------- | | Sandbox | | | Producción | | ## Documentación[​](#documentación "Enlace directo al Documentación") | Ambiente | URL | | ------------- | ------------------------------------ | | Documentación | | --- # 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 suscripción que falla por un error de red puede reintentarse con la misma clave, garantizando que solo se cree una suscripción. ## Cómo usarlo[​](#cómo-usarlo "Enlace directo al Cómo usarlo") Envía la cabecera `X-Idempotency-Key: ` en cualquier solicitud `POST`, `PUT` o `PATCH`. La clave es opaca y la generas en tu lado. Recomendamos `UUID v4` u otra cadena aleatoria con entropía suficiente para evitar colisiones. ``` curl -i \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: 8c0f5d6e-3f8b-4cb5-9a47-d8f5b15e9b21' \ -H 'User-Agent: Kevin Mitnick ' \ -d '{ "subscription": { "billing_account_id": "ba_01HXY123", "plan_id": "plan_01HPRO", "billing_cycle": "monthly" } }' \ -X POST 'https://api.billing.sandbox.kobana.com.br/v1/subscriptions' ``` ## 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 de tu **organización**. Dos organizaciones distintas 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 cabeceras relevantes vinculados a la clave. 4. **Marca la clave como completada**. Cualquier nueva solicitud que reutilice la clave dentro de **24 horas** recibe la respuesta original verbatim — mismo `status_code`, mismo cuerpo, mismas cabeceras — más la cabecera `X-Idempotent-Replay: true` que indica que se trata de una reejecución. La capa guarda el resultado **independientemente de éxito o fracaso**. Los reintentos con la misma clave devuelven el mismo resultado, **incluyendo errores `5xx`**. ### 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. Tras expirar, una nueva solicitud con la misma clave genera un resultado nuevo. * Ámbito: por organización. Una clave usada en una organización no interfiere con otra. * Caracteres aceptados: cualquier cadena UTF-8 imprimible. ## Cuándo el resultado **no** se guarda[​](#cuándo-el-resultado-no-se-guarda "Enlace directo al cuándo-el-resultado-no-se-guarda") La capa solo guarda el resultado cuando el handler ha comenzado a ejecutarse. No se registra nada en los siguientes casos — es seguro reenviar la solicitud: * La clave está vacía o supera los **255 caracteres** → respuesta `400 bad_request`. * El parser del envoltorio de la API rechaza la solicitud antes del handler (JSON inválido, autenticación ausente, etc.). * El handler **lanza una excepción** durante la ejecución — la reserva se libera para que el siguiente reintento pueda correr limpio. * Otra solicitud con la misma clave está ejecutándose en paralelo → respuesta `409 conflict` con `details.reason = "idempotency_request_in_progress"`. ## 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 conflict` con `details.reason = "idempotency_key_reused"`. Esto protege contra reuso accidental — por ejemplo, persistir la clave junto a la operación en tu lado y luego intentar crear dos recursos diferentes con el mismo identificador. ### Respuesta de error[​](#respuesta-de-error "Enlace directo al Respuesta de error") ``` { "error": { "code": "conflict", "message": "X-Idempotency-Key was already used with different request parameters. Reuse the original parameters or generate a new key.", "details": { "reason": "idempotency_key_reused" } } } ``` ### Otras respuestas posibles[​](#otras-respuestas-posibles "Enlace directo al Otras respuestas posibles") | Escenario | Status | `error.code` | `details.reason` | | ---------------------------------------------- | ------ | ------------- | --------------------------------- | | Otra solicitud con la misma clave en ejecución | `409` | `conflict` | `idempotency_request_in_progress` | | Misma clave reutilizada con un cuerpo distinto | `409` | `conflict` | `idempotency_key_reused` | | Clave vacía o mayor que 255 caracteres | `400` | `bad_request` | `invalid_idempotency_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) | Enviar la clave en `GET` o `DELETE` no tiene efecto — la API procesa la solicitud normalmente sin registrar nada. ## Identificando una reejecución[​](#identificando-una-reejecución "Enlace directo al Identificando una reejecución") Toda respuesta servida desde el registro lleva la cabecera: ``` X-Idempotent-Replay: true ``` Puedes usar esta cabecera en tu lado para distinguir la primera ejecución de una reejecución hecha por el servidor. ## 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 conflict`. * **Persiste la clave junto al 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** ante `5xx` o timeout — la clave garantiza que el reintento no duplica el recurso. Como los fallos también se registran, puedes detener los reintentos en cuanto llegue el status code esperado. * **Descarta la clave a las 24 horas**. No tiene sentido mantenerla en tu lado después: el servidor ya ha descartado el registro. * **No envíes la clave en métodos que no la aceptan**. En `GET`/`DELETE` se ignora silenciosamente — preferimos que el cliente la omita para dejar claro qué es idempotente por contrato y qué depende de la clave. --- # Introducción Si eres dev, ¡diviértete! ✨ ## 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** | Número decimal en reales (BRL), con hasta 4 decimales. Ej.: `100.5` = R$ 100,50 | | **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 sustituirse en una URL. | | **`#{variable}`** | Nombre de variable que debe sustituirse 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 con cuerpo de respuesta. | | ✅ | **201 Created** | Recurso creado con éxito. | | ✅ | **204 No Content** | Solicitud exitosa, sin cuerpo de respuesta. | | ❌ | **400 Bad Request** | Solicitud inválida, en general contenido mal formado. | | ❌ | **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 accedida no existe. | | ❌ | **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). | ## ID de las Solicitudes (Request ID)[​](#id-de-las-solicitudes-request-id "Enlace directo al ID de las Solicitudes (Request ID)") Cada solicitud tiene un identificador asociado, disponible en el header `Request-Id` de la respuesta. Este valor ayuda en la depuración y la auditoría — las solicitudes y sus IDs pueden consultarse en el panel del sistema. El log de solicitudes está disponible por **30 días**. Al abrir un ticket de soporte sobre una solicitud específica, informa el `Request-Id` para acelerar la investigación. ## Seguridad[​](#seguridad "Enlace directo al Seguridad") La API de Kobana usa certificados **SSL de 2048 bits**. Toda solicitud debe hacerse por **HTTPS** — las llamadas al puerto 80 se redirigen al 443. Los clientes deben soportar `TLSv1.2` o `TLSv1.3` con una de las cifras: `TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES128-SHA256`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-RSA-CHACHA20-POLY1305`, `ECDHE-RSA-AES256-SHA384`. `TLSv1` y `TLSv1.1` no están soportados. ## Caché HTTP[​](#caché-http "Enlace directo al Caché HTTP") Usa los headers HTTP de caché para reducir la carga y ganar velocidad. La mayoría de las respuestas incluye `ETag` y/o `Last-Modified` — guarda esos valores y reenvíalos en las siguientes solicitudes mediante `If-None-Match` e `If-Modified-Since`. Si el recurso no cambió, 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 fallos en el servidor: **500 Internal Server Error** (aplicación no disponible), **502 Bad Gateway**, **503 Service Unavailable** y **504 Gateway Timeout** (fallos 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: . ## Valores monetarios[​](#valores-monetarios "Enlace directo al Valores monetarios") Todo valor monetario — en la solicitud y en la respuesta — es un número decimal en reales (BRL), con hasta 4 decimales. No hay campos en centavos: envía `100.5` para R$ 100,50 y `0.0125` para R$ 0,0125. Los campos de precios aceptan los 4 decimales; los demás se redondean a 2. ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Especificaciones](https://docs.billing.kobana.com.br/es/es/api/overview/openapi.md) — OpenAPI 3.1 en YAML para descargar. * [Endpoints](https://docs.billing.kobana.com.br/es/es/api/overview/endpoints.md) — URLs de Sandbox y Producción. * [User-Agent](https://docs.billing.kobana.com.br/es/es/api/overview/user-agent.md) — header recomendado para identificar tu aplicación. * [Límite de Solicitudes](https://docs.billing.kobana.com.br/es/es/api/overview/rate-limit.md) — throttling y headers de respuesta. * [Idempotencia](https://docs.billing.kobana.com.br/es/es/api/overview/idempotency.md) — `X-Idempotency-Key` para reintentos seguros. * [Webhooks](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks.md) — eventos disparados en tiempo real. * [Retención de Datos](https://docs.billing.kobana.com.br/es/es/api/overview/data-retention.md) — política de conservación por tipo de recurso. --- # OpenAPI Mantenemos públicamente los archivos de especificación de la API de Facturación Automática en formato abierto para que puedas descargarlos y usarlos 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.billing.kobana.com.br/es/es/assets/files/openapi-v1-pt-c96fdd39d7e5abca6e9821296fdaf848.yaml) | | v1 | English | [openapi-v1-en.yaml](https://docs.billing.kobana.com.br/es/es/assets/files/openapi-v1-en-62097be868d8fc203d6bd3082589d316.yaml) | | v1 | Español | [openapi-v1-es.yaml](https://docs.billing.kobana.com.br/es/es/assets/files/openapi-v1-es-4e3188d5390aab00d50f977b7fc5600a.yaml) | ## Colección de Postman[​](#colección-de-postman "Enlace directo al Colección de Postman") También disponible como colección lista para importar en Postman. Detalles y archivos en [Postman](https://docs.billing.kobana.com.br/es/es/api/overview/postman.md). --- # Listado y Paginación Todos los endpoints `GET` que devuelven colecciones (`/v1/customers`, `/v1/subscriptions`, `/v1/invoices`, etc.) usan paginación por **número de página**. ## Parámetros[​](#parámetros "Enlace directo al Parámetros") Se envían por query string: | Parámetro | Tipo | Default | Descripción | | ------------ | -------------- | ---------------------- | -------------------------------------------------------------------- | | `page` | entero ≥ 1 | `1` | Página solicitada (empieza en 1). | | `per_page` | entero 1–100 | `20` | Cantidad de ítems por página. Máximo **100**. | | `sort_by` | string | varía según el recurso | Campo usado para ordenar. Acepta los mismos nombres de la respuesta. | | `sort_order` | `asc` o `desc` | `desc` | Dirección del orden. | Los valores fuera de los límites se ajustan (ej.: `per_page=999` pasa a `100`; `page=0` pasa a `1`). ## Respuesta[​](#respuesta "Enlace directo al Respuesta") Todo listado sigue este envelope: ``` { "data": [ { "id": "per_01HPER", "name": "João Silva", "email": "joao@example.com" } ], "meta": { "total": 142, "page": 1, "per_page": 20, "total_pages": 8 } } ``` | Campo | Descripción | | ------------------ | --------------------------------------------------------------- | | `data` | Array con los ítems de la página actual. | | `meta.total` | Total de ítems que cumplen los filtros (no solo los devueltos). | | `meta.page` | Página actual. | | `meta.per_page` | Ítems por página efectivamente aplicados. | | `meta.total_pages` | Número total de páginas (`ceil(total / per_page)`). | La última página puede contener menos de `per_page` ítems. Cuando `page > total_pages`, `data` viene vacío (no es un error). ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") ### Primera página, por defecto[​](#primera-página-por-defecto "Enlace directo al Primera página, por defecto") ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ 'https://api.billing.sandbox.kobana.com.br/v1/customers' ``` ### Página 3 con 50 ítems[​](#página-3-con-50-ítems "Enlace directo al Página 3 con 50 ítems") ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ 'https://api.billing.sandbox.kobana.com.br/v1/customers?page=3&per_page=50' ``` ### Ordenado por `name` ascendente[​](#ordenado-por-name-ascendente "Enlace directo al ordenado-por-name-ascendente") ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ 'https://api.billing.sandbox.kobana.com.br/v1/customers?sort_by=name&sort_order=asc' ``` ### Filtros + paginación[​](#filtros--paginación "Enlace directo al Filtros + paginación") Los filtros específicos del recurso conviven con `page`/`per_page`: ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ 'https://api.billing.sandbox.kobana.com.br/v1/customers?search=joao&page=2&per_page=25' ``` ## 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 page = 1; while (true) { const res = await fetch(`${url}?page=${page}&per_page=100`, { headers: { Authorization: `Bearer ${token}` }, }); const { data, meta } = await res.json(); out.push(...data); if (page >= meta.total_pages) break; page += 1; } return out; } ``` ## Buenas prácticas[​](#buenas-prácticas "Enlace directo al Buenas prácticas") * Para sincronización incremental, prefiere filtrar por `updated_at_gte` (o similar disponible en el endpoint) en lugar de recorrer todas las páginas. * `per_page=100` minimiza el número de solicitudes y consume menos del [límite de solicitudes](https://docs.billing.kobana.com.br/es/es/api/overview/rate-limit.md). * Haz **caché** de `meta.total` al renderizar paginadores; no lo recalcules en cada navegación. * Evita asumir un orden estable sin un `sort_by` explícito — el orden por defecto puede cambiar entre recursos. --- # Postman Si prefiere probar la API mediante Postman, descargue la colección en el idioma de su elección e impórtela — o abra 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 Facturación Automática están publicadas en el workspace [**universokobana/kobana-billing-api**](https://www.postman.com/universokobana/kobana-billing-api/overview), con una colección por idioma. [![Workspace Kobana Billing API en Postman](/es/assets/images/postman-workspace-kobana-billing-api-90ee622934c0c69710b5d26a95ef41c5.png)](https://www.postman.com/universokobana/kobana-billing-api/overview) ## Colección[​](#colección "Enlace directo al Colección") Ábrala directamente en Postman (web o app): [**API de Facturación Automática (v1.0.0) — Español**](https://www.postman.com/universokobana/kobana-billing-api/collection/9nekylk/api-de-facturacin-automatizada-v1-0-0-espaol). ## Colecciones descargables[​](#colecciones-descargables "Enlace directo al Colecciones descargables") ¿Prefiere importarla localmente? Descargue el archivo `.json`: | Versión | Idioma | Archivo | | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | v1 | Português | [postman-v1-pt.json](https://docs.billing.kobana.com.br/es/es/assets/files/postman-v1-pt-237ab7a2a047fb07c78b74c423d5230a.json) | | v1 | English | [postman-v1-en.json](https://docs.billing.kobana.com.br/es/es/assets/files/postman-v1-en-68ac75a8e45a054be700f9028be4bf62.json) | | v1 | Español | [postman-v1-es.json](https://docs.billing.kobana.com.br/es/es/assets/files/postman-v1-es-a877a62f36fd3e5dd48fe2d3b6976c8d.json) | ## Uso[​](#uso "Enlace directo al Uso") 1. Importe el archivo `.json` descargado en Postman (**File → Import**) — o abra la [colección online](#colecci%C3%B3n) directamente. 2. Abra la pestaña **Variables** de la colección y rellene: * `baseUrl` — producción o sandbox (`https://api.billing.sandbox.kobana.com.br`). * `bearerToken` — su JWT, generado en **Integraciones → API Kobana → Token de API**. 3. La autenticación `Bearer` ya viene configurada a nivel de colección, apuntando a `{{bearerToken}}`. 4. Abra cualquier request, ajuste los parámetros si es necesario y haga clic en **Send**. --- # Límite de Solicitudes Cuando un cliente excede el límite asociado a él, las solicitudes siguientes se bloquean. El servidor responde con información sobre los límites utilizados y el tiempo de espera necesario para enviar una nueva solicitud, adjuntas a los headers de la respuesta: | Header | Ejemplo | Descripción | | --------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `ratelimit-limit` | `60` | Límite de solicitudes para el cliente. | | `ratelimit-name` | `throttle_authenticated_web` | Nombre del throttle utilizado. | | `ratelimit-remaining` | `0` | Número de solicitudes disponibles. | | `ratelimit-reset` | `1609844400` | [Unix time](https://en.wikipedia.org/wiki/Unix_time) — cuándo se reinicia el conteo. | | `retry-after` | `30` | Segundos hasta que se reinicie el conteo. Ver [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). | Existen dos tipos de límites: solicitudes `GET` y solicitudes `POST`. En ambos casos el conteo se hace por **hora**. Límites máximos: * **60 solicitudes/hora** para `GET` * **1000 solicitudes/hora** para `POST` Si tu operación necesita un número mayor, habla con soporte o con el área comercial. El conteo se reinicia en el primer minuto de cada hora. En cada solicitud, el servidor devuelve `ratelimit-limit` y `ratelimit-remaining`. ### Ejemplo de respuesta exitosa[​](#ejemplo-de-respuesta-exitosa "Enlace directo al Ejemplo de respuesta exitosa") ``` Date: Fri, 05 Nov 2010 12:00:00 GMT Content-Type: application/json; charset=utf-8 ratelimit-limit: 1000 ratelimit-remaining: 486 ``` ### Ejemplo de respuesta con bloqueo[​](#ejemplo-de-respuesta-con-bloqueo "Enlace directo al Ejemplo de respuesta con 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 siguiente solicitud. ``` HTTP/1.1 429 Too Many Requests Date: Fri, 05 Nov 2010 12:00:00 GMT Content-Type: application/json; charset=utf-8 ratelimit-limit: 1000 ratelimit-remaining: 0 ratelimit-reset: 3600 ratelimit-name: throttle_authenticated_web retry-after: 3600 {"error": "Limite de requisições POST por hora excedido para esse usuário."} ``` Referência: --- # User-Agent Puedes incluir el header `User-Agent` con el nombre de tu aplicación y una dirección de e-mail válida, para que podamos contactarte en caso de que: 1. Estés haciendo algo incorrecto, y podamos avisarte antes de bloquear; 2. Estés haciendo algo muy interesante, y podamos felicitarte 🙂 Ejemplo: ``` User-Agent: Meu Nome (meunome@example.com) ``` Ejemplo de cómo pasar este header usando cURL: ``` curl -i \ -H "Authorization: Bearer <>" \ -H 'Content-Type: application/json' \ -H 'User-Agent: Meu Nome (meunome@example.com)' \ -X GET 'https://api.billing.sandbox.kobana.com.br/v1/me' ``` Este header es **opcional** en todas las solicitudes, pero se recomienda. --- # Webhooks Los webhooks son notificaciones HTTP enviadas por la API de Facturación Automática siempre que ocurre un evento relevante en tu Organización — suscripción creada, factura pagada, NF-e emitida, etc. En lugar de hacer polling, registras un **endpoint HTTP público** y recibes un `POST` con el payload del evento en cuanto ocurre. ## Registro[​](#registro "Enlace directo al Registro") Gestiona los endpoints en **Dashboard → Configuración → API → Webhooks**. Cada endpoint tiene: * **URL** — destino HTTPS público de tu servidor. * **Eventos suscritos** — lista de los `event types` que deseas recibir. Si está vacía, recibes todos. * **Estado** — `active` o `inactive`. * **Secret** — cadena secreta usada para firmar cada entrega (HMAC-SHA256). Se genera automáticamente; puede rotarse. * **Auth headers** — opcionalmente, headers adicionales (Basic, Bearer, personalizados) inyectados en cada request. ## Entrega[​](#entrega "Enlace directo al Entrega") Cada evento dispara una request `POST` a la URL registrada: ``` POST /seu-endpoint HTTP/1.1 Content-Type: application/json User-Agent: Kobana-Webhooks/1.0 X-Kobana-App: billing X-Kobana-Environment: production X-Kobana-Webhook-Id: 7c1e9d2a-3b4f-4c5d-8e6f-0a1b2c3d4e5f X-Kobana-Event: invoice.paid X-Kobana-Event-Id: 3d1f0c9a-5b2e-4c7d-9e1f-8a6b4c2d0e9f X-Kobana-Delivery-Id: 9b2e4a10-7c3f-4d8e-a1b2-c3d4e5f60718 X-Kobana-Timestamp: 1753272000 X-Kobana-Signature: v1,MEUCIQD3… webhook-id: 9b2e4a10-7c3f-4d8e-a1b2-c3d4e5f60718 webhook-timestamp: 1753272000 webhook-signature: v1,MEUCIQD3… {...payload JSON, em snake_case...} ``` Los headers se describen en [Headers y firma](#headers-y-firma-est%C3%A1ndar-kobana), más abajo. ### Éxito[​](#éxito "Enlace directo al Éxito") Cualquier respuesta `2xx` en un máximo de **30 segundos** marca la entrega como exitosa. Cualquier otra cosa (timeout, `4xx`, `5xx`) se trata como fallo. ### Reintentos[​](#reintentos "Enlace directo al Reintentos") Los fallos se reentregan con backoff exponencial: | Intento | Retraso | | ------- | --------- | | 1 | inmediato | | 2 | +1 min | | 3 | +5 min | | 4 | +30 min | | 5 | +2 h | | 6 | +6 h | | 7 | +24 h | Tras **7 intentos**, la entrega se marca como `failed` de forma permanente. Los eventos huérfanos quedan disponibles en el dashboard para reenvío manual. ## Headers y firma (estándar Kobana)[​](#headers-y-firma-estándar-kobana "Enlace directo al Headers y firma (estándar Kobana)") Toda entrega es un `POST` con `Content-Type: application/json` y los headers de abajo — **los mismos en todos los productos Kobana**, así un único receptor atiende varios productos y ambientes y enruta con seguridad: | Header | Valor | | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `X-Kobana-App` | `billing` — el producto Kobana que envió la entrega. | | `X-Kobana-Environment` | `development`, `sandbox` o `production`. Nunca dejes que una entrega `sandbox` toque datos de producción. | | `X-Kobana-Webhook-Id` | Id del endpoint registrado al que pertenece la entrega. | | `X-Kobana-Event` | Slug del evento (ej.: `invoice.paid`). | | `X-Kobana-Event-Id` | Id del evento. Los reintentos del mismo evento lo repiten — úsalo para deduplicar. | | `X-Kobana-Delivery-Id` | Id único de este intento de entrega. Forma parte del contenido firmado. | | `X-Kobana-Timestamp` | Unix time (segundos) en que se firmó la entrega. Forma parte del contenido firmado. | | `X-Kobana-Signature` | `v1,` — uno o más tokens separados por espacio. | | `webhook-id`, `webhook-timestamp`, `webhook-signature` | Los mismos tres valores, en el layout [Standard Webhooks](https://www.standardwebhooks.com) — verificables con una biblioteca estándar. | Los headers legados `X-Signature` (`t=,v1=` sobre `"{t}.{body}"`), `X-Delivery-Id`, `X-Event-Id`, `X-Event-Type`, `X-Timestamp`, `X-App` y `X-Environment` se siguen enviando, **deprecados**, para integraciones existentes. Migra a los `X-Kobana-*`: se eliminarán en una próxima versión del contrato. ### Cómo se calcula la firma[​](#cómo-se-calcula-la-firma "Enlace directo al Cómo se calcula la firma") ``` clave = base64_decode(secret sin el prefijo "whsec_") contenido = delivery_id + "." + timestamp + "." + body_crudo firma = "v1," + base64(HMAC_SHA256(clave, contenido)) ``` * `body_crudo` es el cuerpo de la request **exactamente como se recibió**, byte a byte. No lo parsees y re-serialices: el orden de claves, espacios o escapes cambiarían y la firma dejaría de coincidir. * Atar el `delivery_id` al contenido firmado impide que una request capturada se reenvíe con otro id para saltarse tu deduplicación; el timestamp limita el replay en el tiempo. * El secret tiene la forma `whsec_` + base64 de 32 bytes aleatorios y se muestra **una sola vez**. Los secrets antiguos (sin prefijo, o con hexadecimal tras él) siguen siendo válidos: la clave es el base64 decodificado tras el prefijo, o los bytes UTF-8 del secret cuando no hay prefijo. * Durante una rotación de secret el header lleva un token por cada secret aún válido (`v1,AAA… v1,BBB…`). La entrega es válida si **cualquier** token coincide con **cualquier** secret que tengas. ### Verificando una entrega[​](#verificando-una-entrega "Enlace directo al Verificando una entrega") 1. Lee `webhook-id`, `webhook-timestamp` y `webhook-signature` (o los equivalentes `X-Kobana-*`). Rechaza la request si falta alguno. 2. Rechaza si `|ahora − timestamp| > 300` segundos: cinco minutos absorben la desviación de reloj y limitan los replays. 3. Arma el contenido firmado con el body crudo y calcula el HMAC esperado para cada secret en el que confíes. 4. Compara con cada token `v1,` en **tiempo constante** — nunca con `==`, que devuelve en el primer byte distinto y filtra el digest por timing. 5. Deduplica por `X-Kobana-Event-Id` para procesar cada evento una vez, o por `webhook-id` para registrar cada intento. 6. Responde `2xx` rápido y haz el trabajo pesado de forma asíncrona. Cualquier otra respuesta entra en el ciclo de reintentos. ``` const crypto = require('node:crypto'); /** * @param headers headers de la request, con nombres en minúsculas * @param rawBody body crudo (string o Buffer), ANTES de cualquier JSON.parse * @param secrets secret actual (y el anterior, durante una rotación) */ function verifyKobanaWebhook(headers, rawBody, secrets) { const id = headers['webhook-id']; const timestamp = headers['webhook-timestamp']; const signature = headers['webhook-signature']; if (!id || !timestamp || !signature) throw new Error('missing signature headers'); if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) throw new Error('timestamp out of tolerance'); const content = `${id}.${timestamp}.${rawBody}`; const received = signature.split(' ').filter((t) => t.startsWith('v1,')).map((t) => Buffer.from(t.slice(3), 'base64')); for (const secret of [].concat(secrets)) { const key = secret.startsWith('whsec_') ? Buffer.from(secret.slice(6), 'base64') : Buffer.from(secret, 'utf8'); const expected = crypto.createHmac('sha256', key).update(content).digest(); if (received.some((r) => r.length === expected.length && crypto.timingSafeEqual(r, expected))) return true; } throw new Error('no matching signature'); } ``` ``` import base64, hashlib, hmac, time def verify_kobana_webhook(headers, raw_body: bytes, secrets) -> bool: msg_id = headers.get("webhook-id") timestamp = headers.get("webhook-timestamp") signature = headers.get("webhook-signature") if not (msg_id and timestamp and signature): raise ValueError("missing signature headers") if abs(time.time() - int(timestamp)) > 300: raise ValueError("timestamp out of tolerance") content = f"{msg_id}.{timestamp}.".encode() + raw_body received = [base64.b64decode(t[3:]) for t in signature.split(" ") if t.startswith("v1,")] for secret in ([secrets] if isinstance(secrets, str) else secrets): key = base64.b64decode(secret[6:]) if secret.startswith("whsec_") else secret.encode() expected = hmac.new(key, content, hashlib.sha256).digest() if any(hmac.compare_digest(r, expected) for r in received): return True raise ValueError("no matching signature") ``` Con Express, conserva el body crudo montando `express.raw({ type: 'application/json' })` en la ruta del webhook (no `express.json()`), verifica y solo entonces haz `JSON.parse`. Con Django/Flask usa `request.body`/`request.get_data()` — nunca el objeto ya parseado. ## Estructura del payload[​](#estructura-del-payload "Enlace directo al Estructura del payload") Todos los eventos comparten el mismo envelope: ``` { "id": "evt_01HXYZABC123", "type": "subscription.status_changed", "created_at": "2026-05-20T12:00:00.000Z", "environment": "production", "version": "2026-03-01", "data": { /* recurso completo */ }, "changes": { /* opcional, mudanças desde o estado anterior */ } } ``` | Campo | Descripción | | ------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `id` | ID único del evento. | | `type` | Tipo del evento (ej.: `invoice.paid`). | | `created_at` | Timestamp ISO 8601 (UTC) del momento en que se generó el evento. | | `environment` | `production` o `sandbox`. | | `version` | Versión del schema del payload (string `YYYY-MM-DD`). | | `data` | El recurso completo en su estado actual. | | `changes` | Para eventos `*.updated` y `*.status_changed`, mapa `campo: {from, to}`. Puede estar ausente en eventos de creación/eliminación. | ## Ejemplos de payload por evento[​](#ejemplos-de-payload-por-evento "Enlace directo al Ejemplos de payload por evento") Consulta los ejemplos completos navegando por las páginas de abajo: * [`customer.db.created`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/customer-created.md) * [`company.db.updated`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/company-updated.md) * [`billing_account.suspended`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/billing-account-suspended.md) * [`subscription.status_changed`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/subscription-status-changed.md) * [`invoice.paid`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/invoice-paid.md) * [`payment.succeeded`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/payment-succeeded.md) * [`payment_method.expired`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/payment-method-expired.md) * [`nfe.issued`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/nfe-issued.md) * [`credit.applied`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/credit-applied.md) * [`proposal.accepted`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/proposal-accepted.md) * [`plan.db.updated`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/plan-updated.md) * [`product.archived`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/product-archived.md) * [`coupon.redeemed`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/coupon-redeemed.md) * [`service_item.db.updated`](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks/service-item-updated.md) ## Buenas prácticas[​](#buenas-prácticas "Enlace directo al Buenas prácticas") * **Idempotencia**: usa `X-Event-Id` para evitar procesar duplicados en caso de reintento. * **Respuesta rápida**: responde `2xx` en un máximo de 30 s. Encola el trabajo pesado en una cola asíncrona. * **Versionado**: el campo `version` indica el schema. Trata los campos nuevos como aditivos. * **Validación obligatoria**: valida siempre la firma antes de confiar en el payload. * **HTTPS**: usa TLS en el endpoint. Los endpoints HTTP se rechazan en producción. * **Lista de eventos**: prefiere suscribirte solo a los eventos que procesas, no a `*`. --- # `billing_account.suspended` Se dispara cuando una BillingAccount se suspende por morosidad o por una acción manual del operador. **Grupo:** Customers ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZBA999", "type": "billing_account.suspended", "created_at": "2026-05-20T14:00:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "ba_01HXY123", "organization_id": "org_01HORG", "person_id": "per_01HPER", "external_id": "customer-42", "currency": "BRL", "billing_email": "cobranca@cliente.com.br", "payment_terms_days": 5, "auto_collection": true, "balance": -198.0, "allowed_negative_balance": 0.0, "status": "suspended", "suspended_at": "2026-05-20T14:00:00.000Z", "suspension_reason": "unpaid_invoices", "tax_exempt": false, "settings": {}, "created_at": "2026-01-15T10:00:00.000Z", "updated_at": "2026-05-20T14:00:00.000Z" } } ``` --- # `company.db.updated` Se dispara en cada actualización de cualquier campo de una empresa (Company). **Grupo:** Customers ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZCMP111", "type": "company.db.updated", "created_at": "2026-05-20T15:00:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "cmp_01HZZ987", "public_id": "cmp_kobana", "organization_id": "org_01HORG", "person_id": "per_01HCMPER", "parent_company_id": null, "is_default": true, "status": "active", "metadata": {}, "created_at": "2026-01-01T00:00:00.000Z", "updated_at": "2026-05-20T15:00:00.000Z", "deleted_at": null }, "changes": { "is_default": { "from": false, "to": true } } } ``` --- # `coupon.redeemed` Se dispara cuando un cupón se canjea en una suscripción o factura. **Grupo:** Catálogo ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZCPN666", "type": "coupon.redeemed", "created_at": "2026-05-20T19:00:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "cpn_01HCPN", "organization_id": "org_01HORG", "code": "WELCOME10", "name": "Boas-vindas 10%", "type": "percentage", "percent_off": 10, "amount_off": null, "currency": "BRL", "duration": "once", "duration_in_months": null, "max_redemptions": 1000, "times_redeemed": 142, "valid_from": "2026-01-01T00:00:00.000Z", "valid_until": "2026-12-31T23:59:59.000Z", "status": "active", "applies_to": "all_plans", "metadata": {}, "created_at": "2026-01-01T00:00:00.000Z", "updated_at": "2026-05-20T19:00:00.000Z" }, "redemption": { "id": "red_01HRED", "billing_account_id": "ba_01HXY123", "subscription_id": "sub_01HABCDEF", "invoice_id": "inv_01HINV", "discount": 9.9, "redeemed_at": "2026-05-20T19:00:00.000Z" } } ``` --- # `credit.applied` Se dispara cuando un crédito existente se aplica a una factura, reduciendo el monto adeudado. **Grupo:** Facturación ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZCRD444", "type": "credit.applied", "created_at": "2026-05-20T17:00:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "cre_01HCRE", "organization_id": "org_01HORG", "billing_account_id": "ba_01HXY123", "invoice_id": "inv_01HINV", "type": "manual", "status": "applied", "amount": 50.0, "balance": 0.0, "currency": "BRL", "reason": "goodwill", "description": "Crédito concedido por atraso na entrega", "expires_at": "2026-12-31T23:59:59.000Z", "applied_at": "2026-05-20T17:00:00.000Z", "metadata": {}, "created_at": "2026-05-10T10:00:00.000Z", "updated_at": "2026-05-20T17:00:00.000Z" } } ``` --- # `customer.db.created` Se dispara cuando un nuevo cliente (persona física o jurídica) se registra en la Organización. **Grupo:** Customers ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZCUS222", "type": "customer.db.created", "created_at": "2026-05-20T15:30:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "per_01HPER", "organization_id": "org_01HORG", "type": "individual", "name": "João Silva", "email": "joao@example.com", "document_type": "cpf", "document_number": "12345678900", "phone": "+5511999999999", "address": { "street": "Av. Paulista", "number": "1000", "city": "São Paulo", "state": "SP", "zip_code": "01310-000", "country": "BR" }, "metadata": {}, "created_at": "2026-05-20T15:30:00.000Z", "updated_at": "2026-05-20T15:30:00.000Z" } } ``` --- # `invoice.paid` Se dispara cuando una factura tiene su pago confirmado y su estado pasa a `paid`. **Grupo:** Facturación ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZINV456", "type": "invoice.paid", "created_at": "2026-05-20T12:05:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "inv_01HINV", "public_id": "inv_2a9c1f4e", "organization_id": "org_01HORG", "number": "INV-2026-0042", "billing_account_id": "ba_01HXY123", "billing_account_public_id": "8f2b1c04-9d3e-4a71-bc55-1f0a2d6e7b48", "company_id": "cmp_01HZZ987", "subscription_id": "sub_01HABCDEF", "status": "paid", "collection_method": "charge_automatically", "currency": "BRL", "subtotal": 99.0, "discount": 0.0, "tax": 0.0, "total": 99.0, "amount_due": 99.0, "amount_paid": 99.0, "amount_remaining": 0.0, "period_start": "2026-05-01T00:00:00.000Z", "period_end": "2026-06-01T00:00:00.000Z", "due_date": "2026-05-05T00:00:00.000Z", "paid_at": "2026-05-20T12:05:00.000Z", "finalized_at": "2026-05-01T00:00:00.000Z", "billing_reason": "subscription_cycle", "hosted_invoice_url": "https://billing.kobana.com.br/invoices/inv_2a9c1f4e", "invoice_pdf_url": "https://billing.kobana.com.br/invoices/inv_2a9c1f4e.pdf", "payment_attempts": 1, "metadata": {}, "created_at": "2026-05-01T00:00:00.000Z", "updated_at": "2026-05-20T12:05:00.000Z", "line_items": [ { "id": "ili_01HLI001", "invoice_id": "inv_01HINV", "product_id": "prod_01HPROD", "product_slug": "plano-mensal", "type": "subscription", "description": "Plano Mensal", "quantity": 1, "unit_amount": 99.0, "amount": 99.0, "period_start": "2026-05-01T00:00:00.000Z", "period_end": "2026-06-01T00:00:00.000Z", "metadata": {} } ] } } ``` ## Identificando la cuenta y el producto[​](#identificando-la-cuenta-y-el-producto "Enlace directo al Identificando la cuenta y el producto") El payload trae **identificadores internos y públicos lado a lado**: | Campo | Úsalo cuando | | --------------------------- | ----------------------------------------------------------------------------------------------------------- | | `billing_account_id` | guardas el id interno de Kobana | | `billing_account_public_id` | identificas la cuenta por su **uid público** — el mismo que la API acepta para resolver una billing account | | `line_items[].product_id` | id interno del producto | | `line_items[].product_slug` | **slug** del producto, estable y legible — la forma recomendada de reconocer *qué* se compró | Un suscriptor externo normalmente enruta por `billing_account_public_id` y reconoce el producto por `product_slug`: son los dos valores que existen fuera de esta base. `product_slug` viene `null` cuando la relación del producto no estaba cargada en el momento de la emisión — `null` significa *"no lo sé"*, nunca *"otro producto"*. --- # `nfe.issued` Se dispara cuando la NF-e (factura electrónica brasileña) se emite con éxito en el proveedor fiscal integrado. **Grupo:** Facturación ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZNFE333", "type": "nfe.issued", "created_at": "2026-05-20T16:00:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "nfe_01HNFE", "organization_id": "org_01HORG", "company_id": "cmp_01HZZ987", "invoice_id": "inv_01HINV", "billing_account_id": "ba_01HXY123", "status": "issued", "provider": "nfeio", "nfe_type": "nfse", "series": "A", "number": "2026000042", "rps_number": "42", "rps_series": "RPS", "issue_date": "2026-05-20T16:00:00.000Z", "verification_code": "ABC123XYZ", "external_id": "nfeio_01HEXT", "pdf_url": "https://billing.kobana.com.br/nfes/nfe_01HNFE.pdf", "xml_url": "https://billing.kobana.com.br/nfes/nfe_01HNFE.xml", "amount": 99.0, "tax": 4.95, "service_code": "01.01", "cnae_code": "6201500", "description": "Plataforma de cobrança recorrente", "metadata": {}, "created_at": "2026-05-20T15:59:30.000Z", "updated_at": "2026-05-20T16:00:00.000Z" } } ``` --- # `payment_method.expired` Se dispara cuando un método de pago expira (tarjeta vencida, mandato cancelado, etc.). **Grupo:** Facturación ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZPM321", "type": "payment_method.expired", "created_at": "2026-05-20T12:10:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "pm_01HPM", "organization_id": "org_01HORG", "billing_account_id": "ba_01HXY123", "credit_card_id": "cc_01HCC", "type": "card", "status": "expired", "is_default": true, "is_backup": false, "bank_account": null, "billing_details": { "name": "João Silva", "email": "joao@example.com" }, "created_at": "2026-01-15T10:00:00.000Z", "updated_at": "2026-05-20T12:10:00.000Z" } } ``` --- # `payment.succeeded` Se dispara cuando el gateway confirma un pago con estado `succeeded`. **Grupo:** Facturación ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZPAY789", "type": "payment.succeeded", "created_at": "2026-05-20T12:05:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "pay_01HPAY", "public_id": "pay_4b8e2c7a", "organization_id": "org_01HORG", "invoice_id": "inv_01HINV", "company_id": "cmp_01HZZ987", "payment_method_id": "pm_01HPM", "gateway_id": "gw_01HGW", "payment_method_type": "card", "amount": 99.0, "paid_amount": 99.0, "currency": "BRL", "status": "succeeded", "payment_gateway": "kobana", "gateway_payment_id": "kbn_charge_abc123", "failure_code": null, "failure_message": null, "paid_at": "2026-05-20T12:05:00.000Z", "metadata": {}, "created_at": "2026-05-20T12:04:55.000Z", "updated_at": "2026-05-20T12:05:00.000Z" } } ``` --- # `plan.db.updated` Se dispara en cada actualización de cualquier campo de un Plan. **Grupo:** Catálogo ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZPLAN555", "type": "plan.db.updated", "created_at": "2026-05-20T13:00:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "plan_01HPRO", "public_id": "plan_pro_monthly", "organization_id": "org_01HORG", "name": "Pro Mensal", "slug": "pro-monthly", "description": "Plano Pro com cobrança mensal", "status": "active", "plan_type": "recurring", "visibility": "public", "trial_period_days": 14, "default_billing_cycle": "monthly", "available_billing_cycles": [ "monthly", "annual" ], "features": [ "unlimited_invoices", "priority_support" ], "limits": { "users": 10 }, "metadata": {}, "created_at": "2026-01-01T00:00:00.000Z", "updated_at": "2026-05-20T13:00:00.000Z" }, "changes": { "description": { "from": "Plano Pro", "to": "Plano Pro com cobrança mensal" } } } ``` --- # `product.archived` Se dispara cuando un producto se archiva y se retira del catálogo activo. **Grupo:** Catálogo ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZPROD777", "type": "product.archived", "created_at": "2026-05-20T13:30:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "prod_01HPROD", "public_id": "prod_setup_fee", "organization_id": "org_01HORG", "company_id": "cmp_01HZZ987", "name": "Taxa de Setup", "slug": "setup-fee", "description": "Taxa única de configuração", "status": "archived", "visibility": "private", "product_type": "service", "unit_label": "unit", "increment": 1, "is_required": false, "metadata": {}, "created_at": "2026-01-10T00:00:00.000Z", "updated_at": "2026-05-20T13:30:00.000Z" } } ``` --- # `proposal.accepted` Se dispara cuando el cliente acepta una propuesta comercial enviada. **Grupo:** Comercial ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZPRO555", "type": "proposal.accepted", "created_at": "2026-05-20T18:00:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "prp_01HPROP", "public_id": "prp_a1b2c3d4", "organization_id": "org_01HORG", "company_id": "cmp_01HZZ987", "code": "P-ABCD1234", "title": "Proposta Pro Mensal", "description": null, "billing_account_id": "ba_01HXY123", "prospect_id": null, "coupon_id": null, "template_id": "tpl_01HTPL", "document_google_id": null, "document_url": "https://docs.google.com/document/d/abc123", "pdf_url": "https://billing.kobana.com.br/proposals/prp_a1b2c3d4.pdf", "generated_at": "2026-05-18T10:00:00.000Z", "pdf_outdated_at": null, "expires_at": "2026-06-20T23:59:59.000Z", "status": "accepted", "rejection_reason": null, "metadata": {}, "notes": null, "created_at": "2026-05-18T09:55:00.000Z", "updated_at": "2026-05-20T18:00:00.000Z", "sent_at": "2026-05-18T10:00:00.000Z", "viewed_at": "2026-05-19T14:30:00.000Z", "accepted_at": "2026-05-20T18:00:00.000Z", "rejected_at": null, "items": [ { "id": "pitem_01HITEM", "proposal_id": "prp_01HPROP", "product_id": "prod_01HPROD", "price_id": "price_01HPRC", "quantity": 1, "unit_amount": 99.0, "metadata": {}, "created_at": "2026-05-18T09:55:00.000Z", "updated_at": "2026-05-18T09:55:00.000Z" } ], "subscription_id": "sub_01HABCDEF", "invoice_id": "inv_01HINV" }, "changes": { "status": { "from": "viewed", "to": "accepted" } } } ``` --- # `service_item.db.updated` Se dispara en cada actualización de ítems de servicio (códigos CNAE, ISS, descripción fiscal). **Grupo:** Catálogo ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZSVC777", "type": "service_item.db.updated", "created_at": "2026-05-20T20:00:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "svc_01HSVC", "organization_id": "org_01HORG", "company_id": "cmp_01HZZ987", "code": "01.01", "description": "Análise e desenvolvimento de sistemas", "cnae": "6201500", "municipal_service_code": "0101", "federal_service_code": "01.01", "tax_rate": 5, "iss_withholding": false, "is_default": true, "status": "active", "metadata": {}, "created_at": "2026-01-15T10:00:00.000Z", "updated_at": "2026-05-20T20:00:00.000Z" }, "changes": { "tax_rate": { "from": 3, "to": 5 } } } ``` --- # `subscription.status_changed` Se dispara siempre que cambia el `status` de una suscripción (`active`, `trialing`, `past_due`, `paused`, `canceled`). **Grupo:** Facturación ## Payload[​](#payload "Enlace directo al Payload") ``` { "id": "evt_01HXYZABC123", "type": "subscription.status_changed", "created_at": "2026-05-20T12:00:00.000Z", "environment": "production", "version": "2026-03-01", "data": { "id": "sub_01HABCDEF", "public_id": "sub_8f3d2a1b", "organization_id": "org_01HORG", "billing_account_id": "ba_01HXY123", "company_id": "cmp_01HZZ987", "plan_id": "plan_01HPRO", "status": "active", "billing_cycle": "monthly", "billing_cycle_anchor": "2026-05-01T00:00:00.000Z", "current_period_start": "2026-05-01T00:00:00.000Z", "current_period_end": "2026-06-01T00:00:00.000Z", "trial_start": null, "trial_end": null, "activated_at": "2026-04-01T12:00:00.000Z", "cancel_at_period_end": false, "canceled_at": null, "cancellation_reason": null, "recurring_amount": 99.0, "collection_method": "charge_automatically", "proration_behavior": "create_prorations", "metadata": {}, "created_at": "2026-04-01T12:00:00.000Z", "updated_at": "2026-05-20T12:00:00.000Z", "items": [ { "id": "sitem_01HSITEM", "subscription_id": "sub_01HABCDEF", "product_id": "prod_01HPROD", "price_id": "price_01HPRC", "quantity": 1, "unit_amount": 99.0, "metadata": {}, "created_at": "2026-04-01T12:00:00.000Z", "updated_at": "2026-04-01T12:00:00.000Z" } ] }, "changes": { "status": { "from": "past_due", "to": "active" } } } ``` --- ## [📄️Ciclo de Vida de la Suscripción](https://docs.billing.kobana.com.br/es/es/assinaturas/ciclo-de-vida/.md) [Estados](https://docs.billing.kobana.com.br/es/es/assinaturas/ciclo-de-vida/.md) --- ## [📄️Ciclo de Vida de la Suscripción](https://docs.billing.kobana.com.br/es/es/assinaturas/ciclo-de-vida/.md) [Estados](https://docs.billing.kobana.com.br/es/es/assinaturas/ciclo-de-vida/.md) --- # Ciclo de Vida de la Suscripción ## Estados[​](#estados "Enlace directo al Estados") ``` draft → confirmed → trialing → active ↔ past_due → canceled ↕ paused ``` | Estado | Descripción | | ------------- | ----------------------------------------------------------- | | **draft** | Borrador. Puede editarse libremente antes de ser confirmada | | **confirmed** | Confirmada, esperando activación | | **trialing** | En período de prueba gratuito | | **active** | Activa, generando cobros recurrentes | | **past\_due** | Con pago atrasado | | **paused** | Pausada temporalmente (sin cobros) | | **canceled** | Cancelada (estado terminal) | ## Creación de una Suscripción[​](#creación-de-una-suscripción "Enlace directo al Creación de una Suscripción") Para crear una suscripción, informe: | Campo | Obligatorio | Descripción | | ----------------------- | ----------- | ---------------------------------------------------------- | | **Cuenta de cobro** | Sí | La cuenta del cliente que será cobrada | | **Plan** | No | Plan preconfigurado (o ítems sueltos) | | **Ciclo de cobro** | Sí | `monthly`, `quarterly`, `semiannual` o `annual` | | **Método de cobro** | Sí | `charge_automatically`, `manual_charge` o `manual_invoice` | | **Período de prueba** | No | 0 a 90 días de prueba gratuita | | **Código de descuento** | No | Descuento a aplicar | | **Ítems** | No | Productos, precios y cantidades (si no usa plan) | | **Empresa** | No | Empresa emisora (para multi-empresa) | ### Flujo de Creación[​](#flujo-de-creación "Enlace directo al Flujo de Creación") 1. La suscripción se crea con estado `draft` 2. Los ítems se crean a partir de los ítems proporcionados o de los ítems del plan 3. El uso del código de descuento se incrementa (si fue proporcionado) 4. Se emite un evento `subscription.db.created` ## Confirmación y Activación[​](#confirmación-y-activación "Enlace directo al Confirmación y Activación") ### Confirmar (`draft` → `confirmed`)[​](#confirmar-draft--confirmed "Enlace directo al confirmar-draft--confirmed") Confirma la suscripción, opcionalmente creando la primera factura. ### Activar (`draft`/`confirmed` → `trialing`/`active`)[​](#activar-draftconfirmed--trialingactive "Enlace directo al activar-draftconfirmed--trialingactive") * Si tiene período de prueba: el estado cambia a `trialing`, con `trial_start` y `trial_end` definidos * Si no tiene prueba: el estado cambia directamente a `active` * Define las fechas del período de cobro (`current_period_start`, `current_period_end`) ### Vista previa de la Activación[​](#vista-previa-de-la-activación "Enlace directo al Vista previa de la Activación") Antes de activar, es posible visualizar: * Fecha de inicio, si habrá prueba, duración de la prueba * Fechas del período de cobro * Fecha de la primera factura * Totales de setup y recurrentes ## Renovación[​](#renovación "Enlace directo al Renovación") La renovación es automática mediante un worker diario (00:00 UTC): 1. Busca suscripciones activas con `currentPeriodEnd ≤ ahora` 2. Si `cancelAtPeriodEnd = true`: cancela la suscripción 3. De lo contrario: avanza al siguiente período de cobro 4. Usa lock optimista para prevenir renovaciones duplicadas ### Cálculo de los Períodos[​](#cálculo-de-los-períodos "Enlace directo al Cálculo de los Períodos") | Ciclo | Duración | | ------------ | -------- | | `monthly` | +1 mes | | `quarterly` | +3 meses | | `semiannual` | +6 meses | | `annual` | +1 año | ## Cancelación[​](#cancelación "Enlace directo al Cancelación") ### Cancelar al Fin del Período (`cancelAtPeriodEnd: true`)[​](#cancelar-al-fin-del-período-cancelatperiodend-true "Enlace directo al cancelar-al-fin-del-período-cancelatperiodend-true") * Define la flag `cancel_at_period_end` * La suscripción continúa activa hasta el fin del período actual * En la renovación, el estado cambia a `canceled` * Puede revertirse antes de la fecha de cancelación ### Cancelar Inmediatamente (`cancelAtPeriodEnd: false`)[​](#cancelar-inmediatamente-cancelatperiodend-false "Enlace directo al cancelar-inmediatamente-cancelatperiodend-false") * El estado cambia a `canceled` inmediatamente * La fecha de cancelación se registra * El motivo de la cancelación se almacena ## Revertir a Confirmado[​](#revertir-a-confirmado "Enlace directo al Revertir a Confirmado") Las suscripciones activas pueden revertirse a `confirmed` para permitir la edición antes de reactivar. Útil para corregir errores antes de la próxima renovación. ## Eliminación[​](#eliminación "Enlace directo al Eliminación") Solo las suscripciones en `draft`, `confirmed` o `canceled` pueden eliminarse, y únicamente si no existen facturas con pagos. ## Cálculo del MRR[​](#cálculo-del-mrr "Enlace directo al Cálculo del MRR") El MRR (Monthly Recurring Revenue) se calcula normalizando el valor total a mensual: | Ciclo | Fórmula | | ------------ | ------------------ | | `monthly` | Total de los ítems | | `quarterly` | Total ÷ 3 | | `semiannual` | Total ÷ 6 | | `annual` | Total ÷ 12 | ## Eventos Emitidos[​](#eventos-emitidos "Enlace directo al Eventos Emitidos") | Evento | Cuándo | | ----------------------------------- | ---------------------------------------- | | `subscription.db.created` | Suscripción creada | | `subscription.confirmed` | Confirmada | | `subscription.activated` | Activada | | `subscription.renewed` | Renovada | | `subscription.paused` | Pausada | | `subscription.resumed` | Reanudada | | `subscription.canceled` | Cancelada | | `subscription.pending_cancellation` | Marcada para cancelar al fin del período | | `subscription.plan_changed` | Plan modificado | | `subscription_status_changed` | Cualquier cambio de estado | --- # Cambio de Plan (Upgrade/Downgrade) El sistema permite que los clientes cambien el plan de la suscripción con cálculo automático de proration (prorrateo proporcional). ## Tipos de Cambio[​](#tipos-de-cambio "Enlace directo al Tipos de Cambio") | Tipo | Descripción | | ------------- | ----------------------------------- | | **upgrade** | Nuevo plan más caro que el actual | | **downgrade** | Nuevo plan más barato que el actual | | **lateral** | Mismo valor (cambio de features) | ## Timing del Cambio[​](#timing-del-cambio "Enlace directo al Timing del Cambio") | Timing | Descripción | | ------------------- | ------------------------------------------------------------------- | | **immediate** | Se aplica inmediatamente, cobra/acredita la diferencia proporcional | | **end\_of\_period** | Programa el cambio para el inicio del próximo período | ## Proration (Prorrateo Proporcional)[​](#proration-prorrateo-proporcional "Enlace directo al Proration (Prorrateo Proporcional)") ### Métodos de Proration[​](#métodos-de-proration "Enlace directo al Métodos de Proration") | Método | Descripción | | ------------------- | ----------------------------------------------------------------- | | `full_proration` | Acredita el plan anterior y cobra el nuevo por el tiempo restante | | `partial_proration` | Cobra solo la diferencia (solo para upgrade) | | `no_proration` | Sin ajuste de valor a mitad del ciclo | ### Fórmula de Cálculo[​](#fórmula-de-cálculo "Enlace directo al Fórmula de Cálculo") ``` dias_restantes = max(0, techo((fin_período - ahora) / 86400000)) total_dias_período = techo((fin_período - inicio_período) / 86400000)) Full proration: crédito = (precio_anterior × dias_restantes) / total_dias_período cobro = (precio_nuevo × dias_restantes) / total_dias_período Partial proration (solo upgrade): diferencia = precio_nuevo - precio_anterior cobro = (diferencia × dias_restantes) / total_dias_período Cobro neto = cobro - crédito ``` ## Configuración Predeterminada[​](#configuración-predeterminada "Enlace directo al Configuración Predeterminada") La configuración de cambio de plan define el comportamiento predeterminado: | Configuración | Predeterminado | | ------------------------------ | ---------------- | | Permitir upgrade | Sí | | Permitir downgrade | Sí | | Proration en upgrade | `full_proration` | | Proration en downgrade | `no_proration` | | Timing del upgrade | `immediate` | | Timing del downgrade | `end_of_period` | | Reembolso en downgrade | No | | Crédito en downgrade | Sí | | Aplicar descuento en el cambio | Sí | ## Reglas de Cambio de Plan[​](#reglas-de-cambio-de-plan "Enlace directo al Reglas de Cambio de Plan") Es posible crear reglas específicas para controlar las transiciones entre planes: | Campo | Descripción | | ------------------------ | ------------------------------------ | | **Plan de origen** | Plan actual (null = cualquiera) | | **Plan de destino** | Nuevo plan (null = cualquiera) | | **Tipo de cambio** | upgrade, downgrade o lateral | | **Permitido** | Si la transición está permitida | | **Timing** | Sobrescribe el timing predeterminado | | **Método de proration** | Sobrescribe el método predeterminado | | **Descuento (%)** | Descuento porcentual en el cobro | | **Días de bonificación** | Extensión del período de prueba | | **Mensaje** | Razón si no está permitido | | **Prioridad** | Mayor prioridad prevalece | ### Orden de Prioridad de las Reglas[​](#orden-de-prioridad-de-las-reglas "Enlace directo al Orden de Prioridad de las Reglas") 1. Regla con plan de origen **Y** plan de destino (más específica) 2. Regla con solo plan de origen 3. Regla con solo plan de destino 4. Regla global (ambos null) ## Vista Previa del Cambio[​](#vista-previa-del-cambio "Enlace directo al Vista Previa del Cambio") Antes de ejecutar, es posible visualizar: * Si el cambio está permitido * Tipo (upgrade/downgrade/lateral) * Valores de crédito y cobro prorrateados * Cobro neto final * Fecha efectiva * Días restantes en el período ## Ejecución del Cambio[​](#ejecución-del-cambio "Enlace directo al Ejecución del Cambio") ### Cambio Inmediato[​](#cambio-inmediato "Enlace directo al Cambio Inmediato") 1. Se calculan la validación y la vista previa 2. Se crea el registro de PlanChange (estado: `pending`) 3. Se genera crédito si `prorationCreditSubcents > 0` 4. Se genera factura si `netChargeSubcents > 0` 5. La suscripción se actualiza con el nuevo plan 6. PlanChange se marca como `completed` ### Cambio Programado[​](#cambio-programado "Enlace directo al Cambio Programado") 1. Se crea el registro de PlanChange (estado: `scheduled`) 2. En la fecha efectiva, el worker procesa el cambio 3. La suscripción se actualiza con el nuevo plan 4. PlanChange se marca como `completed` > **Limitación**: El sistema mantiene solo **un cambio programado** a la vez. Un nuevo cambio programado cancela el anterior. ## Cancelar Cambio Programado[​](#cancelar-cambio-programado "Enlace directo al Cancelar Cambio Programado") Los cambios programados pueden cancelarse antes de la fecha efectiva. El estado cambia a `canceled` y el motivo se registra. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") La pantalla `/dashboard/plan-changes` presenta el historial de cambios de plan de la organización, con filtros por status, tipo (upgrade/downgrade/lateral), plan de origen y de destino. La pestaña de configuración centraliza el comportamiento predeterminado de proration y las reglas por par de planes. ![Historial y configuración de cambios de plan](/es/assets/images/mudancas-de-plano-ef5e550442456e2bc66300597ed624c9.png) --- # Cambios de Ítems de la Suscripción Además de los cambios de plan (upgrade/downgrade), Facturación Automática soporta **cambios en los ítems individuales** de una suscripción — modificar cantidades, agregar add-ons, cambiar un producto suelto o un ítem metered sin necesidad de cambiar el plan principal. La pantalla `/dashboard/subscription-changes` agrupa el historial de estos cambios y la configuración predeterminada de proration. ## Pestaña Historial[​](#pestaña-historial "Enlace directo al Pestaña Historial") Muestra todos los cambios de ítems registrados en la organización. Cada fila corresponde a un registro de `SubscriptionItemChange` y muestra: * **ID de la suscripción** afectada * **Status**: `pending`, `scheduled`, `completed`, `canceled` o `failed` * **Timing**: `immediate` (se aplica ahora) o `end_of_period` (se aplica en el próximo ciclo) * **Cambios**: ítems agregados, eliminados o modificados (con cantidad y precio) * **Crédito generado** (`proration_credit`) y **cobro generado** (`proration_charge`) * **Fecha efectiva** y **fecha de creación** Los cambios `completed` ya fueron procesados; los `scheduled` esperan a que el worker de renovación los ejecute en el cambio de ciclo. ## Pestaña Configuración[​](#pestaña-configuración "Enlace directo al Pestaña Configuración") Define el comportamiento predeterminado cuando un ítem se agrega, se elimina o cambia de cantidad: * **Permitir aumento de cantidad** y **permitir reducción** — controla quién puede cambiar qué. * **Timing predeterminado** — cuándo se aplica el cambio (inmediato o al final del período). * **Método de proration** — `full_proration`, `partial_proration` o `no_proration`. * **Crédito en reducción** — si genera saldo en la cuenta del cliente al reducir la cantidad. * **Reembolso en reducción** — si devuelve el valor vía gateway en lugar de generar crédito. La configuración se resuelve por organización y puede sobrescribirse con reglas específicas al momento del cambio vía API. ## Diferencia entre cambio de ítems y cambio de plan[​](#diferencia-entre-cambio-de-ítems-y-cambio-de-plan "Enlace directo al Diferencia entre cambio de ítems y cambio de plan") | Escenario | Pantalla | | --------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Cambiar de **Starter** a **Growth** | [Cambio de Plan](https://docs.billing.kobana.com.br/es/es/assinaturas/mudanca-de-plano/.md) | | Agregar 10 usuarios extra al plan actual | Cambios de Ítems | | Cambiar el add-on `Email Premium` por `SMS Premium` | Cambios de Ítems | | Reducir la cantidad de licencias al final del ciclo | Cambios de Ítems | Ambos flujos generan proration cuando corresponde, y ambos disparan eventos y webhooks (`subscription.updated`, `subscription_item.changed`). ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Historial y configuración de cambios de ítems de suscripción](/es/assets/images/mudancas-de-itens-39469e28ad8b942d4dbc034efc245cde.png) --- # Pausar Suscripción La funcionalidad de pausar suscripciones permite suspender temporalmente el cobro de un cliente sin cancelar la suscripción. Es una herramienta estratégica de retención. ## Beneficios[​](#beneficios "Enlace directo al Beneficios") * **Reducir churn**: Evita cancelaciones ofreciendo una alternativa temporal * **Mantener ingresos**: El servicio continúa activo por el período ya pagado * **Flexibilidad**: Atiende situaciones como vacaciones, restricciones presupuestarias o uso estacional * **Experiencia del cliente**: Demuestra compromiso con las necesidades del suscriptor ## Prerrequisitos[​](#prerrequisitos "Enlace directo al Prerrequisitos") Para pausar una suscripción, esta debe: * Estar con estado `active` o `past_due` * No puede ser una suscripción futura, en prueba o cancelada ## Comportamiento de la Pausa[​](#comportamiento-de-la-pausa "Enlace directo al Comportamiento de la Pausa") Al pausar una suscripción, se configura: | Campo | Descripción | | ------------------ | ---------------------------------------- | | **Behavior** | Cómo tratar las facturas pendientes | | **Reanudación en** | Fecha opcional de reanudación automática | ### Comportamiento para Facturas Pendientes[​](#comportamiento-para-facturas-pendientes "Enlace directo al Comportamiento para Facturas Pendientes") | Behavior | Descripción | | -------------------- | ---------------------------------------------- | | `mark_uncollectible` | Marca las facturas pendientes como incobrables | | `keep_as_draft` | Mantiene las facturas futuras como borrador | | `void` | Anula las facturas pendientes | ## Efectos de la Pausa[​](#efectos-de-la-pausa "Enlace directo al Efectos de la Pausa") * El estado cambia a `paused` * **No se genera ninguna factura** durante la pausa * **No se realiza ningún cobro** * El período actual no se modifica * **Los cupones siguen expirando** normalmente (no se pausan junto) * **MRR**: Contribución cero durante la pausa * **Analytics**: Las suscripciones pausadas cuentan como "activas" (no como churn) ## Reanudación[​](#reanudación "Enlace directo al Reanudación") ### Reanudación Manual[​](#reanudación-manual "Enlace directo al Reanudación Manual") 1. Acceda a la suscripción en el dashboard 2. Haga clic en "Reanudar" 3. El estado vuelve a `active` 4. El campo de pausa se limpia 5. Se inicia un nuevo ciclo de cobro ### Reanudación Automática[​](#reanudación-automática "Enlace directo al Reanudación Automática") Si se definió una fecha de reanudación (`pause_collection.resumes_at`), la suscripción se reanuda automáticamente en esa fecha. ## Eventos[​](#eventos "Enlace directo al Eventos") | Evento | Descripción | | ---------------------- | --------------------- | | `subscription.paused` | Suscripción pausada | | `subscription.resumed` | Suscripción reanudada | ## Consideraciones[​](#consideraciones "Enlace directo al Consideraciones") * Cada pausa debe completarse antes de iniciar otra * Los cambios en la suscripción durante la pausa cancelan la pausa programada * Cerrar la cuenta del cliente finaliza inmediatamente todas las suscripciones pausadas * Las suscripciones pausadas no aparecen en el listado de "pendientes de facturación" --- # Términos de Cobro Los términos de cobro definen cómo y cuándo se cobra al cliente por la suscripción. ## Ciclos de Cobro[​](#ciclos-de-cobro "Enlace directo al Ciclos de Cobro") | Ciclo | Frecuencia | Duración | | ------------ | ---------- | -------- | | `monthly` | Mensual | 1 mes | | `quarterly` | Trimestral | 3 meses | | `semiannual` | Semestral | 6 meses | | `annual` | Anual | 12 meses | ### Ancla de Cobro[​](#ancla-de-cobro "Enlace directo al Ancla de Cobro") Los períodos de cobro se calculan enteramente a partir de `current_period_start` y `current_period_end`, que avanzan en cada renovación. El día de cobro del ciclo vive en `cycle_billing_date`, definido al activar la suscripción. ### Período Actual[​](#período-actual "Enlace directo al Período Actual") * `current_period_start`: Inicio del período de cobro actual * `current_period_end`: Fin del período de cobro actual ## Métodos de Cobro[​](#métodos-de-cobro "Enlace directo al Métodos de Cobro") | Método | Generación de Factura | Cobro | | ---------------------- | --------------------- | ---------- | | `charge_automatically` | Automática | Automático | | `manual_charge` | Automática | Manual | | `manual_invoice` | Manual | Manual | ### Cobro Automático (`charge_automatically`)[​](#cobro-automático-charge_automatically "Enlace directo al cobro-automático-charge_automatically") * La factura se genera automáticamente por el worker * Al finalizarse, el sistema intenta cobrar automáticamente usando el método de pago predeterminado del cliente * Para tarjeta: cobro inmediato * Para boleto (comprobante bancario brasileño)/PIX (transferencia instantánea brasileña): genera el cobro y espera confirmación vía webhook * En caso de fallo: programa intentos de reintento (dunning) ### Cobro Manual con Factura Automática (`manual_charge`)[​](#cobro-manual-con-factura-automática-manual_charge "Enlace directo al cobro-manual-con-factura-automática-manual_charge") * La factura se crea automáticamente por el worker * El cliente recibe la factura por correo electrónico * El pago se realiza manualmente (boleto, PIX) o el operador acciona el cobro ### Factura y Cobro Manual (`manual_invoice`)[​](#factura-y-cobro-manual-manual_invoice "Enlace directo al factura-y-cobro-manual-manual_invoice") * No se genera ninguna factura automáticamente * El operador crea las facturas manualmente cuando sea necesario * Útil para cobros puntuales o facturación irregular ## Comportamiento de Proration[​](#comportamiento-de-proration "Enlace directo al Comportamiento de Proration") Configura cómo se trata el cambio de plan a mitad del ciclo: | Comportamiento | Descripción | | ------------------- | ------------------------------------------------------ | | `create_prorations` | Crea créditos y cobros proporcionales (predeterminado) | | `none` | Ningún ajuste proporcional | | `always_invoice` | Siempre genera factura por la diferencia | ## Período de Prueba[​](#período-de-prueba "Enlace directo al Período de Prueba") * Configurable de 0 a 90 días * Durante la prueba, la suscripción permanece con estado `trialing` * Al finalizar la prueba, la suscripción cambia a `active` y comienza el período de cobro ## Permisos de la Suscripción[​](#permisos-de-la-suscripción "Enlace directo al Permisos de la Suscripción") | Configuración | Descripción | | -------------- | ------------------------------------------- | | `allow_pause` | Si el cliente puede pausar la suscripción | | `allow_cancel` | Si el cliente puede cancelar la suscripción | Estas configuraciones pueden definirse por suscripción y controlan las opciones disponibles en el portal del cliente. --- # Autenticación :::caution Los productos no comparten credenciales `KOBANA_TOKEN` guarda la credencial **de un producto por vez**. Un token de Facturación Automática no autentica en ningún otro producto Kobana, y viceversa. ::: ## El token[​](#el-token "Enlace directo al El token") Facturación Automática 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.billing.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. Pon el JWT en `KOBANA_TOKEN` antes de llamar al producto: ``` export KOBANA_TOKEN=$JWT_BILLING kobana billing subscriptions list --fields "id,status,plan_id" ``` 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_BILLING kobana billing subscriptions list --fields "id,status,plan_id" ``` ## Scopes[​](#scopes "Enlace directo al Scopes") Cada comando exige del token el mismo nivel de acceso que el endpoint detrás de él — un nivel por comando, y ninguno sustituye a otro: | Comando | Nivel | | ----------------------------------------------------------------------------- | -------- | | `list`, `get` y las demás lecturas | `read` | | `create`, `update` y las demás acciones (`archive`, `unarchive`, `cancel`, …) | `write` | | `delete` y `bulk delete` | `delete` | | `nfes import-barueri create` | `import` | `all` vale por todos. Un token solo con `write` recibe `403 insufficient_scope` en `delete`: pide también el nivel `delete` en tu cuenta Kobana si tu automatización elimina. Mira [Autenticación de la API](https://docs.billing.kobana.com.br/es/es/api/overview/authentication.md) para los seis niveles y los endpoints que cambiaron de método — las eliminaciones en lote, por ejemplo, pasaron a `bulk delete` (`DELETE /v1/{recurso}/bulk`). ## 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.billing.kobana.com.br` | `production` (por defecto) | | Sandbox | `api.billing.sandbox.kobana.com.br` | `sandbox` | Facturación Automática no tiene host de desarrollo propio: con `--env development` el CLI cae en producción. ``` # Producción (por defecto — sin flag) kobana billing subscriptions list # Sandbox kobana billing subscriptions list --env sandbox # Vía variable de ambiente export KOBANA_ENVIRONMENT=sandbox kobana billing subscriptions 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.billing.kobana.com.br/es/es/cli/usage/overview.md) — sintaxis, recursos, ejemplos. * [Variables de ambiente](https://docs.billing.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) | | `KOBANA_INBOX_CLIENT_CERT` | Ruta al PEM (certificado + clave) usado en el mTLS de `inbox` | ## 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.billing.kobana.com.br/es/es/cli/overview/authentication.md) — prioridad de resolución y credenciales por producto. * [Códigos de salida](https://docs.billing.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.billing.kobana.com.br/es/es/cli/usage/overview.md) — sintaxis, recursos, ejemplos. * [Flags globales](https://docs.billing.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.billing.kobana.com.br/es/es/cli/overview/authentication.md) — tokens y ambientes. * [Uso](https://docs.billing.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 — Facturación Automática 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 `billing` habla con la misma API documentada en este sitio. Sus recursos — mira el [catálogo completo](https://docs.billing.kobana.com.br/es/es/cli/resources/overview.md) — apuntan a los mismos endpoints de la [Referencia de la API](https://docs.billing.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.billing.kobana.com.br/es/es/cli/overview/authentication.md). ## Comenzando[​](#comenzando "Enlace directo al Comenzando") 1. **Instálalo** — mira [Instalación](https://docs.billing.kobana.com.br/es/es/cli/overview/installation.md). 2. **Autentícate** en el producto que vas a usar. Mira [Autenticación](https://docs.billing.kobana.com.br/es/es/cli/overview/authentication.md). 3. **Haz la primera llamada**: ``` kobana billing subscriptions list --fields "id,status,plan_id" ``` 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.billing.kobana.com.br/es/es/cli/overview/installation.md) — Homebrew, binarios precompilados, Nix, build desde el source. * [Autenticación](https://docs.billing.kobana.com.br/es/es/cli/overview/authentication.md) — tokens, ambientes y las credenciales propias de `billing`. * [Uso](https://docs.billing.kobana.com.br/es/es/cli/usage/overview.md) — sintaxis, recursos, ejemplos. * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — `kobana schema` para parámetros y formato de solicitud y respuesta. * [Flags globales](https://docs.billing.kobana.com.br/es/es/cli/usage/global-flags.md) — las flags que acepta todo comando. * [Helpers](https://docs.billing.kobana.com.br/es/es/cli/usage/helpers.md) — atajos `+verbo` para flujos comunes. * [Variables de ambiente](https://docs.billing.kobana.com.br/es/es/cli/overview/environment-variables.md) — autenticación, configuración y logs. * [Códigos de salida](https://docs.billing.kobana.com.br/es/es/cli/overview/exit-codes.md) — códigos de salida del proceso, para scripts. --- # Cuentas de cobro La cuenta que acumula suscripciones, facturas y créditos de un cliente. Suspender interrumpe el cobro sin terminar la relación; cerrar la termina. | Comando | HTTP | Descripción | | -------------------------------- | --------------------------------------------- | --------------------------------------------- | | `billing-accounts list` | `GET /v1/billing_accounts` | Listar cuentas de cobro | | `billing-accounts create` | `POST /v1/billing_accounts` | Crear cuenta de cobro | | `billing-accounts get` | `GET /v1/billing_accounts/{id}` | Obtener cuenta de cobro | | `billing-accounts update` | `PATCH /v1/billing_accounts/{id}` | Actualizar cuenta de cobro | | `billing-accounts delete` | `DELETE /v1/billing_accounts/{id}` | Eliminar cuenta de cobro (soft delete) | | `billing-accounts close` | `POST /v1/billing_accounts/{id}/close` | Cerrar cuenta de cobro (POST /close) | | `billing-accounts credits` | `GET /v1/billing_accounts/{id}/credits` | Listar los créditos de la cuenta | | `billing-accounts entitlements` | `GET /v1/billing_accounts/{id}/entitlements` | Listar los productos contratados de la cuenta | | `billing-accounts invoices` | `GET /v1/billing_accounts/{id}/invoices` | Listar las facturas de la cuenta | | `billing-accounts reactivate` | `POST /v1/billing_accounts/{id}/reactivate` | Reactivar cuenta de cobro | | `billing-accounts subscriptions` | `GET /v1/billing_accounts/{id}/subscriptions` | Listar las suscripciones de la cuenta | | `billing-accounts suspend` | `POST /v1/billing_accounts/{id}/suspend` | Suspender cuenta de cobro | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar cuentas de cobro kobana billing billing-accounts list \ --fields "id,public_id,external_id,currency,billing_email" # Obtener cuenta de cobro kobana billing billing-accounts get --params '{"id": "BILLING_ACCOUNT_ID"}' # Crear cuenta de cobro kobana billing billing-accounts create --json '{"customer": "CUSTOMER"}' # Actualizar cuenta de cobro kobana billing billing-accounts update \ --params '{"id": "BILLING_ACCOUNT_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "name": "NAME", "email": "EMAIL"}' # Cerrar cuenta de cobro (POST /close) kobana billing billing-accounts close \ --params '{"id": "BILLING_ACCOUNT_ID"}' \ --json '{"reason": "REASON"}' # Eliminar cuenta de cobro (soft delete) kobana billing billing-accounts delete \ --params '{"id": "BILLING_ACCOUNT_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Facturas](https://docs.billing.kobana.com.br/es/es/cli/resources/invoices.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Certificados digitales Los certificados A1 usados para firmar la emisión fiscal. El archivo se envía una vez y nunca vuelve en la respuesta. | Comando | HTTP | Descripción | | --------------------- | ------------------------------ | ----------------------------- | | `certificates list` | `GET /v1/certificates` | Listar certificados digitales | | `certificates create` | `POST /v1/certificates` | Enviar certificado digital | | `certificates get` | `GET /v1/certificates/{id}` | Obtener certificado | | `certificates delete` | `DELETE /v1/certificates/{id}` | Quitar certificado | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar certificados digitales kobana billing certificates list \ --fields "id,public_id,external_id,person_id,name" # Obtener certificado kobana billing certificates get --params '{"id": "CERTIFICATE_ID"}' # Enviar certificado digital kobana billing certificates create # Quitar certificado kobana billing certificates delete \ --params '{"id": "CERTIFICATE_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Consumo](https://docs.billing.kobana.com.br/es/es/cli/resources/usage.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Empresas Las empresas emisoras — quién cobra. Llevan el perfil fiscal usado en la emisión de nota, y una de ellas es la predeterminada. | 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 (soft delete) | | `companies deactivate` | `POST /v1/companies/{id}/deactivate` | Desactivar empresa (POST /deactivate) | | `companies reactivate` | `POST /v1/companies/{id}/reactivate` | Reactivar empresa | | `companies set-default` | `POST /v1/companies/{id}/set-default` | Definir empresa predeterminada | | `companies fiscal get` | `GET /v1/companies/{id}/fiscal` | Obtener el perfil fiscal | | `companies fiscal update` | `PATCH /v1/companies/{id}/fiscal` | Actualizar el perfil fiscal | | `companies fiscal-profile get` | `GET /v1/companies/{id}/fiscal-profile` | Obtener el perfil fiscal (alias) | | `companies fiscal-profile update` | `PATCH /v1/companies/{id}/fiscal-profile` | Actualizar el perfil fiscal (alias) | | `companies matriz list` | `GET /v1/companies/matriz` | Listar matrices | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar empresas kobana billing companies list \ --fields "id,public_id,external_id,organization_id,person_id" # Obtener empresa por ID kobana billing companies get --params '{"id": "COMPANIE_ID"}' # Crear empresa kobana billing companies create \ --json '{"name": "NAME", "document_type": "cpf", "document_number": "DOCUMENT_NUMBER", "email": "EMAIL"}' # Actualizar empresa kobana billing companies update \ --params '{"id": "COMPANIE_ID"}' \ --json '{"name": "NAME", "external_id": "EXTERNAL_ID", "legal_name": "LEGAL_NAME"}' # Desactivar empresa (POST /deactivate) kobana billing companies deactivate --params '{"id": "COMPANIE_ID"}' # Eliminar empresa kobana billing companies delete --params '{"id": "COMPANIE_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Organización](https://docs.billing.kobana.com.br/es/es/cli/resources/organization.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Cupones Descuentos con regla de validez y límite de uso. `redemptions` muestra dónde se aplicó efectivamente cada cupón. | Comando | HTTP | Descripción | | --------------------- | ---------------------------------- | --------------------------- | | `coupons list` | `GET /v1/coupons` | Listar cupones | | `coupons create` | `POST /v1/coupons` | Crear cupón | | `coupons get` | `GET /v1/coupons/{id}` | Obtener cupón | | `coupons update` | `PATCH /v1/coupons/{id}` | Actualizar cupón | | `coupons delete` | `DELETE /v1/coupons/{id}` | Eliminar cupón | | `coupons deactivate` | `POST /v1/coupons/{id}/deactivate` | Desactivar cupón | | `coupons redemptions` | `GET /v1/coupons/{id}/redemptions` | Listar los canjes del cupó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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar cupones kobana billing coupons list --fields "id,public_id,external_id,code,name" # Obtener cupón kobana billing coupons get --params '{"id": "COUPON_ID"}' # Crear cupón kobana billing coupons create \ --json '{"code": "CODE", "name": "NAME", "discount_type": "percentage", "discount_value": 0}' # Actualizar cupón kobana billing coupons update \ --params '{"id": "COUPON_ID"}' \ --json '{"name": "NAME", "external_id": "EXTERNAL_ID", "description": "DESCRIPTION"}' # Desactivar cupón kobana billing coupons deactivate --params '{"id": "COUPON_ID"}' # Eliminar cupón kobana billing coupons delete --params '{"id": "COUPON_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Clientes](https://docs.billing.kobana.com.br/es/es/cli/resources/customers.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Créditos Saldo a favor del cliente, aplicable a facturas futuras. Aplicar y quitar créditos son comandos de la propia factura. | Comando | HTTP | Descripción | | ---------------- | ------------------------- | ------------------ | | `credits list` | `GET /v1/credits` | Listar créditos | | `credits create` | `POST /v1/credits` | Agregar crédito | | `credits get` | `GET /v1/credits/{id}` | Obtener crédito | | `credits update` | `PATCH /v1/credits/{id}` | Actualizar crédito | | `credits delete` | `DELETE /v1/credits/{id}` | Eliminar crédito | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar créditos kobana billing credits list \ --fields "id,public_id,external_id,billing_account_id,organization_id" # Obtener crédito kobana billing credits get --params '{"id": "CREDIT_ID"}' # Agregar crédito kobana billing credits create \ --json '{"billing_account_id": "BILLING_ACCOUNT_ID", "type": "promotional", "amount_cents": 10000}' # Actualizar crédito kobana billing credits update \ --params '{"id": "CREDIT_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "type": "promotional", "amount_cents": 100}' # Eliminar crédito kobana billing credits delete --params '{"id": "CREDIT_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Retenciones](https://docs.billing.kobana.com.br/es/es/cli/resources/withholdings.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Clientes Quién es cobrado, sus usuarios de portal y el extracto consolidado. `recalculate-mrr` recalcula el ingreso recurrente del cliente. | Comando | HTTP | Descripción | | --------------------------------- | ------------------------------------------------------ | ---------------------------------------------- | | `customers list` | `GET /v1/customers` | Listar clientes | | `customers create` | `POST /v1/customers` | Crear cliente | | `customers get` | `GET /v1/customers/{id}` | Obtener cliente | | `customers update` | `PATCH /v1/customers/{id}` | Actualizar cliente | | `customers delete` | `DELETE /v1/customers/{id}` | Quitar cliente (soft delete) | | `customers recalculate-mrr` | `POST /v1/customers/{id}/recalculate-mrr` | Recalcular el MRR del cliente | | `customers statement list` | `GET /v1/customers/{id}/statement` | Listar el extracto financiero del cliente | | `customers statement sync create` | `POST /v1/customers/{id}/statement/sync` | Reconstruir el extracto a partir del historial | | `customers users list` | `GET /v1/customers/{id}/users` | Listar los usuarios del portal del cliente | | `customers users get` | `GET /v1/customers/{id}/users/{user_id}` | Obtener usuario del portal | | `customers users create` | `POST /v1/customers/{id}/users` | Invitar usuario del portal | | `customers users update` | `PATCH /v1/customers/{id}/users/{user_id}` | Actualizar usuario del portal | | `customers users delete` | `DELETE /v1/customers/{id}/users/{user_id}` | Eliminar usuario del portal (soft delete) | | `customers users email-preview` | `GET /v1/customers/{id}/users/{user_id}/email-preview` | Previsualizar el correo del usuario del portal | | `customers users resend` | `POST /v1/customers/{id}/users/{user_id}/resend` | Reenviar correo de invitación o verificación | | `customers users invite create` | `POST /v1/customers/{id}/users/invite` | Invitar usuario del portal (verbo) | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar clientes kobana billing customers list \ --fields "id,public_id,external_id,name,nickname" # Obtener cliente kobana billing customers get --params '{"id": "CUSTOMER_ID"}' # Crear cliente kobana billing customers create --json '{"name": "NAME"}' # Actualizar cliente kobana billing customers update \ --params '{"id": "CUSTOMER_ID"}' \ --json '{"name": "NAME", "external_id": "EXTERNAL_ID", "nickname": "NICKNAME"}' # Recalcular el MRR del cliente kobana billing customers recalculate-mrr --params '{"id": "CUSTOMER_ID"}' # Quitar cliente (soft delete) kobana billing customers delete --params '{"id": "CUSTOMER_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Empresas](https://docs.billing.kobana.com.br/es/es/cli/resources/companies.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Usuarios del panel Quién tiene acceso al panel de tu organización — los operadores, no los clientes. | Comando | HTTP | Descripción | | ------------------------ | --------------------------------- | ---------------------------- | | `dashboard-users list` | `GET /v1/dashboard_users` | Listar usuarios del panel | | `dashboard-users create` | `POST /v1/dashboard_users` | Invitar usuario del panel | | `dashboard-users get` | `GET /v1/dashboard_users/{id}` | Obtener usuario del panel | | `dashboard-users update` | `PATCH /v1/dashboard_users/{id}` | Actualizar usuario del panel | | `dashboard-users delete` | `DELETE /v1/dashboard_users/{id}` | Quitar usuario del panel | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar usuarios del panel kobana billing dashboard-users list \ --fields "id,public_id,organization_id,person_id,external_id" # Obtener usuario del panel kobana billing dashboard-users get --params '{"id": "DASHBOARD_USER_ID"}' # Invitar usuario del panel kobana billing dashboard-users create \ --json '{"email": "EMAIL", "role_ids": []}' # Actualizar usuario del panel kobana billing dashboard-users update \ --params '{"id": "DASHBOARD_USER_ID"}' \ --json '{"name": "NAME", "picture": "PICTURE", "status": "active"}' # Quitar usuario del panel kobana billing dashboard-users delete \ --params '{"id": "DASHBOARD_USER_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Roles de equipo](https://docs.billing.kobana.com.br/es/es/cli/resources/team-roles.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Facturas El documento a cobrar, del borrador al pagado. `finalize` sella el borrador, `pay` registra la liquidación, `void` la anula, y las cuotas viven en `installments`. | Comando | HTTP | Descripción | | --------------------------------- | --------------------------------------------------------------- | ---------------------------------- | | `invoices list` | `GET /v1/invoices` | Listar facturas | | `invoices create` | `POST /v1/invoices` | Crear factura | | `invoices get` | `GET /v1/invoices/{id}` | Obtener factura | | `invoices update` | `PATCH /v1/invoices/{id}` | Actualizar factura | | `invoices delete` | `DELETE /v1/invoices/{id}` | Eliminar factura | | `invoices apply-credits` | `POST /v1/invoices/{id}/apply-credits` | Aplicar créditos en la factura | | `invoices finalize` | `POST /v1/invoices/{id}/finalize` | Finalizar factura | | `invoices issue-nfe` | `POST /v1/invoices/{id}/issue-nfe` | Emitir NF-e para la factura | | `invoices pay` | `POST /v1/invoices/{id}/pay` | Pagar factura | | `invoices payment-methods` | `GET /v1/invoices/{id}/payment-methods` | Listar métodos de pago disponibles | | `invoices pdf` | `GET /v1/invoices/{id}/pdf` | Descargar el PDF de la factura | | `invoices remove-credits` | `POST /v1/invoices/{id}/remove-credits` | Quitar créditos aplicados | | `invoices send-reminder` | `POST /v1/invoices/{id}/send-reminder` | Enviar recordatorio de cobro | | `invoices undo-payment` | `POST /v1/invoices/{id}/undo-payment` | Deshacer el pago de la factura | | `invoices void` | `POST /v1/invoices/{id}/void` | Anular (void) factura | | `invoices installments get` | `GET /v1/invoices/{id}/installments` | Listar las cuotas de la factura | | `invoices installments create` | `POST /v1/invoices/{id}/installments` | Crear/actualizar plan de cuotas | | `invoices installments mark-paid` | `POST /v1/invoices/{id}/installments/{installmentId}/mark-paid` | Marcar cuota como pagada | | `invoices installments pay` | `POST /v1/invoices/{id}/installments/{installmentId}/pay` | Pagar cuota | | `invoices pending-nfe list` | `GET /v1/invoices/pending-nfe` | Listar facturas con NF-e pendiente | | `invoices pending-payment list` | `GET /v1/invoices/pending-payment` | Listar facturas con pago pendiente | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar facturas kobana billing invoices list \ --fields "id,public_id,external_id,number,billing_account_id" # Obtener factura kobana billing invoices get --params '{"id": "INVOICE_ID"}' # Crear factura kobana billing invoices create \ --json '{"billing_account_id": "BILLING_ACCOUNT_ID", "line_items": []}' # Actualizar factura kobana billing invoices update \ --params '{"id": "INVOICE_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "company_id": "COMPANY_ID", "collection_method": "charge_automatically"}' # Aplicar créditos en la factura kobana billing invoices apply-credits \ --params '{"id": "INVOICE_ID"}' \ --json '{"credit_ids": []}' # Eliminar factura kobana billing invoices delete --params '{"id": "INVOICE_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Pagos](https://docs.billing.kobana.com.br/es/es/cli/resources/payments.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Notas fiscales La emisión fiscal de una factura: emitir, cancelar, descargar PDF y XML, y seguir cada intento ante la municipalidad. Barueri tiene comandos propios. | Comando | HTTP | Descripción | | ------------------------------ | ---------------------------------------- | ------------------------------------------- | | `nfes list` | `GET /v1/nfes` | Listar NF-es | | `nfes create` | `POST /v1/nfes` | Crear NF-e (borrador) | | `nfes get` | `GET /v1/nfes/{id}` | Obtener NF-e | | `nfes update` | `PATCH /v1/nfes/{id}` | Actualizar NF-e (borrador) | | `nfes delete` | `DELETE /v1/nfes/{id}` | Eliminar NF-e | | `nfes cancel` | `POST /v1/nfes/{id}/cancel` | Cancelar NF-e | | `nfes issue` | `POST /v1/nfes/{id}/issue` | Emitir NF-e | | `nfes pdf` | `GET /v1/nfes/{id}/pdf` | Descargar el PDF de la NF-e | | `nfes retry-cancel` | `POST /v1/nfes/{id}/retry-cancel` | Reintentar la cancelación de la NF-e | | `nfes validate-barueri` | `POST /v1/nfes/{id}/validate-barueri` | Validar NFS-e de Barueri | | `nfes xml` | `GET /v1/nfes/{id}/xml` | Descargar el XML de la NF-e | | `nfes bulk create` | `POST /v1/nfes/bulk` | Actualizar NF-es en lote | | `nfes bulk delete` | `DELETE /v1/nfes/bulk` | Eliminar NF-es en lote | | `nfes fetch-barueri create` | `POST /v1/nfes/fetch-barueri` | Buscar NFS-e en Barueri | | `nfes fetch-from-sefaz create` | `POST /v1/nfes/fetch-from-sefaz` | Buscar NFS-e en el ADN (SEFAZ) | | `nfes import-barueri create` | `POST /v1/nfes/import-barueri` | Importar NFS-e de Barueri | | `nfes request-tries list` | `GET /v1/nfes/request-tries` | Listar intentos de solicitud (organización) | | `nfes request-tries get` | `GET /v1/nfes/{id}/request-tries` | Listar los intentos de solicitud de la NF-e | | `nfes requests list` | `GET /v1/nfes/{id}/requests` | Listar solicitudes externas de la NF-e | | `nfes requests get` | `GET /v1/nfes/{id}/requests/{requestId}` | Obtener solicitud externa | | `nfes sync create` | `POST /v1/nfes/sync` | Sincronizar las NF-es de la organizació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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar NF-es kobana billing nfes list \ --fields "id,public_id,external_id,invoice_id,transaction_id" # Obtener NF-e kobana billing nfes get --params '{"id": "NFE_ID"}' # Crear NF-e (borrador) kobana billing nfes create \ --json '{"billing_account_id": "BILLING_ACCOUNT_ID", "amount_cents": 100, "customer": {}}' # Actualizar NF-e (borrador) kobana billing nfes update \ --params '{"id": "NFE_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "service_code": "SERVICE_CODE", "service_description": "SERVICE_DESCRIPTION"}' # Cancelar NF-e kobana billing nfes cancel \ --params '{"id": "NFE_ID"}' \ --json '{"reason": "REASON"}' # Eliminar NF-e kobana billing nfes delete --params '{"id": "NFE_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Reglas de impuesto](https://docs.billing.kobana.com.br/es/es/cli/resources/tax-rules.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Organización Las configuraciones en la cima de la jerarquía, comunes a todas las empresas de la cuenta. | Comando | HTTP | Descripción | | --------------------- | ------------------------ | --------------------------------- | | `organization list` | `GET /v1/organization` | Obtener la organización actual | | `organization update` | `PATCH /v1/organization` | Actualizar la organización actual | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Obtener la organización actual kobana billing organization list \ --fields "id,public_id,external_id,status,created_at" # Actualizar la organización actual kobana billing organization update \ --json '{"name": "NAME", "email": "EMAIL", "phone": "PHONE"}' ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Propuestas](https://docs.billing.kobana.com.br/es/es/cli/resources/proposals.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Recursos Todo recurso de `billing` abajo se genera a partir de la misma spec OpenAPI documentada en la [Referencia de la API](https://docs.billing.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.billing.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 billing [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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. Mira [Autenticación](https://docs.billing.kobana.com.br/es/es/cli/overview/authentication.md) para las credenciales propias de `billing`. ## El catálogo[​](#el-catálogo "Enlace directo al El catálogo") | Recurso | Comando | Métodos | | -------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Planes](https://docs.billing.kobana.com.br/es/es/cli/resources/plans.md) | `plans` | list, create, get, update, delete, archive, duplicate, bulk-archive create, bulk delete, bulk-move-group create, items get, items update | | [Grupos de planes](https://docs.billing.kobana.com.br/es/es/cli/resources/plan-groups.md) | `plan-groups` | list, create, get, update, delete, archive, reorder create | | [Productos](https://docs.billing.kobana.com.br/es/es/cli/resources/products.md) | `products` | list, create, get, update, delete, archive, publish, restore, bulk-archive create, bulk-change-company create, bulk delete, bulk-move-group create, bulk-visibility create, reorder create, reorder update | | [Grupos de productos](https://docs.billing.kobana.com.br/es/es/cli/resources/product-groups.md) | `product-groups` | list, create, get, update, delete, archive, unarchive, reorder create, reorder update | | [Ítems de servicio](https://docs.billing.kobana.com.br/es/es/cli/resources/service-items.md) | `service-items` | list, create, get, update, delete | | [Suscripciones](https://docs.billing.kobana.com.br/es/es/cli/resources/subscriptions.md) | `subscriptions` | list, create, get, update, delete, activate, cancel, change-plan, create-invoice, items get, pause, resume, revert-to-confirmed, sync-plan-items | | [Cambios de suscripción](https://docs.billing.kobana.com.br/es/es/cli/resources/subscription-changes.md) | `subscription-changes` | config list, config update | | [Cambios de ítems](https://docs.billing.kobana.com.br/es/es/cli/resources/subscription-item-changes.md) | `subscription-item-changes` | list, get, cancel | | [Cambios de plan](https://docs.billing.kobana.com.br/es/es/cli/resources/plan-changes.md) | `plan-changes` | list, create, get, config list, config update, rules list, rules create, rules get, rules update, rules delete, stats list | | [Cuentas de cobro](https://docs.billing.kobana.com.br/es/es/cli/resources/billing-accounts.md) | `billing-accounts` | list, create, get, update, delete, close, credits, entitlements, invoices, reactivate, subscriptions, suspend | | [Facturas](https://docs.billing.kobana.com.br/es/es/cli/resources/invoices.md) | `invoices` | list, create, get, update, delete, apply-credits, finalize, issue-nfe, pay, payment-methods, pdf, remove-credits, send-reminder, undo-payment, void, installments get, installments create, installments mark-paid, installments pay, pending-nfe list, pending-payment list | | [Pagos](https://docs.billing.kobana.com.br/es/es/cli/resources/payments.md) | `payments` | list, create, get, delete, cancel, change-card, change-due-date, refund, retry, send-email, sync, bulk-update-invoice create | | [Medios de pago](https://docs.billing.kobana.com.br/es/es/cli/resources/payment-methods.md) | `payment-methods` | list, create, get, update, delete, set-default | | [Créditos](https://docs.billing.kobana.com.br/es/es/cli/resources/credits.md) | `credits` | list, create, get, update, delete | | [Retenciones](https://docs.billing.kobana.com.br/es/es/cli/resources/withholdings.md) | `withholdings` | list, get, convert-to-credit, convert-to-credits create | | [Cupones](https://docs.billing.kobana.com.br/es/es/cli/resources/coupons.md) | `coupons` | list, create, get, update, delete, deactivate, redemptions | | [Clientes](https://docs.billing.kobana.com.br/es/es/cli/resources/customers.md) | `customers` | list, create, get, update, delete, recalculate-mrr, statement list, statement sync create, users list, users get, users create, users update, users delete, users email-preview, users resend, users invite create | | [Empresas](https://docs.billing.kobana.com.br/es/es/cli/resources/companies.md) | `companies` | list, create, get, update, delete, deactivate, reactivate, set-default, fiscal get, fiscal update, fiscal-profile get, fiscal-profile update, matriz list | | [Organización](https://docs.billing.kobana.com.br/es/es/cli/resources/organization.md) | `organization` | list, update | | [Propuestas](https://docs.billing.kobana.com.br/es/es/cli/resources/proposals.md) | `proposals` | list, create, get, update, delete, accept, cancel, duplicate, generate-pdf, json, pricing, publish, send, undo-accept, unpublish, bulk-cancel create, bulk delete, bulk-send create, items get, items create, items update, items delete, stats list | | [Plantillas de propuesta](https://docs.billing.kobana.com.br/es/es/cli/resources/proposal-templates.md) | `proposal-templates` | list, create, get, update, delete, activate, deactivate, duplicate | | [Notas fiscales](https://docs.billing.kobana.com.br/es/es/cli/resources/nfes.md) | `nfes` | list, create, get, update, delete, cancel, issue, pdf, retry-cancel, validate-barueri, xml, bulk create, bulk delete, fetch-barueri create, fetch-from-sefaz create, import-barueri create, request-tries list, request-tries get, requests list, requests get, sync create | | [Reglas de impuesto](https://docs.billing.kobana.com.br/es/es/cli/resources/tax-rules.md) | `tax-rules` | list, create, get, update, delete | | [Períodos fiscales](https://docs.billing.kobana.com.br/es/es/cli/resources/tax-periods.md) | `tax-periods` | list, create, get, update, delete | | [Certificados digitales](https://docs.billing.kobana.com.br/es/es/cli/resources/certificates.md) | `certificates` | list, create, get, delete | | [Consumo](https://docs.billing.kobana.com.br/es/es/cli/resources/usage.md) | `usage` | list, create, snapshots daily list, snapshots daily create, snapshots monthly list, snapshots monthly create, summary list | | [Usuarios del panel](https://docs.billing.kobana.com.br/es/es/cli/resources/dashboard-users.md) | `dashboard-users` | list, create, get, update, delete | | [Roles de equipo](https://docs.billing.kobana.com.br/es/es/cli/resources/team-roles.md) | `team-roles` | list, create, get, update, delete | --- # Medios de pago Las tarjetas y demás medios guardados de un cliente, y cuál de ellos es el predeterminado. | Comando | HTTP | Descripción | | ----------------------------- | ------------------------------------------- | ------------------------------------- | | `payment-methods list` | `GET /v1/payment_methods` | Listar métodos de pago | | `payment-methods create` | `POST /v1/payment_methods` | Crear método de pago | | `payment-methods get` | `GET /v1/payment_methods/{id}` | Obtener método de pago | | `payment-methods update` | `PATCH /v1/payment_methods/{id}` | Actualizar la validez de la tarjeta | | `payment-methods delete` | `DELETE /v1/payment_methods/{id}` | Eliminar método de pago (soft delete) | | `payment-methods set-default` | `POST /v1/payment_methods/{id}/set-default` | Definir método como predeterminado | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar métodos de pago kobana billing payment-methods list \ --fields "id,public_id,external_id,billing_account_id,credit_card_id" # Obtener método de pago kobana billing payment-methods get --params '{"id": "PAYMENT_METHOD_ID"}' # Crear método de pago kobana billing payment-methods create \ --json '{"billingAccountId": "BILLINGACCOUNTID", "type": "card"}' # Actualizar la validez de la tarjeta kobana billing payment-methods update \ --params '{"id": "PAYMENT_METHOD_ID"}' \ --json '{"exp_month": 0, "exp_year": 0}' # Definir método como predeterminado kobana billing payment-methods set-default \ --params '{"id": "PAYMENT_METHOD_ID"}' # Quitar método de pago kobana billing payment-methods delete \ --params '{"id": "PAYMENT_METHOD_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Créditos](https://docs.billing.kobana.com.br/es/es/cli/resources/credits.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Pagos Los intentos de liquidación de una factura: reintento, cambio de tarjeta, cambio de vencimiento, reembolso y reenvío del correo de cobro. | Comando | HTTP | Descripción | | ------------------------------------- | ---------------------------------------- | --------------------------------- | | `payments list` | `GET /v1/payments` | Listar pagos | | `payments create` | `POST /v1/payments` | Procesar pago | | `payments get` | `GET /v1/payments/{id}` | Obtener pago | | `payments delete` | `DELETE /v1/payments/{id}` | Eliminar pago | | `payments cancel` | `POST /v1/payments/{id}/cancel` | Cancelar pago | | `payments change-card` | `POST /v1/payments/{id}/change-card` | Cambiar la tarjeta del pago | | `payments change-due-date` | `POST /v1/payments/{id}/change-due-date` | Cambiar el vencimiento del boleto | | `payments refund` | `POST /v1/payments/{id}/refund` | Reembolsar pago | | `payments retry` | `POST /v1/payments/{id}/retry` | Reintentar el pago | | `payments send-email` | `POST /v1/payments/{id}/send-email` | Enviar el boleto por correo | | `payments sync` | `POST /v1/payments/{id}/sync` | Sincronizar pago con la pasarela | | `payments bulk-update-invoice create` | `POST /v1/payments/bulk-update-invoice` | Reasignar pagos a otra factura | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar pagos kobana billing payments list \ --fields "id,public_id,external_id,invoice_id,billing_account_id" # Obtener pago kobana billing payments get --params '{"id": "PAYMENT_ID"}' # Procesar pago kobana billing payments create --json '{"invoiceId": "INVOICEID"}' # Cancelar pago kobana billing payments cancel \ --params '{"id": "PAYMENT_ID"}' \ --json '{"reason": "REASON", "cancel_on_gateway": true}' # Eliminar pago kobana billing payments delete --params '{"id": "PAYMENT_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Medios de pago](https://docs.billing.kobana.com.br/es/es/cli/resources/payment-methods.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Cambios de plan Upgrades y downgrades: las reglas que definen qué puede convertirse en qué, la configuración del prorrateo y las estadísticas de lo que se cambió. | Comando | HTTP | Descripción | | ---------------------------- | ------------------------------------ | --------------------------------------------- | | `plan-changes list` | `GET /v1/plan_changes` | Listar cambios de plan | | `plan-changes create` | `POST /v1/plan_changes` | Ejecutar cambio de plan | | `plan-changes get` | `GET /v1/plan_changes/{id}` | Obtener cambio de plan | | `plan-changes config list` | `GET /v1/plan_changes/config` | Obtener la configuración de cambio de plan | | `plan-changes config update` | `PATCH /v1/plan_changes/config` | Actualizar la configuración de cambio de plan | | `plan-changes rules list` | `GET /v1/plan_changes/rules` | Listar reglas de cambio de plan | | `plan-changes rules create` | `POST /v1/plan_changes/rules` | Crear regla de cambio de plan | | `plan-changes rules get` | `GET /v1/plan_changes/rules/{id}` | Obtener regla de cambio de plan | | `plan-changes rules update` | `PATCH /v1/plan_changes/rules/{id}` | Actualizar regla de cambio de plan | | `plan-changes rules delete` | `DELETE /v1/plan_changes/rules/{id}` | Eliminar regla de cambio de plan | | `plan-changes stats list` | `GET /v1/plan_changes/stats` | Estadísticas de cambios de plan | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar cambios de plan kobana billing plan-changes list \ --fields "id,public_id,external_id,subscription_id,billing_account_id" # Obtener cambio de plan kobana billing plan-changes get --params '{"id": "PLAN_CHANGE_ID"}' # Ejecutar cambio de plan kobana billing plan-changes create \ --json '{"subscription_id": "SUBSCRIPTION_ID", "to_plan_id": "TO_PLAN_ID"}' # Actualizar la configuración de cambio de plan kobana billing plan-changes config update \ --json '{"allow_upgrade": true, "allow_downgrade": true, "upgrade_proration": "full_proration"}' # Eliminar regla de cambio de plan kobana billing plan-changes rules delete \ --params '{"id": "RULE_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Cuentas de cobro](https://docs.billing.kobana.com.br/es/es/cli/resources/billing-accounts.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Grupos de planes El estante en que los planes se muestran y ordenan. `reorder` cambia el orden; `archive` retira el grupo de circulación sin borrarlo. | Comando | HTTP | Descripción | | ---------------------------- | ----------------------------------- | -------------------------- | | `plan-groups list` | `GET /v1/plan_groups` | Listar grupos de planes | | `plan-groups create` | `POST /v1/plan_groups` | Crear grupo de planes | | `plan-groups get` | `GET /v1/plan_groups/{id}` | Obtener grupo de planes | | `plan-groups update` | `PATCH /v1/plan_groups/{id}` | Actualizar grupo de planes | | `plan-groups delete` | `DELETE /v1/plan_groups/{id}` | Quitar grupo de planes | | `plan-groups archive` | `POST /v1/plan_groups/{id}/archive` | Archivar grupo de planes | | `plan-groups reorder create` | `POST /v1/plan_groups/reorder` | Reordenar grupos de planes | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar grupos de planes kobana billing plan-groups list \ --fields "id,public_id,external_id,organization_id,company_id" # Obtener grupo de planes kobana billing plan-groups get --params '{"id": "PLAN_GROUP_ID"}' # Crear grupo de planes kobana billing plan-groups create --json '{"name": "NAME"}' # Actualizar grupo de planes kobana billing plan-groups update \ --params '{"id": "PLAN_GROUP_ID"}' \ --json '{"name": "NAME", "slug": "SLUG", "external_id": "EXTERNAL_ID"}' # Archivar grupo de planes kobana billing plan-groups archive --params '{"id": "PLAN_GROUP_ID"}' # Quitar grupo de planes kobana billing plan-groups delete --params '{"id": "PLAN_GROUP_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Productos](https://docs.billing.kobana.com.br/es/es/cli/resources/products.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Planes Lo que se suscribe: precio, periodicidad y la lista de ítems que entrega el plan. Las operaciones `bulk-*` actúan sobre varios planes a la vez. | Comando | HTTP | Descripción | | ------------------------------ | -------------------------------- | --------------------------------- | | `plans list` | `GET /v1/plans` | Listar planes | | `plans create` | `POST /v1/plans` | Crear plan | | `plans get` | `GET /v1/plans/{id}` | Obtener plan | | `plans update` | `PATCH /v1/plans/{id}` | Actualizar plan | | `plans delete` | `DELETE /v1/plans/{id}` | Eliminar plan (soft delete) | | `plans archive` | `POST /v1/plans/{id}/archive` | Archivar plan | | `plans duplicate` | `POST /v1/plans/{id}/duplicate` | Duplicar plan | | `plans bulk-archive create` | `POST /v1/plans/bulk-archive` | Archivar planes en lote | | `plans bulk delete` | `DELETE /v1/plans/bulk` | Eliminar planes en lote | | `plans bulk-move-group create` | `POST /v1/plans/bulk-move-group` | Mover planes a otro grupo en lote | | `plans items get` | `GET /v1/plans/{id}/items` | Listar los ítems del plan | | `plans items update` | `PUT /v1/plans/{id}/items` | Reemplazar los ítems del plan | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar planes kobana billing plans list \ --fields "id,public_id,external_id,organization_id,company_id" # Obtener plan kobana billing plans get --params '{"id": "PLAN_ID"}' # Crear plan kobana billing plans create --json '{"name": "NAME", "slug": "SLUG"}' # Actualizar plan kobana billing plans update \ --params '{"id": "PLAN_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "company_id": "COMPANY_ID", "plan_group_id": "PLAN_GROUP_ID"}' # Duplicar plan kobana billing plans duplicate --params '{"id": "PLAN_ID"}' # Archivar plan (reversible) kobana billing plans archive --params '{"id": "PLAN_ID"}' # Eliminar plan (soft delete) kobana billing plans delete --params '{"id": "PLAN_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Grupos de planes](https://docs.billing.kobana.com.br/es/es/cli/resources/plan-groups.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Grupos de productos La agrupación del catálogo de productos, con ordenación y archivado propios. | Comando | HTTP | Descripción | | ------------------------------- | ---------------------------------------- | ---------------------------------------- | | `product-groups list` | `GET /v1/product_groups` | Listar grupos de producto | | `product-groups create` | `POST /v1/product_groups` | Crear grupo de producto | | `product-groups get` | `GET /v1/product_groups/{id}` | Obtener grupo de producto | | `product-groups update` | `PATCH /v1/product_groups/{id}` | Actualizar grupo de producto | | `product-groups delete` | `DELETE /v1/product_groups/{id}` | Quitar grupo de producto | | `product-groups archive` | `POST /v1/product_groups/{id}/archive` | Archivar grupo de producto | | `product-groups unarchive` | `POST /v1/product_groups/{id}/unarchive` | Desarchivar grupo de producto | | `product-groups reorder create` | `POST /v1/product_groups/reorder` | Reordenar grupos de producto | | `product-groups reorder update` | `PUT /v1/product_groups/reorder` | Reordenar grupos de producto (alias PUT) | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar grupos de producto kobana billing product-groups list \ --fields "id,public_id,external_id,organization_id,company_id" # Obtener grupo de producto kobana billing product-groups get --params '{"id": "PRODUCT_GROUP_ID"}' # Crear grupo de producto kobana billing product-groups create --json '{"name": "NAME"}' # Actualizar grupo de producto kobana billing product-groups update \ --params '{"id": "PRODUCT_GROUP_ID"}' \ --json '{"name": "NAME", "slug": "SLUG", "company_id": "COMPANY_ID"}' # Quitar grupo de producto kobana billing product-groups delete \ --params '{"id": "PRODUCT_GROUP_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Ítems de servicio](https://docs.billing.kobana.com.br/es/es/cli/resources/service-items.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Productos El catálogo de lo que se cobra, ítem a ítem, antes de convertirse en plan o ítem de factura. Publicar, archivar y restaurar controlan la visibilidad sin destruir el historial. | Comando | HTTP | Descripción | | ------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------- | | `products list` | `GET /v1/products` | Listar productos | | `products create` | `POST /v1/products` | Crear producto | | `products get` | `GET /v1/products/{id}` | Obtener producto | | `products update` | `PATCH /v1/products/{id}` | Actualizar producto | | `products delete` | `DELETE /v1/products/{id}` | Eliminar producto (soft delete: desaparece de toda lectura y de los planes) | | `products archive` | `POST /v1/products/{id}/archive` | Archivar producto | | `products publish` | `POST /v1/products/{id}/publish` | Publicar producto | | `products restore` | `POST /v1/products/{id}/restore` | Restaurar producto archivado | | `products bulk-archive create` | `POST /v1/products/bulk-archive` | Archivar productos en lote | | `products bulk-change-company create` | `POST /v1/products/bulk-change-company` | Cambiar la empresa de productos en lote | | `products bulk delete` | `DELETE /v1/products/bulk` | Eliminar productos en lote | | `products bulk-move-group create` | `POST /v1/products/bulk-move-group` | Mover productos a otro grupo | | `products bulk-visibility create` | `POST /v1/products/bulk-visibility` | Cambiar visibilidad en lote | | `products reorder create` | `POST /v1/products/reorder` | Reordenar productos | | `products reorder update` | `PUT /v1/products/reorder` | Reordenar productos (PUT /reorder) | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar productos kobana billing products list \ --fields "id,public_id,external_id,organization_id,company_id" # Obtener producto kobana billing products get --params '{"id": "PRODUCT_ID"}' # Crear producto kobana billing products create --json '{"name": "NAME", "slug": "SLUG"}' # Actualizar producto kobana billing products update \ --params '{"id": "PRODUCT_ID"}' \ --json '{"name": "NAME", "slug": "SLUG", "description": "DESCRIPTION"}' # Archivar producto kobana billing products archive --params '{"id": "PRODUCT_ID"}' # Eliminar producto (soft delete) kobana billing products delete --params '{"id": "PRODUCT_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Grupos de productos](https://docs.billing.kobana.com.br/es/es/cli/resources/product-groups.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Plantillas de propuesta Las plantillas de las que nacen las propuestas, con una marcada como predeterminada. | Comando | HTTP | Descripción | | ------------------------------- | --------------------------------------------- | --------------------------------- | | `proposal-templates list` | `GET /v1/proposal_templates` | Listar plantillas de propuesta | | `proposal-templates create` | `POST /v1/proposal_templates` | Crear plantilla de propuesta | | `proposal-templates get` | `GET /v1/proposal_templates/{id}` | Obtener plantilla de propuesta | | `proposal-templates update` | `PATCH /v1/proposal_templates/{id}` | Actualizar plantilla de propuesta | | `proposal-templates delete` | `DELETE /v1/proposal_templates/{id}` | Eliminar plantilla de propuesta | | `proposal-templates activate` | `POST /v1/proposal_templates/{id}/activate` | Activar plantilla de propuesta | | `proposal-templates deactivate` | `POST /v1/proposal_templates/{id}/deactivate` | Desactivar plantilla de propuesta | | `proposal-templates duplicate` | `POST /v1/proposal_templates/{id}/duplicate` | Duplicar plantilla de propuesta | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar plantillas de propuesta kobana billing proposal-templates list \ --fields "id,public_id,external_id,name,description" # Obtener plantilla de propuesta kobana billing proposal-templates get \ --params '{"id": "PROPOSAL_TEMPLATE_ID"}' # Crear plantilla de propuesta kobana billing proposal-templates create \ --json '{"name": "NAME", "googleDocId": "GOOGLEDOCID"}' # Actualizar plantilla de propuesta kobana billing proposal-templates update \ --params '{"id": "PROPOSAL_TEMPLATE_ID"}' \ --json '{"name": "NAME", "description": "DESCRIPTION", "documentType": "google_doc"}' # Activar plantilla de propuesta kobana billing proposal-templates activate \ --params '{"id": "PROPOSAL_TEMPLATE_ID"}' # Eliminar plantilla de propuesta kobana billing proposal-templates delete \ --params '{"id": "PROPOSAL_TEMPLATE_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Notas fiscales](https://docs.billing.kobana.com.br/es/es/cli/resources/nfes.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Propuestas El presupuesto antes de la suscripción: publicar, enviar, generar PDF y aceptar. Aceptar es lo que convierte la propuesta en suscripción — y `undo-accept` lo deshace. | Comando | HTTP | Descripción | | ------------------------------ | ------------------------------------------ | -------------------------------------------- | | `proposals list` | `GET /v1/proposals` | Listar propuestas | | `proposals create` | `POST /v1/proposals` | Crear propuesta | | `proposals get` | `GET /v1/proposals/{id}` | Obtener propuesta | | `proposals update` | `PATCH /v1/proposals/{id}` | Actualizar propuesta | | `proposals delete` | `DELETE /v1/proposals/{id}` | Eliminar propuesta | | `proposals accept` | `POST /v1/proposals/{id}/accept` | Aceptar propuesta | | `proposals cancel` | `POST /v1/proposals/{id}/cancel` | Cancelar propuesta | | `proposals duplicate` | `POST /v1/proposals/{id}/duplicate` | Duplicar propuesta | | `proposals generate-pdf` | `POST /v1/proposals/{id}/generate-pdf` | Generar el PDF de la propuesta | | `proposals json` | `GET /v1/proposals/{id}/json` | Obtener la instantánea JSON de la propuesta | | `proposals pricing` | `GET /v1/proposals/{id}/pricing` | Obtener el cálculo de precio de la propuesta | | `proposals publish` | `POST /v1/proposals/{id}/publish` | Publicar propuesta | | `proposals send` | `POST /v1/proposals/{id}/send` | Enviar propuesta por correo | | `proposals undo-accept` | `POST /v1/proposals/{id}/undo-accept` | Deshacer la aceptación de la propuesta | | `proposals unpublish` | `POST /v1/proposals/{id}/unpublish` | Despublicar propuesta | | `proposals bulk-cancel create` | `POST /v1/proposals/bulk-cancel` | Cancelar propuestas en lote | | `proposals bulk delete` | `DELETE /v1/proposals/bulk` | Eliminar propuestas en lote | | `proposals bulk-send create` | `POST /v1/proposals/bulk-send` | Enviar propuestas en lote | | `proposals items get` | `GET /v1/proposals/{id}/items` | Listar los ítems de la propuesta | | `proposals items create` | `POST /v1/proposals/{id}/items` | Agregar ítem a la propuesta | | `proposals items update` | `PATCH /v1/proposals/{id}/items/{itemId}` | Actualizar ítem de la propuesta | | `proposals items delete` | `DELETE /v1/proposals/{id}/items/{itemId}` | Eliminar ítem de la propuesta | | `proposals stats list` | `GET /v1/proposals/stats` | Obtener estadísticas de propuestas | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar propuestas kobana billing proposals list \ --fields "id,public_id,external_id,company_id,code" # Obtener propuesta kobana billing proposals get --params '{"id": "PROPOSAL_ID"}' # Crear propuesta kobana billing proposals create \ --json '{"company_id": "COMPANY_ID", "title": "TITLE", "description": "DESCRIPTION"}' # Actualizar propuesta kobana billing proposals update \ --params '{"id": "PROPOSAL_ID"}' \ --json '{"company_id": "COMPANY_ID", "title": "TITLE", "description": "DESCRIPTION"}' # Aceptar propuesta kobana billing proposals accept \ --params '{"id": "PROPOSAL_ID"}' \ --json '{"cycle": "monthly"}' # Eliminar propuesta kobana billing proposals delete --params '{"id": "PROPOSAL_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Plantillas de propuesta](https://docs.billing.kobana.com.br/es/es/cli/resources/proposal-templates.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Ítems de servicio Los servicios de la lista municipal usados para describir qué está cobrando la nota fiscal. | Comando | HTTP | Descripción | | ---------------------- | ------------------------------- | --------------------------------------- | | `service-items list` | `GET /v1/service_items` | Listar ítems de servicio | | `service-items create` | `POST /v1/service_items` | Crear ítem de servicio | | `service-items get` | `GET /v1/service_items/{id}` | Obtener ítem de servicio | | `service-items update` | `PATCH /v1/service_items/{id}` | Actualizar ítem de servicio | | `service-items delete` | `DELETE /v1/service_items/{id}` | Eliminar ítem de servicio (soft delete) | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar ítems de servicio kobana billing service-items list \ --fields "id,public_id,external_id,organization_id,company_id" # Obtener ítem de servicio kobana billing service-items get --params '{"id": "SERVICE_ITEM_ID"}' # Crear ítem de servicio kobana billing service-items create \ --json '{"name": "NAME", "internal_code": "INTERNAL_CODE", "lc116_code": "01.05"}' # Actualizar ítem de servicio kobana billing service-items update \ --params '{"id": "SERVICE_ITEM_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "company_id": "COMPANY_ID", "name": "NAME"}' # Eliminar ítem de servicio kobana billing service-items delete \ --params '{"id": "SERVICE_ITEM_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Suscripciones](https://docs.billing.kobana.com.br/es/es/cli/resources/subscriptions.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Cambios de suscripción La configuración de cómo se aplican los cambios de suscripción — de inmediato, en el próximo ciclo, con o sin prorrateo. | Comando | HTTP | Descripción | | ------------------------------------ | ------------------------------------- | ----------------------------------------------------- | | `subscription-changes config list` | `GET /v1/subscription_changes/config` | Obtener la configuración de cambios de suscripción | | `subscription-changes config update` | `PUT /v1/subscription_changes/config` | Actualizar la configuración de cambios de suscripció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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Obtener la configuración de cambios de suscripción kobana billing subscription-changes config list \ --fields "id,publicId,organizationId,externalId,allowItemAdd" # Actualizar la configuración de cambios de suscripción kobana billing subscription-changes config update \ --json '{"allow_item_add": true, "allow_item_remove": true, "allow_quantity_change": true}' ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Cambios de ítems](https://docs.billing.kobana.com.br/es/es/cli/resources/subscription-item-changes.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Cambios de ítems El historial de cambios en los ítems de una suscripción, y la cancelación de un cambio aún agendado. | Comando | HTTP | Descripción | | ---------------------------------- | ------------------------------------------------ | -------------------------------------- | | `subscription-item-changes list` | `GET /v1/subscription_item_changes` | Listar cambios de ítems de suscripción | | `subscription-item-changes get` | `GET /v1/subscription_item_changes/{id}` | Obtener cambio de ítem de suscripción | | `subscription-item-changes cancel` | `POST /v1/subscription_item_changes/{id}/cancel` | Cancelar un cambio aún agendado | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar cambios de ítems de suscripción kobana billing subscription-item-changes list \ --fields "id,publicId,organizationId,subscriptionId,billingAccountId" # Obtener cambio de ítem de suscripción kobana billing subscription-item-changes get \ --params '{"id": "SUBSCRIPTION_ITEM_CHANGE_ID"}' ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Cambios de plan](https://docs.billing.kobana.com.br/es/es/cli/resources/plan-changes.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Suscripciones El contrato vivo entre un cliente y un plan: activar, pausar, reanudar, cambiar de plan y cancelar. `create-invoice` fuerza una factura fuera del ciclo. | Comando | HTTP | Descripción | | ----------------------------------- | ------------------------------------------------- | ---------------------------------------------- | | `subscriptions list` | `GET /v1/subscriptions` | Listar suscripciones | | `subscriptions create` | `POST /v1/subscriptions` | Crear suscripción | | `subscriptions get` | `GET /v1/subscriptions/{id}` | Obtener suscripción | | `subscriptions update` | `PATCH /v1/subscriptions/{id}` | Actualizar suscripción | | `subscriptions delete` | `DELETE /v1/subscriptions/{id}` | Cancelar y quitar suscripción (soft delete) | | `subscriptions activate` | `POST /v1/subscriptions/{id}/activate` | Activar suscripción en borrador/confirmada | | `subscriptions cancel` | `POST /v1/subscriptions/{id}/cancel` | Cancelar suscripción | | `subscriptions change-plan` | `POST /v1/subscriptions/{id}/change-plan` | Cambiar el plan de la suscripción | | `subscriptions create-invoice` | `POST /v1/subscriptions/{id}/create-invoice` | Generar una factura suelta para la suscripción | | `subscriptions items get` | `GET /v1/subscriptions/{id}/items` | Listar los ítems de la suscripción | | `subscriptions pause` | `POST /v1/subscriptions/{id}/pause` | Pausar suscripción | | `subscriptions resume` | `POST /v1/subscriptions/{id}/resume` | Reanudar suscripción pausada | | `subscriptions revert-to-confirmed` | `POST /v1/subscriptions/{id}/revert-to-confirmed` | Revertir la suscripción al estado confirmado | | `subscriptions sync-plan-items` | `POST /v1/subscriptions/{id}/sync-plan-items` | Resincronizar ítems con el plan actual | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar suscripciones kobana billing subscriptions list \ --fields "id,public_id,external_id,billing_account_id,company_id" # Obtener suscripción kobana billing subscriptions get --params '{"id": "SUBSCRIPTION_ID"}' # Crear suscripción kobana billing subscriptions create \ --json '{"billing_account_id": "BILLING_ACCOUNT_ID"}' # Actualizar suscripción kobana billing subscriptions update \ --params '{"id": "SUBSCRIPTION_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "plan_id": "PLAN_ID", "billing_cycle": "monthly"}' # Activar suscripción en borrador/confirmada kobana billing subscriptions activate --params '{"id": "SUBSCRIPTION_ID"}' # Cancelar y quitar suscripción (soft delete) kobana billing subscriptions delete \ --params '{"id": "SUBSCRIPTION_ID"}' \ --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Cambios de suscripción](https://docs.billing.kobana.com.br/es/es/cli/resources/subscription-changes.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Períodos fiscales Los períodos fiscales que agrupan las notas emitidas. | Comando | HTTP | Descripción | | -------------------- | ----------------------------- | ---------------------------------------- | | `tax-periods list` | `GET /v1/tax_periods` | Listar períodos tributarios | | `tax-periods create` | `POST /v1/tax_periods` | Procesar período tributario mensual | | `tax-periods get` | `GET /v1/tax_periods/{id}` | Obtener período tributario | | `tax-periods update` | `PATCH /v1/tax_periods/{id}` | Ejecutar acción en el período tributario | | `tax-periods delete` | `DELETE /v1/tax_periods/{id}` | Eliminar período tributario | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar períodos tributarios kobana billing tax-periods list \ --fields "id,public_id,external_id,company_id,period_type" # Obtener período tributario kobana billing tax-periods get --params '{"id": "TAX_PERIOD_ID"}' # Procesar período tributario mensual kobana billing tax-periods create --json '{"year": 2026, "month": 6}' # Ejecutar acción en el período tributario kobana billing tax-periods update \ --params '{"id": "TAX_PERIOD_ID"}' \ --json '{"action": "recalculate"}' # Eliminar período tributario kobana billing tax-periods delete --params '{"id": "TAX_PERIOD_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Certificados digitales](https://docs.billing.kobana.com.br/es/es/cli/resources/certificates.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Reglas de impuesto Qué tributo incide sobre qué, y con qué alícuota — lo que consulta la emisión de nota. | Comando | HTTP | Descripción | | ------------------ | --------------------------- | --------------------------- | | `tax-rules list` | `GET /v1/tax_rules` | Listar reglas tributarias | | `tax-rules create` | `POST /v1/tax_rules` | Crear regla tributaria | | `tax-rules get` | `GET /v1/tax_rules/{id}` | Obtener regla tributaria | | `tax-rules update` | `PATCH /v1/tax_rules/{id}` | Actualizar regla tributaria | | `tax-rules delete` | `DELETE /v1/tax_rules/{id}` | Eliminar regla tributaria | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar reglas tributarias kobana billing tax-rules list \ --fields "id,public_id,external_id,scope,priority" # Obtener regla tributaria kobana billing tax-rules get --params '{"id": "TAX_RULE_ID"}' # Crear regla tributaria kobana billing tax-rules create \ --json '{"name": "NAME", "scope": "global", "items": []}' # Actualizar regla tributaria kobana billing tax-rules update \ --params '{"id": "TAX_RULE_ID"}' \ --json '{"name": "NAME", "description": "DESCRIPTION", "priority": 0}' # Eliminar regla tributaria kobana billing tax-rules delete --params '{"id": "TAX_RULE_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Períodos fiscales](https://docs.billing.kobana.com.br/es/es/cli/resources/tax-periods.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Roles de equipo Los roles que definen qué puede hacer cada usuario del panel. | Comando | HTTP | Descripción | | ------------------- | ---------------------------- | ----------------------- | | `team-roles list` | `GET /v1/team_roles` | Listar roles del equipo | | `team-roles create` | `POST /v1/team_roles` | Crear rol personalizado | | `team-roles get` | `GET /v1/team_roles/{id}` | Obtener rol | | `team-roles update` | `PATCH /v1/team_roles/{id}` | Actualizar rol | | `team-roles delete` | `DELETE /v1/team_roles/{id}` | Quitar rol | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar roles del equipo kobana billing team-roles list \ --fields "id,public_id,organization_id,name,slug" # Obtener rol kobana billing team-roles get --params '{"id": "TEAM_ROLE_ID"}' # Crear rol personalizado kobana billing team-roles create \ --json '{"name": "NAME", "slug": "billing_manager", "permissions": []}' # Actualizar rol kobana billing team-roles update \ --params '{"id": "TEAM_ROLE_ID"}' \ --json '{"name": "NAME", "slug": "SLUG", "description": "DESCRIPTION"}' # Quitar rol kobana billing team-roles delete --params '{"id": "TEAM_ROLE_ID"}' --dry-run ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Consumo Los eventos de consumo que alimentan el cobro por uso, con instantáneas diarias y mensuales y un resumen consolidado. | Comando | HTTP | Descripción | | -------------------------------- | ---------------------------------- | ------------------------------------ | | `usage list` | `GET /v1/usage` | Listar registros de uso | | `usage create` | `POST /v1/usage` | Reportar uso (metered) | | `usage snapshots daily list` | `GET /v1/usage/snapshots/daily` | Listar instantáneas diarias de uso | | `usage snapshots daily create` | `POST /v1/usage/snapshots/daily` | Crear instantáneas diarias de uso | | `usage snapshots monthly list` | `GET /v1/usage/snapshots/monthly` | Listar instantáneas mensuales de uso | | `usage snapshots monthly create` | `POST /v1/usage/snapshots/monthly` | Crear instantáneas mensuales de uso | | `usage summary list` | `GET /v1/usage/summary` | Resumen de uso del período | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar registros de uso kobana billing usage list \ --fields "id,public_id,external_id,subscription_item_id,quantity" # Reportar uso (metered) kobana billing usage create ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Usuarios del panel](https://docs.billing.kobana.com.br/es/es/cli/resources/dashboard-users.md) * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — todos los parámetros que este recurso acepta. --- # Retenciones Los importes retenidos en la fuente por el cliente, que pueden convertirse en crédito. | Comando | HTTP | Descripción | | ---------------------------------------- | ---------------------------------------------- | ------------------------------------------------------ | | `withholdings list` | `GET /v1/withholdings` | Listar retenciones | | `withholdings get` | `GET /v1/withholdings/{id}` | Obtener retención | | `withholdings convert-to-credit` | `POST /v1/withholdings/{id}/convert-to-credit` | Convertir retención en crédito | | `withholdings convert-to-credits create` | `POST /v1/withholdings/convert-to-credits` | Convertir retenciones pendientes en créditos (en lote) | ## 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) para la referencia completa. ``` # Listar retenciones kobana billing withholdings list \ --fields "id,public_id,external_id,organization_id,invoice_id" # Obtener retención kobana billing withholdings get --params '{"id": "WITHHOLDING_ID"}' # Convertir retenciones pendientes en créditos (en lote) kobana billing withholdings convert-to-credits create \ --json '{"tax_type": "iss", "competence_year": 0, "competence_month": 0}' # Convertir retención en crédito kobana billing withholdings convert-to-credit \ --params '{"id": "WITHHOLDING_ID"}' \ --json '{"amount_cents": 100}' ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Cupones](https://docs.billing.kobana.com.br/es/es/cli/resources/coupons.md) * [Introspección de schema](https://docs.billing.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) | | `--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) | ## 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 billing --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.billing.kobana.com.br/es/es/cli/usage/overview.md) — sintaxis, recursos, ejemplos. * [Introspección de schema](https://docs.billing.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.billing.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.billing.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: `subscriptions`, `invoices installments`, `customers users`. * **``** — 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 billing --help # recursos de Facturación Automática kobana billing plans --help # métodos de un recurso ``` ## Recursos de `billing`[​](#recursos-de-billing "Enlace directo al recursos-de-billing") | Recurso | Descripción | | --------------------------- | ----------------------- | | `plans` | Planes | | `plan-groups` | Grupos de planes | | `products` | Productos | | `product-groups` | Grupos de productos | | `service-items` | Ítems de servicio | | `subscriptions` | Suscripciones | | `subscription-changes` | Cambios de suscripción | | `subscription-item-changes` | Cambios de ítems | | `plan-changes` | Cambios de plan | | `billing-accounts` | Cuentas de cobro | | `invoices` | Facturas | | `payments` | Pagos | | `payment-methods` | Medios de pago | | `credits` | Créditos | | `withholdings` | Retenciones | | `coupons` | Cupones | | `customers` | Clientes | | `companies` | Empresas | | `organization` | Organización | | `proposals` | Propuestas | | `proposal-templates` | Plantillas de propuesta | | `nfes` | Notas fiscales | | `tax-rules` | Reglas de impuesto | | `tax-periods` | Períodos fiscales | | `certificates` | Certificados digitales | | `usage` | Consumo | | `dashboard-users` | Usuarios del panel | | `team-roles` | Roles de equipo | Cada recurso tiene su propia página, con la tabla completa de comandos y ejemplos — mira el [catálogo](https://docs.billing.kobana.com.br/es/es/cli/resources/overview.md). ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") ``` # Suscripciones activas kobana billing subscriptions list \ --params '{"status": "active"}' \ --fields "id,status,plan_id,next_billing_at" # Pausar y reanudar una suscripción kobana billing subscriptions pause --params '{"id": "SUBSCRIPTION_ID"}' kobana billing subscriptions resume --params '{"id": "SUBSCRIPTION_ID"}' # Cerrar una factura y emitir la NF-e kobana billing invoices finalize --dry-run --params '{"id": "INVOICE_ID"}' kobana billing invoices issue-nfe --dry-run --params '{"id": "INVOICE_ID"}' # Crear un plan kobana billing plans create --json '{"name": "Pro", "slug": "pro"}' # Listar con paginación automática (NDJSON) kobana billing invoices list --page-all --fields "id,status,total" # Salida en tabla kobana billing plans list --output-format table # Guardar la respuesta en un archivo kobana billing invoices get --params '{"id": "INVOICE_ID"}' --output fatura.json ``` ## Próximos pasos[​](#próximos-pasos "Enlace directo al Próximos pasos") * [Introspección de schema](https://docs.billing.kobana.com.br/es/es/cli/usage/schema.md) — inspecciona parámetros y cuerpo de cualquier endpoint. * [Flags globales](https://docs.billing.kobana.com.br/es/es/cli/usage/global-flags.md) — todas las flags que acepta un comando. * [Helpers](https://docs.billing.kobana.com.br/es/es/cli/usage/helpers.md) — atajos `+verbo` para flujos comunes. * [Recursos](https://docs.billing.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 billing.subscriptions.list kobana schema billing.subscriptions.create kobana schema billing.invoices.finalize ``` 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.billing.kobana.com.br/es/es/cli/usage/global-flags.md) — `--params`, `--json`, `--dry-run` y las demás. * [Uso](https://docs.billing.kobana.com.br/es/es/cli/usage/overview.md) — sintaxis, recursos, ejemplos. --- ## [📄️Analytics](https://docs.billing.kobana.com.br/es/es/configuracoes/analytics.md) [El área de Analytics (/dashboard/analytics) traduce los datos operativos de la facturación en métricas SaaS que pueden consumir los equipos de finanzas y producto: MRR, ARR, churn, LTV, ARPU, retención por cohorte y embudo de cobro.](https://docs.billing.kobana.com.br/es/es/configuracoes/analytics.md) --- ## [📄️Analytics](https://docs.billing.kobana.com.br/es/es/configuracoes/analytics.md) [El área de Analytics (/dashboard/analytics) traduce los datos operativos de la facturación en métricas SaaS que pueden consumir los equipos de finanzas y producto: MRR, ARR, churn, LTV, ARPU, retención por cohorte y embudo de cobro.](https://docs.billing.kobana.com.br/es/es/configuracoes/analytics.md) --- # Analytics El área de Analytics (`/dashboard/analytics`) traduce los datos operativos de la facturación en **métricas SaaS** que pueden consumir los equipos de finanzas y producto: MRR, ARR, churn, LTV, ARPU, retención por cohorte y embudo de cobro. ## Métricas principales[​](#métricas-principales "Enlace directo al Métricas principales") * **MRR** (Monthly Recurring Revenue) — suma normalizada de las suscripciones activas en el mes. * **ARR** — proyección anualizada del MRR. * **MRR Movement** — cuánto de la variación vino de **nuevos**, **expansión**, **contracción**, **reactivación** y **churn**. * **Churn** — número y porcentaje de suscripciones canceladas en el período. * **NRR** (Net Revenue Retention) — cuánto creció o se redujo la base existente, sin contar clientes nuevos. * **ARPU** (Average Revenue Per User) — ingreso promedio por cuenta de cobro. * **LTV** (Lifetime Value) — estimación de ingresos por cliente a lo largo del tiempo. ## Visualizaciones[​](#visualizaciones "Enlace directo al Visualizaciones") La página usa gráficos de Vega/Vega-Lite para presentar: * **Serie temporal de MRR** con waterfall del movimiento mensual. * **Embudo de cobro** — emitidas → enviadas → pagadas → fallidas. * **Retención por cohorte** — heatmap que muestra la supervivencia de cada cohorte de clientes. * **Distribución por plan** — cuántas suscripciones hay en cada plan y el MRR por plan. ## Filtros[​](#filtros "Enlace directo al Filtros") * **Rango de fechas** — por defecto, los últimos 12 meses. * **Plan** — filtrar por uno o más planes. * **Moneda** — cuando la organización opera en más de una. ## De dónde vienen los datos[​](#de-dónde-vienen-los-datos "Enlace directo al De dónde vienen los datos") Analytics consulta directamente las tablas operativas (`subscriptions`, `subscription_versions`, `invoices`, `payments`) filtradas por `organization_id`. No hay ETL: los números reflejan el estado actual de la base de datos en tiempo real. ## Exportación[​](#exportación "Enlace directo al Exportación") Cada gráfico puede exportarse en CSV o PNG. Para extracciones en bruto (fila por fila), usa [Reportes](https://docs.billing.kobana.com.br/es/es/configuracoes/relatorios.md) o [Exportaciones](https://docs.billing.kobana.com.br/es/es/exportacao-e-importacao/exportacoes/.md). ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Panel de Analytics con MRR, churn, retención por cohorte y distribución por plan](/es/assets/images/analytics-a59ef437f78c6f858aa112df1bf66251.png) --- # API Keys En `/dashboard/api` la organización gestiona las **claves de API**. Cada clave pertenece a una organización, tiene un conjunto de alcances (scopes) y puede revocarse en cualquier momento. :::caution La API pública ya no usa clave de API La `/api/v1` pasó a aceptar **solo** el access token del Authorization Server de Kobana (`Authorization: Bearer `), verificado contra la clave pública que este publica. Una clave creada aquí **no** autentica la API pública. El motivo es que la clave era al mismo tiempo la credencial y lo que la verificaba: quien leyera el repositorio de claves actuaba como cualquier organización, y cada rotación era una conversación con un cliente. Con el token, quien emite es el Authorization Server y la plataforma solo puede verificar. ::: ## Tipos de clave[​](#tipos-de-clave "Enlace directo al Tipos de clave") * **Live** (`sk_live_...`) — se usan en producción. Operan contra datos reales y generan cobros reales. * **Test** (`sk_test_...`) — apuntan al sandbox; ideales para la integración inicial y las pruebas automatizadas. ## Crear una clave[​](#crear-una-clave "Enlace directo al Crear una clave") 1. Haz clic en **Nueva clave**. 2. Dale un nombre descriptivo (ej.: "Backend producción", "Worker de importación"). 3. Selecciona los alcances: * `subscriptions:read` / `subscriptions:write` * `invoices:read` / `invoices:write` * `payments:read` / `payments:write` * `customers:read` / `customers:write` * `nfes:read` / `nfes:write` * `webhooks:manage` 4. Opcionalmente, restringe por **IP** (lista de prefijos CIDR). 5. La clave se muestra **una única vez** después de crearla. Cópiala y guárdala en un gestor de secretos. ## Buenas prácticas[​](#buenas-prácticas "Enlace directo al Buenas prácticas") * **Una clave por aplicación** — facilita revocar el acceso sin afectar otros sistemas. * **Alcances mínimos** — concede solo lo que la aplicación necesita. * **Rotación periódica** — genera una clave nueva, actualiza la aplicación y revoca la anterior. * **Nunca hagas commit** — las claves deben vivir en variables de entorno o en un gestor de secretos. ## Rate limits[​](#rate-limits "Enlace directo al Rate limits") Cada clave respeta los límites configurados en [Rate Limiting](https://docs.billing.kobana.com.br/es/es/configuracoes/rate-limiting/.md). Los excesos devuelven `429 Too Many Requests` con el header `Retry-After`. ## Auditoría y uso[​](#auditoría-y-uso "Enlace directo al Auditoría y uso") La página muestra: * **Status** — `active` o `revoked` * **Último uso** — fecha, IP y endpoint llamado * **Volumen** — solicitudes en las últimas 24 h y en los últimos 30 días Toda creación o revocación queda registrada en [Auditoría](https://docs.billing.kobana.com.br/es/es/configuracoes/auditoria.md). ## Documentación de la API[​](#documentación-de-la-api "Enlace directo al Documentación de la API") La referencia completa de los endpoints está disponible en la sección **API** del menú lateral. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Lista de API keys con nombre, alcances, último uso y status](/es/assets/images/api-3a1f94f54dd8792f4783417ee5f8f25f.png) --- # Auditoría La pista de auditoría (`/dashboard/audit`) registra **toda modificación de datos** hecha en el dashboard o vía API. Cada entrada captura quién lo hizo, qué se modificó, los valores antes y después, la IP, el User-Agent y el horario, formando un historial inmutable para compliance, depuración y análisis de incidentes. ## Qué se registra[​](#qué-se-registra "Enlace directo al Qué se registra") Toda operación sensible pasa por el `auditService`. Entre las acciones registradas: * Creación, actualización, suspensión y activación de **cuentas de cobro** y **clientes** * Cambios de **plan**, **ítems**, **status de suscripción**, **pausa** y **cancelación** * Operaciones en **facturas**, **pagos**, **reembolsos** y **créditos** * Emisión, cancelación y errores de **NF-e** * Modificaciones en **empresas**, **gateways**, **webhooks** y **API keys** * Cambios en **miembros**, **roles**, **configuraciones** y **templates** * Inicios y cierres de sesión administrativos La lista completa de acciones está definida en `lib/services/audit.service.ts` (`AuditActions`). ## Filtros[​](#filtros "Enlace directo al Filtros") La interfaz permite filtrar por: * **Acción** (por ejemplo, `subscription.canceled`, `invoice.paid`) * **Tipo de recurso** (subscription, invoice, customer, nfe, etc.) * **Usuario** que la ejecutó * **Rango de fechas** * **Búsqueda de texto** por ID o nombre del recurso ## Detalle de una entrada[​](#detalle-de-una-entrada "Enlace directo al Detalle de una entrada") Cada fila puede expandirse en un modal que muestra: * **previous\_values** — JSON con el estado anterior * **new\_values** — JSON con el estado después de la modificación * **metadata** — contexto adicional (origen, motivo, idempotency key) * **IP** y **User-Agent** capturados en la solicitud ## Retención y exportación[​](#retención-y-exportación "Enlace directo al Retención y exportación") Las entradas de auditoría son inmutables. Para análisis externos o retención a largo plazo, usa [Exportaciones](https://docs.billing.kobana.com.br/es/es/exportacao-e-importacao/exportacoes/.md) para descargarlas en CSV. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Pista de auditoría con acciones, recursos y detalles de la modificación](/es/assets/images/auditoria-7a4b2e3666237fdcca923d2f7b4da815.png) --- # Configuraciones de Cobro Configuraciones que afectan la fijación de precios y el comportamiento de cobro de la organización. ## Campos[​](#campos "Enlace directo al Campos") | Campo | Predeterminado | Descripción | | ---------------------------------- | -------------- | ---------------------------------------------- | | **Descuento trimestral (%)** | 5% | Descuento para ciclo trimestral | | **Descuento semestral (%)** | 10% | Descuento para ciclo semestral | | **Descuento anual (%)** | 15% | Descuento para ciclo anual | | **Validez de la propuesta (días)** | 30 | Días hasta que la propuesta expire | | **Ciclo de cobro predeterminado** | `monthly` | Ciclo predeterminado para nuevas suscripciones | ## Descuentos por Ciclo[​](#descuentos-por-ciclo "Enlace directo al Descuentos por Ciclo") Los descuentos se aplican automáticamente al calcular precios de propuestas y al presentar opciones de ciclo al cliente: | Ciclo | Descuento Predeterminado | Ejemplo (plan R$ 100/mes) | | ---------- | ------------------------ | ---------------------------- | | Mensual | 0% | R$ 100/mes | | Trimestral | 5% | R$ 285/trimestre (R$ 95/mes) | | Semestral | 10% | R$ 540/semestre (R$ 90/mes) | | Anual | 15% | R$ 1.020/año (R$ 85/mes) | ## Dónde Se Usan[​](#dónde-se-usan "Enlace directo al Dónde Se Usan") * **Propuestas**: Cálculo de precios por ciclo * **Suscripciones**: Definición del ciclo predeterminado * **Portal**: Presentación de opciones de ciclo al cliente --- # Empresa (Entidad Fiscal) Las empresas representan las entidades jurídicas que emiten facturas y notas fiscales. Una organización puede tener múltiples empresas (matriz y sucursales). ## Campos[​](#campos "Enlace directo al Campos") | Campo | Descripción | | ------------------------ | -------------------------------------------------- | | **Nombre** | Nombre comercial | | **Razón social** | Nombre legal completo | | **Tipo de documento** | CPF o CNPJ | | **Número del documento** | CPF o CNPJ | | **Predeterminada** | Si es la empresa predeterminada de la organización | | **Status** | `active` o `inactive` | | **Empresa matriz** | Para sucursales, referencia a la matriz | ## Jerarquía[​](#jerarquía "Enlace directo al Jerarquía") ``` Matriz (CNPJ principal) ├── Sucursal 1 (mismo prefijo CNPJ) └── Sucursal 2 (mismo prefijo CNPJ) ``` ### Reglas de Sucursales[​](#reglas-de-sucursales "Enlace directo al Reglas de Sucursales") * La matriz debe tener CNPJ para tener sucursales * El CNPJ de la sucursal debe tener el mismo prefijo de la matriz * Las sucursales no pueden ser marcadas como predeterminadas ## Empresa Predeterminada[​](#empresa-predeterminada "Enlace directo al Empresa Predeterminada") Una empresa por organización es marcada como predeterminada. Usada automáticamente cuando la empresa no es especificada en operaciones. Al desactivar la empresa predeterminada, otra es automáticamente promovida. ## Perfil Fiscal[​](#perfil-fiscal "Enlace directo al Perfil Fiscal") Cada empresa posee un perfil fiscal vinculado que define: * Régimen tributario (Simples Nacional, Lucro Presumido, Lucro Real) * Alícuotas de impuestos * Configuración del Simples Nacional * Configuración CBS/IBS ## Operaciones[​](#operaciones "Enlace directo al Operaciones") * **Crear**: Crear empresa o sucursal * **Actualizar**: Editar datos de registro * **Definir como predeterminada**: Marca como empresa predeterminada * **Desactivar**: No es posible si hay suscripciones activas o si es la única empresa activa * **Reactivar**: Vuelve al status `active` --- # Eventos La pantalla de eventos (`/dashboard/events`) expone el **stream interno de eventos de dominio** que genera el sistema cada vez que cambia un estado relevante — `invoice.created`, `payment.succeeded`, `subscription.canceled`, `nfe.issued` y decenas de otros. Es la misma cola que alimenta los [Webhooks](https://docs.billing.kobana.com.br/es/es/webhooks.md) y el historial del cliente en el portal. ## Por qué es importante[​](#por-qué-es-importante "Enlace directo al Por qué es importante") A diferencia de la [Auditoría](https://docs.billing.kobana.com.br/es/es/configuracoes/auditoria.md), que registra las modificaciones hechas por personas, los **eventos** representan lo que ocurrió desde el punto de vista del dominio del negocio — sin importar el origen (UI, API, worker, webhook recibido de un gateway). Los eventos son útiles para: * **Depuración**: descubrir por qué un webhook no llegó a su destino o por qué una suscripción se canceló inesperadamente. * **Replays**: reenviar eventos a un endpoint que estaba fuera de servicio. * **Integraciones**: confirmar que un evento esperado realmente se generó. ## Estructura del evento[​](#estructura-del-evento "Enlace directo al Estructura del evento") Cada evento contiene: * **type** — nombre con el patrón `recurso.accion` (ej.: `invoice.paid`) * **resource\_type** y **resource\_id** — la entidad afectada * **payload** — JSON con el estado relevante en el momento del evento * **created\_at** — cuándo se emitió el evento * **delivery\_status** — agregado de los intentos de entrega a los endpoints suscritos ## Filtros y búsqueda[​](#filtros-y-búsqueda "Enlace directo al Filtros y búsqueda") La lista ofrece filtros por tipo de evento, recurso, rango de fechas y status de entrega. Cada fila puede expandirse para mostrar el payload completo y el historial de intentos en cada endpoint suscrito. ## Catálogo de eventos[​](#catálogo-de-eventos "Enlace directo al Catálogo de eventos") La referencia completa de los tipos de evento (y cuándo se dispara cada uno) está en [Webhooks > Eventos](https://docs.billing.kobana.com.br/es/es/webhooks/eventos/.md). ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Lista de eventos con tipo, recurso, payload y status de entrega](/es/assets/images/eventos-ba5fd219aa724612cae4dffaaa2284c4.png) --- # Feriados Los feriados son los días en que los bancos no operan. Sirven a dos propósitos: * **Encontrar el vencimiento efectivo**: una factura que vence en fin de semana o feriado puede pagarse el siguiente día hábil sin multa ni intereses. * **Contar días hábiles** cuando la política de intereses y multas cobra intereses por día hábil en lugar de por día corrido. Cada organización tiene su propia lista. Un feriado municipal mueve el día hábil para un cliente y no para otro, y eliminar un feriado en su cuenta no afecta a ninguna otra. ## Dónde configurar[​](#dónde-configurar "Enlace directo al Dónde configurar") `Sistema` → **Feriados**. La pantalla muestra los feriados del año seleccionado, con el día de la semana y el origen de cada fila. ## Importación automática[​](#importación-automática "Enlace directo al Importación automática") Toda organización creada en la plataforma ya viene con los **feriados nacionales** del año corriente y los dos siguientes, importados de [BrasilAPI](https://brasilapi.com.br/docs#tag/Feriados-Nacionais). Para traer otro año, o completar lo que faltó, use **Importar nacionales** con el año seleccionado. La importación incluye Carnaval, Viernes Santo, Pascua y Corpus Christi. Técnicamente Carnaval y Corpus Christi son puntos facultativos, no feriados nacionales — pero los bancos cierran en ellos, y es el cierre del banco lo que importa para contar un día hábil. :::note La importación no deshace una eliminación Si usted elimina un feriado, importar los nacionales de nuevo **no** lo trae de vuelta. La fila eliminada queda registrada precisamente para que la importación respete su decisión. Cuando eso ocurre, la pantalla avisa cuántos feriados eliminados quedaron fuera. ::: ## Registrar a mano[​](#registrar-a-mano "Enlace directo al Registrar a mano") Use **Nuevo feriado** para feriados estatales, municipales, puntos facultativos de su operación o fechas propias. | Campo | Descripción | | ----------------- | ------------------------------------------------------------------------------------------ | | **Fecha** | El día en el calendario. Sin hora — un feriado es una fecha, no un instante | | **Nombre** | Junto con la fecha identifica la fila. Un municipal y un nacional pueden caer el mismo día | | **Alcance** | Nacional, estatal, municipal, punto facultativo o propio | | **Observaciones** | Texto libre — la ciudad de un feriado municipal, por ejemplo | Un feriado que cae en sábado o domingo no cambia nada en el conteo: esos días ya no eran hábiles. La pantalla lo señala para ahorrarle la duda. ## Cómo afecta los intereses[​](#cómo-afecta-los-intereses "Enlace directo al Cómo afecta los intereses") En la política de intereses y multas, el campo **Conteo de días** decide qué cuenta: * **Días corridos** — todos los días, incluidos fines de semana y feriados. * **Días hábiles** — solo los días en que el banco opera, según esta lista. Con R$ 1.000,00 al 1% mensual vencidos un jueves y revisados el lunes siguiente: | Conteo | Días | Intereses | | ------------------------------- | ------------------- | --------- | | Corridos | 4 | R$ 1,33 | | Hábiles | 2 (viernes y lunes) | R$ 0,67 | | Hábiles, con el viernes feriado | 1 (lunes) | R$ 0,33 | La **multa** no se ve afectada: incide una vez, contada en días corridos. El registro bancario también la trata así — no existe instrucción de "días hábiles para la multa". :::caution Sin feriados registrados la cuenta queda mal Si la política cobra por día hábil y la lista está vacía, el cálculo descuenta solo los fines de semana. El banco descuenta los feriados también, así que recaudará menos de lo que calculamos — y la diferencia aparece como crédito en la cuenta del cliente, junto con el evento `invoice.late_charges_unexplained`. Importe los nacionales antes de activar el cobro por día hábil. ::: ## Vencimiento en fin de semana o feriado[​](#vencimiento-en-fin-de-semana-o-feriado "Enlace directo al Vencimiento en fin de semana o feriado") Un boleto que vence en un día sin atención bancaria puede pagarse el siguiente día hábil sin cargos — es la regla de la Febraban, y el boleto ya se registra con esa fecha. La multa y los intereses siguen el vencimiento del boleto: cuentan a partir del **siguiente día hábil**, sea cual sea el conteo de días de la política. Una factura que vence el sábado y se paga el lunes no paga multa ni intereses. Pagada el martes, cuenta un día de atraso, a partir del lunes. Para que la propia factura ya muestre esa fecha — y no solo el boleto —, active **Vencimiento siempre en día hábil** en `Configuraciones` → **Facturación**. Con la opción activa, todo vencimiento que caiga en fin de semana o feriado pasa al siguiente día hábil: el calculado por el plazo de pago, el ingresado a mano y el de cada cuota. Las facturas importadas mantienen la fecha del archivo. ## Por la API[​](#por-la-api "Enlace directo al Por la API") El recurso es `/v1/holidays`. Las fechas son días civiles (`YYYY-MM-DD`), nunca instantes. ``` # Listar los feriados de un año curl "https://api.kobana.com.br/billing/v1/holidays?year=2026" \ -H "Authorization: Bearer $TOKEN" # Registrar un feriado municipal curl -X POST https://api.kobana.com.br/billing/v1/holidays \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "date": "2026-01-25", "name": "Aniversário de São Paulo", "type": "municipal", "notes": "São Paulo, SP" }' # Importar los nacionales curl -X POST https://api.kobana.com.br/billing/v1/holidays/sync \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"years": [2026, 2027]}' ``` La respuesta de la importación trae `created`, `existing` y `skipped_removed` — el último cuenta los feriados que estaban eliminados y quedaron fuera. ## Preguntas frecuentes[​](#preguntas-frecuentes "Enlace directo al Preguntas frecuentes") **¿Necesito registrar feriados si cobro intereses por día corrido?** Sí. Incluso con días corridos, un vencimiento que cae en feriado pasa al siguiente día hábil, y solo la lista dice qué días son feriados. Sin ella, solo los fines de semana mueven el vencimiento. **¿Los feriados valen para todas mis empresas?** La lista es por organización, así que vale para todas las empresas dentro de ella. Si una empresa está en un municipio con feriado propio, regístrelo con alcance municipal y anote la ciudad. **¿Por qué aparece la Pascua, si siempre cae en domingo?** BrasilAPI la devuelve, y guardarla es inofensivo: un feriado en fin de semana no altera el conteo. **¿Quién puede editar?** Quien tenga permiso de actualizar configuraciones — el mismo de `Configuración`. --- # Miembros y Roles La página de miembros (`/dashboard/members`) lista a todas las personas con acceso al dashboard de la organización. Cada miembro tiene un e-mail vinculado a la autenticación Kobana y uno o más **roles** que definen lo que puede ver y modificar. ## Invitar a un miembro[​](#invitar-a-un-miembro "Enlace directo al Invitar a un miembro") 1. Haz clic en **Invitar miembro** e informa el e-mail. 2. Selecciona uno o más roles (ej.: `admin`, `fiscal`, `financeiro`, `read_only`). 3. El usuario recibe un enlace de aceptación por e-mail. 4. Después de aceptar, el miembro aparece con status `active` y puede entrar por SSO. ## Status del miembro[​](#status-del-miembro "Enlace directo al Status del miembro") * **invited** — invitación enviada, esperando aceptación. * **active** — acceso habilitado. * **suspended** — acceso bloqueado temporalmente, sin eliminar el historial. * **removed** — miembro eliminado (mantiene la auditoría de las acciones anteriores). ## Roles[​](#roles "Enlace directo al Roles") Los roles se gestionan en `/dashboard/members/roles`. Cada rol es un conjunto de permisos granulares — por ejemplo, "puede emitir NF-e", "puede reembolsar un pago", "puede cambiar el plan". La organización puede crear roles personalizados además de los roles predeterminados. ### Roles predeterminados[​](#roles-predeterminados "Enlace directo al Roles predeterminados") | Rol | Acceso típico | | -------------- | --------------------------------------------------------- | | **Owner** | Acceso total, incluida la facturación de la plataforma | | **Admin** | Configuraciones, miembros, facturas, planes, NF-e | | **Financiero** | Facturas, pagos, créditos, dunning, exportaciones | | **Fiscal** | NF-e, reglas tributarias, períodos fiscales, certificados | | **Comercial** | Clientes, planes, suscripciones, propuestas | | **Read-only** | Visualización de todas las áreas, sin acciones | ### Permisos personalizados[​](#permisos-personalizados "Enlace directo al Permisos personalizados") Al crear un rol nuevo, es posible activar o desactivar permisos individualmente por recurso (clientes, suscripciones, facturas, NF-e, reglas fiscales, gateways, webhooks, etc.). Cada permiso puede ser de lectura, creación, edición o eliminación. ## Auditoría[​](#auditoría "Enlace directo al Auditoría") Toda modificación en miembros y roles queda registrada en [Auditoría](https://docs.billing.kobana.com.br/es/es/configuracoes/auditoria.md): quién invitó, quién aceptó, quién modificó un rol, IP y User-Agent. ## Capturas de pantalla[​](#capturas-de-pantalla "Enlace directo al Capturas de pantalla") ### Lista de miembros[​](#lista-de-miembros "Enlace directo al Lista de miembros") ![Lista de miembros con e-mail, roles y status](/es/assets/images/membros-b82a417349ad15e57e7c5058df84f049.png) ### Gestión de roles[​](#gestión-de-roles "Enlace directo al Gestión de roles") ![Pantalla de configuración de roles y permisos granulares](/es/assets/images/membros-papeis-ff3a3b313af9cafce6afb4b736e3a95c.png) --- # Notificaciones El sistema de notificaciones envía comunicaciones multicanal a clientes sobre eventos importantes. ## Canales[​](#canales "Enlace directo al Canales") | Canal | Descripción | | ----------- | ----------------------------------------------------------- | | **email** | Envío vía SMTP | | **in\_app** | Almacenada en la base de datos para exhibición en el portal | | **webhook** | Enviada al endpoint configurado | ## Tipos de Notificación[​](#tipos-de-notificación "Enlace directo al Tipos de Notificación") ### Suscripciones[​](#suscripciones "Enlace directo al Suscripciones") * `subscription_renewal` — Suscripción renovada * `subscription_created` — Nueva suscripción * `subscription_canceled` — Suscripción cancelada ### Pagos[​](#pagos "Enlace directo al Pagos") * `payment_succeeded` — Pago procesado * `payment_failed` — Pago falló ### Facturas[​](#facturas "Enlace directo al Facturas") * `invoice_created` — Factura generada * `invoice_overdue` — Factura vencida ### Cuenta[​](#cuenta "Enlace directo al Cuenta") * `trial_ending` — Trial por expirar * `plan_changed` — Plan modificado * `account_suspended` — Cuenta suspendida * `account_activated` — Cuenta reactivada ### Portal[​](#portal "Enlace directo al Portal") * `portal_invitation` — Invitación para el portal * `portal_signup_verification` — Verificación de e-mail ### Propuestas[​](#propuestas "Enlace directo al Propuestas") * `proposal_sent` — Propuesta enviada * `proposal_reminder` — Recordatorio de propuesta * `proposal_expired` — Propuesta expirada * `proposal_accepted` — Propuesta aceptada * `proposal_rejected` — Propuesta rechazada ## Status de la Notificación[​](#status-de-la-notificación "Enlace directo al Status de la Notificación") | Status | Descripción | | ----------- | ------------------------- | | `pending` | Esperando envío | | `sent` | Enviada/encolada | | `delivered` | Confirmada como entregada | | `failed` | Falla en el envío | | `read` | Leída (solo in\_app) | ## Preferencias[​](#preferencias "Enlace directo al Preferencias") Cada cuenta de cobro puede configurar preferencias por tipo de notificación: * Habilitar/deshabilitar e-mail * Habilitar/deshabilitar in-app * Habilitar/deshabilitar webhook El sistema verifica las preferencias antes de enviar. ## Retry[​](#retry "Enlace directo al Retry") Las notificaciones fallidas pueden ser reintentadas manualmente. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") La pantalla `/dashboard/notifications` reúne la configuración de canales (e-mail, in-app, webhook), los templates por evento, el historial de envíos con status (`sent`, `delivered`, `bounced`, `failed`), gráficos de entregas en el período y filtros por canal, destinatario y tipo de notificación. ![Configuración e historial de notificaciones multicanal](/es/assets/images/notificacoes-e49adeb5e3cf555c2f5bc7397b44c6d0.png) --- # Perfil del Usuario La página `/dashboard/profile` reúne las **preferencias personales** del operador que inició sesión: tema, idioma, zona horaria y configuraciones de notificación. A diferencia de las configuraciones de la organización (que afectan a todos los miembros), las preferencias de perfil son por usuario y se almacenan localmente y en el servidor. ## Datos de la cuenta[​](#datos-de-la-cuenta "Enlace directo al Datos de la cuenta") Muestra la información que proviene del proveedor de autenticación (Kobana OAuth): * **Nombre** y **e-mail** * **Organizaciones** a las que el usuario tiene acceso * **Roles** asignados en cada organización ## Apariencia[​](#apariencia "Enlace directo al Apariencia") * **Tema** — claro, oscuro o automático (sigue el sistema operativo). * **Idioma** — `pt-BR` o `en-US`. El cambio actualiza de inmediato los mensajes de la interfaz. ## Onboarding[​](#onboarding "Enlace directo al Onboarding") El perfil también expone los controles del onboarding interactivo: reactivar sugerencias, marcar etapas como vistas y volver a ver el checklist inicial del dashboard. ## Editor de firma de e-mail[​](#editor-de-firma-de-e-mail "Enlace directo al Editor de firma de e-mail") Incluye un editor rich-text que se usa para personalizar la firma aplicada en las comunicaciones enviadas en nombre del operador (negrita, cursiva, enlaces, imágenes, listas, tablas, etc.). ## Cómo se guardan las preferencias[​](#cómo-se-guardan-las-preferencias "Enlace directo al Cómo se guardan las preferencias") * **localStorage** — `kobana-billing-preferences` guarda el tema y el idioma para la hidratación inmediata. * **Servidor** — los cambios se guardan en la cuenta del usuario para sincronizarse entre dispositivos. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Perfil del usuario con apariencia, idioma y firma de e-mail](/es/assets/images/perfil-dcd92f056ea31bcf8f619813e41f6edc.png) --- # Rate Limiting El sistema implementa límites de solicitudes de la API para proteger la plataforma y garantizar un uso justo. ## Límites Predeterminados[​](#límites-predeterminados "Enlace directo al Límites Predeterminados") | Tipo | Por Minuto | Por Hora | | ------------------------------------- | ---------- | -------- | | **Lectura (GET)** | 200 | 5.000 | | **Escritura (POST/PUT/PATCH/DELETE)** | 60 | 1.000 | ### Límite de Burst[​](#límite-de-burst "Enlace directo al Límite de Burst") | Campo | Predeterminado | Descripción | | -------------------- | -------------- | --------------------------------- | | **Burst limit** | 20 | Máximo de solicitudes simultáneas | | **Ventana de burst** | 5 segundos | Ventana para conteo de burst | ## Configuración por Organización[​](#configuración-por-organización "Enlace directo al Configuración por Organización") Cada organización puede tener límites personalizados. Si no está configurado, usa los límites globales. ## Jerarquía[​](#jerarquía "Enlace directo al Jerarquía") 1. Configuración de la organización (si existe) 2. Configuración global predeterminada (si existe) 3. Valores hardcoded del sistema ## Operaciones[​](#operaciones "Enlace directo al Operaciones") * **Visualizar**: Ver límites actuales de la organización * **Personalizar**: Definir límites customizados * **Remover**: Volver a los límites globales * **Deshabilitar**: Desactivar rate limiting (no recomendado) --- # Reportes La central de reportes (`/dashboard/reports`) es donde los equipos de finanzas, operaciones y atención generan **extracciones tabulares** de los datos de la organización. A diferencia de [Analytics](https://docs.billing.kobana.com.br/es/es/configuracoes/analytics.md), que agrega métricas, los reportes entregan datos fila por fila listos para conciliar, auditar o armar hojas de cálculo externas. ## Reportes disponibles[​](#reportes-disponibles "Enlace directo al Reportes disponibles") * **Facturas del período** — todas las facturas con cliente, status, valor, fechas y medio de pago. * **Pagos del período** — pagos recibidos, con gateway, método, comisión y valor neto. * **Contracargos y reembolsos** — operaciones de reversión, con motivo y operador. * **Suscripciones activas** — snapshot de la base activa con plan, MRR, próximo ciclo y método de cobro. * **Churn detallado** — suscripciones canceladas en el período, con motivo y LTV final. * **Morosidad** — cuentas con factura abierta, agrupadas por rango (1-30, 31-60, 61-90, 90+). * **Conciliación de gateway** — comparativo entre lo que registró la plataforma y lo que confirmó el gateway. ## Cómo generarlos[​](#cómo-generarlos "Enlace directo al Cómo generarlos") 1. Elige el tipo de reporte. 2. Define los filtros (rango de fechas, empresa, plan, status, gateway). 3. Selecciona el formato (CSV o XLSX). 4. Confirma — la generación entra en la cola de exportaciones. 5. Cuando esté listo, el archivo queda disponible en [Exportaciones](https://docs.billing.kobana.com.br/es/es/exportacao-e-importacao/exportacoes/.md) y se envía por e-mail. Los reportes pesados se ejecutan en segundo plano para no bloquear el navegador. El status (`pending`, `processing`, `completed`, `failed`) se actualiza en tiempo real. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Central de reportes con filtros y formato de exportación](/es/assets/images/relatorios-ca30cc6680e6b8dc7cceea941823c99a.png) --- # Templates de E-mail Los templates de e-mail permiten personalizar las comunicaciones transaccionales enviadas a los clientes. ## Campos del Template[​](#campos-del-template "Enlace directo al Campos del Template") | Campo | Descripción | | ------------------ | --------------------------------------------------- | | **Nombre** | Nombre del template | | **Slug** | Identificador único | | **Tipo** | Tipo de notificación asociada | | **Asunto** | Línea de asunto (soporta variables) | | **Cuerpo HTML** | Contenido HTML del e-mail (soporta variables) | | **Cuerpo texto** | Versión en texto puro (fallback) | | **Variables** | Lista de variables utilizadas | | **Predeterminado** | Un template predeterminado por tipo de notificación | | **Activo** | Si el template está disponible | ## Variables[​](#variables "Enlace directo al Variables") Las variables son sustituidas en el asunto y cuerpo usando la sintaxis `\{{ nombre_variable \}}`: | Variable | Descripción | | ------------------------- | ------------------------------ | | `{{ customer_name }}` | Nombre del cliente | | `{{ invoice_number }}` | Número de la factura | | `{{ amount }}` | Valor en moneda | | `{{ due_date }}` | Fecha de vencimiento | | `{{ verification_url }}` | Link de verificación de e-mail | | `{{ reset_url }}` | Link de reset de contraseña | | `{{ subscription_name }}` | Nombre del plan | | `{{ trial_end_date }}` | Fecha de fin del trial | ## Operaciones[​](#operaciones "Enlace directo al Operaciones") * **Crear**: Nuevo template con nombre, slug, tipo y contenido * **Actualizar**: Editar asunto, cuerpo y variables * **Duplicar**: Copiar template con nuevo slug * **Eliminar**: No es posible eliminar el template predeterminado * **Preview**: Visualizar el template con datos de ejemplo * **Definir como predeterminado**: Marca como template predeterminado para el tipo ## Renderización[​](#renderización "Enlace directo al Renderización") 1. Obtiene el template por ID o por el tipo (usa el predeterminado) 2. Carga todas las variables del contexto 3. Sustituye todos los patrones `\{{ clave \}}` por los valores 4. Retorna asunto y cuerpo HTML renderizados ## Seguridad[​](#seguridad "Enlace directo al Seguridad") * Los caracteres especiales son escapados vía regex para prevenir ReDoS * El input del usuario es sanitizado antes de la renderización --- # Uso y Consumo La pantalla `/dashboard/usage` consolida el **consumo medido** (metered) de todos los clientes de la organización: eventos de API, mensajes enviados, transacciones procesadas, almacenamiento — cualquier métrica que el catálogo defina como "uso" y que se cobre por consumo. ## Vista consolidada[​](#vista-consolidada "Enlace directo al Vista consolidada") La tabla principal agrupa el consumo por producto y por cuenta de cobro, con: * **Producto** (con unidad de medida — llamadas, eventos, mensajes, GB) * **Cliente / cuenta de cobro** * **Cantidad en el período** * **Último evento registrado** — con tiempo relativo * **Valor estimado** — proyección del cobro para la próxima factura ## Filtros[​](#filtros "Enlace directo al Filtros") * **Rango de fechas** — por defecto, desde el inicio del mes actual hasta hoy. * **Cliente** — combobox de cuentas de cobro. * **Mostrar ceros** — alterna si las cuentas sin consumo aparecen en la lista. ## De dónde vienen los datos[​](#de-dónde-vienen-los-datos "Enlace directo al De dónde vienen los datos") Los eventos de uso llegan por: 1. **API de Usage Records** — `POST /v1/subscription_items/{id}/usage_records` (patrón tipo Stripe). 2. **Worker `usage-sync`** — se ejecuta cada hora y agrega contadores externos cuando está configurado. 3. **Importación CSV** — para cargas por lote, vía [Importaciones](https://docs.billing.kobana.com.br/es/es/exportacao-e-importacao/importacoes/.md). Cada registro de uso se vincula a un `SubscriptionItem` con producto **metered**. En el cambio de ciclo, el worker `invoice-generation` materializa el consumo del período en una línea de factura. ## Limpieza[​](#limpieza "Enlace directo al Limpieza") Los operadores con permiso pueden poner en cero los registros de uso de un cliente (útil en casos de prueba). La acción queda registrada en [Auditoría](https://docs.billing.kobana.com.br/es/es/configuracoes/auditoria.md). ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Panel de uso consolidado con consumo por producto y cliente](/es/assets/images/uso-ce9128ea7ef3d3aaa5eff04ad7c2ab6e.png) --- # Usuarios La página `/dashboard/users` lista los **usuarios del portal del cliente** — personas físicas vinculadas a una cuenta de cobro (`BillingAccount`) que pueden entrar al portal para ver facturas, pagar boletos, gestionar tarjetas y actualizar datos. A diferencia de los [Miembros](https://docs.billing.kobana.com.br/es/es/configuracoes/membros.md), que son operadores internos de la organización, los usuarios del portal son clientes finales (B2B2C). Se autentican mediante enlace mágico u OAuth Kobana y solo ven los datos de su propia cuenta de cobro. ## Qué muestra la lista[​](#qué-muestra-la-lista "Enlace directo al Qué muestra la lista") * **E-mail** del usuario * **Cuenta de cobro** vinculada (razón social o nombre del cliente) * **Status** — `pending`, `active`, `suspended` * **Último acceso** — fecha y hora de la última sesión * **Invitaciones pendientes** — enlaces que todavía no se aceptaron ## Invitar a un usuario[​](#invitar-a-un-usuario "Enlace directo al Invitar a un usuario") Desde el detalle de una [cuenta de cobro](https://docs.billing.kobana.com.br/es/es/contas/contas-de-cobranca/.md) o directamente en esta pantalla, es posible: 1. Ingresar el e-mail del contacto responsable. 2. Definir los permisos dentro del portal (ver, pagar, cambiar de plan, gestionar métodos). 3. Enviar la invitación — el usuario recibe un enlace de activación. El token de activación se almacena cifrado (`lib/crypto.ts`) y expira después de usarse o del plazo configurado. ## Reenviar y revocar[​](#reenviar-y-revocar "Enlace directo al Reenviar y revocar") * **Reenviar invitación** — genera un nuevo token y envía un nuevo e-mail. * **Suspender** — bloquea el inicio de sesión sin borrar datos. * **Eliminar** — desactiva de forma definitiva. El historial de auditoría se conserva. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Lista de usuarios del portal con e-mail, cuenta de cobro y status](/es/assets/images/usuarios-do-portal-aa1e6e82c60d643ff7e4f100e284d8a4.png) --- ## [📄️Clientes (Personas)](https://docs.billing.kobana.com.br/es/es/contas/clientes/.md) [Los clientes son representados por el modelo Persona (Person) con diferentes tipos según el contexto.](https://docs.billing.kobana.com.br/es/es/contas/clientes/.md) --- ## [📄️Clientes (Personas)](https://docs.billing.kobana.com.br/es/es/contas/clientes/.md) [Los clientes son representados por el modelo Persona (Person) con diferentes tipos según el contexto.](https://docs.billing.kobana.com.br/es/es/contas/clientes/.md) --- # Clientes (Personas) Los clientes son representados por el modelo **Persona** (`Person`) con diferentes tipos según el contexto. ## Tipos de Persona[​](#tipos-de-persona "Enlace directo al Tipos de Persona") | Tipo | Descripción | | -------------- | ----------------------------------------- | | `organization` | Tenant/organización que usa la plataforma | | `customer` | Cliente de una organización | | `contact` | Contacto secundario | ## Campos del Cliente[​](#campos-del-cliente "Enlace directo al Campos del Cliente") | Campo | Descripción | | ------------------------ | ----------------------------------------------------------- | | **Nombre** | Nombre o razón social | | **Apodo** | Nombre comercial | | **Nombre legal** | Razón social completa | | **Tipo de documento** | CPF o CNPJ | | **Número del documento** | Normalizado (solo dígitos) | | **Naturaleza** | `natural` (persona física) o `juridical` (persona jurídica) | | **Fecha de nacimiento** | Opcional | | **Direcciones** | Lista de direcciones (JSON) | | **Teléfonos** | Lista de teléfonos (JSON) | | **E-mails** | Lista de e-mails (JSON) | | **Sitios web** | Lista de websites (JSON) | | **Tags** | Lista de tags para categorización | | **Notas** | Observaciones internas | | **Datos personalizados** | Campos customizados (JSON) | ## Jerarquía[​](#jerarquía "Enlace directo al Jerarquía") Los clientes pertenecen a una organización vía el campo `parent_id`: ``` Organización (type=organization, parentId=null) ├── Cliente A (type=customer, parentId=org_id) ├── Cliente B (type=customer, parentId=org_id) └── Contacto (type=contact, parentId=org_id) ``` ## Validaciones[​](#validaciones "Enlace directo al Validaciones") * Número de documento único dentro de la organización * Código externo (`external_id`) único por organización * Restricciones en el formato del documento: CPF (11 dígitos) o CNPJ (14 dígitos) ## Capturas de pantalla[​](#capturas-de-pantalla "Enlace directo al Capturas de pantalla") ### Lista de clientes[​](#lista-de-clientes "Enlace directo al Lista de clientes") La pantalla `/dashboard/customers` lista los clientes de la organización con búsqueda por nombre, documento o e-mail. La tabla muestra el documento, el e-mail, el total de cuentas de cobro vinculadas y el MRR consolidado. ![Lista de clientes con nombre, documento y cuentas de cobro](/es/assets/images/clientes-78e3677f85ef1959b6dec2ff94c9eb26.png) ### Detalle del cliente[​](#detalle-del-cliente "Enlace directo al Detalle del cliente") La página `/dashboard/customers/[id]` reúne los datos de registro, las cuentas de cobro vinculadas, suscripciones, facturas, pagos, NF-e y auditoría — todo en un único contexto para soporte y finanzas. ![Detalle de un cliente con pestañas de cobro, suscripciones y facturas](/es/assets/images/cliente-detalhe-8477adfe7b1499264110564da91b7c24.png) --- # Cuentas de Cobro Las cuentas de cobro (BillingAccount) representan la relación financiera entre una organización y su cliente. Cada cuenta posee suscripciones, facturas, pagos y métodos de pago. ## Campos[​](#campos "Enlace directo al Campos") | Campo | Descripción | | ------------------- | --------------------------------------------------------- | | **Organización** | Organización propietaria (obligatorio) | | **Persona** | Cliente asociado (tipo=customer) | | **ID externo** | Identificador para integraciones (único por organización) | | **Moneda** | Moneda de cobro (predeterminado: BRL) | | **E-mail de cobro** | E-mail para recibir facturas | | **Días de plazo** | Plazo de pago en días (predeterminado: 10) | | **Auto-cobro** | Si las facturas se cobran automáticamente | | **Saldo** | Saldo de créditos/débitos de la cuenta | | **Status** | `active`, `suspended` o `closed` | ### Configuración Fiscal[​](#configuración-fiscal "Enlace directo al Configuración Fiscal") | Campo | Descripción | | --------------------------- | ------------------------------- | | **Exento de impuestos** | Si el cliente está exento | | **Certificado de exención** | Documento de exención | | **Tipo fiscal del cliente** | Clasificación tributaria | | **Retener ISS** | Flag de retención de ISS | | **Retener IRRF** | Flag de retención de IRRF | | **Retener CSRF** | Flag de retención de CSRF | | **Retener INSS** | Flag de retención de INSS | | **Inscripción municipal** | Número de inscripción municipal | ## Status y Ciclo de Vida[​](#status-y-ciclo-de-vida "Enlace directo al Status y Ciclo de Vida") ``` active → suspended ↔ active ↓ closed ``` | Status | Descripción | | ------------- | -------------------------------------------------------------- | | **active** | Cuenta operacional | | **suspended** | Suspendida por morosidad o manualmente. Suscripciones pausadas | | **closed** | Cerrada permanentemente | ### Suspensión[​](#suspensión "Enlace directo al Suspensión") * Define `suspended_at` y `suspension_reason` * Todas las suscripciones activas son pausadas * Notificación enviada al cliente * Puede ser reactivada manualmente ### Cierre[​](#cierre "Enlace directo al Cierre") * Todas las suscripciones deben estar inactivas/canceladas * Permanente (soft delete vía `deletedAt`) ## Unicidad[​](#unicidad "Enlace directo al Unicidad") * Una cuenta de cobro por cliente por organización * ID externo único por organización * Documento del cliente único por organización ## Estadísticas[​](#estadísticas "Enlace directo al Estadísticas") El dashboard muestra contadores por status: * Total de cuentas * Cuentas activas * Cuentas suspendidas * Cuentas con suscripción activa --- # Empresas En `/dashboard/companies` la organización registra las **personas jurídicas emisoras** — empresas que firman contratos, facturas y NF-e. Una organización puede tener varias empresas (casa matriz, sucursales o CNPJ distintos del mismo grupo) y definir una como predeterminada para los cobros. ## Datos de registro[​](#datos-de-registro "Enlace directo al Datos de registro") Cada empresa concentra: * **Razón social y nombre comercial** * **CNPJ** e inscripciones municipal y estatal * **Dirección completa** (CEP, calle, número, complemento, barrio, ciudad, UF) * **Régimen tributario** — Simples Nacional, Lucro Presumido, Lucro Real, MEI * **Anexo del Simples Nacional** (cuando corresponde) y factor R * **Contacto fiscal** — e-mail y teléfono para el envío de NF-e y comunicaciones fiscales * **Status** — activa o desactivada ## Empresa predeterminada[​](#empresa-predeterminada "Enlace directo al Empresa predeterminada") Una de las empresas se marca como predeterminada. Toda nueva factura o NF-e usa esa empresa como emisora, excepto cuando el cliente, el plan o la suscripción especifican otra. Cambiar la empresa predeterminada no altera las facturas ni las suscripciones ya existentes. ## Multiempresa[​](#multiempresa "Enlace directo al Multiempresa") El soporte multiempresa permite que un grupo opere CNPJ distintos en el mismo panel: * **Catálogo separado por empresa** — cada empresa puede tener sus propios productos, ítems de servicio y reglas tributarias. * **Apuración fiscal aislada** — los períodos fiscales y el DAS se calculan por empresa. * **Facturas emitidas por la empresa correcta** — el cliente ve el CNPJ correcto en la factura y en el boleto. ## Desactivación[​](#desactivación "Enlace directo al Desactivación") Las empresas pueden desactivarse (no eliminarse) para dejar de recibir nuevas facturas manteniendo accesible el historial fiscal. La acción queda registrada en [Auditoría](https://docs.billing.kobana.com.br/es/es/configuracoes/auditoria.md). ## Captura de pantalla — lista[​](#captura-de-pantalla--lista "Enlace directo al Captura de pantalla — lista") ![Lista de empresas registradas con CNPJ y régimen tributario](/es/assets/images/empresas-89a0c8213e9e210e918f51fbda9fc323.png) ## Captura de pantalla — detalle[​](#captura-de-pantalla--detalle "Enlace directo al Captura de pantalla — detalle") La página de detalle (`/dashboard/companies/[id]`) reúne los datos fiscales, contactos, dirección y el historial de facturas y NF-e emitidas por la empresa. ![Detalle de una empresa con datos fiscales y pestañas de facturas y NF-e](/es/assets/images/empresa-detalhe-07489c6db8aa2ff604496db293c5631b.png) --- # Organizaciones Las organizaciones son los tenants (inquilinos) de la plataforma. Cada organización es un negocio que usa Facturación Automática para cobrar a sus propios clientes. ## Campos de la Organización[​](#campos-de-la-organización "Enlace directo al Campos de la Organización") | Campo | Descripción | | ------------------------ | ----------------------------------------------- | | **ID externo** | Identificador único para integraciones externas | | **Nombre** | Nombre de la organización | | **Tipo de documento** | CPF o CNPJ | | **Número del documento** | CPF o CNPJ (normalizado, solo dígitos) | | **E-mail** | E-mail principal de contacto | | **Teléfono** | Teléfono de contacto | | **Direcciones** | Lista de direcciones | | **Status** | `active` (predeterminado) | ## Bootstrap Automático[​](#bootstrap-automático "Enlace directo al Bootstrap Automático") Al crear una organización, el sistema automáticamente: 1. **Crea la empresa predeterminada** con los mismos datos de registro 2. **Crea los roles de dashboard** predeterminados (owner, admin, viewer) 3. **Crea el usuario propietario** con el e-mail de la organización ## Ciclo de Vida[​](#ciclo-de-vida "Enlace directo al Ciclo de Vida") * **Crear**: Proporciona datos de registro, recibe organización lista con empresa y usuarios * **Actualizar**: Nombre, contacto y direcciones editables * **Eliminar**: Soft delete (solo si no hay cuentas de cobro activas) ## Modelo de Datos[​](#modelo-de-datos "Enlace directo al Modelo de Datos") La organización utiliza una **Persona** (`Person` con `type=organization`) para almacenar los datos de registro. Esto permite que organizaciones y clientes compartan el mismo modelo flexible de datos. --- # Portal del Cliente El portal del cliente permite que los clientes finales de cada organización gestionen sus suscripciones, facturas y métodos de pago de forma autónoma. ## Acceso[​](#acceso "Enlace directo al Acceso") El portal es accedido vía URL personalizada de la organización. Cada organización configura su portal con branding, dominio y funcionalidades específicas. ## Funcionalidades del Portal[​](#funcionalidades-del-portal "Enlace directo al Funcionalidades del Portal") * Visualizar y pagar facturas * Gestionar suscripciones (pausar, cancelar, si está permitido) * Actualizar métodos de pago * Visualizar historial de transacciones * Aceptar/rechazar propuestas comerciales ## Usuario del Portal (PortalUser)[​](#usuario-del-portal-portaluser "Enlace directo al Usuario del Portal (PortalUser)") | Campo | Descripción | | ------------------- | -------------------------------- | | **E-mail** | Único por cuenta de cobro | | **Cuenta de cobro** | Vínculo con la cuenta financiera | | **Solo SSO** | Si es true, login solo vía SSO | | **Status** | Estado del usuario | ### Status del Usuario[​](#status-del-usuario "Enlace directo al Status del Usuario") | Status | Descripción | | ---------------------- | ----------------------------------------- | | `active` | Usuario activo con acceso completo | | `pending_verification` | Esperando verificación de e-mail (signup) | | `pending_invitation` | Esperando aceptar invitación | | `suspended` | Cuenta suspendida | | `locked` | Bloqueado por intentos de login fallidos | ### Seguridad[​](#seguridad "Enlace directo al Seguridad") * Contraseñas hasheadas con bcrypt * Tokens de verificación/reset basados en HMAC * Bloqueo automático después de intentos de login fallidos * Tokens de verificación expiran en 24 horas * Tokens de invitación expiran en 7 días ## Invitaciones[​](#invitaciones "Enlace directo al Invitaciones") El sistema de invitaciones permite que la organización envíe invitaciones por e-mail: 1. La invitación es enviada con un token temporal (7 días) 2. El destinatario acepta y define su contraseña 3. El status cambia a `active` 4. Invitaciones pendientes pueden ser canceladas o reenviadas ## Registro Self-Service[​](#registro-self-service "Enlace directo al Registro Self-Service") Las organizaciones pueden habilitar registro público: 1. El cliente accede a la página de signup vía slug único 2. Informa CNPJ (validado en la Receita Federal vía API minhareceita.org) 3. Completa datos de la empresa y administrador 4. Un e-mail de verificación es enviado 5. Después de la verificación, el acceso es liberado ### Validación de CNPJ[​](#validación-de-cnpj "Enlace directo al Validación de CNPJ") * El CNPJ debe estar con situación registral "Ativa" * El CNPJ no puede estar ya registrado en la organización * CNPJs con situación "Baixada" son bloqueados ## Configuración del Portal[​](#configuración-del-portal "Enlace directo al Configuración del Portal") | Configuración | Descripción | | ------------------------ | -------------------------------------------------- | | **Nombre de la empresa** | Nombre mostrado en el portal | | **Logo** | Logotipo claro y oscuro | | **Colores** | Tema claro y oscuro (HSL) | | **Idiomas** | Idiomas disponibles (predeterminado: pt-BR, en-US) | | **Pagos** | Métodos habilitados (tarjeta, boleto, PIX) | | **Suscripciones** | Permitir pausar/cancelar | | **Invitaciones** | Habilitar invitaciones y dominios permitidos | | **Signup** | Slug y habilitar registro público | | **SSO** | Clave pública, algoritmo y emisor | ### SSO (Single Sign-On)[​](#sso-single-sign-on "Enlace directo al SSO (Single Sign-On)") El portal soporta SSO vía JWT: * Algoritmos soportados: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 * Configurar clave pública PEM y emisor (iss claim) * Usuarios SSO-only no necesitan contraseña ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") La pantalla `/dashboard/portal` reúne la configuración visual y funcional del portal del cliente: logo, paleta de colores para tema claro y oscuro, idiomas soportados, dominio personalizado, texto del e-mail de invitación, métodos de pago habilitados, autenticación (enlace mágico, OAuth, JWT SSO) y qué áreas puede ver/editar el cliente. ![Configuración visual y funcional del portal del cliente](/es/assets/images/portal-do-cliente-e2a82af63734f30ed0ee98d2667081d0.png) Para la documentación de las pantallas que ve el cliente final, consulta [Portal del Cliente](https://docs.billing.kobana.com.br/es/es/portal.md). --- ## [📄️Códigos de Descuento](https://docs.billing.kobana.com.br/es/es/cupons-e-descontos/codigos-de-desconto/.md) [Los códigos de descuento se aplican directamente a suscripciones en el momento de la creación, ofreciendo descuentos recurrentes o puntuales.](https://docs.billing.kobana.com.br/es/es/cupons-e-descontos/codigos-de-desconto/.md) --- ## [📄️Códigos de Descuento](https://docs.billing.kobana.com.br/es/es/cupons-e-descontos/codigos-de-desconto/.md) [Los códigos de descuento se aplican directamente a suscripciones en el momento de la creación, ofreciendo descuentos recurrentes o puntuales.](https://docs.billing.kobana.com.br/es/es/cupons-e-descontos/codigos-de-desconto/.md) --- # Códigos de Descuento Los códigos de descuento se aplican directamente a suscripciones en el momento de la creación, ofreciendo descuentos recurrentes o puntuales. ## Campos[​](#campos "Enlace directo al Campos") | Campo | Descripción | | --------------------- | ------------------------------------------------- | | **Código** | Código único, mayúsculas | | **Nombre** | Nombre del descuento | | **Descripción** | Detalles del descuento | | **Tipo** | `percentage` o `fixed_amount` | | **Valor fijo** | Para tipo `fixed_amount` | | **Porcentaje** | Para tipo `percentage` (máx 100%) | | **Duración** | `once`, `repeating` o `forever` | | **Duración en meses** | Para `repeating`, cuántos meses dura el descuento | | **Máximo de canjes** | Total global de usos permitidos | | **Veces canjeado** | Contador de usos | | **Válido de / hasta** | Período de validez | | **Status** | `active`, `expired` o `depleted` | ## Duración del Descuento[​](#duración-del-descuento "Enlace directo al Duración del Descuento") | Duración | Descripción | | ----------- | ------------------------------------------------------------ | | `once` | Aplicado solo en la primera factura | | `repeating` | Aplicado por N meses consecutivos | | `forever` | Aplicado indefinidamente mientras la suscripción esté activa | ## Restricciones[​](#restricciones "Enlace directo al Restricciones") | Restricción | Descripción | | ------------------- | --------------------------------------------- | | **Valor mínimo** | Valor mínimo de la suscripción para usar | | **Solo primer uso** | Válido solo para nuevos clientes | | **Ciclos válidos** | Qué ciclos de facturación acepta el descuento | ## Aplicación[​](#aplicación "Enlace directo al Aplicación") | Filtro | Descripción | | ------------- | ----------------------------------------------- | | **Productos** | Lista de productos donde el descuento se aplica | | **Planes** | Lista de planes donde el descuento se aplica | ## Status[​](#status "Enlace directo al Status") | Status | Descripción | | ---------- | ---------------------------- | | `active` | Válido y utilizable | | `expired` | Fuera del período de validez | | `depleted` | Límite de canjes alcanzado | --- # Cupones Los cupones son códigos promocionales que los clientes pueden canjear para obtener descuentos en compras y facturas. ## Campos del Cupón[​](#campos-del-cupón "Enlace directo al Campos del Cupón") | Campo | Descripción | | ----------------------- | ------------------------------------------------------- | | **Código** | Código único, almacenado en mayúsculas | | **Nombre** | Nombre interno del cupón | | **Descripción** | Detalles de la promoción | | **Tipo de descuento** | `percentage` (porcentual) o `fixed_amount` (valor fijo) | | **Valor del descuento** | Porcentaje (0–100) o valor en BRL, según el tipo | | **Moneda** | Predeterminado: BRL | | **Compra mínima** | Valor mínimo del pedido para usar el cupón | | **Descuento máximo** | Tope del descuento (para cupones porcentuales) | | **Límite de uso total** | Máximo de canjes permitidos | | **Límite por cliente** | Máximo de canjes por cuenta de cobro | | **Válido de / hasta** | Período de validez | | **Se aplica a** | Planes y/o productos específicos (JSON) | | **Excluye** | Planes y/o productos excluidos (JSON) | | **Activo** | Si el cupón está habilitado | ## Validación de Cupón[​](#validación-de-cupón "Enlace directo al Validación de Cupón") Al validar un cupón, el sistema verifica: 1. El cupón existe y el código coincide 2. El cupón está activo (`isActive = true`) 3. Está dentro del período de validez 4. El límite de uso total no fue alcanzado 5. El límite de uso por cliente no fue alcanzado 6. La compra alcanza el valor mínimo ### Cálculo del Descuento[​](#cálculo-del-descuento "Enlace directo al Cálculo del Descuento") ``` Si porcentual: descuento = subtotal × porcentaje / 100 Si fijo: descuento = valor_del_descuento Aplica tope: descuento = min(descuento, maxDiscountCents) No excede subtotal: descuento = min(descuento, subtotal) ``` ## Canjeando un Cupón[​](#canjeando-un-cupón "Enlace directo al Canjeando un Cupón") Al aplicar un cupón: 1. Valida todas las condiciones 2. Crea un registro de `CouponRedemption` con el valor del descuento 3. Incrementa el contador de uso del cupón 4. Retorna el canje con el valor descontado El proceso es **atómico** (transacción) para prevenir condiciones de carrera. ## Operaciones[​](#operaciones "Enlace directo al Operaciones") * **Activar/Desactivar**: Controla si el cupón puede ser validado * **Eliminar**: Solo si nunca fue utilizado (ningún canje registrado) * **Actualizar**: Código, nombre, límites, fechas y valores editables ## Reporte de Canjes[​](#reporte-de-canjes "Enlace directo al Reporte de Canjes") Para cada cupón, el sistema rastrea: * Quién canjeó (cuenta de cobro) * Cuándo canjeó * Valor del descuento aplicado * Factura asociada (opcional) ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") La pantalla `/dashboard/coupons` lista todos los cupones de la organización, con código, tipo de descuento, valor, vigencia, número de canjes y status. La interfaz permite crear cupones porcentuales o de valor fijo, con límite total y por cliente. ![Lista de cupones con tipo de descuento, vigencia y canjes](/es/assets/images/cupons-f4e9148af0f45d9e5b6937a70ad4efba.png) --- # 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 Facturación Automática salen del contenido publicado, en el idioma que elijas. ``` https://docs.billing.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 clientes, suscripciones ni facturas y no cambia nada. Para que un agente opere Facturación Automática, usa el **MCP del producto** (`mcp.billing.kobana.com.br`), que pide inicio de sesión y respeta tus permisos. Consulta [MCP › Clientes](https://docs.billing.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/assinaturas`) o la URL completa | | `list_pages` | Lista todas las páginas, con ruta y resumen | `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.billing.kobana.com.br/mcp" ``` ### Claude Code[​](#claude-code "Enlace directo al Claude Code") ``` claude mcp add --transport http kobana-billing-docs https://docs.billing.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-billing-docs": { "url": "https://docs.billing.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-billing-docs": { "type": "http", "url": "https://docs.billing.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.billing.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-billing-docs": { "type": "http", "url": "https://docs.billing.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 funciona el prorrateo cuando un cliente cambia de plan a mitad del ciclo?" * "¿Qué eventos de webhook existen para facturas y cómo valido la firma?" * "¿Cómo configuro la emisión de NF-e con certificado digital?" * "Arma un ejemplo de llamada a la API para crear una suscripción, según la documentación." ## Probar sin cliente[​](#probar-sin-cliente "Enlace directo al Probar sin cliente") ``` curl -s https://docs.billing.kobana.com.br/mcp \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"webhook","locale":"es"}}}' ``` ## Límites[​](#límites "Enlace directo al Límites") * Las páginas de referencia de cada endpoint de la API (`/api/v1/...`) no están en el MCP. La fuente legible por máquina de la API es la especificación OpenAPI, en [API › OpenAPI](https://docs.billing.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.billing.kobana.com.br/es/llms-full.txt). --- ## [📄️Exportaciones](https://docs.billing.kobana.com.br/es/es/exportacao-e-importacao/exportacoes/.md) [Exporte datos de la plataforma en diferentes formatos para reportes e integraciones.](https://docs.billing.kobana.com.br/es/es/exportacao-e-importacao/exportacoes/.md) --- ## [📄️Exportaciones](https://docs.billing.kobana.com.br/es/es/exportacao-e-importacao/exportacoes/.md) [Exporte datos de la plataforma en diferentes formatos para reportes e integraciones.](https://docs.billing.kobana.com.br/es/es/exportacao-e-importacao/exportacoes/.md) --- # Exportaciones Exporte datos de la plataforma en diferentes formatos para reportes e integraciones. ## Recursos Exportables[​](#recursos-exportables "Enlace directo al Recursos Exportables") | Recurso | Descripción | | ---------------- | ---------------------------------- | | `products` | Catálogo de productos con precios | | `customers` | Lista de clientes/cuentas de cobro | | `invoices` | Facturas con line items | | `subscriptions` | Suscripciones activas | | `plans` | Definiciones de planes | | `service_items` | Ítems de servicio (fiscal) | | `coupons` | Códigos de cupón | | `product_groups` | Grupos de productos | ## Formatos Soportados[​](#formatos-soportados "Enlace directo al Formatos Soportados") | Formato | Descripción | | ------- | ------------------------------------------- | | `csv` | Valores separados por coma (predeterminado) | | `xlsx` | Planilla Excel | | `json` | JSON estructurado | ## Status de la Exportación[​](#status-de-la-exportación "Enlace directo al Status de la Exportación") | Status | Descripción | | ------------ | --------------------------- | | `pending` | En cola para procesamiento | | `processing` | Siendo procesado | | `completed` | Listo para descarga | | `failed` | Error durante procesamiento | ## Flujo[​](#flujo "Enlace directo al Flujo") 1. Cree una exportación informando el tipo de recurso y formato 2. El job es encolado para procesamiento asíncrono 3. El worker busca los datos, aplica filtros y genera el archivo 4. El archivo es almacenado en S3 con validez de **7 días** 5. La exportación es actualizada con la URL de descarga ## Campos de la Exportación[​](#campos-de-la-exportación "Enlace directo al Campos de la Exportación") | Campo | Descripción | | ---------------------- | ------------------------------- | | **Tipo de recurso** | Qué exportar | | **Formato** | CSV, XLSX o JSON | | **Status** | Estado del procesamiento | | **Nombre del archivo** | Generado automáticamente | | **URL del archivo** | Link para descarga | | **Tamaño** | Tamaño en bytes | | **Total de líneas** | Registros exportados | | **Filtros** | Filtros aplicados | | **Expira en** | 7 días después de la conclusión | ## Limpieza Automática[​](#limpieza-automática "Enlace directo al Limpieza Automática") Las exportaciones expiradas son automáticamente removidas (archivo en S3 + registro en la base de datos). --- # Importaciones Importe datos en masa a la plataforma vía carga de archivos. ## Recursos Importables[​](#recursos-importables "Enlace directo al Recursos Importables") Los mismos recursos soportados en las exportaciones: productos, clientes, facturas, suscripciones, planes, ítems de servicio, cupones y grupos de productos. ## Status de la Importación[​](#status-de-la-importación "Enlace directo al Status de la Importación") | Status | Descripción | | ----------------------- | ----------------------------------------- | | `pending` | En cola | | `processing` | Siendo procesado | | `completed` | Éxito, sin errores | | `completed_with_errors` | Éxito parcial, algunos registros fallaron | | `failed` | Error crítico, procesamiento abortado | ## Flujo[​](#flujo "Enlace directo al Flujo") 1. Cargue el archivo (CSV, XLSX o JSON) 2. El archivo es almacenado en S3 3. El job es encolado para procesamiento asíncrono 4. El worker lee el archivo, valida cada línea y crea/actualiza los registros 5. Los errores son rastreados por línea 6. La importación es actualizada con el resultado ## Seguimiento de Progreso[​](#seguimiento-de-progreso "Enlace directo al Seguimiento de Progreso") | Campo | Descripción | | --------------------------- | ------------------------------ | | **Total de líneas** | Total en el archivo | | **Líneas procesadas** | Progreso actual | | **Éxito** | Registros importados con éxito | | **Errores** | Registros con falla | | **Detalles de los errores** | Línea y motivo de cada error | ## Ejemplo de Errores[​](#ejemplo-de-errores "Enlace directo al Ejemplo de Errores") ``` [ { "row": 5, "error": "Nombre del producto inválido" }, { "row": 12, "error": "CNPJ duplicado" } ] ``` --- ## [📄️Créditos](https://docs.billing.kobana.com.br/es/es/faturas-e-pagamentos/creditos/.md) [El sistema de créditos permite agregar saldo en la cuenta del cliente que se aplica automáticamente en facturas futuras.](https://docs.billing.kobana.com.br/es/es/faturas-e-pagamentos/creditos/.md) --- ## [📄️Créditos](https://docs.billing.kobana.com.br/es/es/faturas-e-pagamentos/creditos/.md) [El sistema de créditos permite agregar saldo en la cuenta del cliente que se aplica automáticamente en facturas futuras.](https://docs.billing.kobana.com.br/es/es/faturas-e-pagamentos/creditos/.md) --- # Créditos El sistema de créditos permite agregar saldo en la cuenta del cliente que se aplica automáticamente en facturas futuras. ## Tipos de Crédito[​](#tipos-de-crédito "Enlace directo al Tipos de Crédito") | Tipo | Descripción | | ------------- | --------------------------------------- | | `promotional` | Créditos promocionales (pueden expirar) | | `adjustment` | Ajustes administrativos de saldo | | `refund` | Crédito generado por reembolso | | `manual` | Adición manual de crédito | ## Campos del Crédito[​](#campos-del-crédito "Enlace directo al Campos del Crédito") | Campo | Descripción | | ------------------- | -------------------------------------------- | | **Cuenta de cobro** | Cliente que recibe el crédito | | **Empresa** | Empresa emisora (para alcance de aplicación) | | **Tipo** | Tipo del crédito | | **Valor** | Valor total del crédito | | **Valor restante** | Saldo aún no utilizado | | **Descripción** | Motivo o descripción del crédito | | **Expira en** | Fecha de expiración (null = nunca expira) | ## Aplicación Automática de Créditos[​](#aplicación-automática-de-créditos "Enlace directo al Aplicación Automática de Créditos") Cuando una factura es **finalizada**, el sistema aplica créditos automáticamente usando la estrategia **FIFO**: ### Orden de Aplicación[​](#orden-de-aplicación "Enlace directo al Orden de Aplicación") 1. Créditos que expiran más pronto (prioridad para evitar pérdida) 2. Créditos más antiguos (cuando la fecha de expiración es igual) ### Reglas de Alcance por Empresa[​](#reglas-de-alcance-por-empresa "Enlace directo al Reglas de Alcance por Empresa") * Si la factura tiene empresa: aplica créditos de la misma empresa **y** créditos sin empresa * Si la factura no tiene empresa: aplica solo créditos sin empresa ### Proceso (en transacción atómica)[​](#proceso-en-transacción-atómica "Enlace directo al Proceso (en transacción atómica)") 1. Busca créditos no expirados con saldo disponible 2. Para cada crédito: aplica el mínimo entre (saldo del crédito, valor restante de la factura) 3. Crea registro de `CreditApplication` para trazabilidad 4. Actualiza el saldo del crédito y de la factura 5. Si la factura fue totalmente pagada: marca como `paid` 6. Actualiza el `balance` de la cuenta de cobro ## Restauración de Créditos[​](#restauración-de-créditos "Enlace directo al Restauración de Créditos") Cuando una factura es **anulada** (void), todos los créditos aplicados son restaurados: * Cada crédito tiene su saldo restante incrementado * Los registros de `CreditApplication` son eliminados * La factura vuelve al status `open` * El saldo de la cuenta de cobro es actualizado ## Expiración de Créditos[​](#expiración-de-créditos "Enlace directo al Expiración de Créditos") Los créditos con fecha de expiración son automáticamente reducidos a cero cuando la fecha pasa: * El `amount_remaining` se define como 0 * El saldo de la cuenta de cobro es reducido ## Operaciones[​](#operaciones "Enlace directo al Operaciones") * **Agregar crédito**: Crea crédito e incrementa el saldo de la cuenta * **Ajustar saldo**: Agrega o sustrae créditos * **Crédito de reembolso**: Crea crédito del tipo `refund` * **Crédito promocional**: Crea crédito con expiración opcional * **Eliminar crédito**: Solo si nunca fue utilizado (saldo restante = valor total) * **Consultar saldo disponible**: Retorna total disponible, créditos activos y créditos por expirar ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") La pantalla `/dashboard/credits` lista todos los créditos de la organización, con filtros por status, origen (downgrade, reembolso, ajuste manual, promoción), cuenta de cobro y período. La interfaz también permite crear créditos sueltos y ver el saldo agregado por cliente. ![Lista de créditos con origen, saldo y aplicaciones](/es/assets/images/creditos-3af3d87312decbb7c2239225a1a764a4.png) --- # Facturas Las facturas representan cobros enviados a los clientes. Cada factura contiene line items que detallan los productos y valores cobrados. ## Estados de la Factura[​](#estados-de-la-factura "Enlace directo al Estados de la Factura") ``` draft → open → paid ↓ ↓ void uncollectible ``` | Status | Descripción | | ----------------- | ---------------------------------------------------------------------- | | **draft** | Borrador. Puede ser editada, se pueden agregar/eliminar ítems | | **open** | Finalizada. Cobrable, puede recibir pagos y tener créditos aplicados | | **paid** | Totalmente pagada | | **void** | Anulada. Los créditos aplicados son restaurados, las cuotas canceladas | | **uncollectible** | Marcada como incobrable (write-off) | ## Campos de la Factura[​](#campos-de-la-factura "Enlace directo al Campos de la Factura") ### Identificación[​](#identificación "Enlace directo al Identificación") | Campo | Descripción | | ------------------- | -------------------------------------------------- | | **Número** | Número secuencial único (formato: INV-YYYY-NNNNNN) | | **Cuenta de cobro** | Cliente que recibirá la factura | | **Suscripción** | Suscripción asociada (opcional) | | **Empresa** | Empresa emisora (para multi-empresa) | ### Valores (en BRL)[​](#valores-en-brl "Enlace directo al Valores (en BRL)") | Campo | Descripción | | ------------------ | ------------------------------------------------------ | | **Subtotal** | Suma de los line items antes de descuentos e impuestos | | **Descuento** | Total de descuento aplicado | | **Impuestos** | Total de impuestos calculados | | **Total retenido** | Impuestos retenidos (PIS/COFINS/IRPJ) | | **Valor neto** | Valor neto después de retenciones | | **Total** | Valor final (subtotal - descuento + impuestos) | | **Valor adeudado** | Monto total a pagar | | **Valor pagado** | Monto ya recibido | | **Valor restante** | Saldo pendiente | ### Configuración[​](#configuración "Enlace directo al Configuración") | Campo | Descripción | | ------------------------ | ----------------------------------------------------------------------------- | | **Método de cobro** | `charge_automatically`, `manual_charge` o `manual_invoice` | | **Razón de cobro** | `subscription_cycle`, `subscription_create`, `subscription_update` o `manual` | | **Política de NF-e** | `disabled`, `on_finalization`, `on_full_payment` o `per_installment` | | **Fecha de vencimiento** | Calculada a partir de los días de plazo del cliente | ## Line Items[​](#line-items "Enlace directo al Line Items") Cada factura contiene ítems de línea que detallan los cobros: | Campo | Descripción | | ------------------ | --------------------------------------- | | **Tipo** | `subscription` o `invoiceitem` | | **Descripción** | Texto descriptivo | | **Cantidad** | Cantidad cobrada | | **Valor unitario** | Precio por unidad | | **Valor total** | Cantidad × valor unitario | | **Proration** | Si el ítem es un prorrateo proporcional | | **Período** | Inicio y fin del período cobrado | ## Operaciones[​](#operaciones "Enlace directo al Operaciones") ### Crear Factura[​](#crear-factura "Enlace directo al Crear Factura") Al crear una factura, informe: * Cuenta de cobro (obligatorio) * Line items con descripción, cantidad y valor * Fecha de vencimiento (o usa los días de plazo del cliente) * Cuotas (opcional, mínimo 2, la suma debe ser igual al total) * Política de NF-e (opcional) El número de la factura se genera automáticamente usando lock advisory de PostgreSQL para prevenir duplicación. ### Editar Factura[​](#editar-factura "Enlace directo al Editar Factura") Las facturas `draft` y `open` aceptan la edición de todos los campos. Una vez liquidada — `paid`, `void` o `uncollectible` — la factura mantiene sus condiciones bloqueadas: | Estado | Campos editables | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **draft**, **open** | Todos | | **paid** | ID público, suscripción, descripción, ítems, metadatos, ID externo, política de emisión de la NF-e y línea de descripción de la NF-e | | **void**, **uncollectible** | ID público, suscripción, descripción, ítems, metadatos e ID externo | Empresa, método de cobro, política de intereses y multa, vencimiento, período y pie de página quedan bloqueados. Los ítems pueden corregirse (por la API o con la edición inline de la pestaña de ítems, tras un aviso), pero no mientras la factura tenga una NF-e emitida o en proceso — cancélela antes. La regla vale en el dashboard, la API y el MCP: cambiar un campo bloqueado responde `422` con el código `INVOICE_FIELD_LOCKED`, listando los campos rechazados. Reenviar un campo bloqueado con el mismo valor ya guardado no se considera un cambio. ### Finalizar (`draft` → `open`)[​](#finalizar-draft--open "Enlace directo al finalizar-draft--open") Al finalizar una factura: 1. Valida que exista al menos 1 line item 2. Valida que la suma de las cuotas = total (si tiene cuotas) 3. Calcula impuestos automáticamente 4. **Aplica créditos automáticamente** (FIFO: vencimiento más próximo primero, luego más antiguo) 5. Si el método es `charge_automatically`: intenta cobrar inmediatamente ### Marcar como Pagada[​](#marcar-como-pagada "Enlace directo al Marcar como Pagada") * Soporta pagos parciales * Al recibir el valor total, el status cambia a `paid` * Crea un registro de transacción ### Anular (Void)[​](#anular-void "Enlace directo al Anular (Void)") Al anular una factura: * Los créditos aplicados son restaurados automáticamente * Las cuotas pendientes son canceladas * El motivo de la anulación es almacenado ### Deshacer Pago[​](#deshacer-pago "Enlace directo al Deshacer Pago") Revierte una factura de `paid` a `open`: * Restablece el valor pagado a cero * Crea una transacción de ajuste (valor negativo) * Almacena el motivo en el metadata ### Marcar como Incobrable[​](#marcar-como-incobrable "Enlace directo al Marcar como Incobrable") Marca la factura como write-off. Irreversible. Ningún intento automático de pago será realizado. ## Generación Automática de Números[​](#generación-automática-de-números "Enlace directo al Generación Automática de Números") Los números de factura se generan secuencialmente por año usando advisory locks de PostgreSQL. Formato: `INV-\{año\}-\{secuencial con 6 dígitos\}`. Ejemplo: `INV-2026-000147` ## Capturas de pantalla[​](#capturas-de-pantalla "Enlace directo al Capturas de pantalla") ### Lista de facturas[​](#lista-de-facturas "Enlace directo al Lista de facturas") La pantalla `/dashboard/invoices` lista todas las facturas con filtros por status, cuenta de cobro, empresa emisora, período y medio de pago. Cada fila muestra el número, el cliente, el valor, el vencimiento, el status y acciones rápidas (descargar PDF, copiar boleto/PIX, marcar como pagada). ![Lista de facturas del dashboard con filtros y acciones](/es/assets/images/faturas-b49fc1c78dd0e435f214fd0fe160308a.png) ### Detalle de la factura[​](#detalle-de-la-factura "Enlace directo al Detalle de la factura") La página `/dashboard/invoices/[id]` muestra la factura completa: ítems (con cantidad y valor unitario), totales, descuentos, créditos aplicados, impuestos retenidos, historial de pagos, NF-e vinculada y línea de tiempo de eventos. ![Detalle de una factura con ítems, totales e historial](/es/assets/images/fatura-detalhe-dda3e2b8c4c8b78dd0f478663f33deb9.png) --- # Métodos de Pago Cada cuenta de cobro puede tener múltiples métodos de pago almacenados. Uno de ellos se marca como **predeterminado** para cobros automáticos. ## Tipos Soportados[​](#tipos-soportados "Enlace directo al Tipos Soportados") | Tipo | Descripción | Cobro Automático | | ------------------ | ------------------------------- | ---------------- | | **card** | Tarjeta de crédito/débito | Sí | | **bank\_slip** | Boleto bancario | No | | **pix** | PIX (transferencia instantánea) | No | | **bank\_transfer** | Transferencia bancaria | No | > **Nota**: Solo la tarjeta de crédito soporta cobro automático (`charge_automatically`). ## Tarjeta de Crédito[​](#tarjeta-de-crédito "Enlace directo al Tarjeta de Crédito") ### Datos Almacenados[​](#datos-almacenados "Enlace directo al Datos Almacenados") * Marca (Visa, Mastercard, Elo, Amex, Hipercard) * Primeros 6 dígitos (BIN) * Últimos 4 dígitos * Nombre del titular * Mes y año de vencimiento * Fingerprint (identificador único de la tarjeta en el gateway) ### Tokenización[​](#tokenización "Enlace directo al Tokenización") La tarjeta es tokenizada en el lado del cliente vía SDK del gateway y almacenada de forma segura: 1. El cliente envía los datos de la tarjeta por el formulario del gateway 2. El gateway retorna un token de tarjeta temporal (enviado a la API como `card_token`) 3. El servidor usa el token para crear el cliente y la tarjeta en el gateway (Pagar.me) 4. Solo los tokens del gateway y datos enmascarados son almacenados ### Monitoreo de Vencimiento[​](#monitoreo-de-vencimiento "Enlace directo al Monitoreo de Vencimiento") El sistema verifica automáticamente las tarjetas que vencen en los próximos 30 días y puede enviar notificaciones proactivas al cliente. ## Boleto Bancario (`bank_slip`)[​](#boleto-bancario-bank_slip "Enlace directo al boleto-bancario-bank_slip") * Generado para cada cobro individual * Posee código de barras y URL para descarga del PDF * Plazo de vencimiento configurable (predeterminado: 3 días) * Confirmación vía webhook del gateway cuando es pagado ## PIX[​](#pix "Enlace directo al PIX") * QR Code generado para cada cobro * Formato EMV con imagen PNG/base64 * Expiración predeterminada: 30 minutos * Confirmación en tiempo real vía webhook ## Transferencia Bancaria (`bank_transfer`)[​](#transferencia-bancaria-bank_transfer "Enlace directo al transferencia-bancaria-bank_transfer") Datos almacenados: * Código del banco, nombre del banco * Sucursal y cuenta * Tipo: corriente o ahorro * Nombre y documento del titular La confirmación es manual — el operador necesita verificar la recepción. ## Método Predeterminado[​](#método-predeterminado "Enlace directo al Método Predeterminado") * Cada cuenta de cobro tiene **un** método predeterminado * El primer método creado se define automáticamente como predeterminado * Al eliminar el método predeterminado, el siguiente método activo es promovido ## Eliminación[​](#eliminación "Enlace directo al Eliminación") Al eliminar un método de pago: * Valida que no haya pagos pendientes/procesando con este método * Para tarjetas: elimina la tarjeta del gateway * Si era el predeterminado: reasigna a otro método activo * El status cambia a `removed` --- # Pagos Los pagos representan intentos de cobro asociados a facturas. Cada pago rastrea el estado, método, gateway utilizado y respuesta del proveedor. ## Estados del Pago[​](#estados-del-pago "Enlace directo al Estados del Pago") ``` pending → processing → succeeded → refunded ↓ ↓ failed partially_refunded ↓ canceled ``` | Status | Descripción | | ----------------------- | --------------------------------------- | | **pending** | Esperando procesamiento | | **processing** | Enviado al gateway, esperando respuesta | | **succeeded** | Confirmado como pagado | | **failed** | Rechazado por el gateway o error | | **canceled** | Cancelado manualmente | | **partial** | Pago parcial recibido | | **refunded** | Totalmente reembolsado | | **partially\_refunded** | Parcialmente reembolsado | ## Flujo de Pago[​](#flujo-de-pago "Enlace directo al Flujo de Pago") ### 1. Cobro Automático (`charge_automatically`)[​](#1-cobro-automático-charge_automatically "Enlace directo al 1-cobro-automático-charge_automatically") ``` Factura finalizada → Aplica créditos automáticamente → Si los créditos pagan todo: factura = paid → Si no: → Obtiene método de pago predeterminado → Procesa pago vía gateway → Tarjeta: respuesta inmediata → Boleto/PIX: espera webhook del gateway → Éxito: factura = paid → Fallo: agenda retry (dunning) ``` ### 2. Pago Manual[​](#2-pago-manual "Enlace directo al 2. Pago Manual") El operador o cliente acciona el pago vía dashboard o portal. ## Procesando un Pago[​](#procesando-un-pago "Enlace directo al Procesando un Pago") Al procesar, el sistema: 1. Valida que la factura esté `open` 2. Determina el método de pago (proporcionado, guardado o predeterminado) 3. Obtiene el gateway de la organización para el tipo de pago 4. Crea registro del pago con clave de idempotencia 5. Envía cobro al gateway 6. Actualiza el pago con la respuesta ### Idempotencia[​](#idempotencia "Enlace directo al Idempotencia") Cada pago tiene una clave de idempotencia única. Solicitudes duplicadas retornan el resultado existente sin procesar nuevamente. ## Escenarios Especiales[​](#escenarios-especiales "Enlace directo al Escenarios Especiales") ### Pago Parcial[​](#pago-parcial "Enlace directo al Pago Parcial") * El valor recibido es menor que el total * La factura permanece `open` con el saldo actualizado * El cliente puede pagar el restante con otro pago ### Pago Excedente (Overpayment)[​](#pago-excedente-overpayment "Enlace directo al Pago Excedente (Overpayment)") Cuando el valor pagado excede el saldo de la factura: 1. El valor de la factura se aplica normalmente 2. El **excedente se convierte en crédito** automáticamente en la cuenta del cliente 3. El crédito es del tipo `adjustment` con descripción "Crédito de pago excedente en la factura {número}" 4. El crédito será aplicado automáticamente en facturas futuras ### Factura Ya Pagada[​](#factura-ya-pagada "Enlace directo al Factura Ya Pagada") Si la factura ya estaba pagada cuando el pago es procesado, el valor total se convierte en crédito en la cuenta del cliente. ## Operaciones[​](#operaciones "Enlace directo al Operaciones") ### Cancelar Pago[​](#cancelar-pago "Enlace directo al Cancelar Pago") Solo pagos `pending` pueden ser cancelados. Para boleto/PIX, la cancelación es enviada al gateway. ### Reembolsar[​](#reembolsar "Enlace directo al Reembolsar") Pagos `succeeded` o `partially_refunded` pueden ser reembolsados: * **Reembolso total**: El status cambia a `refunded` * **Reembolso parcial**: El status cambia a `partially_refunded` * La solicitud es enviada al gateway cuando está disponible ### Reintentar[​](#reintentar "Enlace directo al Reintentar") Pagos `failed` pueden ser reintentados. Un nuevo pago es creado con el mismo valor, factura y método. ## Capturas de pantalla[​](#capturas-de-pantalla "Enlace directo al Capturas de pantalla") ### Lista de pagos[​](#lista-de-pagos "Enlace directo al Lista de pagos") La pantalla `/dashboard/payments` agrupa todos los pagos recibidos, con filtros por status, método, gateway, cliente y período. Cada fila muestra la factura relacionada, el valor, la comisión del gateway, el valor neto y el mensaje de respuesta. ![Lista de pagos con filtros por gateway y método](/es/assets/images/pagamentos-a0ee99ca505f8cb440e0718fa6d2adb3.png) ### Detalle del pago[​](#detalle-del-pago "Enlace directo al Detalle del pago") La página `/dashboard/payments/[id]` presenta el registro completo: gateway, transacción en el proveedor, factura saldada, método (con los últimos 4 dígitos de la tarjeta o el banco del boleto), historial de intentos, reembolsos y webhooks recibidos. ![Detalle de un pago con gateway, método e historial](/es/assets/images/pagamento-detalhe-195e4e592c1af2087dd8aae3421233ff.png) --- # Pagos en Cuotas Las facturas pueden ser divididas en múltiples cuotas con fechas de vencimiento individuales. ## Estados de la Cuota[​](#estados-de-la-cuota "Enlace directo al Estados de la Cuota") ``` scheduled → pending → paid ↓ overdue ↓ canceled ``` | Status | Descripción | | ------------- | ------------------------------------------- | | **scheduled** | Vencimiento futuro, esperando procesamiento | | **pending** | El vencimiento llegó, esperando pago | | **paid** | Cuota pagada | | **overdue** | Vencida y no pagada | | **canceled** | Cancelada (factura anulada) | ## Creando Cuotas[​](#creando-cuotas "Enlace directo al Creando Cuotas") Al crear o editar una factura, informe las cuotas: | Campo | Descripción | | ------------------------ | ---------------------- | | **Valor** | Monto de la cuota | | **Fecha de vencimiento** | Fecha de pago esperada | ### Reglas de Validación[​](#reglas-de-validación "Enlace directo al Reglas de Validación") * Mínimo de **2 cuotas** * Las fechas deben ser **estrictamente crecientes** * La suma de los valores debe ser **igual al total de la factura** * La fecha de vencimiento de la factura se define como la fecha de la última cuota ## Cobro de Cuotas[​](#cobro-de-cuotas "Enlace directo al Cobro de Cuotas") ### Procesamiento Secuencial[​](#procesamiento-secuencial "Enlace directo al Procesamiento Secuencial") Las cuotas se procesan secuencialmente — cada cuota solo se cobra cuando la anterior está pagada: 1. El worker busca cuotas con vencimiento ≤ hoy 2. Verifica si la cuota anterior está pagada (o si es la primera) 3. Para `charge_automatically`: cobra el método de pago predeterminado 4. Vincula el pago a la cuota 5. Si es la última cuota: factura marcada como `paid` ### Política de NF-e por Cuota[​](#política-de-nf-e-por-cuota "Enlace directo al Política de NF-e por Cuota") Cuando la política de NF-e es `per_installment`, una nota fiscal es emitida para cada cuota pagada individualmente. ## Cancelación[​](#cancelación "Enlace directo al Cancelación") Cuando la factura es anulada: * Todas las cuotas con status `scheduled` o `pending` son canceladas * Las cuotas ya pagadas no son afectadas --- ## [📄️Callbacks (Webhooks de los Proveedores)](https://docs.billing.kobana.com.br/es/es/gateways-de-pagamento/callbacks/.md) [Los proveedores de gateway envían notificaciones al sistema cuando el estado de los pagos cambia. Estas notificaciones se procesan de forma asíncrona.](https://docs.billing.kobana.com.br/es/es/gateways-de-pagamento/callbacks/.md) --- ## [📄️Callbacks (Webhooks de los Proveedores)](https://docs.billing.kobana.com.br/es/es/gateways-de-pagamento/callbacks/.md) [Los proveedores de gateway envían notificaciones al sistema cuando el estado de los pagos cambia. Estas notificaciones se procesan de forma asíncrona.](https://docs.billing.kobana.com.br/es/es/gateways-de-pagamento/callbacks/.md) --- # Callbacks (Webhooks de los Proveedores) Los proveedores de gateway envían notificaciones al sistema cuando el estado de los pagos cambia. Estas notificaciones se procesan de forma asíncrona. ## Endpoints de Callback[​](#endpoints-de-callback "Enlace directo al Endpoints de Callback") ### Kobana[​](#kobana "Enlace directo al Kobana") ``` POST /api/callbacks/kobana ``` **Header de Firma:** `X-Kobana-Signature: sha256=` **Eventos recibidos:** * `pix.register.confirmed` / `error` / `failed` / `requested` * `pix.paid` * `bank_billet.register.confirmed` / `error` / `failed` / `requested` * `bank_billet.paid` ### Pagar.me[​](#pagarme "Enlace directo al Pagar.me") ``` POST /api/callbacks/pagarme ``` **Header de Firma:** `x-hub-signature: sha256=` **Eventos recibidos:** * `order.*` (paid, payment\_failed, created, canceled, closed, updated) * `charge.*` (paid, payment\_failed, refunded, pending, processing, etc.) * `card.*` (created, updated, deleted, expired) ## Flujo de Procesamiento[​](#flujo-de-procesamiento "Enlace directo al Flujo de Procesamiento") ``` Recibe POST del proveedor → Valida firma HMAC-SHA256 → Verifica clave de idempotencia (ignora duplicados) → Crea registro de Callback (status=pending) → Encola job para procesamiento asíncrono → Retorna 200 inmediatamente ``` ### Procesamiento Asíncrono[​](#procesamiento-asíncrono "Enlace directo al Procesamiento Asíncrono") ``` Worker procesa la cola → Enruta al handler del proveedor → Mapea estado del proveedor a estado interno → Actualiza registro de pago → Crea evento para notificación → Actualiza Callback (status=completed) ``` ## Seguridad[​](#seguridad "Enlace directo al Seguridad") * **Validación de firma**: HMAC-SHA256 con comparación timing-safe * **Idempotencia**: Clave única `[provider, idempotencyKey]` previene duplicación * **Reintentos**: Máximo de 5 intentos con backoff exponencial * **Retención**: Callbacks fallidos mantenidos por 7 días ## Registro de Callback[​](#registro-de-callback "Enlace directo al Registro de Callback") Cada callback recibido se registra con: * Proveedor de origen * Clave de idempotencia * Headers y payload completos * Estado de procesamiento * Número de intentos * Resultado o mensaje de error --- # Configuración de Gateways Cada organización puede configurar múltiples gateways y definir valores predeterminados por método de pago. ## Campos del Gateway[​](#campos-del-gateway "Enlace directo al Campos del Gateway") | Campo | Descripción | | ------------------------------- | ------------------------------------------------------ | | **Proveedor** | MOCK, KOBANA o PAGARME | | **Nombre** | Nombre de visualización | | **Ambiente** | SANDBOX o PRODUCTION | | **Activo** | Si el gateway está habilitado | | **Credenciales** | Configuraciones específicas del proveedor (cifradas) | | **Predeterminado para tarjeta** | Si es el gateway predeterminado para pagos con tarjeta | | **Predeterminado para boleto** | Si es el gateway predeterminado para boletos | | **Predeterminado para PIX** | Si es el gateway predeterminado para PIX | ## Gateway Predeterminado[​](#gateway-predeterminado "Enlace directo al Gateway Predeterminado") Cada organización define **un gateway predeterminado por método de pago**: * Un gateway predeterminado para tarjeta * Un gateway predeterminado para boleto * Un gateway predeterminado para PIX Al definir un gateway como predeterminado, el anterior se desmarca automáticamente. El sistema usa transacciones para garantizar consistencia. ## Operaciones[​](#operaciones "Enlace directo al Operaciones") ### Crear Gateway[​](#crear-gateway "Enlace directo al Crear Gateway") 1. Seleccione el proveedor 2. Ingrese las credenciales 3. Elija el ambiente (sandbox/producción) 4. Defina si será predeterminado para algún método **Kobana**: Requiere autorización OAuth antes de activar **Pagar.me**: Requiere prueba de conexión antes de activar **Mock**: Activado automáticamente ### Actualizar Gateway[​](#actualizar-gateway "Enlace directo al Actualizar Gateway") Actualice nombre, credenciales, estado o configuración predeterminada. Los valores enmascarados se filtran para evitar sobrescritura accidental. ### Eliminar Gateway[​](#eliminar-gateway "Enlace directo al Eliminar Gateway") Solo si no hay pagos asociados. ## Monitoreo[​](#monitoreo "Enlace directo al Monitoreo") Para cada gateway, el sistema rastrea: * Total de gateways (activos/inactivos) * Conteo por proveedor * Pagos procesados por gateway * Fallos consecutivos de entrega --- # Proveedores de Gateway El sistema soporta tres proveedores de pago, cada uno con capacidades específicas. ## Proveedores Disponibles[​](#proveedores-disponibles "Enlace directo al Proveedores Disponibles") ### Pagar.me (`PAGARME`)[​](#pagarme-pagarme "Enlace directo al pagarme-pagarme") * **Propósito**: Procesamiento de tarjetas de crédito * **Métodos soportados**: Tarjeta de crédito únicamente * **API**: Pagar.me v5 () * **Ambiente**: Sandbox y Producción **Credenciales necesarias:** | Campo | Obligatorio | Descripción | | ------------ | ----------- | ------------------------------- | | `secretKey` | Sí | Clave secreta de la API | | `publicKey` | No | Clave pública para tokenización | | `merchantId` | No | ID del merchant | | `accountId` | No | ID de la cuenta | **Funcionalidades:** * Tokenización de tarjetas (cliente → token → gateway) * Autorización y captura * Reembolsos totales y parciales * Gestión de clientes y tarjetas en el gateway ### Kobana (`KOBANA`)[​](#kobana-kobana "Enlace directo al kobana-kobana") * **Propósito**: Métodos de pago brasileños * **Métodos soportados**: Boleto bancario y PIX * **Ambiente**: Sandbox y Producción **Credenciales necesarias:** | Campo | Obligatorio | Descripción | | ----------------- | ----------- | ------------------------------------------- | | `accessToken` | Sí | Token de acceso a la API | | `billetAccountId` | No | ID de la cuenta de boletos | | `pixAccountUid` | No | UID de la cuenta PIX (obligatorio para PIX) | | `webhookSecret` | No | Secreto para validación de webhooks | **Funcionalidades:** * Emisión de boletos con código de barras y PDF * Generación de QR Code PIX (EMV) * Cancelación de cobros * Webhooks para confirmación de pago ### Mock (`MOCK`)[​](#mock-mock "Enlace directo al mock-mock") * **Propósito**: Desarrollo y pruebas * **Métodos soportados**: Tarjeta, Boleto y PIX * **Credenciales**: Ninguna necesaria * **Activación**: Automática al crear Simula todos los tipos de pago para ambiente de desarrollo. ## Métodos de Pago por Proveedor[​](#métodos-de-pago-por-proveedor "Enlace directo al Métodos de Pago por Proveedor") | Método | Pagar.me | Kobana | Mock | | ------------------ | -------- | ------ | ---- | | Tarjeta de crédito | Sí | - | Sí | | Boleto bancario | - | Sí | Sí | | PIX | - | Sí | Sí | | Transferencia | - | - | - | ## Seguridad de Credenciales[​](#seguridad-de-credenciales "Enlace directo al Seguridad de Credenciales") * Todas las credenciales son **cifradas** en reposo usando AES-256-GCM * Las credenciales se descifran solo en el momento de la llamada a la API * Las respuestas de la API enmascaran credenciales (formato: `****[últimos 4]`) * Los campos sensibles se filtran de los logs --- ## [📄️Configuración de Dunning](https://docs.billing.kobana.com.br/es/es/gestao-de-inadimplencia/configuracao-de-dunning/.md) [La configuración de dunning define cómo el sistema trata los pagos en atraso: cuántos intentos, el intervalo entre ellos y el comportamiento después de agotarlos.](https://docs.billing.kobana.com.br/es/es/gestao-de-inadimplencia/configuracao-de-dunning/.md) --- ## [📄️Configuración de Dunning](https://docs.billing.kobana.com.br/es/es/gestao-de-inadimplencia/configuracao-de-dunning/.md) [La configuración de dunning define cómo el sistema trata los pagos en atraso: cuántos intentos, el intervalo entre ellos y el comportamiento después de agotarlos.](https://docs.billing.kobana.com.br/es/es/gestao-de-inadimplencia/configuracao-de-dunning/.md) --- # Configuración de Dunning La configuración de dunning define cómo el sistema trata los pagos en atraso: cuántos intentos, el intervalo entre ellos y el comportamiento después de agotarlos. ## Campos de Configuración[​](#campos-de-configuración "Enlace directo al Campos de Configuración") | Campo | Predeterminado | Rango | Descripción | | ----------------------------------- | --------------------- | ----- | ------------------------------------------------------- | | **Máximo de intentos** | 3 | 1-10 | Total de intentos permitidos | | **Intervalo entre intentos (días)** | \[2, 5, 7] | - | Días de espera entre cada intento | | **Período de gracia (días)** | 3 | 1-90 | Días antes de la suspensión | | **Retry automático** | Sí | - | Si los intentos se disparan automáticamente | | **Suspender después de intentos** | Sí | - | Si la cuenta se suspende después de agotar los intentos | | **Métodos de pago para retry** | pix, bank\_slip, card | - | Qué métodos usar en los intentos | ## Jerarquía de Configuración[​](#jerarquía-de-configuración "Enlace directo al Jerarquía de Configuración") 1. **Configuración de la organización**: Cada organización puede personalizar sus reglas 2. **Configuración global predeterminada**: Usada cuando la organización no tiene configuración personalizada 3. **Valores predeterminados del sistema**: Valores hardcoded como fallback final ## Ejemplo de Timeline[​](#ejemplo-de-timeline "Enlace directo al Ejemplo de Timeline") Con la configuración predeterminada (intentos: \[2, 5, 7], gracia: 3 días): ``` Día 0: Factura vence Día 2: 1er intento de retry Día 5: 2do intento de retry (si el 1ro falló) Día 7: 3er intento de retry (si el 2do falló) Día 10: Período de gracia finaliza → cuenta suspendida ``` ## Etapas de Dunning[​](#etapas-de-dunning "Enlace directo al Etapas de Dunning") La cuenta morosa progresa por las siguientes etapas: | Etapa | Días en atraso | Descripción | | ----------- | ----------------- | ---------------------------------- | | `initial` | 1-7 días | Atraso reciente | | `reminder` | 8-15 días | Recordatorios enviados | | `warning` | 16-30 días | Aviso de suspensión inminente | | `final` | 30+ días | Última oportunidad antes de acción | | `suspended` | Después de gracia | Cuenta suspendida | ## Gestión[​](#gestión "Enlace directo al Gestión") ### Pausar Dunning[​](#pausar-dunning "Enlace directo al Pausar Dunning") Use "Detener Dunning" para suspender las comunicaciones temporalmente manteniendo la factura como past-due. ### Cancelar Intentos[​](#cancelar-intentos "Enlace directo al Cancelar Intentos") Cancela todos los intentos pendientes para una factura específica y limpia la fecha del próximo intento. ### Retry Manual[​](#retry-manual "Enlace directo al Retry Manual") El operador puede disparar un intento manual en cualquier momento, independiente de la programación automática. --- # Intereses y Multas Una factura vencida puede acumular **multa** (cobrada una sola vez) e **intereses de mora** (que corren por día de atraso). La política de intereses y multas define ambos, vale para toda la organización y puede cambiarse por cliente, por suscripción o por factura. Toda organización empieza con una política que **no cobra nada**. Activar el cobro es una decisión comercial explícita, porque cambia lo que sus clientes deben. ## Dónde configurar[​](#dónde-configurar "Enlace directo al Dónde configurar") `Configuración` → pestaña **Intereses y multas**. La pantalla muestra la lista de políticas y un simulador en vivo: al editar los valores, usted ve el efecto sobre una factura de R$ 1.000,00 vencida hace quince días, antes de aplicar la regla a clientes reales. ## Campos[​](#campos "Enlace directo al Campos") ### Multa[​](#multa "Enlace directo al Multa") | Campo | Descripción | | -------------------------------- | ------------------------------------------------------------------------------------------------- | | **Tipo de multa** | `Sin cobro`, `Porcentaje del saldo` o `Valor fijo` | | **Porcentaje / Valor** | Solo aparece el campo que usa el tipo elegido | | **Días después del vencimiento** | Cuándo comienza a aplicarse la multa. El valor por defecto es 1 — el día siguiente al vencimiento | La multa se cobra **una sola vez**, no por día. ### Intereses de mora[​](#intereses-de-mora "Enlace directo al Intereses de mora") | Campo | Descripción | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tipo de intereses** | `Sin cobro`, porcentaje por día, por mes o por año, o valor fijo por día | | **Porcentaje / Valor por día** | Solo aparece el campo que usa el tipo elegido | | **Días después del vencimiento** | Cuándo comienzan a correr los intereses. El valor por defecto es 1 | | **Conteo de días** | Días corridos o días hábiles. Los días hábiles vienen del registro de [Feriados](https://docs.billing.kobana.com.br/es/es/configuracoes/feriados.md) | El porcentaje mensual se divide *pro rata die* por 30, y el anual por 360 — la base que usa el registro bancario. Una tasa del 1% mensual sobre R$ 1.000,00 rinde R$ 0,33 por día de atraso. Los intereses corren **sobre el saldo**, nunca sobre el saldo más la multa. ### Topes[​](#topes "Enlace directo al Topes") | Campo | Descripción | | -------------------------------- | ------------------------------------------------------------------------------------------- | | **Máximo de meses de intereses** | Interrumpe la acumulación. Vacío = sin límite | | **Tope del cargo total** | Porcentaje del saldo. Al alcanzar el tope, la multa se preserva y los intereses se recortan | | **Respetar los topes legales** | Rechaza multa superior al 2% e intereses superiores al 1% mensual | El tope legal viene del art. 52 del Código de Defensa del Consumidor brasileño y vale para **relación de consumo**. Los contratos entre empresas pueden pactar por encima, y para eso la traba puede desactivarse — la decisión queda registrada en la auditoría, aparte del cambio común de política. ### Comportamiento[​](#comportamiento "Enlace directo al Comportamiento") | Campo | Descripción | | ---------------------------------------- | ------------------------------------------------------------------------------------- | | **Un pago parcial abona primero** | `Intereses y multa` (por defecto) o `El valor de la factura` | | **Registrar la instrucción en el banco** | El boleto o Pix recauda los cargos por su cuenta después del vencimiento | | **Recalcular en tarjeta y reemisión** | En tarjeta no existe instrucción bancaria, así que el cargo entra en el valor cobrado | | **Instrucciones impresas en el boleto** | Texto libre | El valor por defecto `Intereses y multa` sigue el art. 354 del Código Civil brasileño: un pago parcial se imputa primero a los intereses, luego a la multa, y solo el resto abona el valor de la factura. Así la deuda no deja de rendir silenciosamente. ## Qué política vale para una factura[​](#qué-política-vale-para-una-factura "Enlace directo al Qué política vale para una factura") La resolución es en cascada, y gana el primer nivel que indica una política: ``` Factura → Suscripción → Cuenta de cobro → Política por defecto de la organización ``` Un nivel en blanco significa **heredar**, nunca "sin cobro". No cobrar nada es una política explícita, con los dos tipos en `Sin cobro`. ### Las facturas ya emitidas no cambian[​](#las-facturas-ya-emitidas-no-cambian "Enlace directo al Las facturas ya emitidas no cambian") Al finalizarse, la factura **congela** la política vigente en ese momento. Si renegocia la política en marzo, las facturas emitidas en enero siguen cobrando las reglas de enero — tanto en el cálculo como en la instrucción registrada en el banco. ## Cómo se cobra el cargo[​](#cómo-se-cobra-el-cargo "Enlace directo al Cómo se cobra el cargo") | Medio | Cómo funciona | | ----------- | ------------------------------------------------------------------------------------------------------------------- | | **Boleto** | La instrucción de multa e intereses se registra en el banco, que calcula y recauda el valor extra en la liquidación | | **Pix** | Registrado como Pix Cobrança, con la misma lógica. Un Pix instantáneo no acepta cargos | | **Tarjeta** | No existe instrucción bancaria: el valor cobrado se recalcula en el momento del intento | Al reemitir un boleto vencido, el **vencimiento original se preserva**. Cambiar la fecha del boleto a hoy pondría el atraso en cero y perdonaría el cargo que el cliente ya debe. :::caution Los días hábiles dependen del registro de feriados Con el conteo en días hábiles y la lista de feriados vacía, el cálculo descuenta solo los fines de semana — el banco descuenta los feriados también y recaudará menos de lo que calculamos. Importe los feriados nacionales en `Sistema` → [Feriados](https://docs.billing.kobana.com.br/es/es/configuracoes/feriados.md) antes de activar esta opción. ::: :::note Bancos y el porcentaje mensual En el boleto, el tipo "porcentaje por mes" es soportado por Bradesco, BB, BTG, Caixa, Inter, Itaú, Safra, Santander, Sicoob y Sicredi. En otros bancos, prefiera el porcentaje diario. ::: ## Qué sucede cuando el cliente paga[​](#qué-sucede-cuando-el-cliente-paga "Enlace directo al Qué sucede cuando el cliente paga") El valor liquidado se descompone en tres partes: 1. **Principal** — abona el saldo de la factura 2. **Multa e intereses** — registrados aparte, como ingreso financiero 3. **Excedente inexplicado** — lo que la política no justifica se convierte en crédito en la cuenta del cliente, como antes Esa separación importa en tres lugares: * **Nota fiscal**: el valor de la NF-e es el valor del servicio, sin los cargos. Multa e intereses son ingreso financiero y quedan fuera de la base de cálculo del ISS y de las retenciones. * **Informes de ingresos**: el ingreso por cliente cuenta solo el principal. Contar los cargos infla el LTV con dinero que no vino de la venta. * **Extracto del cliente**: los cargos aparecen en línea propia, "Juros e multa — fatura X". Cuando el valor recibido supera lo que la política explica, el sistema emite el evento `invoice.late_charges_unexplained`. Eso normalmente significa que nuestro cálculo y el del banco divergieron más allá del redondeo, y vale revisarlo. ## Dónde hacer seguimiento[​](#dónde-hacer-seguimiento "Enlace directo al Dónde hacer seguimiento") * **Detalle de la factura**: tarjeta "Cargos por atraso", con días de atraso, multa, intereses, total actualizado y lo ya recibido. Aparece solo en factura vencida o que ya recibió cargo. * **Morosidad**: el total vencido sigue siendo solo el principal — es la métrica comparable entre períodos. Los cargos acumulados aparecen en columna separada. ## Por la API[​](#por-la-api "Enlace directo al Por la API") El recurso es `/v1/late_fee_policies`. Los porcentajes son float (`2.0` para 2%) y los valores en reales. ``` curl -X POST https://api.kobana.com.br/billing/v1/late_fee_policies \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Estándar", "is_default": true, "fine_mode": "percentage", "fine_percent": 2.0, "interest_mode": "monthly_percentage", "interest_percent": 1.0 }' ``` Para conciliar el cálculo antes de que una factura venza de verdad: ``` curl -X POST https://api.kobana.com.br/billing/v1/late_fee_policies/simulate \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "principal": 1000.0, "due_date": "2026-09-10", "reference_date": "2026-10-10", "policy_id": "..." }' ``` La respuesta trae `days_past_due`, `fine`, `interest`, `total` y `total_due`. ## Preguntas frecuentes[​](#preguntas-frecuentes "Enlace directo al Preguntas frecuentes") **¿Los cargos entran en el valor de la nota fiscal?** No. La NF-e usa el valor del servicio. Multa e intereses son ingreso financiero, fuera de la base del ISS y de las retenciones. Si su operación necesita una nota complementaria por los cargos, se emite manualmente. **¿Qué pasa con las facturas antiguas al activar el cobro?** Las facturas aún en `draft` heredan la política nueva al ser finalizadas. Las ya finalizadas mantienen lo que llevan — incluidas las que no tenían ninguna política. **¿Y si el cliente paga más de lo que multa e intereses justifican?** La diferencia se convierte en crédito en su cuenta, y se emite el evento `invoice.late_charges_unexplained` para que usted lo revise. **¿Puedo cobrar intereses sin multa, o multa sin intereses?** Sí. Los dos tipos son independientes; basta dejar uno en `Sin cobro`. --- # Recuperación de Ingresos El sistema rastrea todos los ingresos recuperados vía dunning para análisis de eficiencia. ## Registro de Recuperación[​](#registro-de-recuperación "Enlace directo al Registro de Recuperación") Cada pago exitoso vía retry crea un `RecoveryRecord`: | Campo | Descripción | | --------------------------------- | ---------------------------------------------------- | | **Cuenta de cobro** | Cuenta que pagó | | **Factura** | Factura recuperada | | **Pago** | Pago que se efectivó | | **Valor** | Monto recuperado | | **Días en atraso** | Cuántos días de atraso al momento de la recuperación | | **Intentos** | Cuántos intentos hasta el éxito | | **Método de recuperación** | Ej: `auto_retry_pix`, `manual_retry_card` | | **Fecha original de vencimiento** | Cuándo la factura debería haber sido pagada | | **Recuperado en** | Fecha del pago | ## Métricas Disponibles[​](#métricas-disponibles "Enlace directo al Métricas Disponibles") ### Visión General[​](#visión-general "Enlace directo al Visión General") | Métrica | Descripción | | -------------------------------- | ---------------------------------------- | | **Total recuperado** | Suma de todos los pagos recuperados | | **Total perdido** | Facturas marcadas como incobrables | | **Tasa de recuperación** | Porcentaje del potencial recuperado | | **Días promedio para recuperar** | Promedio de días en atraso hasta el pago | | **Intentos promedio** | Promedio de intentos hasta el éxito | ### Por Método de Pago[​](#por-método-de-pago "Enlace directo al Por Método de Pago") Distribución de recuperaciones por método: * PIX * Tarjeta de crédito * Boleto bancario * Transferencia bancaria ### Por Rango de Atraso (Aging Buckets)[​](#por-rango-de-atraso-aging-buckets "Enlace directo al Por Rango de Atraso (Aging Buckets)") | Rango | Tasa estimada de recuperación | | ---------- | ----------------------------- | | 1-7 días | 85% | | 8-15 días | 70% | | 16-30 días | 50% | | 30+ días | 25% | ### Tendencias[​](#tendencias "Enlace directo al Tendencias") Acompañe la evolución mensual: * Valores recuperados y perdidos por mes * Tasa de recuperación mensual * Cantidad de facturas procesadas ### Potencial de Recuperación[​](#potencial-de-recuperación "Enlace directo al Potencial de Recuperación") Estimación de cuánto puede ser recuperado de las facturas actualmente en atraso, basada en las tasas históricas por rango de atraso. --- # Suspensión de Cuentas Las cuentas morosas son automáticamente suspendidas cuando el período de gracia es excedido. ## Worker de Suspensión[​](#worker-de-suspensión "Enlace directo al Worker de Suspensión") Se ejecuta **diariamente a las 02:00 UTC** y: 1. Sincroniza el status de las cuentas morosas 2. Obtiene el `gracePeriodDays` de la configuración de dunning (predeterminado: 3 días) 3. Busca cuentas morosas con: * Etapa `warning` o `final` * Fecha del atraso más antiguo > período de gracia * Aún no suspendidas * No recuperadas 4. Para cada cuenta: * Cambia el status de la cuenta de cobro a `suspended` * Actualiza la etapa de morosidad a `suspended` * **Pausa todas las suscripciones activas** * Envía notificación de suspensión ## Efectos de la Suspensión[​](#efectos-de-la-suspensión "Enlace directo al Efectos de la Suspensión") * Status de la cuenta de cobro: `suspended` * Todas las suscripciones activas son pausadas automáticamente * El motivo de la suspensión es registrado (ej: "Morosidad por X+ días") * Notificación enviada al titular de la cuenta ## Notificación de Suspensión[​](#notificación-de-suspensión "Enlace directo al Notificación de Suspensión") Tipo: `account_suspended` Variables disponibles: * Nombre de la organización * Total en atraso * Fecha de la suspensión ## Reactivación[​](#reactivación "Enlace directo al Reactivación") La reactivación se realiza manualmente después de que el pago sea regularizado: 1. El operador accede a la cuenta de cobro 2. Hace clic en "Reactivar" 3. El status vuelve a `active` 4. Los campos de suspensión son limpiados 5. Las suscripciones pausadas pueden ser reanudadas individualmente --- # Intentos de Pago (Payment Retry) El sistema de retry procesa automáticamente intentos de cobro para facturas en atraso. ## Estados del Intento[​](#estados-del-intento "Enlace directo al Estados del Intento") | Status | Descripción | | ------------ | ------------------------------------------ | | `pending` | Esperando procesamiento | | `processing` | Siendo procesado (reclamado por el worker) | | `succeeded` | Pago exitoso | | `failed` | Pago rechazado, más intentos disponibles | | `exhausted` | Máximo de intentos alcanzado | ## Campos del Intento[​](#campos-del-intento "Enlace directo al Campos del Intento") | Campo | Descripción | | ---------------------- | ---------------------------------------- | | **Factura** | Factura asociada | | **Pago** | Registro de pago creado | | **Número del intento** | Secuencial (1, 2, 3...) | | **Método de pago** | Método utilizado en el intento | | **Valor** | Valor a ser cobrado | | **Código de fallo** | Motivo del rechazo | | **Mensaje de fallo** | Descripción detallada del error | | **Programado para** | Fecha/hora del intento | | **Procesado en** | Fecha/hora del procesamiento | | **Próximo retry en** | Cuándo el próximo intento será realizado | ## Worker de Retry[​](#worker-de-retry "Enlace directo al Worker de Retry") El worker se ejecuta **cada 6 horas** y: 1. Busca intentos con `status=pending` y `scheduledFor ≤ ahora` 2. Reclama atómicamente cada intento (`pending → processing`) para evitar duplicación 3. Para cada intento: * Verifica si la factura ya fue pagada (omite) * Crea registro de pago * Procesa el pago vía gateway 4. En caso de **éxito**: * Marca la factura como pagada * Crea registro de recuperación * Elimina la cuenta de la lista de morosos 5. En caso de **fallo**: * Si hay intentos restantes: programa el próximo * Si agotó los intentos: marca como `exhausted` y suspende la cuenta (si está configurado) ## Prevención de Condiciones de Carrera[​](#prevención-de-condiciones-de-carrera "Enlace directo al Prevención de Condiciones de Carrera") El sistema usa `updateMany` atómico con verificación de status para garantizar que solo un worker procese cada intento: ``` WHERE id = X AND status = 'pending' SET status = 'processing' ``` Si `count = 0`, otro worker ya reclamó el intento. ## Retry para Cuotas[​](#retry-para-cuotas "Enlace directo al Retry para Cuotas") Los intentos también pueden ser dirigidos a cuotas específicas: * El `metadata.installmentId` identifica la cuota * El valor del intento es el de la cuota, no el de la factura completa --- # Primeros Pasos La página **Getting Started** (`/dashboard/getting-started`) es el punto de partida para las nuevas organizaciones. Presenta una secuencia guiada de las tareas necesarias para empezar a cobrar de forma recurrente: registrar la empresa, configurar gateways y NF-e, crear planes y productos, importar clientes y activar la primera suscripción. Cada tarjeta de la página representa un hito del onboarding y muestra el estado de la organización en tiempo real (completado, pendiente o bloqueado). El dashboard usa estas mismas verificaciones para decidir cuándo ocultar las instrucciones iniciales y mostrar las métricas operativas. ## Etapas sugeridas[​](#etapas-sugeridas "Enlace directo al Etapas sugeridas") 1. **Configurar la empresa y los datos fiscales** — informa el CNPJ, el régimen tributario y las direcciones en `Cuentas > Empresas`. 2. **Conectar un gateway de pago** — elige el proveedor (Kobana, Asaas, Iugu, Pagar.me) en `Gateways de Pago` y define el gateway predeterminado por método (tarjeta, boleto, PIX). 3. **Registrar planes y productos** — define el catálogo en `Planes y Productos`, con ciclos, valores en reales y reglas de proration. 4. **Habilitar la emisión de NF-e** (opcional) — selecciona el proveedor en `Nota Fiscal > Configuraciones`, adjunta el certificado digital y mapea los códigos de servicio. 5. **Importar clientes** — usa la importación CSV en `Exportación e Importación > Importaciones` o regístralos manualmente. 6. **Crear la primera suscripción** — vincula un cliente a un plan en `Suscripciones` y confirma el inicio del ciclo. 7. **Configurar dunning y notificaciones** — en `Gestión de Morosidad` y `Configuraciones > Notificaciones`. 8. **Conectar webhooks y API** — registra endpoints en `Webhooks`. La API pública usa el access token de la Cuenta Kobana (`Authorization: Bearer`), no una clave generada aquí. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Panel de onboarding con checklist de configuración inicial](/es/assets/images/primeiros-passos-14b35a2d2d07e9533b5f39cd86c72b72.png) --- ## [📄️Impuestos](https://docs.billing.kobana.com.br/es/es/impostos.md) [Facturación Automática posee un motor de cálculo fiscal completo para el mercado brasileño, con soporte a múltiples regímenes tributarios, retenciones y el nuevo sistema CBS/IBS.](https://docs.billing.kobana.com.br/es/es/impostos.md) --- ## [📄️Impuestos](https://docs.billing.kobana.com.br/es/es/impostos.md) [Facturación Automática posee un motor de cálculo fiscal completo para el mercado brasileño, con soporte a múltiples regímenes tributarios, retenciones y el nuevo sistema CBS/IBS.](https://docs.billing.kobana.com.br/es/es/impostos.md) --- # Motor de Cálculo de Impuestos El motor de cálculo determina todos los impuestos aplicables con base en las reglas fiscales, perfil de la empresa y tipo fiscal del cliente. ## Impuestos Soportados[​](#impuestos-soportados "Enlace directo al Impuestos Soportados") | Impuesto | Descripción | Jurisdicción | | ---------- | ---------------------------------------------------------- | --------------- | | **ISS** | Impuesto sobre Servicios | Municipal | | **PIS** | Programa de Integración Social | Federal | | **COFINS** | Contribución para el Financiamiento de la Seguridad Social | Federal | | **CSLL** | Contribución Social sobre la Ganancia Neta | Federal | | **IRPJ** | Impuesto a la Renta de Personas Jurídicas | Federal | | **IRRF** | Impuesto a la Renta Retenido en la Fuente | Federal | | **CSRF** | PIS + COFINS + CSLL retenidos en conjunto | Federal | | **INSS** | Contribución a la Seguridad Social | Federal | | **CBS** | Contribución sobre Bienes y Servicios (2026+) | Federal | | **IBS** | Impuesto sobre Bienes y Servicios (2026+) | Federal/Estatal | ## Flujo de Cálculo[​](#flujo-de-cálculo "Enlace directo al Flujo de Cálculo") ### 1. Obtener Reglas Aplicables[​](#1-obtener-reglas-aplicables "Enlace directo al 1. Obtener Reglas Aplicables") Consulta el `TaxRuleService` con el contexto de la operación. Las reglas se filtran por ámbito y prioridad. ### 2. Resolver Alícuotas[​](#2-resolver-alícuotas "Enlace directo al 2. Resolver Alícuotas") * Extrae alícuotas de las reglas aplicables * Hace fallback al Perfil Fiscal de la empresa * Aplica sobrescrituras de retención de la cuenta de cobro ### 3. Calcular Cada Impuesto[​](#3-calcular-cada-impuesto "Enlace directo al 3. Calcular Cada Impuesto") ``` ISS = valor_servicio × (alícuota_iss / 100) PIS = valor_servicio × (alícuota_pis / 100) COFINS = valor_servicio × (alícuota_cofins / 100) CSLL = valor_servicio × (alícuota_csll / 100) IRRF = valor_servicio × (alícuota_irrf / 100) [siempre retenido] CSRF = valor_servicio × (4,65 / 100) [siempre retenido] INSS = valor_servicio × (alícuota_inss / 100) [siempre retenido] ``` ### 4. Redondeo[​](#4-redondeo "Enlace directo al 4. Redondeo") Cada impuesto se redondea independientemente con `Math.round()`. Compensación de redondeo aplicada al impuesto con mayor contribución. ### 5. Resultado[​](#5-resultado "Enlace directo al 5. Resultado") ``` Total de impuestos = suma de todos los impuestos Total retenido = suma de los impuestos con flag isWithheld Valor neto = valor del servicio - total de impuestos ``` ## CBS/IBS (Reforma Tributaria 2026+)[​](#cbsibs-reforma-tributaria-2026 "Enlace directo al CBS/IBS (Reforma Tributaria 2026+)") El sistema ya soporta los nuevos impuestos de la reforma tributaria: | Modo | Descripción | | ------------- | --------------------------------------------- | | `informative` | Calculado pero no incluido en el total (2026) | | `compositive` | Incluido en el total (2027+) | Las alícuotas de CBS e IBS son configurables en el Perfil Fiscal de la empresa. --- # Perfil Fiscal El perfil fiscal define la configuración tributaria de cada empresa (entidad jurídica) de la organización. ## Campos Principales[​](#campos-principales "Enlace directo al Campos Principales") ### Régimen Tributario[​](#régimen-tributario "Enlace directo al Régimen Tributario") | Régimen | Descripción | | ----------------- | ---------------------------- | | `simple_national` | Simples Nacional | | `presumed_profit` | Lucro Presumido | | `real_profit` | Lucro Real | | `mei` | Microempreendedor Individual | ### Simples Nacional[​](#simples-nacional "Enlace directo al Simples Nacional") | Campo | Descripción | | ---------------------- | --------------------------------------------------- | | **Anexo** | `annex_iii`, `annex_iv` o `annex_v` | | **RBT12** | Receita Bruta Tributária de los últimos 12 meses | | **Factor R** | Relación nómina / ingresos | | **CPP dentro del DAS** | Si la Contribución Patronal está incluida en el DAS | ### Lucro Presumido[​](#lucro-presumido "Enlace directo al Lucro Presumido") | Campo | Descripción | | ---------------------- | ------------------------------------- | | **Tasa de presunción** | Predeterminado: 32% de la facturación | ### ISS[​](#iss "Enlace directo al ISS") | Campo | Descripción | | -------------------- | ------------------------- | | **Municipio (IBGE)** | Código IBGE del municipio | | **Alícuota ISS** | Porcentaje de ISS | ### Impuestos Federales[​](#impuestos-federales "Enlace directo al Impuestos Federales") | Campo | Descripción | | ------------------- | ----------------------- | | **Alícuota PIS** | Porcentaje del PIS | | **Alícuota COFINS** | Porcentaje de la COFINS | | **Alícuota CSLL** | Porcentaje de la CSLL | | **Alícuota IRPJ** | Porcentaje del IRPJ | ### CBS/IBS (2026+)[​](#cbsibs-2026 "Enlace directo al CBS/IBS (2026+)") | Campo | Descripción | | ---------------- | -------------------------------------------- | | **Habilitado** | Si el nuevo sistema está activo | | **Alícuota CBS** | Porcentaje de la CBS | | **Alícuota IBS** | Porcentaje del IBS | | **Modo** | `informative` (2026) o `compositive` (2027+) | ## Versionado[​](#versionado "Enlace directo al Versionado") Los perfiles fiscales son versionados: * `effective_from` y `effective_to` definen la vigencia * `version` se incrementa automáticamente en cada modificación * El historial permite rastrear cambios a lo largo del tiempo ## RBT12 Histórico[​](#rbt12-histórico "Enlace directo al RBT12 Histórico") El sistema mantiene el historial de la Receita Bruta Tributária mensual para el cálculo preciso del Simples Nacional. Cada registro contiene mes, año y valor de los ingresos. --- # Períodos Fiscales Los períodos fiscales agregan las facturas para la liquidación mensual o trimestral de impuestos. ## Tipos de Período[​](#tipos-de-período "Enlace directo al Tipos de Período") | Tipo | Descripción | | ----------- | -------------------------------------- | | `monthly` | Liquidación mensual (mes 1-12) | | `quarterly` | Liquidación trimestral (trimestre 1-4) | ## Campos del Período[​](#campos-del-período "Enlace directo al Campos del Período") ### Ingresos[​](#ingresos "Enlace directo al Ingresos") | Campo | Descripción | | ------------------------ | -------------------------------- | | **Ingresos brutos** | Total facturado en el período | | **Ingresos tributables** | Base de cálculo de los impuestos | ### Impuestos Adeudados[​](#impuestos-adeudados "Enlace directo al Impuestos Adeudados") | Campo | Descripción | | ------------------- | -------------- | | **ISS adeudado** | ISS a pagar | | **PIS adeudado** | PIS a pagar | | **COFINS adeudado** | COFINS a pagar | | **IRPJ adeudado** | IRPJ a pagar | | **CSLL adeudado** | CSLL a pagar | ### Compensación de Retenciones[​](#compensación-de-retenciones "Enlace directo al Compensación de Retenciones") | Campo | Descripción | | -------------------- | ---------------------------------------------- | | **IRRF a compensar** | IRRF retenido para deducir del IRPJ | | **CSRF a compensar** | CSRF retenido para deducir del PIS/COFINS/CSLL | | **ISS a compensar** | ISS retenido para deducir | ### Simples Nacional[​](#simples-nacional "Enlace directo al Simples Nacional") | Campo | Descripción | | --------------------- | ------------------------------- | | **DAS estimado** | Valor estimado del DAS | | **Alícuota efectiva** | Alícuota calculada | | **Anexo** | Anexo del Simples (III, IV o V) | ### CBS/IBS[​](#cbsibs "Enlace directo al CBS/IBS") | Campo | Descripción | | ---------------- | ----------- | | **CBS adeudado** | CBS a pagar | | **IBS adeudado** | IBS a pagar | ## Estado[​](#estado "Enlace directo al Estado") | Estado | Descripción | | ------------ | ------------------------------------ | | `open` | Período abierto, recibiendo facturas | | `calculated` | Impuestos calculados | | `closed` | Período cerrado | ## Cálculos[​](#cálculos "Enlace directo al Cálculos") ### Para Simples Nacional[​](#para-simples-nacional "Enlace directo al Para Simples Nacional") 1. Obtiene RBT12 (Receita Bruta Tributária de los últimos 12 meses) 2. Localiza la franja aplicable 3. Calcula la alícuota efectiva 4. Aplica a los ingresos mensuales 5. Distribuye entre ISS, PIS, COFINS, CPP 6. Rastrea retenciones para compensación ### Para Lucro Presumido[​](#para-lucro-presumido "Enlace directo al Para Lucro Presumido") 1. Obtiene los ingresos brutos 2. Aplica la tasa de presunción (predeterminado: 32%) 3. Calcula IRPJ sobre el lucro presumido 4. Calcula CSLL sobre el lucro presumido 5. Calcula PIS/COFINS sobre los ingresos brutos 6. Calcula ISS conforme reglas municipales 7. Rastrea retenciones para compensación ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") La pantalla `/dashboard/tax-periods` lista cada período fiscal (mensual, trimestral o anual), con ingreso bruto, ingreso tributable, tributos adeudados (ISS, PIS, COFINS, IRPJ, CSLL, CBS, IBS), retenciones a compensar, DAS estimado y alícuota efectiva. Los períodos pueden cerrarse (`closed`) — una operación irreversible que congela los valores calculados. ![Períodos fiscales con ingresos, tributos y status de cierre](/es/assets/images/periodos-fiscais-e590b02f3b379faa9e3dabad94ecda26.png) --- # Reglas Fiscales Las reglas fiscales permiten configurar alícuotas de impuestos con diferentes niveles de especificidad. ## Campos de la Regla[​](#campos-de-la-regla "Enlace directo al Campos de la Regla") | Campo | Descripción | | ------------- | ------------------------------------------------ | | **Nombre** | Nombre descriptivo de la regla | | **Ámbito** | Nivel de aplicación (ver tabla) | | **Prioridad** | Mayor número = mayor prioridad dentro del ámbito | | **Activa** | Si la regla está activa | | **Vigencia** | Período de validez (desde/hasta) | | **Ítems** | Lista de impuestos y alícuotas | ### Criterios de Correspondencia (opcionales)[​](#criterios-de-correspondencia-opcionales "Enlace directo al Criterios de Correspondencia (opcionales)") | Campo | Descripción | | --------------------------- | -------------------------- | | **Empresa** | Empresa emisora específica | | **Ítem de servicio** | Servicio específico | | **Cuenta de cobro** | Cliente específico | | **Tipo fiscal del cliente** | Clasificación del cliente | | **Municipio** | Código IBGE del municipio | | **Tipo de operación** | `interno` o `externo` | ## Ámbito y Prioridad[​](#ámbito-y-prioridad "Enlace directo al Ámbito y Prioridad") Las reglas se evalúan de lo más específico a lo más genérico: | Ámbito | Prioridad | Descripción | | -------------- | --------- | -------------------------------------- | | `customer` | 100 | Regla para cliente específico | | `service` | 80 | Regla para ítem de servicio específico | | `company` | 60 | Regla para empresa emisora | | `municipality` | 40 | Regla por municipio | | `organization` | 20 | Regla general de la organización | | `global` | 0 | Predeterminado del sistema | **La regla con mayor prioridad prevalece.** Múltiples reglas de la misma prioridad se combinan. ## Ítems de la Regla[​](#ítems-de-la-regla "Enlace directo al Ítems de la Regla") Cada regla contiene ítems que definen alícuotas: | Campo | Descripción | | ------------------------- | ------------------------------------------------------------ | | **Tipo de impuesto** | ISS, PIS, COFINS, CSLL, IRPJ, IRRF, CSRF, INSS | | **Alícuota** | Porcentaje (ej: 5,00 para 5%) | | **Retenido** | Si es retenido en la fuente | | **Base de cálculo** | `service_value`, `service_value_minus_iss` o `presumed_base` | | **Exento** | Si el impuesto es exento | | **Motivo de la exención** | Justificación de la exención | ## Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") ### ISS predeterminado de la organización[​](#iss-predeterminado-de-la-organización "Enlace directo al ISS predeterminado de la organización") ``` Ámbito: organization (prioridad 20) Ítem: ISS = 5,00%, retenido en la fuente, base = valor del servicio ``` ### Regla específica para servicio[​](#regla-específica-para-servicio "Enlace directo al Regla específica para servicio") ``` Ámbito: service (prioridad 80) Ítem de servicio: "Desarrollo de Software" Ítems: - ISS = 3,50%, no retenido - IRRF = 15,00%, retenido en la fuente ``` La regla de servicio prevalece sobre la regla de la organización para el ISS. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") La pantalla `/dashboard/tax-rules` permite crear, editar y priorizar reglas tributarias. Los filtros principales incluyen empresa, cliente, ítem de servicio, tipo de impuesto e indicación de retención. Cada regla contiene una lista de tributos con alícuota, indicador de retención y exención. ![Lista de reglas tributarias con ámbito, prioridad y alícuotas](/es/assets/images/regras-fiscais-8f3a52d2341b239a71bcaea9fd7962b5.png) --- # Informes Fiscales El área de informes fiscales (`/dashboard/fiscal/reports`) consolida la información necesaria para el cierre contable y la generación de obligaciones accesorias. Los datos se generan a partir de las facturas pagadas, las NF-e emitidas, las retenciones y los períodos fiscales ya cerrados por la organización. ## Tipos de informe[​](#tipos-de-informe "Enlace directo al Tipos de informe") * **Resumen por período de competencia** — ingreso bruto, ingreso tributable, ISS, PIS, COFINS, IR, CSLL, INSS y DAS estimado por mes, trimestre o año. * **Retenciones sufridas** — todas las retenciones aplicadas por los tomadores (IR, INSS, CSRF, ISS), con base de cálculo, alícuota, valor retenido y status (`open`, `partially_compensated`, `fully_compensated`). * **NF-e emitidas en el período** — lista paginada con número, serie, valor, status, código del municipio, alícuotas aplicadas y tributos calculados. * **DAS / Simples Nacional** — para empresas en el régimen simplificado, el informe muestra el RBT12, el rango actual y el valor estimado de la guía. ## Filtros disponibles[​](#filtros-disponibles "Enlace directo al Filtros disponibles") * **Empresa** — limita a una de las empresas registradas. * **Período** — mes, trimestre, año o rango personalizado. * **Régimen tributario** — cuando la organización tiene empresas en regímenes diferentes. ## Cómo se calculan los valores[​](#cómo-se-calculan-los-valores "Enlace directo al Cómo se calculan los valores") Los informes consultan directamente las tablas `tax_periods`, `tax_computations`, `withholdings` y `nfes`, siempre filtradas por `organization_id`. Los períodos `closed` son inmutables; los períodos `open` pueden cambiar a medida que se pagan nuevas facturas o se emiten NF-e. Para cerrar el período de competencia, usa [Períodos Fiscales](https://docs.billing.kobana.com.br/es/es/impostos/periodos-fiscais/.md). ## Exportación[​](#exportación "Enlace directo al Exportación") Los informes pueden exportarse en CSV para enviarlos al contador o importarlos en sistemas de escrituración. Las exportaciones quedan disponibles en [Exportación e Importación](https://docs.billing.kobana.com.br/es/es/exportacao-e-importacao.md). ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Informes fiscales con tributos por período de competencia y retenciones](/es/assets/images/relatorios-fiscais-05f82637c820f94fb221084b3031aab9.png) --- # Retenciones en la Fuente Las retenciones son impuestos retenidos por el pagador (cliente) que deben ser rastreados, reportados y compensados. ## Tipos de Retención[​](#tipos-de-retención "Enlace directo al Tipos de Retención") | Impuesto | Descripción | | -------- | --------------------------------------- | | **ISS** | Retenido por el tomador del servicio | | **IRRF** | Impuesto de renta retenido en la fuente | | **CSRF** | PIS + COFINS + CSLL combinados (4,65%) | | **INSS** | Contribución previsional | ## Campos de la Retención[​](#campos-de-la-retención "Enlace directo al Campos de la Retención") | Campo | Descripción | | -------------------------- | ---------------------------------------------------- | | **Factura** | Factura de origen | | **NF-e** | Nota fiscal relacionada | | **Tipo de impuesto** | Cuál impuesto fue retenido | | **Base** | Base de cálculo | | **Alícuota** | Porcentaje retenido | | **Valor** | Monto retenido | | **Retenedor** | Entidad que retuvo (generalmente la cuenta de cobro) | | **Mes/Año de competencia** | Período contable | | **Estado** | Estado de la retención | | **Compensado** | Valor ya utilizado para deducir impuestos | ## Estado de la Retención[​](#estado-de-la-retención "Enlace directo al Estado de la Retención") | Estado | Descripción | | ----------------------- | ----------------------------- | | `retained` | Registrada, aún no compensada | | `compensated` | Totalmente compensada | | `partially_compensated` | Parcialmente compensada | ## Flujo[​](#flujo "Enlace directo al Flujo") 1. **Creación**: Generada automáticamente a partir del cálculo de impuestos de cada factura 2. **Retención**: El valor es retenido por el cliente en el momento del pago 3. **Rastreo**: Almacenada por mes/año de competencia 4. **Compensación**: Aplicada para reducir la obligación tributaria en los períodos siguientes 5. **Conciliación**: Reportada en las declaraciones fiscales ## Configuración por Cliente[​](#configuración-por-cliente "Enlace directo al Configuración por Cliente") Cada cuenta de cobro puede tener flags individuales de retención: * `withholdIss` — Retener ISS * `withholdIrrf` — Retener IRRF * `withholdCsrf` — Retener CSRF (PIS/COFINS/CSLL) * `withholdInss` — Retener INSS Estos flags sobrescriben el comportamiento predeterminado de las reglas fiscales. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") La pantalla `/dashboard/withholdings` lista todas las retenciones de la organización, con filtros por tipo de impuesto, status, mes/año de competencia, empresa retenedora y búsqueda por factura o NF-e. Cada fila muestra la base, la alícuota, el valor retenido, el valor ya compensado y acciones para abrir la factura/NF-e de origen. ![Lista de retenciones con tipo, base, alícuota y compensación](/es/assets/images/retencoes-004a0c8ebeefa70c24a7e2f8393e9014.png) --- # Simples Nacional El sistema calcula automáticamente el DAS (Documento de Recaudación del Simples Nacional) con base en los ingresos y el anexo correcto. ## Anexos Soportados[​](#anexos-soportados "Enlace directo al Anexos Soportados") ### Anexo III — Servicios en General[​](#anexo-iii--servicios-en-general "Enlace directo al Anexo III — Servicios en General") | Franja | RBT12 (R$ mil) | Alícuota Nominal | | ------ | -------------- | ---------------- | | 1.ª | Hasta 180 | 6,0% | | 2.ª | 180 a 360 | 11,2% | | 3.ª | 360 a 720 | 13,5% | | 4.ª | 720 a 1.800 | 16,0% | | 5.ª | 1.800 a 3.600 | 21,0% | | 6.ª | 3.600 a 4.800 | 33,0% | ### Anexo IV — Construcción, Vigilancia, Limpieza[​](#anexo-iv--construcción-vigilancia-limpieza "Enlace directo al Anexo IV — Construcción, Vigilancia, Limpieza") | Franja | RBT12 (R$ mil) | Alícuota Nominal | | ------ | -------------- | ---------------- | | 1.ª | Hasta 180 | 4,5% | | 2.ª | 180 a 360 | 9,0% | | 3.ª | 360 a 720 | 10,2% | | 4.ª | 720 a 1.800 | 14,0% | | 5.ª | 1.800 a 3.600 | 22,0% | | 6.ª | 3.600 a 4.800 | 33,0% | ### Anexo V — Servicios Intelectuales[​](#anexo-v--servicios-intelectuales "Enlace directo al Anexo V — Servicios Intelectuales") | Franja | RBT12 (R$ mil) | Alícuota Nominal | | ------ | -------------- | ---------------- | | 1.ª | Hasta 180 | 15,5% | | 2.ª | 180 a 360 | 18,0% | | 3.ª | 360 a 720 | 19,5% | | 4.ª | 720 a 1.800 | 20,5% | | 5.ª | 1.800 a 3.600 | 23,0% | | 6.ª | 3.600 a 4.800 | 30,5% | ## Factor R[​](#factor-r "Enlace directo al Factor R") El Factor R determina si las empresas originalmente en el Anexo V pueden usar el Anexo III (alícuotas menores): ``` Factor R = Nómina (12 meses) / Ingresos Brutos (12 meses) ``` * **Factor R ≥ 28%**: Puede usar el Anexo III * **Factor R < 28%**: Permanece en el Anexo V ## Cálculo de la Alícuota Efectiva[​](#cálculo-de-la-alícuota-efectiva "Enlace directo al Cálculo de la Alícuota Efectiva") ``` Alícuota Efectiva = (RBT12 × Alícuota Nominal - Deducción) / RBT12 × 100 ``` ## Cálculo del DAS[​](#cálculo-del-das "Enlace directo al Cálculo del DAS") ``` DAS = Ingresos Mensuales × Alícuota Efectiva ``` ## Distribución del DAS[​](#distribución-del-das "Enlace directo al Distribución del DAS") El valor del DAS se distribuye entre los impuestos: * IRPJ: 4,0% a 35% * CSLL: 3,5% a 15% * COFINS: 12,82% a 16,03% * PIS: 2,78% a 3,47% * CPP: 30,5% a 43,4% * ISS: 0% a 33,5% Las proporciones varían según el anexo y la franja. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") La pantalla `/dashboard/simples` presenta el cálculo del Simples Nacional por empresa: anexo actual, RBT12 (ingreso bruto de los últimos 12 meses), rango en el que está la empresa, alícuota nominal, parcela a deducir, factor R cuando corresponde y estimación del DAS para el mes en curso. Incluye alertas de proximidad al tope y de cambio de rango. ![Cálculo del Simples Nacional con anexo, rango y DAS estimado](/es/assets/images/simples-nacional-10d3d554918be06f63d9f278fc9462ab.png) --- # Autenticación El servidor MCP acepta un **Bearer token** en la cabecera `Authorization`, y nada más — sin cookie, sin certificado de cliente. :::warning Nunca en la URL Un token en la query string (`?access_token=…`, o parámetros como `token` y `api_key`) **no autentica**, aunque venga junto a una cabecera válida: la petición responde `401` con `error="invalid_request"` en `WWW-Authenticate`. Un token en la URL se filtra en logs de proxy y CDN, en el `Referer` y en el historial — la especificación de autorización de MCP y la RFC 6750 lo prohíben. ::: 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**, cuyo `aud` es `https://mcp.billing.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 igual en los dos casos. ``` Authorization: Bearer eyJhbGciOiJSUzI1NiIs… ``` :::info Cada superficie tiene su propia audience Un token emitido para el MCP **no vale** en la API REST (`api.billing.*`), 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 conectarse[​](#dos-formas-de-conectarse "Enlace directo al Dos formas de conectarse") | | Flujo OAuth | Token personal | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Cómo lo obtienes | Pegas la URL en el cliente; abre el inicio de sesión de Kobana y autorizas | Lo creas en **Cuenta Kobana → Tokens y Acceso → Nuevo Token Personal**: app **Faturamento Automático**, 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 | 30 minutos, renovado por el cliente | De 7 días a 1 año, a tu elección | | Alcance | Los recursos y niveles de acceso que dejaste marcados en la pantalla de consentimiento (`read`, `write`, `delete`, `import`, `export`, `all`) | Los recursos y accesos que marcaste | | Bueno para | Claude, ChatGPT, IDEs y cualquier cliente con OAuth | Clientes sin soporte de OAuth, scripts y automatizaciones | El token personal tiene que crearse con el uso **MCP**. Un token creado para la **API REST** tiene la audience de la API y aquí se rechaza con `401` — y lo contrario también vale. ## 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 petición 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-billing-mcp", error="invalid_token", resource_metadata="https://mcp.billing.kobana.com.br/.well-known/oauth-protected-resource" ``` 2. **Metadata del recurso.** El cliente lee el documento señalado. Es público y no lleva ningún secreto — solo punteros: ``` curl https://mcp.billing.kobana.com.br/.well-known/oauth-protected-resource ``` ``` { "resource": "https://mcp.billing.kobana.com.br", "authorization_servers": ["https://account.kobana.com.br"], "bearer_methods_supported": ["header"], "scopes_supported": [ "billing/billing_accounts", "billing/certificates", "billing/companies", "billing/coupons", "billing/credits", "billing/customers", "billing/dashboard_users", "billing/invoices", "billing/nfes", "billing/organization", "billing/payment_methods", "billing/payments", "billing/plan_changes", "billing/plan_groups", "billing/plans", "billing/portal_users", "billing/product_groups", "billing/products", "billing/proposal_templates", "billing/proposals", "billing/service_items", "billing/subscription_changes", "billing/subscription_item_changes", "billing/subscriptions", "billing/tax_periods", "billing/tax_rules", "billing/team_roles", "billing/usage", "billing/withholdings", "read", "write", "delete", "import", "export", "all" ], "resource_documentation": "https://docs.billing.kobana.com.br" } ``` 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 lo envía en cada petición, renovándolo cuando expira. El token lleva quién eres (`sub`) y la organización que autorizaste (`org`). Es el `org` lo que delimita los datos — ninguna tool acepta organización como argumento. Un token cuya organización no existe en Facturación recibe `403 unknown_organization`. ## Autorización: los permisos de quien autorizó[​](#autorización-los-permisos-de-quien-autorizó "Enlace directo al Autorización: los permisos de quien autorizó") Lo que un llamador ve es **más estrecho** que el catálogo: las tools se filtran por los **permisos de dashboard de la persona que autorizó el cliente**, en esa organización, resueltos en cada petición. El techo es siempre lo que esa persona puede hacer en la interfaz. | Situación | Resultado | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | La persona no es miembro de la organización | **Niega todas las tools** (`key_owner_not_member`). Autoriza de nuevo con una cuenta que pertenezca a la organización. | | Vínculo activo | Los permisos y roles de la persona, aplicados tool a tool. `owner` y el comodín `*` lo liberan todo; `invoices.*` libera la familia. | | Vínculo suspendido, eliminado, o sin ningún rol | **Niega todas las tools** (`membership_inactive`). | | La consulta de permisos falla | **Niega todas las tools.** Falla cerrada. | Los permisos se leen en cada llamada, así que revocar un rol en el dashboard vale ya en la tool siguiente, sin esperar a que el token expire. Una tool que el llamador no puede ejecutar **no aparece** en `tools/list`. 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 dice cuál). | | `membership_inactive` | Reactivar a la persona — ningún permiso arregla un vínculo muerto. | | `key_owner_not_member` | Autorizar de nuevo con una cuenta que sea miembro de la organización. | :::tip Postura recomendada para agentes Autoriza el cliente con una cuenta que tenga solo los permisos que el agente necesita. Un cliente autorizado por un analista de solo lectura expone solo las tools de lectura, haga lo que haga el modelo del otro lado. ::: ## Alcance del token[​](#alcance-del-token "Enlace directo al Alcance del token") Además de los permisos, el MCP aplica el alcance que trae el token, en el claim `scope`. Las dos verificaciones se suman: una tool solo aparece si las dos lo permiten. Lectura es tool de lectura, resource, prompt de lectura y completion. Las tools de eliminación (`*_delete`, incluidas las masivas) exigen `delete`; la importación de NFS-e de Barueri (`billing_nfes_import_barueri`) exige `import`; todo lo demás que altera datos exige `write`. Un nivel no sustituye a otro: `write` no elimina ni importa. Cada tool exige exactamente el nivel que exige el endpoint REST detrás de ella — toda tool de eliminación llama a un `DELETE`, y el endpoint vuelve a verificar el token con ese nivel. **Token con recursos** — el caso del token personal y del flujo OAuth. Los recursos definen hasta dónde llega el token, y los verbos valen solo dentro de ellos: | Alcance del token | Resultado | | ----------------------------------------------- | ---------------------------------------------- | | `billing/invoices billing/customers read write` | Lee y escribe facturas y clientes — y nada más | | `billing/invoices read` | Solo lee facturas | | `billing/all read` | Lee todo, no escribe nada | Las cuentas bancarias, los bancos y las claves Pix solo se alcanzan con `billing/all`. `delete`, `import` y `export` solos no cuentan como escritura, y `write` solo no elimina. Para eliminar, el token necesita el recurso y `delete`: `billing/products read write delete` lee, modifica y elimina productos. **Token sin recursos** — un token que no trae ningún alcance `billing/…`. Vale solo el nivel de acceso: lectura con `read`, `write` o `all`; escritura con `write` o `all`; eliminación con `delete` o `all`; importación con `import` o `all`; exportación con `export` o `all`. Un token sin ninguno de esos niveles y sin `billing/…` no alcanza ninguna tool salvo `billing_me`. :::info Los clientes conectados por el flujo OAuth piden todos los niveles — tú eliges cuáles conceder El documento `/.well-known/oauth-protected-resource` anuncia los recursos del billing y los seis niveles de acceso — `read`, `write`, `delete`, `import`, `export` y `all` —, y eso es lo que el cliente (Claude, ChatGPT, el MCP Inspector, IDEs) pide en la pantalla de consentimiento. Ahí desmarcas lo que no quieres conceder, nivel por nivel: el token emitido trae solo los recursos y niveles que quedaron marcados, y el MCP lista solo las tools que ellos alcanzan. Una tool fuera de él devuelve `insufficient_scope`, y la salida es autorizar de nuevo concediendo el acceso que faltó — por ejemplo, `delete` para las tools de eliminación. ::: La misma regla vale en la API REST, con el recurso tomado de la ruta y un nivel por solicitud: `GET` exige `read`, `DELETE` exige `delete`, la importación exige `import` y el resto exige `write` — sin el nivel, la respuesta es `403 insufficient_scope`. Mira [Autenticación de la API](https://docs.billing.kobana.com.br/es/es/api/overview/authentication.md). ### 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**: Facturación verifica el token por su cuenta, sin consultar a Kobana en cada llamada, y sigue aceptándolo hasta su vencimiento. 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 quita el vínculo de la persona con la organización — los permisos se leen en cada llamada y valen al instante. ## Modos de fallo[​](#modos-de-fallo "Enlace directo al Modos de fallo") | HTTP | `code` | Causa | | ---- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `-32022` (JSON-RPC) | Versión del protocolo no soportada, en la cabecera `MCP-Protocol-Version` o en `_meta`; `data.supported` lista las que sí. Ve [Transporte](https://docs.billing.kobana.com.br/es/es/mcp/overview/transport.md#versiones-del-protocolo). | | 401 | `invalid_token` | Token ausente, malformado, inválido, emitido para otro recurso (por ejemplo, para la API REST) o con más de una audience en `aud`. | | 401 | `token_expired` | El token expiró. El cliente lo renueva y reintenta. | | 401 | `invalid_request` | Token en la query string — ve el aviso al inicio de esta página. | | 403 | `unknown_organization` | El token es válido, pero la organización que nombra no existe en Facturación. | | 403 | `FORBIDDEN` | `Origin` fuera de la allowlist (`origin_not_allowed`). | | 404 | `NOT_FOUND` | La petición llegó por un host que no sirve MCP. | | 429 | `TOO_MANY_REQUESTS` | Límite de peticiones alcanzado, con `Retry-After` y `X-RateLimit-*` — ver [Límite de peticiones](https://docs.billing.kobana.com.br/es/es/mcp/overview/rate-limit.md). | | 503 | `SERVICE_UNAVAILABLE` | No pudimos hablar con el authorization server para verificar el token. Es de nuestro lado: reintenta después del `Retry-After`. | Todo `401` lleva el desafío `WWW-Authenticate` de arriba, que devuelve al cliente al flujo OAuth. El desafío dice siempre `error="invalid_token"` (o `invalid_request`, para un token en la URL), como manda la RFC 6750; es el `code` del cuerpo lo que distingue un token expirado (`token_expired`) de los demás. Ninguna respuesta de `/mcp` es cacheable: todas, incluidas las negativas, llevan `Cache-Control: no-store` y `Content-Security-Policy: default-src 'none'`. La excepción es el documento público `/.well-known/oauth-protected-resource`, servido con `Cache-Control: public, max-age=300`. Las negativas 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.billing.kobana.com.br/es/es/mcp/overview/errors.md). ## Host y edge[​](#host-y-edge "Enlace directo al Host y edge") `/mcp` tiene que ser alcanzable **solo** por `mcp.billing.*` — nunca por el host de la app, nunca por el host de la API, cuyas distributions apuntan al mismo origin. Cualquier otro camino responde `404`: el endpoint no anuncia que existe en otro lugar. El identificador de recurso OAuth — y, por tanto, la audience que el token necesita tener — se deriva de la **configuración del servidor**, nunca del `Host` de la petición, 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; el cliente descubre solo dónde autenticarse, abre el inicio de sesión de Kobana en el navegador y guarda el token — ver [Autenticación](https://docs.billing.kobana.com.br/es/es/mcp/overview/authentication.md). Un cliente sin soporte de OAuth también se conecta, con un **token personal**: créalo en **Cuenta Kobana → Tokens y Acceso → Nuevo Token Personal**, con la app **Faturamento Automático** y el uso **MCP**, y configura el cliente para enviarlo en la cabecera `Authorization: Bearer `. ## Claude Code[​](#claude-code "Enlace directo al Claude Code") ``` claude mcp add --transport http kobana-billing https://mcp.billing.kobana.com.br ``` Después, ejecuta `/mcp` en una sesión y elige **Authenticate** para iniciar sesión en Kobana. Con un token personal, sin flujo OAuth: ``` claude mcp add --transport http kobana-billing https://mcp.billing.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 cabecera de autenticación: ``` { "mcpServers": { "kobana-billing": { "type": "http", "url": "https://mcp.billing.kobana.com.br" } } } ``` En la primera conexión el cliente abre el navegador para que autorices. No hay cabecera de selección de organización: eliges la organización en la pantalla de consentimiento, y queda grabada en el token. Con un token personal, agrega la cabecera — la organización es la de la cuenta en la que creaste el token: ``` { "mcpServers": { "kobana-billing": { "type": "http", "url": "https://mcp.billing.kobana.com.br", "headers": { "Authorization": "Bearer " } } } } ``` Trata el archivo como secreto: quien lo lee usa el token. ## Clientes que conectan por URL[​](#clientes-que-conectan-por-url "Enlace directo al Clientes que conectan por URL") Claude y ChatGPT conectan un servidor remoto pegando la URL `https://mcp.billing.kobana.com.br` en la configuración de conectores. El flujo OAuth corre dentro de la propia app. ## Postura recomendada para agentes[​](#postura-recomendada-para-agentes "Enlace directo al Postura recomendada para agentes") * **Autoriza con la cuenta correcta.** Las tools se estrechan a los permisos de dashboard de quien autorizó el cliente. 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 apagar un agente, quita su autorización en Kobana sin afectar tus integraciones. * **Token personal: validez corta y alcance 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 del vencimiento — ver [Revocación del token personal](https://docs.billing.kobana.com.br/es/es/mcp/overview/authentication.md#revocaci%C3%B3n-del-token-personal). * **Empieza en sandbox.** Las tools destructivas cancelan suscripciones y anulan facturas de verdad; el servidor pide confirmación antes de cada una (y las rechaza a un cliente que no puede confirmar), pero la primera exploración no debe ser en producción. ## Verificando la conexión[​](#verificando-la-conexión "Enlace directo al Verificando la conexión") La forma más simple es preguntarle al asistente: "¿qué organización estoy usando en Facturación?" — llama a `billing_organization_get`. Con un token emitido para el MCP — un token personal con uso **MCP**, por ejemplo —, puedes comprobarlo con `curl`: ``` # 1. ¿Qué organización alcanza este token? curl -s https://mcp.billing.kobana.com.br/ \ -H "Authorization: Bearer $MCP_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call", "params":{"name":"billing_organization_get","arguments":{}}}' # 2. ¿Cuántas tools alcanza este token? curl -s https://mcp.billing.kobana.com.br/ \ -H "Authorization: Bearer $MCP_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | jq '.result.tools | length' ``` Si el número es menor de lo que esperabas, son los permisos de quien autorizó o el alcance del token — ver [Autenticación](https://docs.billing.kobana.com.br/es/es/mcp/overview/authentication.md). No es un error. --- # Endpoints ## Servidor MCP[​](#servidor-mcp "Enlace directo al Servidor MCP") | Ambiente | URL | | ---------- | ------------------------------------------- | | Producción | `https://mcp.billing.kobana.com.br` | | Sandbox | `https://mcp.billing.sandbox.kobana.com.br` | La URL del servidor es la **raíz del host** — esa dirección entera es la que pegas en un cliente MCP. Es también el *resource identifier* OAuth, y por eso no lleva ninguna ruta. ## Rutas servidas[​](#rutas-servidas "Enlace directo al Rutas servidas") | Método | Ruta | Para qué | | -------- | --------------------------------------- | ---------------------------------------------------------------------- | | `POST` | `/` | Un mensaje JSON-RPC por petición. 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 terminar. | ## Documentación y API[​](#documentación-y-api "Enlace directo al Documentación y API") | | URL | | --------------------- | ------------------------------------------- | | Documentación | | | API REST (producción) | | | API REST (sandbox) | | tip Cada ambiente tiene su propia base de datos y su propio authorization server. Un token emitido en sandbox no vale en producción — empieza por sandbox. :::info Host separado, a propósito El servidor MCP tiene host propio en lugar de una ruta en el host de la API o de la app. Tres razones: el documento de descubrimiento OAuth debe vivir en la raíz del host; ninguna cookie del panel se envía a este origin, lo que elimina por construcción toda una clase de problemas de *confused deputy*; y el host de la API tiene una política de edge diseñada para integraciones servidor a servidor, no para una app de consumo. ::: ## Desarrollo local[​](#desarrollo-local "Enlace directo al Desarrollo local") En desarrollo el endpoint responde en `/mcp` en el host de la app (`http://localhost:3001/mcp`), y el documento de descubrimiento en `/.well-known/oauth-protected-resource`. Fuera de desarrollo la allowlist de host esconde el endpoint (`404`) fuera de `mcp.billing.*`. En el host MCP, cualquier ruta que no sea el endpoint ni el documento de descubrimiento responde un `404` en JSON, con cualquier método: ``` { "error": { "code": "NOT_FOUND", "message": "Not found." } } ``` --- # Errores Los fallos llegan por **dos canales distintos**, y la diferencia importa: uno es una petición 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, alcance insuficiente, 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\": \"Invoice not found\" } }" }] } } ``` El vocabulario de `code` es el de la API REST, sin cambios. Los que más vas a encontrar: | `code` | Cuándo | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `VALIDATION_ERROR` | Los argumentos fallaron la validación del endpoint; los detalles nombran los campos. | | `NOT_FOUND` | No existe ese registro, o pertenece a otra organización. | | `CONFLICT` / `DUPLICATE_ERROR` | `external_id` ya en uso, o una clave de negocio duplicada. | | `BAD_REQUEST` | Regla de negocio violada — cancelar una suscripción ya cancelada, finalizar una factura que no es borrador. | | `FORBIDDEN` | La operación no está permitida para este recurso en el estado en que está. | | `GATEWAY_ERROR` / `EXTERNAL_SERVICE_ERROR` | La pasarela de pago o el proveedor de NF-e rechazó o no respondió. | | `USER_DECLINED` | En la era `2026-07-28`, el usuario rechazó o canceló la confirmación de una tool destructiva. No se cambió nada. | | `confirmation_required` | La tool es destructiva, el cliente no puede confirmar en el chat y el token no tiene una persona que pueda abrir un enlace de aprobación. Usa un cliente en la revisión `2026-07-28` con elicitation. No se ejecutó nada. | | `confirmation_replayed` | La confirmación enviada ya se había usado — cada una ejecuta una llamada una vez. Llama la tool de nuevo para que se te pregunte otra vez. No se ejecutó nada. | | `confirmation_unavailable` | El servidor no pudo registrar la confirmación (o la aprobación por enlace) ahora, así que rechazó la tool. No se ejecutó nada; inténtalo de nuevo más tarde. | Y los cuatro que el propio MCP agrega, porque son sobre *autorización*, no sobre el recurso: | `code` | Quién lo resuelve | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `insufficient_scope` | El alcance del token no llega a la tool: el recurso no está en el token, o falta el verbo que la tool exige (`write`, `delete` o `import`). Autoriza de nuevo concediendo el acceso que faltó (por el flujo OAuth: lectura, escritura e importación sobre los recursos aprobados), o usa un token personal que alcance el recurso con el verbo pedido — la eliminación (`delete`) solo por token personal. | | `insufficient_permission` | Un admin de la organización, concediendo el permiso que el error nombra. | | `membership_inactive` | Reactivar a la persona que autorizó el cliente — ningún permiso arregla un vínculo muerto. | | `key_owner_not_member` | Autorizar el cliente de nuevo con una cuenta que sea miembro de la organización. | Esos cuatro están separados **a propósito**: son conversaciones distintas, con personas distintas. Un error único diría "no puedes" sin decir a quién pedírselo. Ve [Autenticación](https://docs.billing.kobana.com.br/es/es/mcp/overview/authentication.md). ### `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 con `resultType: "input_required"` y un pedido de confirmación al usuario. Es el flujo normal, no una falla: el cliente muestra la pregunta y reenvía la misma llamada con la respuesta. Ve [Confirmación de tools destructivas](https://docs.billing.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 es 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 — fallo inesperado al ejecutar la tool | ``` { "jsonrpc": "2.0", "id": 3, "error": { "code": -32601, "message": "Method not found: tools/describe" } } ``` ## 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, con el envoltorio de error de la API: token ausente o inválido, versión de protocolo no soportada, `Origin` fuera de la allowlist, límite de peticiones, cuerpo de más de **1 MB** (`413`, con el error JSON-RPC `-32600` `Request body too large`). Están listados en [Autenticación → Modos de fallo](https://docs.billing.kobana.com.br/es/es/mcp/overview/authentication.md#modos-de-fallo). ## Por qué `isError` y no un error JSON-RPC[​](#por-qué-iserror-y-no-un-error-json-rpc "Enlace directo al por-qué-iserror-y-no-un-error-json-rpc") Un `404` en una factura 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 fallo de transporte, escondiera el texto y, en el mejor caso, reintentara idéntico. De ahí la regla: **si el llamador puede actuar, es un resultado; si la petición está rota, es un error.** ## Observabilidad[​](#observabilidad "Enlace directo al Observabilidad") Cada `tools/call` escribe una línea estructurada con la tool, la organización, el token, el estado y la duración. Las **escrituras** también aparecen en la traza de auditoría de la organización, escrita por el propio endpoint despachado y atribuida a la persona que autorizó el cliente — lo que hizo un agente aparece al lado de lo que hizo una persona, en la misma pantalla. --- # Idempotencia Las tools que **crean un recurso o mueven dinero** aceptan un argumento opcional `idempotency_key`. Se envía al endpoint como la cabecera `X-Idempotency-Key` que la API REST ya honra. ``` { "name": "billing_invoices_create", "arguments": { "billing_account_id": "…", "total": 1250.00, "idempotency_key": "7c4a8d09-ca37-4f21-b1f0-3d2f2b8c9a11" } } ``` | | | | ---------------------------------- | --------------------------------------------------------------------- | | **Formato** | Cadena opaca, de 1 a 255 caracteres. Un UUID es la elección habitual. | | **Repetición con el mismo cuerpo** | Devuelve la respuesta original, sin ejecutar la operación de nuevo. | | **Repetición con cuerpo distinto** | Conflicto. | ## Por qué un agente necesita esto más que tu backend[​](#por-qué-un-agente-necesita-esto-más-que-tu-backend "Enlace directo al Por qué un agente necesita esto más que tu backend") Un cliente MCP que agota el tiempo y reintenta, o un modelo que decide "no estoy seguro de que eso funcionó, lo rehago", es exactamente el patrón que crea la segunda factura, el segundo cobro y el segundo cliente. Tu backend tiene un bucle de reintento que escribiste tú; el agente tiene un juicio. **Envía una clave siempre que la operación cobre, emita o cree.** Las lecturas y actualizaciones son naturalmente idempotentes y no piden clave. ## Tools que la aceptan[​](#tools-que-la-aceptan "Enlace directo al Tools que la aceptan") | Familia | Tools | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customers` | `billing_customers_create`, `billing_customers_upsert`, `billing_billing_accounts_create`, `billing_billing_accounts_upsert` | | `portal-users` | `billing_customer_users_create`, `billing_customer_users_invite` | | `users`, `roles` | `billing_dashboard_users_create`, `billing_dashboard_users_upsert`, `billing_team_roles_create`, `billing_team_roles_upsert` | | `products`, `plans`, `services` | `billing_products_create`, `billing_products_upsert`, `billing_product_groups_create`, `billing_product_groups_upsert`, `billing_plans_create`, `billing_plans_upsert`, `billing_plan_groups_create`, `billing_plan_groups_upsert`, `billing_service_items_create`, `billing_service_items_upsert` | | `subscriptions`, `plan-changes` | `billing_subscriptions_create`, `billing_subscriptions_upsert`, `billing_subscriptions_items_change`, `billing_plan_changes_execute`, `billing_plan_changes_rules_create` | | `invoices` | `billing_invoices_create`, `billing_invoices_upsert`, `billing_invoices_finalize`, `billing_invoices_pay`, `billing_invoices_installments_pay`, `billing_subscriptions_create_invoice` | | `payments` | `billing_payments_create`, `billing_payments_retry`, `billing_payments_refund`, `billing_payment_methods_create`, `billing_payment_methods_upsert` | | `credits`, `coupons` | `billing_credits_create`, `billing_credits_upsert`, `billing_coupons_create`, `billing_coupons_upsert` | | `nfes`, `companies` | `billing_nfes_create`, `billing_nfes_upsert`, `billing_nfes_issue`, `billing_companies_create`, `billing_companies_upsert` | | `tax-rules`, `tax-periods`, `withholdings` | `billing_tax_rules_create`, `billing_tax_rules_upsert`, `billing_tax_periods_process_month`, `billing_withholdings_create`, `billing_withholdings_upsert`, `billing_withholdings_convert_to_credit`, `billing_withholdings_convert_to_credits` | | `proposals`, `templates` | `billing_proposals_create`, `billing_proposals_upsert`, `billing_proposals_send`, `billing_proposals_accept`, `billing_proposal_templates_create`, `billing_proposal_templates_upsert` | | `usage` | `billing_usage_report`, `billing_usage_snapshots_daily_create`, `billing_usage_snapshots_monthly_create` | :::caution Las que cobran `billing_invoices_pay`, `billing_payments_create`, `billing_payments_retry` y `billing_nfes_issue` producen un efecto en el mundo — un cobro en la pasarela, una nota fiscal en la autoridad tributaria — que ningún `_delete` deshace. Envía `idempotency_key` en esas incluso cuando creas que no vas a repetir. ::: ## Upsert no es idempotencia[​](#upsert-no-es-idempotencia "Enlace directo al Upsert no es idempotencia") `*_upsert` empareja un registro existente por `id`, luego `external_id`, luego por la clave de negocio del recurso, y crea solo si no encuentra ninguno. Eso resuelve "no sé si ya existe", que es un problema distinto de "no sé si mi llamada llegó". Las dos cosas se combinan bien: un `upsert` con `idempotency_key` es seguro en ambas dimensiones. --- # Introducción El **servidor MCP de Facturación Automática** es un servidor [Model Context Protocol](https://modelcontextprotocol.io) remoto que expone las operaciones de la API pública — clientes, suscripciones, facturas, pagos, notas fiscales, propuestas y consumo — como **tools** que un cliente de IA puede llamar. Lo conectas por URL; no hay nada que instalar. Se sirve en host propio, `mcp.billing.kobana.com.br`, con transporte **Streamable HTTP** en modo stateless y autenticación por **Bearer token**. No hay certificado de cliente involucrado. :::info Disponibilidad El servidor y sus **293 tools** están implementados, y la autenticación pasa por el authorization server de Kobana: por el flujo **OAuth 2.1**, en el que el cliente recibe solo la URL e inicia sesión solo, o por un **token personal** creado en tu cuenta Kobana. El edge dedicado (distribución `mcp.billing.*`, WAF y DNS) aún se está aprovisionando. ::: ## 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 | un token, fuera de banda | una URL | | 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 | | Superficie | 178 rutas | 293 tools sobre los mismos endpoints | El servidor MCP **no reemplaza** la API REST. Cada tool despacha in-process al endpoint que implementa la operación, así que filtros, reglas de upsert, validación, prorrateo y aislamiento por organización son exactamente los mismos. Si estás escribiendo código, usa la [API REST](https://docs.billing.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 existe en MCP solo si existe en la API pública.** No hay una segunda implementación de nada. La tool llama al handler del endpoint con la identidad que el token del llamador ya probó — la misma persona, la misma organización —, así que corre como correría para cualquier petición HTTP, y la auditoría que escribe se atribuye a quien autorizó el cliente. Una tool hace lo que el endpoint hace por REST — nunca más. La consecuencia práctica: lo que hoy solo existe en el panel no se vuelve tool antes de volverse 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**, filtradas por los permisos de panel de quien autorizó el cliente. A un agente no se le informa de capacidades que solo le darían una negativa. Las reglas están en [Autenticación](https://docs.billing.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** — ve [Endpoints](https://docs.billing.kobana.com.br/es/es/mcp/overview/endpoints.md) y [Clientes](https://docs.billing.kobana.com.br/es/es/mcp/overview/clients.md). 2. **Autoriza.** El cliente abre el inicio de sesión de Kobana; entra con una cuenta de la organización y autoriza el acceso. Ve [Autenticación](https://docs.billing.kobana.com.br/es/es/mcp/overview/authentication.md). 3. **Lista las tools** para confirmar qué alcanza tu acceso — pídeselo al asistente, o, con un token emitido para el MCP a mano: ``` curl https://mcp.billing.kobana.com.br/ \ -H "Authorization: Bearer $MCP_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "MCP-Protocol-Version: 2025-06-18" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }' ``` 4. **Explora la documentación** — el catálogo completo está en [Tools](https://docs.billing.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.billing.kobana.com.br/es/es/mcp/overview/authentication.md) — el flujo OAuth, el token personal, el alcance y los permisos aplicados, y los modos de fallo. * [Endpoints](https://docs.billing.kobana.com.br/es/es/mcp/overview/endpoints.md) — URLs por ambiente y rutas servidas. * [Transporte](https://docs.billing.kobana.com.br/es/es/mcp/overview/transport.md) — JSON-RPC, cabeceras y métodos. * [Resources y prompts](https://docs.billing.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md) — documentos por URI, guiones listos, autocompletado y la confirmación de tools destructivas. * [Clientes](https://docs.billing.kobana.com.br/es/es/mcp/overview/clients.md) — cómo conectar Claude Code y clientes por archivo. * [Listado, orden y campos](https://docs.billing.kobana.com.br/es/es/mcp/overview/pagination.md) — `page`, `sort_by`, `fields`. * [Errores](https://docs.billing.kobana.com.br/es/es/mcp/overview/errors.md) — los dos canales de fallo, y por qué la diferencia importa. * [Tools](https://docs.billing.kobana.com.br/es/es/mcp/tools/overview.md) — el catálogo de las 293 tools. --- # Listado, Orden y Campos Las tools `*_list` usan la misma paginación de la API REST: **por número de página**. | Argumento | Predeterminado | Máximo | | ---------- | -------------- | ------ | | `page` | `1` | — | | `per_page` | `20` | `100` | ``` { "name": "billing_invoices_list", "arguments": { "status": "open", "page": 2, "per_page": 50 } } ``` El resultado trae el envoltorio de siempre: ``` { "data": [ /* ... */ ], "meta": { "total": 142, "page": 2, "per_page": 50, "total_pages": 3 } } ``` Cuando `page > total_pages`, `data` vuelve vacío — no es un error. :::note Colecciones que no paginan Algunas colecciones son **conjuntos hijos limitados por construcción** (los ítems de un plan, los intentos de una NF-e) o listas de configuración pequeñas. Esas responden el conjunto entero y **no aceptan `page`** — y la tool correspondiente tampoco ofrece el argumento. Es intencional: una tool que anunciara `page` en una ruta que lo ignora haría que el modelo paginara para siempre una lista que no avanza. ::: ## Orden[​](#orden "Enlace directo al Orden") | Argumento | Valores | Predeterminado | | ------------ | --------------------------------------------------------------- | ----------------- | | `sort_by` | Nombre de columna en **snake\_case** (`due_date`, `created_at`) | varía por recurso | | `sort_order` | `asc` o `desc`, en cualquier caja | varía por recurso | ``` { "name": "billing_invoices_list", "arguments": { "sort_by": "due_date", "sort_order": "asc" } } ``` Dos reglas que vale conocer, distintas entre sí a propósito: * **Una columna que el recurso no ordena cae al predeterminado.** Ordenar por un campo inexistente es un pedido que el servidor no puede atender, pero tampoco es motivo para tumbar la llamada entera; `billing_schemas_get` lista los aceptados en `sortable_fields`. * **Una dirección que no es dirección es `400`.** `sort_order: "descending"` es error, no un `desc` silencioso — devolver el orden correcto por accidente escondería el bug hasta el día en que el accidente cambiara de lado. ## Campos (`fields`)[​](#campos-fields "Enlace directo al campos-fields") Toda tool de lectura acepta `fields`, un array de nombres de columna. Omitido, vuelve el recurso entero; informado, vuelve solo eso: ``` { "name": "billing_invoices_list", "arguments": { "status": "open", "fields": ["number", "total", "due_date"] } } ``` | Regla | Por qué | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`id` siempre vuelve** | Una proyección que no puedes seguir no sirve de nada, y quitar el `id` en silencio rompería la llamada siguiente, no esta. | | **Solo el nivel de arriba** | `fields: ["billing_account"]` devuelve el objeto anidado entero; no hay sintaxis `billing_account.name`. | | **Solo en lectura** | Un create responde con un envoltorio que el llamador no eligió; proyectarlo escondería la mitad del recibo de una operación que ya ocurrió. | | **Un nombre desconocido es `400`** | Con la lista de lo que existe. Ignorarlo devolvería menos campos de los pedidos y parecería que el recurso no los tiene — respuesta equivocada con cara de correcta. | `fields` es la forma más barata de reducir el contexto que gasta un agente: la lista de 300 facturas con tres columnas cabe donde la misma lista completa no cabría. ## `billing_schemas_get` — el catálogo de campos[​](#billing_schemas_get--el-catálogo-de-campos "Enlace directo al billing_schemas_get--el-catálogo-de-campos") `fields` solo sirve si sabes qué pedir, y un modelo que tiene que adivinar intentará `invoice.amount` cuando el contrato dice `total`. `billing_schemas_get` responde eso directamente: ``` { "name": "billing_schemas_get", "arguments": {} } { "name": "billing_schemas_get", "arguments": { "resource": "invoice" } } ``` Sin argumento devuelve el catálogo de recursos. Con `resource`, devuelve todos los campos de ese recurso — nombre, tipo, enum, si acepta nulo, descripción — y, por separado, sus `sortable_fields`. Viene de los mismos esquemas que generan el OpenAPI publicado, así que la lista que reporta la tool y la que publica esta documentación no pueden divergir. ## Contrato de datos[​](#contrato-de-datos "Enlace directo al Contrato de datos") Lo que vale para la API v1 vale aquí, porque es el mismo código: * **snake\_case en todo**, argumentos y respuestas. * **El dinero es float en BRL**, en ambos sentidos, sin sufijo de unidad. `amount: 100` es R$ 100,00; los campos de precios aceptan hasta 4 decimales. * **Fechas en ISO 8601**, procesadas en UTC. * **Las escrituras aceptan `idempotency_key`** — ve [Idempotencia](https://docs.billing.kobana.com.br/es/es/mcp/overview/idempotency.md). --- # Límite de Peticiones El servidor MCP comparte los **mismos límites de la API REST**, contados **por persona y organización** — el `sub` y el `org` del token, no el token en sí. Cambiar de token no reinicia el presupuesto: un token nuevo, ya sea de una nueva autorización OAuth o un nuevo token personal, de la misma persona en la misma organización cae en el mismo bucket. La misma persona en otra organización tiene presupuesto propio. Una llamada de tool **nunca es más barata que el endpoint que refleja**: la petición se cuenta una vez en el bucket del propio MCP y, cuando es un `tools/call`, otra vez por el bucket del endpoint al que despacha. Es deliberado — un agente que recorre listados en bucle no debería poder esquivar el límite que ese mismo recorrido pagaría por REST. Los intentos con token inválido se estrangulan **por IP**, no por token, igual que en el edge REST: un token que no se verifica no puede tener bucket propio. Una petición sin ningún token — el primer paso de todo cliente, antes del OAuth — no cuenta como intento. ## Cuando se alcanza el límite[​](#cuando-se-alcanza-el-límite "Enlace directo al Cuando se alcanza el límite") El servidor responde `429` — **el mensaje JSON-RPC ni siquiera se procesa**: ``` HTTP/1.1 429 Too Many Requests Retry-After: 37 X-RateLimit-Limit: 100 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1793280037 Cache-Control: no-store Content-Type: application/json { "error": { "code": "TOO_MANY_REQUESTS", "message": "Rate limit exceeded" }, "retry_after": 37 } ``` Espera los segundos de `Retry-After` antes de la próxima petición. `X-RateLimit-Limit` y `X-RateLimit-Remaining` dicen el tamaño del bucket y lo que queda; `X-RateLimit-Reset` es cuándo se renueva, en segundos desde la época Unix. Los límites por cuenta y por tipo de petición están en la [página de límites de la API](https://docs.billing.kobana.com.br/es/es/api/overview/rate-limit.md) — son los mismos. ## Gastando menos[​](#gastando-menos "Enlace directo al Gastando menos") Un agente consume el mismo presupuesto que tu backend, y además paga contexto por cada fila que trae. Dos hábitos resuelven casi todo: * **Filtra antes de paginar.** `billing_invoices_list { status: "open", due_date_lte: "2026-09-30" }` cuesta una petición; recorrer todas las facturas para filtrar en el modelo cuesta decenas. * **Pide solo las columnas que importan.** `fields: ["number", "total", "due_date"]` no reduce el número de peticiones, pero reduce mucho el contexto gastado — ve [Listado, orden y campos](https://docs.billing.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 el usuario adjunta a la conversación), **prompts** (guiones listos que el usuario elige) y **completions** (autocompletado de sus argumentos). En la era `2026-07-28` también pide **confirmación** antes de ejecutar una tool destructiva. Nada de esto abre un camino nuevo hacia tus datos: todo pasa por las mismas tools, con los mismos permisos y el mismo [alcance del token](https://docs.billing.kobana.com.br/es/es/mcp/overview/authentication.md#alcance-del-token). Con un token solo de lectura, los resources y las completions siguen disponibles, pero un prompt que escribe — como `collect_overdue_invoices`, que envía recordatorios — no aparece. ## Resources[​](#resources "Enlace directo al Resources") Un resource es un documento identificado por una URI. El usuario elige, por ejemplo, una factura, y el cliente lee el documento y lo pone en el contexto, sin que el modelo tenga que llamar a una tool. | URI | Qué vuelve | | ------------------------------------- | ------------------------------------------------------------------------ | | `kobana://billing/organization` | La organización del token (JSON) | | `kobana://billing/schemas` | El catálogo de recursos de la API (JSON) | | `kobana://billing/schemas/{resource}` | Los campos de un recurso: tipo, enum, significado, cuáles ordenan (JSON) | | `kobana://billing/customers/{id}` | Un cliente (JSON) | | `kobana://billing/subscriptions/{id}` | Una suscripción (JSON) | | `kobana://billing/invoices/{id}` | Una factura (JSON) | | `kobana://billing/invoices/{id}/pdf` | El PDF de la factura | | `kobana://billing/nfes/{id}` | Una NF-e (JSON) | | `kobana://billing/nfes/{id}/pdf` | El DANFE de la NF-e | | `kobana://billing/nfes/{id}/xml` | El XML autorizado de la NF-e (texto) | `resources/list` trae las URIs fijas y `resources/templates/list` las plantillas con `{id}`. * **Permisos.** Cada resource se lee con la tool correspondiente (`kobana://billing/invoices/{id}` es `billing_invoices_get`). Solo aparece, y solo se lee, si puedes ejecutar esa tool. * **Binarios.** Los PDF vuelven en base64 (`blob`), hasta **10 MB**. A diferencia de las tools, que solo describen el archivo, aquí el documento es la respuesta: lo pidió el cliente. * **No encontrado.** Una URI desconocida, o un registro que no existe en esta organización, es `-32002` en la era 2025 y `-32602` en la `2026-07-28` — ve [Errores](https://docs.billing.kobana.com.br/es/es/mcp/overview/errors.md). * **Sin suscripción a cambios.** El servidor es stateless: no hay `resources/subscribe` ni aviso de lista cambiada. ## 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. | Prompt | Argumentos | Qué hace | | -------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `collect_overdue_invoices` | `customer_id` (opcional) | Lista las facturas abiertas vencidas, muestra una tabla y **pregunta** cuáles deben recibir recordatorio antes de enviar. | | `review_pending_nfes` | — | Junta las facturas que aún no tienen NF-e y las NF-e rechazadas, las resume y sugiere el próximo paso, sin emitir nada. | | `customer_overview` | `customer_id` | El retrato de un cliente: datos, suscripciones, lo que está abierto y lo que está vencido. | | `monthly_billing_summary` | `month` (opcional, `YYYY-MM`) | Lo que se facturó, se cobró y quedó abierto en el mes. | Un argumento obligatorio ausente, o un `month` mal formado, es `-32602`. ## Completions[​](#completions "Enlace directo al Completions") `completion/complete` sugiere valores mientras escribes un argumento: * **Ids** (`customer_id`, y el `{id}` de clientes, facturas y suscripciones): busca en el listado correspondiente, con su mismo permiso. Si no puedes listar, no hay sugerencia. * **`{resource}` de `kobana://billing/schemas/{resource}`**: los nombres del catálogo, 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 destructivas — las que borran, anulan, cancelan o archivan en masa; cobran, pagan, reembolsan, marcan como pagado o aplican crédito; emiten o cancelan una nota fiscal; envían un e-mail, invitación, recordatorio o propuesta, o publican un link público; o cambian la cuenta bancaria y la clave Pix de cobro — llevan `destructiveHint`. El **servidor** no confía solo en el cliente: en la era `2026-07-28` pide la confirmación él mismo: 1. El primer `tools/call` no ejecuta nada. Vuelve con `resultType: "input_required"` y 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 la ejecuta. Rechazar o cancelar devuelve un resultado `isError` con `USER_DECLINED`, y nada cambia. La confirmación vale **solo para esa llamada**: la misma tool, los mismos argumentos, la misma persona y organización, durante **5 minutos**. Una respuesta no puede reutilizarse para otra factura u otra acción; si algo no coincide, el servidor simplemente vuelve a preguntar. Y es de **uso único**: reenviar una llamada ya confirmada devuelve `isError` con `confirmation_replayed`, sin ejecutar nada — para repetir la acción, llama la tool de nuevo y confirma otra vez. ### Cliente sin formulario de confirmación: aprobación por enlace[​](#cliente-sin-formulario-de-confirmación-aprobación-por-enlace "Enlace directo al Cliente sin formulario de confirmación: aprobación por enlace") Un cliente que **no puede confirmar en el chat** — en la era 2025, o en la `2026-07-28` sin declarar formularios de elicitation (la app de Claude en el celular, por ejemplo) — también usa las tools destructivas, mediante un **enlace de aprobación**. La llamada **no ejecuta nada**: el servidor guarda la operación como pendiente y responde con éxito, en un único texto JSON: ``` { "status": "approval_required", "approval": { "id": "6f0c2d1e-…", "url": "https://app.billing.kobana.com.br/approvals/…", "expires_at": "2026-10-31T12:15:00.000Z" }, "message": "… Show this URL to the user … Do not call the tool again … After the user says they decided, call `billing_operation_approvals_get` with this `approval.id` …" } ``` 1. El asistente muestra la URL. No llames la tool de nuevo: eso crearía otra aprobación. 2. Abres el enlace **con sesión iniciada en Facturación Automática** (sin sesión, pasa por el login y vuelve al enlace). La pantalla muestra lo que va a pasar ("Pagar la factura", "Eliminar el cliente"), quién lo pidió, cuándo, la organización, los datos actuales del registro y **todos** los argumentos — cada ítem de un lote, uno por uno. Los argumentos crudos están en "Detalles técnicos". 3. **Continuar** ejecuta la operación en el momento, con los permisos que tienes **ahora**: si perdiste el permiso desde el pedido, la ejecución falla y nada cambia. **Cancelar** la cierra sin ejecutar nada. El enlace vale **15 minutos** y decide **una sola vez**: dos clics en Continuar ejecutan una vez, y un enlace vencido o cancelado no ejecuta. Solo **tú** — la persona detrás del token que hizo la llamada — abres el enlace: para cualquier otra persona, incluso de tu organización, no existe. Tus aprobaciones están en **Sistema → Aprobaciones** en el panel, con pestañas por estado; al hacer clic en una fila se abre la aprobación solo para lectura (una pendiente se decide en el enlace que mostró el asistente). #### Después de la decisión: el resultado en el propio chat[​](#después-de-la-decisión-el-resultado-en-el-propio-chat "Enlace directo al Después de la decisión: el resultado en el propio chat") La misma sesión que pidió la operación consulta qué pasó, sin que copies nada de la pantalla. Cuando le dices al asistente que decidiste, llama **una vez** a `billing_operation_approvals_get` con el `approval.id` de la respuesta — sin consultar en bucle mientras no decides: ``` { "data": { "id": "6f0c2d1e-…", "status": "executed", "action": "billing_invoices_pay", "title": "Pagar la factura", "resource": "invoices", "operation": "pay", "amount": 150.5, "requested_at": "2026-10-31T12:00:00.000Z", "expires_at": "2026-10-31T12:15:00.000Z", "decided_at": "2026-10-31T12:03:10.000Z", "executed_at": "2026-10-31T12:03:11.000Z", "error": null, "result": { "data": { "id": "…", "status": "paid" } }, "result_hidden": false } } ``` | `status` | Qué significa | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `pending` | Aún sin decidir. | | `approved` | Elegiste Continuar y la ejecución está en curso. | | `executed` | Ejecutada: `result` trae lo que devolvió la tool, con los secretos enmascarados (el valor en claro aparece una sola vez, en la pantalla). | | `failed` | No se ejecutó; `error.code` dice por qué (`subject_changed`, falta de permiso…). No cambió nada. | | `declined` | Cancelaste. No se ejecutó nada. | | `expired` | El enlace venció sin decisión. No se ejecutó nada. | `billing_operation_approvals_list` lista tus aprobaciones, de la más reciente a la más antigua, con filtro por `status` y por `created_after`/`created_before`. Las dos tools son de solo lectura — ninguna aprueba, cancela ni reabre una aprobación — y no piden scope ni permiso: cualquier token con persona lee sus **propias** aprobaciones en esa organización. La de otra persona, de otra organización o un id inexistente responden el mismo `NOT_FOUND`. Lo que devolvió la operación (`result`, `error` y un `amount` leído del registro) solo viene cuando el token también lee el recurso de esa aprobación y aún tienes permiso de lectura sobre él: un token restringido a productos ve su aprobación sobre una factura — estado, título, fechas —, pero con esos campos `null` y `result_hidden: true`. El `title` sale en el idioma del pedido (`Accept-Language`), y la respuesta nunca trae el enlace ni los argumentos. En la API REST, lo mismo está en `GET /v1/operation_approvals` y `GET /v1/operation_approvals/{id}`. Si la factura, el pago, la cuenta o la clave de destino cambia entre abrir la pantalla y Continuar, no se ejecuta nada (`subject_changed`): pide la operación de nuevo y revisa el nuevo enlace. Los datos de tarjeta en claro (número o CVV) nunca se guardan esperando aprobación: la llamada devuelve `confirmation_required` — usa un `card_token` o un cliente con formulario de confirmación. Un token sin persona que pueda abrir el enlace devuelve `isError` con `confirmation_required`. Si el servidor no puede registrar la aprobación en ese momento, la tool se rechaza con `confirmation_unavailable`; inténtalo de nuevo más tarde. Las demás tools siguen funcionando normalmente. --- # 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 toda operación larga ya responde de inmediato y termina en un worker en segundo plano, no en el canal MCP. ## 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 — se descubre con `server/discover` | Soportada | | `2025-06-18` | Handshake con `initialize` — la versión en la que `initialize` cierra por defecto | Soportada | | `2025-03-26` | Handshake con `initialize` | Soportada | La era se decide **por el cuerpo** de la petición, con las cabeceras como verificación: * **`params._meta` trae `io.modelcontextprotocol/protocolVersion`** → era `2026-07-28` (ve abajo). * **Sin ese sobre**, con `MCP-Protocol-Version` de 2025 o sin la cabecera → era 2025, con `initialize`. * **`MCP-Protocol-Version: 2026-07-28` sin el sobre** → `400` con `-32602`. El servidor no cae a la era antigua en silencio: pediste la semántica stateless y recibirías la otra. Una versión que el servidor no habla — en la cabecera o en el sobre, 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 la cabecera `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** petición lleva su propia versión y las capacidades del cliente en `params._meta`, y el servidor no recuerda nada de una petición a otra. | Clave de `params._meta` | Obligatoria | Significado | | -------------------------------------------- | ----------- | ----------------------------------------------- | | `io.modelcontextprotocol/protocolVersion` | sí | `2026-07-28` | | `io.modelcontextprotocol/clientCapabilities` | sí | Capacidades del cliente (un objeto; `{}` sirve) | | `io.modelcontextprotocol/clientInfo` | recomendada | `name` y `version` del cliente | Las cabeceras repiten lo que dice el cuerpo, para que los intermediarios puedan enrutar sin leerlo — y por eso tienen que coincidir con él: | Cabecera | Tiene que ser igual a | | ---------------------- | ------------------------------------------------------------------- | | `MCP-Protocol-Version` | La versión del sobre | | `Mcp-Method` | El `method` del mensaje | | `Mcp-Name` | Solo en `tools/call`: el `params.name`, crudo o como `=?base64?…?=` | Cualquier discrepancia 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 se filtra por los permisos de quien llama, así que no debe reutilizarse ni compartirse. Un `tools/call` de una tool destructiva puede volver con `resultType: "input_required"` — ve [Confirmación de tools destructivas](https://docs.billing.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md#confirmaci%C3%B3n-de-tools-destructivas). ## Cabeceras de la petición[​](#cabeceras-de-la-petición "Enlace directo al Cabeceras de la petición") | Cabecera | Obligatoria | Significado | | ---------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | sí | `Bearer ` emitido para el MCP — ve [Autenticación](https://docs.billing.kobana.com.br/es/es/mcp/overview/authentication.md) | | `Content-Type` | sí | `application/json` | | `Accept` | recomendada | `application/json` | | `MCP-Protocol-Version` | sí en la era `2026-07-28`; recomendada 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 `tools/call` de la era `2026-07-28` | El nombre de la tool | | `Origin` | condicional | Enviada por clientes de navegador; validada contra una allowlist | No hay cabecera de selección de inquilino: la organización viene del propio token, y ninguna tool acepta un argumento de organización. El cuerpo de la petición tiene un límite de **1 MB**. Por encima de eso — por el `Content-Length` declarado o por lo que de hecho llega — la respuesta es `413` con `{ "jsonrpc": "2.0", "id": null, "error": { "code": -32600, "message": "Request body too large (limit 1048576 bytes)" } }`. Ninguna tool recibe archivos, así que una llamada legítima queda muy por debajo. ## Cabeceras de la respuesta[​](#cabeceras-de-la-respuesta "Enlace directo al Cabeceras de la respuesta") | Cabecera | Significado | | ---------------------- | -------------------------------------------------------------------------------------------------------------- | | `MCP-Protocol-Version` | Revisión en uso | | `Cache-Control` | Siempre `no-store` | | `Retry-After` | Solo en `429` — ve [Límite de peticiones](https://docs.billing.kobana.com.br/es/es/mcp/overview/rate-limit.md) | ## 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 su 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í | Las plantillas de URI (`kobana://billing/invoices/{id}`, …) que este llamador puede leer | | `resources/read` | sí | sí | Lee un documento por su 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 plantilla | Resources, prompts y completions están en [Resources y prompts](https://docs.billing.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md). Cualquier otro método es `-32601 Method not found` — con HTTP `404` en la era `2026-07-28`; en el cuerpo de un `200` en la de 2025. **El batching JSON-RPC no es soportado** — fue removido en la revisión `2025-06-18`, y un cuerpo en array se responde con `400`. Una **notificación** (mensaje sin `id`, como `notifications/initialized`) se acepta con `202` y cuerpo vacío, en las dos eras. La autenticación va **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 — ve [Autenticación](https://docs.billing.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 Billing: ...", "ttlMs": 0, "cacheScope": "private", "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "kobana-billing", "title": "Kobana Billing", "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-billing", "title": "Kobana Billing", "version": "1.0.0" }, "instructions": "Tools for Kobana Billing: ..." } } ``` ### `tools/list`[​](#toolslist "Enlace directo al toolslist") Devuelve **solo** las tools que el llamador puede ejecutar, filtradas por los permisos de panel de quien autorizó el cliente. 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, cobra, reembolsa, emite una nota fiscal o envía algo a terceros. El servidor pide confirmación en el chat en la era `2026-07-28` con elicitation; a cualquier otro cliente le responde un enlace de aprobación, y nada se ejecuta hasta que eliges Continuar | | `idempotentHint` | Repetir la llamada tiene el mismo efecto | | `openWorldHint` | Siempre `false` — la tool no alcanza nada fuera de Facturación Automática | ### `tools/call`[​](#toolscall "Enlace directo al toolscall") ``` { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "billing_invoices_list", "arguments": { "status": "open", "per_page": 10, "fields": ["number", "total", "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\": { \"total\": 42, ... } }" }] } } ``` Los errores sobre los que el llamador puede actuar vuelven con `isError: true` **dentro** del resultado, no como error JSON-RPC — ve [Errores](https://docs.billing.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 `/api/v1` que implementa la operación. No hay segundo viaje HTTP ni segunda implementación: filtros de listado, reglas de upsert, validación, soft-delete, prorrateo y aislamiento por organización son el mismo código que corre la API REST. Una tool no puede divergir del endpoint que refleja. ## Binarios[​](#binarios "Enlace directo al Binarios") `billing_invoices_pdf`, `billing_nfes_pdf` y `billing_nfes_xml` **no** devuelven 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 la ruta para buscar el archivo en el host de la API, con un token emitido para la API. --- # Catálogo Lo que la organización vende: productos y sus grupos, planes, precios e ítems de servicio sueltos. ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | -------------------------------------------- | ----- | ---- | ----- | ----------- | | `products` — Productos y grupos de productos | 24 | 4 | 16 | 4 | | `plans` — Planes, precios y grupos | 21 | 5 | 12 | 4 | | `services` — Ítems de servicio | 6 | 2 | 3 | 1 | ## `products`[​](#products "Enlace directo al products") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | -------------------------------------- | ----------- | -------- | ----------------- | --------------------------------------- | -------------------------------------------------------------------------------------- | | `billing_products_list` | read | `read` | `products.list` | `GET /v1/products` | List products in the catalog. | | `billing_products_get` | read | `read` | `products.show` | `GET /v1/products/:id` | Fetch one product with its prices. | | `billing_products_create` | write | `write` | `products.create` | `POST /v1/products` | Create a product, optionally with its prices in the same call. | | `billing_products_upsert` | write | `write` | `products.create` | `PUT /v1/products` | Create or update a product matched on `id` → `external_id` → `slug`. | | `billing_products_update` | write | `write` | `products.update` | `PATCH /v1/products/:id` | Update a product in place. | | `billing_products_delete` | destructive | `delete` | `products.delete` | `DELETE /v1/products/:id` | Delete a product: it disappears from every read and leaves every plan. | | `billing_products_publish` | write | `write` | `products.update` | `POST /v1/products/:id/publish` | Move a draft product to `active`, making it sellable. | | `billing_products_archive` | write | `write` | `products.update` | `POST /v1/products/:id/archive` | Archive a product: it stops being sellable but existing subscriptions keep billing it. | | `billing_products_restore` | write | `write` | `products.update` | `POST /v1/products/:id/restore` | Bring an archived product back to `active`. | | `billing_products_reorder` | write | `write` | `products.update` | `POST /v1/products/reorder` | Set the catalog display order. | | `billing_products_bulk_archive` | destructive | `write` | `products.update` | `POST /v1/products/bulk-archive` | Archive up to 100 products in one call. | | `billing_products_bulk_delete` | destructive | `delete` | `products.delete` | `DELETE /v1/products/bulk` | Soft-delete up to 100 products in one call. | | `billing_products_bulk_move_group` | write | `write` | `products.update` | `POST /v1/products/bulk-move-group` | Move products to a product group. | | `billing_products_bulk_change_company` | write | `write` | `products.update` | `POST /v1/products/bulk-change-company` | Reassign the issuing legal entity of several products. | | `billing_products_bulk_visibility` | write | `write` | `products.update` | `POST /v1/products/bulk-visibility` | Set several products public or private at once. | | `billing_product_groups_list` | read | `read` | `products.list` | `GET /v1/product_groups` | List product groups — the catalog sections products are filed under. | | `billing_product_groups_get` | read | `read` | `products.show` | `GET /v1/product_groups/:id` | Fetch one product group with its display order. | | `billing_product_groups_create` | write | `write` | `products.create` | `POST /v1/product_groups` | Create a product group to file products under. | | `billing_product_groups_upsert` | write | `write` | `products.create` | `PUT /v1/product_groups` | Create or update a product group matched on `id` → `external_id` → `slug`. | | `billing_product_groups_update` | write | `write` | `products.update` | `PATCH /v1/product_groups/:id` | Update a product group — name, slug, company or display order. | | `billing_product_groups_delete` | destructive | `delete` | `products.delete` | `DELETE /v1/product_groups/:id` | Soft-delete a product group. | | `billing_product_groups_archive` | write | `write` | `products.update` | `POST /v1/product_groups/:id/archive` | Archive a product group, hiding it from the catalog. | | `billing_product_groups_unarchive` | write | `write` | `products.update` | `POST /v1/product_groups/:id/unarchive` | Bring an archived product group back into the catalog. | | `billing_product_groups_reorder` | write | `write` | `products.update` | `POST /v1/product_groups/reorder` | Set the display order of product groups. | ## `plans`[​](#plans "Enlace directo al plans") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ------------------------------- | ----------- | -------- | -------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `billing_plans_list` | read | `read` | `plans.list` | `GET /v1/plans` | List plans — the bundles of products a subscription can point at. | | `billing_plans_get` | read | `read` | `plans.show` | `GET /v1/plans/:id` | Fetch one plan with its items. | | `billing_plans_create` | write | `write` | `plans.create` | `POST /v1/plans` | Create a plan, optionally with its items in the same call. | | `billing_plans_upsert` | write | `write` | `plans.create` | `PUT /v1/plans` | Create or update a plan matched on `id` → `external_id` → `slug`. | | `billing_plans_update` | write | `write` | `plans.update` | `PATCH /v1/plans/:id` | Update a plan in place. | | `billing_plans_delete` | destructive | `delete` | `plans.delete` | `DELETE /v1/plans/:id` | Delete a plan: it disappears from every read. | | `billing_plans_archive` | write | `write` | `plans.update` | `POST /v1/plans/:id/archive` | Archive a plan: it closes to new subscriptions but stays listed, and existing subscriptions keep billing it. | | `billing_plans_duplicate` | write | `write` | `plans.create` | `POST /v1/plans/:id/duplicate` | Copy a plan and its items into a new draft plan. | | `billing_plans_items_list` | read | `read` | `plans.show` | `GET /v1/plans/:id/items` | List the items of a plan — which product, at which price, in which quantity. | | `billing_plans_items_replace` | write | `write` | `plans.update` | `PUT /v1/plans/:id/items` | Replace every item of a plan atomically. | | `billing_plans_bulk_archive` | destructive | `write` | `plans.update` | `POST /v1/plans/bulk-archive` | Archive up to 100 plans in one call. | | `billing_plans_bulk_delete` | destructive | `delete` | `plans.delete` | `DELETE /v1/plans/bulk` | Soft-delete up to 100 plans in one call. | | `billing_plans_bulk_move_group` | write | `write` | `plans.update` | `POST /v1/plans/bulk-move-group` | Move plans to a plan group. | | `billing_plan_groups_list` | read | `read` | `plans.list` | `GET /v1/plan_groups` | List plan groups — the sections plans are filed under in the catalog. | | `billing_plan_groups_get` | read | `read` | `plans.show` | `GET /v1/plan_groups/:id` | Fetch one plan group with its display order. | | `billing_plan_groups_create` | write | `write` | `plans.create` | `POST /v1/plan_groups` | Create a plan group to file plans under. | | `billing_plan_groups_upsert` | write | `write` | `plans.create` | `PUT /v1/plan_groups` | Create or update a plan group matched on `id` → `external_id` → `slug`. | | `billing_plan_groups_update` | write | `write` | `plans.update` | `PATCH /v1/plan_groups/:id` | Update a plan group — name, slug, description or display order. | | `billing_plan_groups_delete` | destructive | `delete` | `plans.delete` | `DELETE /v1/plan_groups/:id` | Soft-delete a plan group. | | `billing_plan_groups_archive` | write | `write` | `plans.update` | `POST /v1/plan_groups/:id/archive` | Archive a plan group, hiding it from the catalog without touching its plans. | | `billing_plan_groups_reorder` | write | `write` | `plans.update` | `POST /v1/plan_groups/reorder` | Set the display order of plan groups. | ## `services`[​](#services "Enlace directo al services") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ------------------------------ | ----------- | -------- | ----------------- | ------------------------------ | -------------------------------------------------------------------------------------------- | | `billing_service_items_list` | read | `read` | `services.list` | `GET /v1/service_items` | List fiscal service items — the LC 116 / NBS classification an invoice line is issued under. | | `billing_service_items_get` | read | `read` | `services.show` | `GET /v1/service_items/:id` | Fetch one service item with its fiscal codes and default ISS rate. | | `billing_service_items_create` | write | `write` | `services.create` | `POST /v1/service_items` | Create a fiscal service item for products to be invoiced under. | | `billing_service_items_upsert` | write | `write` | `services.create` | `PUT /v1/service_items` | Create or update a service item matched on `id` → `external_id` → `internal_code`. | | `billing_service_items_update` | write | `write` | `services.update` | `PATCH /v1/service_items/:id` | Update a service item. | | `billing_service_items_delete` | destructive | `delete` | `services.delete` | `DELETE /v1/service_items/:id` | Soft-delete a service item. | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.billing.kobana.com.br/es/es/api/v1) y en `billing_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.billing.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Clientes y accesos Clientes, sus cuentas de cobro, los usuarios que entran al portal y el equipo que usa el panel de la organización. ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | ----------------------------------------- | ----- | ---- | ----- | ----------- | | `customers` — Clientes y cuentas de cobro | 19 | 6 | 9 | 4 | | `portal-users` — Usuarios del portal | 9 | 4 | 2 | 3 | | `users` — Usuarios del panel | 6 | 2 | 1 | 3 | | `roles` — Roles del equipo | 6 | 2 | 3 | 1 | ## `customers`[​](#customers "Enlace directo al customers") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | --------------------------------------- | ----------- | -------- | ---------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `billing_customers_list` | read | `read` | `customers.list` | `GET /v1/customers` | List the customers of the token organization. | | `billing_customers_get` | read | `read` | `customers.show` | `GET /v1/customers/:id` | Fetch one customer by id, `public_id` or `external_id`. | | `billing_customers_create` | write | `write` | `customers.create` | `POST /v1/customers` | Create a customer and, unless `create_billing_account` is false, the billing account that bills it. | | `billing_customers_upsert` | write | `write` | `customers.create` | `PUT /v1/customers` | Create or update a customer, matched on `id` → `public_id` → `external_id` → `document_number`, stopping at the first hit. | | `billing_customers_update` | write | `write` | `customers.update` | `PATCH /v1/customers/:id` | Update a customer in place. | | `billing_customers_delete` | destructive | `delete` | `customers.delete` | `DELETE /v1/customers/:id` | Soft-delete a customer (`deleted_at`). | | `billing_customers_recalculate_mrr` | write | `write` | `customers.update` | `POST /v1/customers/:id/recalculate-mrr` | Recompute the customer MRR from its active subscriptions. | | `billing_customers_statement` | read | `read` | `customers.show` | `GET /v1/customers/:id/statement` | Account statement for a customer: invoices, payments, credits and the running balance. | | `billing_customers_statement_sync` | write | `write` | `customers.update` | `POST /v1/customers/:id/statement/sync` | Recompute and persist the customer statement snapshot. | | `billing_billing_accounts_list` | read | `read` | `customers.list` | `GET /v1/billing_accounts` | List billing accounts. | | `billing_billing_accounts_get` | read | `read` | `customers.show` | `GET /v1/billing_accounts/:id` | Fetch one billing account by id, `public_id` or `external_id`. | | `billing_billing_accounts_create` | write | `write` | `customers.create` | `POST /v1/billing_accounts` | Open a billing account for an existing customer. | | `billing_billing_accounts_upsert` | write | `write` | `customers.create` | `PUT /v1/billing_accounts` | Create or update a billing account matched on `id` → `public_id` → `external_id`. | | `billing_billing_accounts_update` | write | `write` | `customers.update` | `PATCH /v1/billing_accounts/:id` | Update a billing account in place. | | `billing_billing_accounts_delete` | destructive | `delete` | `customers.delete` | `DELETE /v1/billing_accounts/:id` | Delete a billing account, with its payment methods, cards, portal users and files: they disappear from every read. | | `billing_billing_accounts_suspend` | destructive | `write` | `customers.suspend` | `POST /v1/billing_accounts/:id/suspend` | Suspend a billing account. | | `billing_billing_accounts_reactivate` | write | `write` | `customers.reactivate` | `POST /v1/billing_accounts/:id/reactivate` | Lift a suspension and resume collection on a billing account. | | `billing_billing_accounts_close` | destructive | `write` | `customers.delete` | `POST /v1/billing_accounts/:id/close` | Close a billing account for good. | | `billing_billing_accounts_entitlements` | read | `read` | `customers.show` | `GET /v1/billing_accounts/:id/entitlements` | What this billing account is entitled to right now, derived from its active subscriptions — the answer to "can this customer use feature X?". | ## `portal-users`[​](#portal-users "Enlace directo al portal-users") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | -------------------------------------- | ----------- | -------- | --------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `billing_customer_users_list` | read | `read` | `portal-users.list` | `GET /v1/customers/:id/users` | List the portal users attached to a customer. | | `billing_customer_users_create` | write | `write` | `portal-users.create` | `POST /v1/customers/:id/users` | Attach a portal user to a customer without sending an invitation e-mail. | | `billing_customer_users_invite` | destructive | `write` | `portal-users.create` | `POST /v1/customers/:id/users/invite` | Invite a portal user to a customer — creates the user and sends the invitation e-mail. | | `billing_customer_users_get` | read | `read` | `portal-users.show` | `GET /v1/customers/:id/users/:user_id` | Fetch one portal user of a customer. | | `billing_customer_users_update` | write | `write` | `portal-users.update` | `PATCH /v1/customers/:id/users/:user_id` | Update a portal user of a customer (name, role, status). | | `billing_customer_users_delete` | destructive | `delete` | `portal-users.delete` | `DELETE /v1/customers/:id/users/:user_id` | Delete a portal user (a pending invitation included): the user loses portal access immediately and the email can be invited again. | | `billing_customer_users_resend_invite` | destructive | `write` | `portal-users.update` | `POST /v1/customers/:id/users/:user_id/resend` | Re-send the portal invitation e-mail to a customer user. | | `billing_customer_users_email_preview` | read | `read` | `portal-users.show` | `GET /v1/customers/:id/users/:user_id/email-preview` | Render the invitation e-mail for a customer user without sending it — subject and HTML, as the recipient would see it. | | `billing_portal_users_list` | read | `read` | `portal-users.list` | `GET /v1/portal_users` | List every portal user of the organization, across customers. | ## `users`[​](#users "Enlace directo al users") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | -------------------------------- | ----------- | -------- | -------------- | -------------------------------- | ---------------------------------------------------------------------------- | | `billing_dashboard_users_list` | read | `read` | `users.list` | `GET /v1/dashboard_users` | List the dashboard (team) users of the organization. | | `billing_dashboard_users_get` | read | `read` | `users.show` | `GET /v1/dashboard_users/:id` | Fetch one dashboard user with the roles they hold. | | `billing_dashboard_users_create` | destructive | `write` | `users.create` | `POST /v1/dashboard_users` | Add a dashboard user to the organization and assign a role. | | `billing_dashboard_users_upsert` | destructive | `write` | `users.create` | `PUT /v1/dashboard_users` | Create or update a dashboard user matched on `id` → `external_id` → `email`. | | `billing_dashboard_users_update` | write | `write` | `users.update` | `PATCH /v1/dashboard_users/:id` | Update a dashboard user — name, role or status. | | `billing_dashboard_users_delete` | destructive | `delete` | `users.delete` | `DELETE /v1/dashboard_users/:id` | Remove a dashboard user. | ## `roles`[​](#roles "Enlace directo al roles") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | --------------------------- | ----------- | -------- | -------------- | --------------------------- | --------------------------------------------------------------------- | | `billing_team_roles_list` | read | `read` | `roles.list` | `GET /v1/team_roles` | List the roles a dashboard user can hold, with their permission sets. | | `billing_team_roles_get` | read | `read` | `roles.show` | `GET /v1/team_roles/:id` | Fetch one role with its permissions. | | `billing_team_roles_create` | write | `write` | `roles.create` | `POST /v1/team_roles` | Create a custom role with an explicit permission list. | | `billing_team_roles_upsert` | write | `write` | `roles.create` | `PUT /v1/team_roles` | Create or update a role matched on `id` → `external_id` → `slug`. | | `billing_team_roles_update` | write | `write` | `roles.update` | `PATCH /v1/team_roles/:id` | Update a custom role. | | `billing_team_roles_delete` | destructive | `delete` | `roles.delete` | `DELETE /v1/team_roles/:id` | Delete a custom role. | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.billing.kobana.com.br/es/es/api/v1) y en `billing_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.billing.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Fiscal Emisión de NF-e, las empresas emisoras y sus certificados digitales, reglas y períodos de cálculo de impuestos, y las retenciones en la fuente. ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | --------------------------------------- | ----- | ---- | ----- | ----------- | | `nfes` — Notas fiscales (NF-e) | 24 | 8 | 10 | 6 | | `companies` — Empresas emisoras | 12 | 4 | 6 | 2 | | `certificates` — Certificados digitales | 3 | 2 | 0 | 1 | | `tax-rules` — Reglas fiscales | 6 | 2 | 3 | 1 | | `tax-periods` — Períodos de cálculo | 5 | 2 | 2 | 1 | | `withholdings` — Retenciones | 8 | 2 | 3 | 3 | ## `nfes`[​](#nfes "Enlace directo al nfes") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | -------------------------------- | ----------- | -------- | ------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `billing_invoices_issue_nfe` | destructive | `write` | `nfes.create` | `POST /v1/invoices/:id/issue-nfe` | Issue the NFe for an invoice now, outside the automatic issuance policy. | | `billing_nfes_list` | read | `read` | `nfes.list` | `GET /v1/nfes` | List NFes. | | `billing_nfes_get` | read | `read` | `nfes.show` | `GET /v1/nfes/:id` | Fetch one NFe with its status and tax breakdown. | | `billing_nfes_create` | write | `write` | `nfes.create` | `POST /v1/nfes` | Create an NFe record. | | `billing_nfes_upsert` | write | `write` | `nfes.create` | `PUT /v1/nfes` | Create or update an NFe matched on `id` → `external_id`. | | `billing_nfes_update` | write | `write` | `nfes.update` | `PATCH /v1/nfes/:id` | Update an NFe. | | `billing_nfes_delete` | destructive | `delete` | `nfes.update` | `DELETE /v1/nfes/:id` | Soft-delete an NFe record. | | `billing_nfes_issue` | destructive | `write` | `nfes.create` | `POST /v1/nfes/:id/issue` | Transmit an NFe to the municipality. | | `billing_nfes_cancel` | destructive | `write` | `nfes.cancel` | `POST /v1/nfes/:id/cancel` | Cancel an issued NFe at the municipality. | | `billing_nfes_retry_cancel` | destructive | `write` | `nfes.retry` | `POST /v1/nfes/:id/retry-cancel` | Retry a cancellation that failed at the municipality. | | `billing_nfes_sync` | write | `write` | `nfes.update` | `POST /v1/nfes/:id/sync` | Re-read one NFe from the provider and update its local status. | | `billing_nfes_sync_all` | write | `write` | `nfes.update` | `POST /v1/nfes/sync` | Re-read every pending NFe of the organization from the provider. | | `billing_nfes_validate_barueri` | write | `write` | `nfes.show` | `POST /v1/nfes/:id/validate-barueri` | Validate an NFe against the Barueri municipal service before issuing it. | | `billing_nfes_pdf` | read | `read` | `nfes.show` | `GET /v1/nfes/:id/pdf` | Metadata for the NFe PDF (DANFSe). | | `billing_nfes_xml` | read | `read` | `nfes.show` | `GET /v1/nfes/:id/xml` | Metadata for the NFe XML. | | `billing_nfes_requests_list` | read | `read` | `nfes.show` | `GET /v1/nfes/:id/requests` | Request/response log between this service and the NFe provider for one note — the first place to look when an issuance fails. | | `billing_nfes_requests_get` | read | `read` | `nfes.show` | `GET /v1/nfes/:id/requests/:requestId` | Fetch one provider request/response pair in full. | | `billing_nfes_request_tries` | read | `read` | `nfes.show` | `GET /v1/nfes/:id/request-tries` | Issuance attempts for one NFe, with the error that stopped each. | | `billing_nfes_request_tries_all` | read | `read` | `nfes.list` | `GET /v1/nfes/request-tries` | Issuance attempts across every NFe of the organization, newest first. | | `billing_nfes_bulk_link_invoice` | write | `write` | `nfes.update` | `POST /v1/nfes/bulk` | Link up to 100 NFes to an invoice, or unlink them with `invoice_id: null`. | | `billing_nfes_bulk_delete` | destructive | `delete` | `nfes.update` | `DELETE /v1/nfes/bulk` | Soft-delete up to 100 NFe records in one call. | | `billing_nfes_fetch_from_sefaz` | write | `write` | `nfes.create` | `POST /v1/nfes/fetch-from-sefaz` | Fetch an NFe from SEFAZ by its access key, signed with one of the organization certificates. | | `billing_nfes_fetch_barueri` | write | `write` | `nfes.show` | `POST /v1/nfes/fetch-barueri` | Look a Barueri NFSe up by its authenticity code without importing it — use to check before `billing_nfes_import_barueri`. | | `billing_nfes_import_barueri` | write | `import` | `nfes.create` | `POST /v1/nfes/import-barueri` | Import a Barueri NFSe into the organization. | ## `companies`[​](#companies "Enlace directo al companies") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ----------------------------------------- | ----------- | -------- | ------------------ | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `billing_companies_list` | read | `read` | `companies.list` | `GET /v1/companies` | List the legal entities that issue invoices and NFes for this organization. | | `billing_companies_get` | read | `read` | `companies.show` | `GET /v1/companies/:id` | Fetch one legal entity with its addresses and default flag. | | `billing_companies_matriz` | read | `read` | `companies.show` | `GET /v1/companies/matriz` | Fetch the head office (matriz) — the company with no parent. | | `billing_companies_create` | write | `write` | `companies.create` | `POST /v1/companies` | Create a legal entity. | | `billing_companies_upsert` | write | `write` | `companies.create` | `PUT /v1/companies` | Create or update a company matched on `id` → `external_id` → `document_number`. | | `billing_companies_update` | write | `write` | `companies.update` | `PATCH /v1/companies/:id` | Update a company. | | `billing_companies_delete` | destructive | `delete` | `companies.delete` | `DELETE /v1/companies/:id` | Delete a company: it disappears from every read (its invoices and NFes keep naming it). | | `billing_companies_set_default` | write | `write` | `companies.update` | `POST /v1/companies/:id/set-default` | Make this the default issuing entity — used whenever an invoice or NFe names no company. | | `billing_companies_deactivate` | destructive | `write` | `companies.update` | `POST /v1/companies/:id/deactivate` | Deactivate a company: no new invoice or NFe can be issued under it. | | `billing_companies_reactivate` | write | `write` | `companies.update` | `POST /v1/companies/:id/reactivate` | Reactivate a company so invoices and NFes can be issued under it again. | | `billing_companies_fiscal_profile_get` | read | `read` | `companies.show` | `GET /v1/companies/:id/fiscal` | Read the fiscal profile of a company: taxation regime, Simples annex, RBT12, factor R and every tax rate used to price an invoice. | | `billing_companies_fiscal_profile_update` | write | `write` | `companies.update` | `PATCH /v1/companies/:id/fiscal` | Upsert the fiscal profile of a company. | ## `certificates`[​](#certificates "Enlace directo al certificates") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ----------------------------- | ----------- | -------- | --------------------- | ----------------------------- | ------------------------------------------------------------------ | | `billing_certificates_list` | read | `read` | `certificates.list` | `GET /v1/certificates` | List the digital certificates used to sign NFes. | | `billing_certificates_get` | read | `read` | `certificates.show` | `GET /v1/certificates/:id` | Fetch one certificate: subject, serial number and validity window. | | `billing_certificates_delete` | destructive | `delete` | `certificates.delete` | `DELETE /v1/certificates/:id` | Remove a certificate. | ## `tax-rules`[​](#tax-rules "Enlace directo al tax-rules") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | -------------------------- | ----------- | -------- | ------------------ | -------------------------- | ------------------------------------------------------------ | | `billing_tax_rules_list` | read | `read` | `tax-rules.list` | `GET /v1/tax_rules` | List tax rules, most specific scope first. | | `billing_tax_rules_get` | read | `read` | `tax-rules.show` | `GET /v1/tax_rules/:id` | Fetch one tax rule with its items. | | `billing_tax_rules_create` | write | `write` | `tax-rules.create` | `POST /v1/tax_rules` | Create a tax rule with its items. | | `billing_tax_rules_upsert` | write | `write` | `tax-rules.create` | `PUT /v1/tax_rules` | Create or update a tax rule matched on `id` → `external_id`. | | `billing_tax_rules_update` | write | `write` | `tax-rules.update` | `PATCH /v1/tax_rules/:id` | Update a tax rule. | | `billing_tax_rules_delete` | destructive | `delete` | `tax-rules.delete` | `DELETE /v1/tax_rules/:id` | Delete a tax rule. | ## `tax-periods`[​](#tax-periods "Enlace directo al tax-periods") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ----------------------------------- | ----------- | -------- | -------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------- | | `billing_tax_periods_list` | read | `read` | `tax-periods.list` | `GET /v1/tax_periods` | List fiscal periods (apurações) with their gross revenue and estimated DAS. | | `billing_tax_periods_get` | read | `read` | `tax-periods.show` | `GET /v1/tax_periods/:id` | Fetch one fiscal period with its computed taxes. | | `billing_tax_periods_process_month` | write | `write` | `tax-periods.create` | `POST /v1/tax_periods` | Compute (or recompute) the monthly fiscal period of a company. | | `billing_tax_periods_action` | write | `write` | `tax-periods.update` | `PATCH /v1/tax_periods/:id` | Act on a fiscal period: `recalculate` (monthly only), `close` to freeze it, or `reopen` to unfreeze. | | `billing_tax_periods_delete` | destructive | `delete` | `tax-periods.update` | `DELETE /v1/tax_periods/:id` | Delete a fiscal period. | ## `withholdings`[​](#withholdings "Enlace directo al withholdings") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ----------------------------------------- | ----------- | -------- | --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `billing_withholdings_list` | read | `read` | `withholdings.list` | `GET /v1/withholdings` | List tax withholdings (retenções). | | `billing_withholdings_get` | read | `read` | `withholdings.show` | `GET /v1/withholdings/:id` | Fetch one tax withholding with how much of it has been compensated. | | `billing_withholdings_create` | write | `write` | `withholdings.create` | `POST /v1/withholdings` | Record a tax withheld at source by a customer, against an invoice or an NFe. | | `billing_withholdings_upsert` | write | `write` | `withholdings.create` | `PUT /v1/withholdings` | Create or update a withholding matched on `id` → `external_id`. | | `billing_withholdings_update` | write | `write` | `withholdings.update` | `PATCH /v1/withholdings/:id` | Update a withholding — its base, amount or competence period. | | `billing_withholdings_delete` | destructive | `delete` | `withholdings.delete` | `DELETE /v1/withholdings/:id` | Soft-delete a withholding. | | `billing_withholdings_convert_to_credit` | destructive | `write` | `withholdings.update` | `POST /v1/withholdings/:id/convert-to-credit` | Turn one retained withholding into a credit on the customer billing account, so it offsets the next invoice. | | `billing_withholdings_convert_to_credits` | destructive | `write` | `withholdings.update` | `POST /v1/withholdings/convert-to-credits` | Convert several retained withholdings into credits in one call. | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.billing.kobana.com.br/es/es/api/v1) y en `billing_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.billing.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Facturas y cobros Facturas y sus ítems, pagos y métodos de pago, las cuentas bancarias y claves Pix que reciben cobros por transferencia, créditos aplicados en la cuenta y cupones de descuento. ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | -------------------------------------------------------- | ----- | ---- | ----- | ----------- | | `invoices` — Facturas | 23 | 8 | 5 | 10 | | `payments` — Pagos y métodos de pago | 19 | 4 | 6 | 9 | | `transfer-destinations` — Cuentas bancarias y claves Pix | 11 | 5 | 0 | 6 | | `credits` — Créditos | 7 | 3 | 1 | 3 | | `coupons` — Cupones y códigos de descuento | 8 | 3 | 4 | 1 | ## `invoices`[​](#invoices "Enlace directo al invoices") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ----------------------------------------- | ----------- | -------- | ----------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `billing_billing_accounts_invoices` | read | `read` | `invoices.list` | `GET /v1/billing_accounts/:id/invoices` | List the invoices of one billing account. | | `billing_subscriptions_create_invoice` | write | `write` | `invoices.create` | `POST /v1/subscriptions/:id/create-invoice` | Raise an invoice for the current period of a subscription now, instead of waiting for the billing worker. | | `billing_invoices_list` | read | `read` | `invoices.list` | `GET /v1/invoices` | List invoices. | | `billing_invoices_get` | read | `read` | `invoices.show` | `GET /v1/invoices/:id` | Fetch one invoice with its line items and totals. | | `billing_invoices_create` | write | `write` | `invoices.create` | `POST /v1/invoices` | Create a draft invoice with its line items. | | `billing_invoices_upsert` | write | `write` | `invoices.create` | `PUT /v1/invoices` | Create or update an invoice matched on `id` → `external_id`. | | `billing_invoices_update` | write | `write` | `invoices.update` | `PATCH /v1/invoices/:id` | Update an invoice. | | `billing_invoices_delete` | destructive | `delete` | `invoices.update` | `DELETE /v1/invoices/:id` | Soft-delete a `draft`, `open` or `void` invoice (credits applied to an open one go back to the customer). | | `billing_invoices_finalize` | destructive | `write` | `invoices.update` | `POST /v1/invoices/:id/finalize` | Finalize a draft invoice: it becomes `open`, gets its number, and — with `charge_automatically` — is charged immediately. | | `billing_invoices_pay` | destructive | `write` | `payments.create` | `POST /v1/invoices/:id/pay` | Settle an invoice. | | `billing_invoices_undo_payment` | destructive | `write` | `invoices.update` | `POST /v1/invoices/:id/undo-payment` | Reverse a manual settlement, sending the invoice back to `open`. | | `billing_invoices_void` | destructive | `write` | `invoices.void` | `POST /v1/invoices/:id/void` | Void an open invoice. | | `billing_invoices_apply_credits` | destructive | `write` | `invoices.update` | `POST /v1/invoices/:id/apply-credits` | Apply credits of the billing account to an open invoice, reducing the amount due. | | `billing_invoices_remove_credits` | destructive | `write` | `invoices.update` | `POST /v1/invoices/:id/remove-credits` | Undo every credit application on an open invoice, returning the credits to the billing account balance. | | `billing_invoices_installments_list` | read | `read` | `invoices.show` | `GET /v1/invoices/:id/installments` | List the installment schedule of an invoice. | | `billing_invoices_installments_create` | write | `write` | `invoices.update` | `POST /v1/invoices/:id/installments` | Split an invoice into installments. | | `billing_invoices_installments_pay` | destructive | `write` | `payments.create` | `POST /v1/invoices/:id/installments/:installmentId/pay` | Charge one installment: through the gateway (`pix`, `bank_slip`, `card`), or as a `bank_transfer` to an organization bank account or Pix key. | | `billing_invoices_installments_mark_paid` | destructive | `write` | `payments.create` | `POST /v1/invoices/:id/installments/:installmentId/mark-paid` | Mark one installment paid out of band, without touching a gateway. | | `billing_invoices_payment_methods` | read | `read` | `invoices.show` | `GET /v1/invoices/:id/payment-methods` | Payment methods usable to settle this invoice, in the order the portal offers them. | | `billing_invoices_send_reminder` | destructive | `write` | `invoices.send` | `POST /v1/invoices/:id/send-reminder` | E-mail the customer a payment reminder for an open invoice. | | `billing_invoices_pdf` | read | `read` | `invoices.show` | `GET /v1/invoices/:id/pdf` | Metadata for the invoice PDF. | | `billing_invoices_pending_nfe` | read | `read` | `invoices.list` | `GET /v1/invoices/pending-nfe` | Invoices that are due an NFe and have not had one issued yet. | | `billing_invoices_pending_payment` | read | `read` | `invoices.list` | `GET /v1/invoices/pending-payment` | Open invoices still awaiting payment. | ## `payments`[​](#payments "Enlace directo al payments") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | -------------------------------------- | ----------- | -------- | ----------------- | ------------------------------------------ | ------------------------------------------------------------------- | | `billing_payments_list` | read | `read` | `payments.list` | `GET /v1/payments` | List payments — every charge attempt, successful or not. | | `billing_payments_get` | read | `read` | `payments.show` | `GET /v1/payments/:id` | Fetch one payment with its gateway status. | | `billing_payments_create` | destructive | `write` | `payments.create` | `POST /v1/payments` | Charge an invoice through a gateway. | | `billing_payments_delete` | destructive | `delete` | `payments.update` | `DELETE /v1/payments/:id` | Soft-delete a payment record. | | `billing_payments_retry` | destructive | `write` | `payments.retry` | `POST /v1/payments/:id/retry` | Retry a failed payment with the same method. | | `billing_payments_refund` | destructive | `write` | `payments.refund` | `POST /v1/payments/:id/refund` | Refund a succeeded payment at the gateway. | | `billing_payments_cancel` | destructive | `write` | `payments.update` | `POST /v1/payments/:id/cancel` | Cancel a pending payment. | | `billing_payments_change_due_date` | destructive | `write` | `payments.update` | `POST /v1/payments/:id/change-due-date` | Move the due date of an open boleto/PIX charge. | | `billing_payments_change_card` | write | `write` | `payments.update` | `POST /v1/payments/:id/change-card` | Point a card payment at a different stored card before retrying it. | | `billing_payments_send_email` | destructive | `write` | `payments.update` | `POST /v1/payments/:id/send-email` | E-mail the charge (boleto/PIX link) to an address. | | `billing_payments_sync` | write | `write` | `payments.update` | `POST /v1/payments/:id/sync` | Re-read a payment from the gateway and update the local status. | | `billing_payments_bulk_update_invoice` | destructive | `write` | `payments.update` | `POST /v1/payments/bulk-update-invoice` | Re-link up to 100 payments to another invoice. | | `billing_payment_methods_list` | read | `read` | `payments.list` | `GET /v1/payment_methods` | List stored payment methods. | | `billing_payment_methods_get` | read | `read` | `payments.show` | `GET /v1/payment_methods/:id` | Fetch one payment method. | | `billing_payment_methods_create` | write | `write` | `payments.create` | `POST /v1/payment_methods` | Attach a payment method to a billing account. | | `billing_payment_methods_upsert` | write | `write` | `payments.create` | `PUT /v1/payment_methods` | Create or update a payment method matched on `id` → `external_id`. | | `billing_payment_methods_update` | write | `write` | `payments.update` | `PATCH /v1/payment_methods/:id` | Update a payment method — the default flag and its metadata. | | `billing_payment_methods_delete` | destructive | `delete` | `payments.update` | `DELETE /v1/payment_methods/:id` | Detach a payment method. | | `billing_payment_methods_set_default` | write | `write` | `payments.update` | `POST /v1/payment_methods/:id/set-default` | Make this the default payment method of its billing account. | ## `transfer-destinations`[​](#transfer-destinations "Enlace directo al transfer-destinations") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ------------------------------ | ----------- | ------------------------ | ----------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- | | `billing_banks_list` | read | `read` · `billing/all` | `settings.view` | `GET /v1/banks` | List the Brazilian banks (COMPE code and name) a bank account can be registered under. | | `billing_bank_accounts_list` | read | `read` · `billing/all` | `settings.view` | `GET /v1/bank_accounts` | List the organization bank accounts customers can be told to transfer to on a `bank_transfer` charge. | | `billing_bank_accounts_get` | read | `read` · `billing/all` | `settings.view` | `GET /v1/bank_accounts/:id` | Fetch one organization bank account, with its bank. | | `billing_bank_accounts_create` | destructive | `write` · `billing/all` | `settings.update` | `POST /v1/bank_accounts` | Register an organization bank account to receive `bank_transfer` charges. | | `billing_bank_accounts_update` | destructive | `write` · `billing/all` | `settings.update` | `PATCH /v1/bank_accounts/:id` | Update an organization bank account. | | `billing_bank_accounts_delete` | destructive | `delete` · `billing/all` | `settings.update` | `DELETE /v1/bank_accounts/:id` | Soft-delete an organization bank account. | | `billing_pix_keys_list` | read | `read` · `billing/all` | `settings.view` | `GET /v1/pix_keys` | List the organization Pix keys customers can be told to transfer to on a `bank_transfer` charge. | | `billing_pix_keys_get` | read | `read` · `billing/all` | `settings.view` | `GET /v1/pix_keys/:id` | Fetch one organization Pix key. | | `billing_pix_keys_create` | destructive | `write` · `billing/all` | `settings.update` | `POST /v1/pix_keys` | Register an organization Pix key to receive `bank_transfer` charges. | | `billing_pix_keys_update` | destructive | `write` · `billing/all` | `settings.update` | `PATCH /v1/pix_keys/:id` | Update an organization Pix key. | | `billing_pix_keys_delete` | destructive | `delete` · `billing/all` | `settings.update` | `DELETE /v1/pix_keys/:id` | Soft-delete an organization Pix key. | ## `credits`[​](#credits "Enlace directo al credits") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ---------------------------------- | ----------- | -------- | ---------------- | -------------------------------------- | ---------------------------------------------------------- | | `billing_billing_accounts_credits` | read | `read` | `credits.list` | `GET /v1/billing_accounts/:id/credits` | List the credits of one billing account. | | `billing_credits_list` | read | `read` | `credits.list` | `GET /v1/credits` | List credits. | | `billing_credits_get` | read | `read` | `credits.show` | `GET /v1/credits/:id` | Fetch one credit with what is left of it. | | `billing_credits_create` | destructive | `write` | `credits.create` | `POST /v1/credits` | Grant a credit to a billing account. | | `billing_credits_upsert` | destructive | `write` | `credits.create` | `PUT /v1/credits` | Create or update a credit matched on `id` → `external_id`. | | `billing_credits_update` | write | `write` | `credits.create` | `PATCH /v1/credits/:id` | Update a credit. | | `billing_credits_delete` | destructive | `delete` | `credits.delete` | `DELETE /v1/credits/:id` | Soft-delete a credit. | ## `coupons`[​](#coupons "Enlace directo al coupons") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ----------------------------- | ----------- | -------- | ---------------- | --------------------------------- | ----------------------------------------------------------------------- | | `billing_coupons_list` | read | `read` | `coupons.list` | `GET /v1/coupons` | List discount coupons with their validity window and usage counters. | | `billing_coupons_get` | read | `read` | `coupons.show` | `GET /v1/coupons/:id` | Fetch one coupon with its usage counters. | | `billing_coupons_create` | write | `write` | `coupons.create` | `POST /v1/coupons` | Create a discount coupon. | | `billing_coupons_upsert` | write | `write` | `coupons.create` | `PUT /v1/coupons` | Create or update a coupon matched on `id` → `external_id` → `code`. | | `billing_coupons_update` | write | `write` | `coupons.update` | `PATCH /v1/coupons/:id` | Update a coupon. | | `billing_coupons_delete` | destructive | `delete` | `coupons.delete` | `DELETE /v1/coupons/:id` | Soft-delete a coupon. | | `billing_coupons_deactivate` | write | `write` | `coupons.update` | `POST /v1/coupons/:id/deactivate` | Stop a coupon being redeemable, keeping its history intact. | | `billing_coupons_redemptions` | read | `read` | `coupons.show` | `GET /v1/coupons/:id/redemptions` | List the redemptions of a coupon — who used it, when, and for how much. | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.billing.kobana.com.br/es/es/api/v1) y en `billing_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.billing.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Organización y esquemas El perfil de la propia organización, `billing_schemas_get` — el catálogo de campos que dice qué pedir en `fields` y en `sort_by` — y tus aprobaciones por enlace: `billing_operation_approvals_get` dice qué pasó con una operación destructiva después de que decidiste en la pantalla de aprobación. ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | ----------------------------------------------- | ----- | ---- | ----- | ----------- | | `settings` — Organización y esquemas | 4 | 3 | 1 | 0 | | `operation-approvals` — Aprobaciones por enlace | 2 | 2 | 0 | 0 | ## `settings`[​](#settings "Enlace directo al settings") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ----------------------------- | ----- | ----------- | ----------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `billing_me` | read | — (ninguno) | — (solo vínculo activo) | `GET /v1/me` | Return the identity behind this connection's token: the person, the organization and the token's own scopes, access level and expiry. | | `billing_organization_get` | read | `read` | `settings.view` | `GET /v1/organization` | Fetch the organization the access token acts for — name, contact details and settings. | | `billing_organization_update` | write | `write` | `settings.update` | `PATCH /v1/organization` | Update the organization profile. | | `billing_schemas_get` | read | `read` | `settings.view` | — (local) | Describe the fields of a resource: every field name, its type, whether it is nullable, its enum values and what it means. | ## `operation-approvals`[​](#operation-approvals "Enlace directo al operation-approvals") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ---------------------------------- | ---- | ----------- | ----------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `billing_operation_approvals_get` | read | — (ninguno) | — (solo vínculo activo) | `GET /v1/operation_approvals/:id` | Read one of your operation approvals: what came of a destructive tool call that answered `approval_required`. | | `billing_operation_approvals_list` | read | — (ninguno) | — (solo vínculo activo) | `GET /v1/operation_approvals` | List your operation approvals in this organization, most recent first — the destructive tool calls that waited for an approval link, with what came of each (`status`, `title`, `amount`, `error`, masked `result` — the last three only where this token can read the approval’s `resource`, else `result_hidden`). | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.billing.kobana.com.br/es/es/api/v1) y en `billing_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.billing.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Tools El servidor expone **296 tools** sobre **26 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 upsert y aislamiento por organización son exactamente los de la API REST — la tool *es* el endpoint. La única excepción, `billing_schemas_get`, responde localmente y está marcada como tal. ## 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 cinco datos, en este orden: > `billing_invoices_void` · **destructive** · scope `write` · recurso `invoices` · permiso `invoices.void` · `POST /v1/invoices/:id/void` | Campo | Significado | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **read** / **write** / **destructive** | La anotación que lee el cliente MCP. Una `destructive` (elimina, anula, cancela, cobra, paga, reembolsa, aplica crédito, emite o cancela una nota fiscal, envía un e-mail, invitación o link público) solo se ejecuta después de que el usuario confirma: en el formulario que envía el servidor, en la revisión 2026-07-28 con elicitation, o mediante un enlace de aprobación que abre con sesión iniciada en el panel, en los demás clientes ([Confirmación de tools destructivas](https://docs.billing.kobana.com.br/es/es/mcp/overview/resources-and-prompts.md#confirmaci%C3%B3n-de-tools-destructivas)). | | **scope** | El verbo de scope que el token debe llevar para la tool: `read`, `write`, `delete` (las tools `*_delete`) o `import` (`billing_nfes_import_barueri`). Ninguno sustituye a otro — ve [Autenticación](https://docs.billing.kobana.com.br/es/es/mcp/overview/authentication.md). Marcada `billing/all`, la tool llama a un endpoint fuera del catálogo de recursos (cuentas bancarias, bancos, claves Pix) y solo un token con `billing/all` la alcanza. Como el AS no concede `billing/all` a un cliente OAuth y rechaza un verbo junto a `billing/all` en el token personal, estas tools son, por MCP, solo lectura y solo por token personal: las que escriben o eliminan no se ejecutan hoy. | | **recurso** | La familia de recurso de la tool — lo que agrupa las tools en esta documentación. | | **permiso** | El permiso de panel que la persona que autorizó el cliente debe tener en la organización. `billing_me` y las tools `billing_operation_approvals_*` (que leen las aprobaciones de la propia persona) no exigen ninguno — solo un vínculo activo. | | **`MÉTODO /ruta`** | El endpoint de `/v1` al que despacha la tool, para cruzar con la [Referencia de la API](https://docs.billing.kobana.com.br/es/es/api/v1). | ## Argumentos comunes[​](#argumentos-comunes "Enlace directo al Argumentos comunes") Aparecen en muchas tools y siempre significan lo mismo. | Argumento | Tipo | Descripción | | ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | entero | Página, desde 1. Predeterminado `1`. | | `per_page` | entero | Ítems por página. Predeterminado `20`, máximo `100`. | | `sort_by` | string | Columna de orden, en snake\_case. Los aceptados están en `billing_schemas_get`. | | `sort_order` | `asc` \| `desc` | Dirección. Un valor que no es dirección es un error, no un `desc` silencioso. | | `fields` | string\[] | Columnas a devolver. Omitido, vuelve el recurso entero; `id` siempre vuelve. | | `filters` | object | Filtros adicionales, reenviados al endpoint. No acepta paginación, ordenación (`page`, `per_page`, `sort_by`, `sort_order`, `limit`, `cursor`, `sort`) ni un filtro que la tool ya nombra — esos van como argumento nombrado; dentro de `filters` se rechazan con `VALIDATION_ERROR`. | | `idempotency_key` | string | Protección contra reintentos, enviada como `X-Idempotency-Key`. | | `custom_metadata` | object | JSON libre tuyo, devuelto en cada lectura y en cada webhook. | ## El catálogo[​](#el-catálogo "Enlace directo al El catálogo") | Familia | Tools | read | write | destructive | | -------------------------------------------------------------------------------------------------------------------------- | ----- | ---- | ----- | ----------- | | [`certificates` — Certificados digitales](https://docs.billing.kobana.com.br/es/es/mcp/tools/fiscal.md) | 3 | 2 | 0 | 1 | | [`companies` — Empresas emisoras](https://docs.billing.kobana.com.br/es/es/mcp/tools/fiscal.md) | 12 | 4 | 6 | 2 | | [`coupons` — Cupones y códigos de descuento](https://docs.billing.kobana.com.br/es/es/mcp/tools/invoices.md) | 8 | 3 | 4 | 1 | | [`credits` — Créditos](https://docs.billing.kobana.com.br/es/es/mcp/tools/invoices.md) | 7 | 3 | 1 | 3 | | [`customers` — Clientes y cuentas de cobro](https://docs.billing.kobana.com.br/es/es/mcp/tools/customers.md) | 19 | 6 | 9 | 4 | | [`invoices` — Facturas](https://docs.billing.kobana.com.br/es/es/mcp/tools/invoices.md) | 23 | 8 | 5 | 10 | | [`nfes` — Notas fiscales (NF-e)](https://docs.billing.kobana.com.br/es/es/mcp/tools/fiscal.md) | 24 | 8 | 10 | 6 | | [`operation-approvals` — Aprobaciones por enlace](https://docs.billing.kobana.com.br/es/es/mcp/tools/organization.md) | 2 | 2 | 0 | 0 | | [`payments` — Pagos y métodos de pago](https://docs.billing.kobana.com.br/es/es/mcp/tools/invoices.md) | 19 | 4 | 6 | 9 | | [`plan-changes` — Cambios de plan](https://docs.billing.kobana.com.br/es/es/mcp/tools/subscriptions.md) | 11 | 6 | 3 | 2 | | [`plans` — Planes, precios y grupos](https://docs.billing.kobana.com.br/es/es/mcp/tools/catalog.md) | 21 | 5 | 12 | 4 | | [`portal-users` — Usuarios del portal](https://docs.billing.kobana.com.br/es/es/mcp/tools/customers.md) | 9 | 4 | 2 | 3 | | [`products` — Productos y grupos de productos](https://docs.billing.kobana.com.br/es/es/mcp/tools/catalog.md) | 24 | 4 | 16 | 4 | | [`proposals` — Propuestas](https://docs.billing.kobana.com.br/es/es/mcp/tools/proposals.md) | 25 | 7 | 7 | 11 | | [`roles` — Roles del equipo](https://docs.billing.kobana.com.br/es/es/mcp/tools/customers.md) | 6 | 2 | 3 | 1 | | [`services` — Ítems de servicio](https://docs.billing.kobana.com.br/es/es/mcp/tools/catalog.md) | 6 | 2 | 3 | 1 | | [`settings` — Organización y esquemas](https://docs.billing.kobana.com.br/es/es/mcp/tools/organization.md) | 4 | 3 | 1 | 0 | | [`subscription-changes` — Cambios de suscripción](https://docs.billing.kobana.com.br/es/es/mcp/tools/subscriptions.md) | 5 | 3 | 1 | 1 | | [`subscriptions` — Suscripciones](https://docs.billing.kobana.com.br/es/es/mcp/tools/subscriptions.md) | 16 | 4 | 6 | 6 | | [`tax-periods` — Períodos de cálculo](https://docs.billing.kobana.com.br/es/es/mcp/tools/fiscal.md) | 5 | 2 | 2 | 1 | | [`tax-rules` — Reglas fiscales](https://docs.billing.kobana.com.br/es/es/mcp/tools/fiscal.md) | 6 | 2 | 3 | 1 | | [`templates` — Plantillas de propuesta](https://docs.billing.kobana.com.br/es/es/mcp/tools/proposals.md) | 9 | 2 | 6 | 1 | | [`transfer-destinations` — Cuentas bancarias y claves Pix](https://docs.billing.kobana.com.br/es/es/mcp/tools/invoices.md) | 11 | 5 | 0 | 6 | | [`usage` — Consumo medido](https://docs.billing.kobana.com.br/es/es/mcp/tools/usage.md) | 7 | 4 | 3 | 0 | | [`users` — Usuarios del panel](https://docs.billing.kobana.com.br/es/es/mcp/tools/customers.md) | 6 | 2 | 1 | 3 | | [`withholdings` — Retenciones](https://docs.billing.kobana.com.br/es/es/mcp/tools/fiscal.md) | 8 | 2 | 3 | 3 | Una tool que no puedes ejecutar no aparece en `tools/list`. Si falta alguna de esta página, ve [Autenticación](https://docs.billing.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Propuestas Propuestas comerciales — del borrador a la aceptación, donde una firma se convierte en suscripción — y las plantillas con que se generan. ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | ------------------------------------- | ----- | ---- | ----- | ----------- | | `proposals` — Propuestas | 25 | 7 | 7 | 11 | | `templates` — Plantillas de propuesta | 9 | 2 | 6 | 1 | ## `proposals`[​](#proposals "Enlace directo al proposals") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | -------------------------------- | ----------- | -------- | ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `billing_proposals_list` | read | `read` | `proposals.list` | `GET /v1/proposals` | List commercial proposals. | | `billing_proposals_get` | read | `read` | `proposals.show` | `GET /v1/proposals/:id` | Fetch one proposal with its items and totals. | | `billing_proposals_create` | write | `write` | `proposals.create` | `POST /v1/proposals` | Create a draft proposal. | | `billing_proposals_upsert` | write | `write` | `proposals.create` | `PUT /v1/proposals` | Create or update a proposal matched on `id` → `external_id` → `code`. | | `billing_proposals_update` | write | `write` | `proposals.update` | `PATCH /v1/proposals/:id` | Update a proposal. | | `billing_proposals_delete` | destructive | `delete` | `proposals.delete` | `DELETE /v1/proposals/:id` | Soft-delete a proposal. | | `billing_proposals_publish` | destructive | `write` | `proposals.update` | `POST /v1/proposals/:id/publish` | Publish a proposal, making its public link reachable by the prospect. | | `billing_proposals_unpublish` | destructive | `write` | `proposals.update` | `POST /v1/proposals/:id/unpublish` | Take a proposal offline; the public link stops resolving. | | `billing_proposals_send` | destructive | `write` | `proposals.send` | `POST /v1/proposals/:id/send` | E-mail a proposal to its contact and move it to `sent`. | | `billing_proposals_accept` | destructive | `write` | `proposals.approve` | `POST /v1/proposals/:id/accept` | Accept a proposal on behalf of the customer. | | `billing_proposals_undo_accept` | destructive | `write` | `proposals.approve` | `POST /v1/proposals/:id/undo-accept` | Undo an acceptance, sending the proposal back to `sent`. | | `billing_proposals_cancel` | destructive | `write` | `proposals.update` | `POST /v1/proposals/:id/cancel` | Cancel a proposal. | | `billing_proposals_duplicate` | write | `write` | `proposals.create` | `POST /v1/proposals/:id/duplicate` | Copy a proposal and its items into a new draft. | | `billing_proposals_generate_pdf` | write | `write` | `proposals.update` | `POST /v1/proposals/:id/generate-pdf` | Render the proposal PDF from its template and store it. | | `billing_proposals_pricing` | read | `read` | `proposals.show` | `GET /v1/proposals/:id/pricing` | Price breakdown of a proposal on every billing cycle: setup, monthly, cycle discount and total — what the prospect sees before picking one. | | `billing_proposals_json` | read | `read` | `proposals.show` | `GET /v1/proposals/:id/json` | The full proposal payload as the template renderer receives it — the merge data behind the PDF. | | `billing_proposals_stats` | read | `read` | `proposals.list` | `GET /v1/proposals/stats` | Aggregate proposal counts and values by status, for the whole organization. | | `billing_proposals_items_list` | read | `read` | `proposals.show` | `GET /v1/proposals/:id/items` | List the items of a proposal. | | `billing_proposals_items_create` | write | `write` | `proposals.update` | `POST /v1/proposals/:id/items` | Add an item to a draft proposal. | | `billing_proposals_items_get` | read | `read` | `proposals.show` | `GET /v1/proposals/:id/items/:itemId` | Fetch one proposal item with its negotiated pricing. | | `billing_proposals_items_update` | write | `write` | `proposals.update` | `PATCH /v1/proposals/:id/items/:itemId` | Update one item of a draft proposal. | | `billing_proposals_items_delete` | destructive | `delete` | `proposals.update` | `DELETE /v1/proposals/:id/items/:itemId` | Remove an item from a draft proposal. | | `billing_proposals_bulk_send` | destructive | `write` | `proposals.send` | `POST /v1/proposals/bulk-send` | Send up to 100 proposals in one call. | | `billing_proposals_bulk_cancel` | destructive | `write` | `proposals.update` | `POST /v1/proposals/bulk-cancel` | Cancel up to 100 proposals in one call. | | `billing_proposals_bulk_delete` | destructive | `delete` | `proposals.delete` | `DELETE /v1/proposals/bulk` | Soft-delete up to 100 proposals in one call. | ## `templates`[​](#templates "Enlace directo al templates") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | --------------------------------------- | ----------- | -------- | ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------ | | `billing_proposal_templates_list` | read | `read` | `templates.list` | `GET /v1/proposal_templates` | List the templates proposals are rendered from. | | `billing_proposal_templates_get` | read | `read` | `templates.show` | `GET /v1/proposal_templates/:id` | Fetch one proposal template. | | `billing_proposal_templates_create` | write | `write` | `templates.create` | `POST /v1/proposal_templates` | Create a proposal template. | | `billing_proposal_templates_upsert` | write | `write` | `templates.create` | `PUT /v1/proposal_templates` | Create or update a proposal template matched on `id` → `external_id` → `name`. | | `billing_proposal_templates_update` | write | `write` | `templates.update` | `PATCH /v1/proposal_templates/:id` | Update a proposal template. | | `billing_proposal_templates_delete` | destructive | `delete` | `templates.delete` | `DELETE /v1/proposal_templates/:id` | Soft-delete a proposal template. | | `billing_proposal_templates_activate` | write | `write` | `templates.update` | `POST /v1/proposal_templates/:id/activate` | Make a template selectable on new proposals. | | `billing_proposal_templates_deactivate` | write | `write` | `templates.update` | `POST /v1/proposal_templates/:id/deactivate` | Hide a template from new proposals. | | `billing_proposal_templates_duplicate` | write | `write` | `templates.create` | `POST /v1/proposal_templates/:id/duplicate` | Copy a proposal template into a new one, ready to be edited. | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.billing.kobana.com.br/es/es/api/v1) y en `billing_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.billing.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Suscripciones El ciclo de vida de la suscripción — prueba, activación, pausa, cancelación — y los cambios de plan, con el prorrateo que genera cada uno. ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | ----------------------------------------------- | ----- | ---- | ----- | ----------- | | `subscriptions` — Suscripciones | 16 | 4 | 6 | 6 | | `plan-changes` — Cambios de plan | 11 | 6 | 3 | 2 | | `subscription-changes` — Cambios de suscripción | 5 | 3 | 1 | 1 | ## `subscriptions`[​](#subscriptions "Enlace directo al subscriptions") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ------------------------------------------- | ----------- | -------- | ---------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `billing_billing_accounts_subscriptions` | read | `read` | `subscriptions.list` | `GET /v1/billing_accounts/:id/subscriptions` | List the subscriptions of one billing account. | | `billing_subscriptions_list` | read | `read` | `subscriptions.list` | `GET /v1/subscriptions` | List subscriptions. | | `billing_subscriptions_get` | read | `read` | `subscriptions.show` | `GET /v1/subscriptions/:id` | Fetch one subscription with its items and current period. | | `billing_subscriptions_create` | write | `write` | `subscriptions.create` | `POST /v1/subscriptions` | Create a subscription. | | `billing_subscriptions_upsert` | write | `write` | `subscriptions.create` | `PUT /v1/subscriptions` | Create or update a subscription matched on `id` → `external_id`. | | `billing_subscriptions_update` | write | `write` | `subscriptions.update` | `PATCH /v1/subscriptions/:id` | Update a subscription in place. | | `billing_subscriptions_delete` | destructive | `delete` | `subscriptions.delete` | `DELETE /v1/subscriptions/:id` | Soft-delete a subscription. | | `billing_subscriptions_activate` | write | `write` | `subscriptions.update` | `POST /v1/subscriptions/:id/activate` | Activate a draft/confirmed subscription and open its first billing period. | | `billing_subscriptions_cancel` | destructive | `write` | `subscriptions.cancel` | `POST /v1/subscriptions/:id/cancel` | Cancel a subscription. | | `billing_subscriptions_pause` | destructive | `write` | `subscriptions.pause` | `POST /v1/subscriptions/:id/pause` | Pause a subscription. | | `billing_subscriptions_resume` | write | `write` | `subscriptions.resume` | `POST /v1/subscriptions/:id/resume` | Resume a paused subscription and reopen billing. | | `billing_subscriptions_revert_to_confirmed` | destructive | `write` | `subscriptions.update` | `POST /v1/subscriptions/:id/revert-to-confirmed` | Send an active subscription back to `confirmed`, undoing an activation. | | `billing_subscriptions_change_plan` | destructive | `write` | `subscriptions.update` | `POST /v1/subscriptions/:id/change-plan` | Move a subscription to another plan, computing proration: an upgrade charges the prorated difference now, a downgrade credits the next invoice. | | `billing_subscriptions_items_list` | read | `read` | `subscriptions.show` | `GET /v1/subscriptions/:id/items` | List the items of a subscription. | | `billing_subscriptions_items_change` | destructive | `write` | `subscriptions.update` | `POST /v1/subscriptions/:id/items` | Apply up to 50 item operations to a subscription in one transaction, with proration. | | `billing_subscriptions_sync_plan_items` | write | `write` | `subscriptions.update` | `POST /v1/subscriptions/:id/sync-plan-items` | Re-align a subscription with its plan: adds items the plan gained and removes items it dropped. | ## `plan-changes`[​](#plan-changes "Enlace directo al plan-changes") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ------------------------------------ | ----------- | -------- | ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `billing_plan_changes_list` | read | `read` | `plan-changes.list` | `GET /v1/plan_changes` | List plan changes — the audit trail of every plan swap, with its proration. | | `billing_plan_changes_get` | read | `read` | `plan-changes.show` | `GET /v1/plan_changes/:id` | Fetch one plan change with the proration it produced. | | `billing_plan_changes_execute` | destructive | `write` | `subscriptions.update` | `POST /v1/plan_changes` | Execute a plan change against the organization rules. | | `billing_plan_changes_stats` | read | `read` | `plan-changes.list` | `GET /v1/plan_changes/stats` | Aggregate plan-change counts and amounts over the last `days` (default 30). | | `billing_plan_changes_config_get` | read | `read` | `plan-changes.config` | `GET /v1/plan_changes/config` | Read the organization plan-change policy: whether upgrades/downgrades are allowed, and how each is prorated and timed. | | `billing_plan_changes_config_update` | write | `write` | `plan-changes.config` | `PATCH /v1/plan_changes/config` | Update the organization plan-change policy. | | `billing_plan_changes_rules_list` | read | `read` | `plan-changes.config` | `GET /v1/plan_changes/rules` | List the per-plan-pair rules that override the global policy — which moves are allowed, and with which discount or bonus. | | `billing_plan_changes_rules_get` | read | `read` | `plan-changes.config` | `GET /v1/plan_changes/rules/:id` | Fetch one plan-change rule. | | `billing_plan_changes_rules_create` | write | `write` | `plan-changes.config` | `POST /v1/plan_changes/rules` | Create a plan-change rule. | | `billing_plan_changes_rules_update` | write | `write` | `plan-changes.config` | `PATCH /v1/plan_changes/rules/:id` | Update a plan-change rule. | | `billing_plan_changes_rules_delete` | destructive | `delete` | `plan-changes.config` | `DELETE /v1/plan_changes/rules/:id` | Delete a plan-change rule; the pair falls back to the global policy. | ## `subscription-changes`[​](#subscription-changes "Enlace directo al subscription-changes") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | -------------------------------------------- | ----------- | ------- | ----------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `billing_subscription_item_changes_list` | read | `read` | `subscription-changes.list` | `GET /v1/subscription_item_changes` | List item changes applied to subscriptions, with the proration each produced and who initiated it. | | `billing_subscription_item_changes_get` | read | `read` | `subscription-changes.show` | `GET /v1/subscription_item_changes/:id` | Fetch one subscription item change. | | `billing_subscription_item_changes_cancel` | destructive | `write` | `subscription-changes.update` | `POST /v1/subscription_item_changes/:id/cancel` | Cancel a scheduled item change before it takes effect. | | `billing_subscription_changes_config_get` | read | `read` | `subscription-changes.list` | `GET /v1/subscription_changes/config` | Read the organization item-change policy: which item operations are allowed, how each is prorated and timed, and what the customer portal may do by itself. | | `billing_subscription_changes_config_update` | write | `write` | `subscription-changes.update` | `PUT /v1/subscription_changes/config` | Replace the organization item-change policy. | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.billing.kobana.com.br/es/es/api/v1) y en `billing_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.billing.kobana.com.br/es/es/mcp/overview/authentication.md). --- # Consumo Consumo medido para cobro por uso: registros crudos, el resumen agregado por ítem de suscripción y los snapshots diarios y mensuales. ## Familias en esta página[​](#familias-en-esta-página "Enlace directo al Familias en esta página") | Familia | Tools | read | write | destructive | | ------------------------ | ----- | ---- | ----- | ----------- | | `usage` — Consumo medido | 7 | 4 | 3 | 0 | ## `usage`[​](#usage "Enlace directo al usage") | Tool | Tipo | Scope | Permiso | Endpoint | Qué hace | | ---------------------------------------- | ----- | ------- | ------------ | ---------------------------------- | -------------------------------------------------------------------------------------------- | | `billing_usage_list` | read | `read` | `usage.view` | `GET /v1/usage` | List raw usage records for metered billing. | | `billing_usage_report` | write | `write` | `usage.view` | `POST /v1/usage` | Report metered usage. | | `billing_usage_summary` | read | `read` | `usage.view` | `GET /v1/usage/summary` | Aggregated usage for a period: total quantity per subscription item, against its plan limit. | | `billing_usage_snapshots_daily_list` | read | `read` | `usage.view` | `GET /v1/usage/snapshots/daily` | List daily usage snapshots. | | `billing_usage_snapshots_daily_create` | write | `write` | `usage.view` | `POST /v1/usage/snapshots/daily` | Push daily usage snapshots — one inline, or up to 100 in `records`. | | `billing_usage_snapshots_monthly_list` | read | `read` | `usage.view` | `GET /v1/usage/snapshots/monthly` | List monthly usage snapshots. | | `billing_usage_snapshots_monthly_create` | write | `write` | `usage.view` | `POST /v1/usage/snapshots/monthly` | Push monthly usage snapshots — one inline, or a batch in `records`. | *** Los campos de cada recurso están en la [Referencia de la API](https://docs.billing.kobana.com.br/es/es/api/v1) y en `billing_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.billing.kobana.com.br/es/es/mcp/overview/authentication.md). --- ## [📄️Certificados Digitales](https://docs.billing.kobana.com.br/es/es/nota-fiscal/certificados.md) [La página /dashboard/certificates gestiona los certificados digitales A1 usados para firmar NF-e y autenticarse en los webservices de las alcaldías (prefeituras). Cada certificado se vincula a una empresa registrada y se almacena cifrado en reposo.](https://docs.billing.kobana.com.br/es/es/nota-fiscal/certificados.md) --- ## [📄️Certificados Digitales](https://docs.billing.kobana.com.br/es/es/nota-fiscal/certificados.md) [La página /dashboard/certificates gestiona los certificados digitales A1 usados para firmar NF-e y autenticarse en los webservices de las alcaldías (prefeituras). Cada certificado se vincula a una empresa registrada y se almacena cifrado en reposo.](https://docs.billing.kobana.com.br/es/es/nota-fiscal/certificados.md) --- # Certificados Digitales La página `/dashboard/certificates` gestiona los **certificados digitales A1** usados para firmar NF-e y autenticarse en los webservices de las alcaldías (prefeituras). Cada certificado se vincula a una empresa registrada y se almacena cifrado en reposo. ## Cómo funciona[​](#cómo-funciona "Enlace directo al Cómo funciona") 1. **Carga del archivo `.pfx`** — el operador envía el certificado e informa la contraseña. 2. **Validación automática** — el sistema verifica el CNPJ, la vigencia y la cadena de certificación. 3. **Almacenamiento cifrado** — el contenido del `.pfx` y la contraseña se cifran con AES-256-GCM antes de ir a la base de datos. 4. **Vinculación a la empresa** — una empresa puede tener solo un certificado activo a la vez. ## Información mostrada[​](#información-mostrada "Enlace directo al Información mostrada") * **Empresa asociada** y **CNPJ** * **Vigencia** — fecha de expiración y aviso cuando faltan menos de 30 días * **Emisor** — Autoridad Certificadora que lo emitió (Serasa, Certisign, Soluti, etc.) * **Status** — `active`, `expired` o `revoked` * **Último uso** — fecha de la última NF-e firmada ## Alertas y renovación[​](#alertas-y-renovación "Enlace directo al Alertas y renovación") El sistema notifica a los administradores cuando un certificado se acerca a su expiración. Después de expirar, el proveedor de NF-e deja de aceptar la firma y las nuevas emisiones fallan hasta que se envíe un certificado nuevo. La renovación reemplaza el archivo sin perder el historial de NF-e emitidas con el certificado anterior. ## Seguridad[​](#seguridad "Enlace directo al Seguridad") * Las contraseñas y los bytes del `.pfx` se cifran en reposo (ver `lib/crypto.ts`). * El acceso a la página está restringido a miembros con el permiso fiscal correspondiente. * Toda creación, sustitución o eliminación genera una entrada en [Auditoría](https://docs.billing.kobana.com.br/es/es/configuracoes/auditoria.md). ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Lista de certificados digitales con empresa, vigencia y status](/es/assets/images/certificados-4083f93b3a90bd99543dd3cf7b21f845.png) --- # Configuración de NF-e Cada organización puede habilitar y configurar la emisión automática de notas fiscais. ## Campos de Configuración[​](#campos-de-configuración "Enlace directo al Campos de Configuración") | Campo | Descripción | | ------------------------------------- | ---------------------------------------------- | | **Proveedor** | `mock`, `nfe_io` o `kobana` | | **Ambiente** | `sandbox` o `production` | | **Habilitado** | Si la emisión de NF-e está activa | | **Política de emisión** | Cuándo la NF-e se emite automáticamente | | **Clave de la API NFe.io** | Clave de autenticación (cifrada) | | **Empresas NFe.io** | Caché de empresas registradas en el proveedor | | **Descripción del servicio** | Descripción predeterminada añadida a las notas | | **Máximo de intentos de emisión** | Predeterminado: 5 | | **Máximo de intentos de cancelación** | Predeterminado: 5 | | **Intervalos de reintento (minutos)** | Predeterminado: \[0, 30, 60, 180, 360] | ## Políticas de Emisión[​](#políticas-de-emisión "Enlace directo al Políticas de Emisión") | Política | Descripción | | ----------------- | ---------------------------------------------------------------- | | `disabled` | Emisión de NF-e deshabilitada | | `on_finalization` | Emitir cuando la factura se finaliza | | `on_full_payment` | Emitir cuando la factura está totalmente pagada (predeterminado) | | `per_installment` | Emitir una NF-e por cada cuota pagada | ### Ejemplos[​](#ejemplos "Enlace directo al Ejemplos") **`on_full_payment`**: Una factura de R$ 1.000 genera **una** NF-e de R$ 1.000 cuando se paga totalmente. **`per_installment`**: Una factura de R$ 1.000 en 3 cuotas genera **tres** NF-e de R$ 333,33 conforme cada cuota se paga. **`on_finalization`**: La NF-e se emite en el momento de la finalización de la factura, independientemente del pago. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") La pantalla `/dashboard/nfe-settings` reúne la configuración de NF-e por empresa: proveedor (NFe.io, Kobana), ambiente (sandbox/producción), clave de API cifrada en reposo, mapeo del código de servicio, política de emisión (`per_payment`, `per_installment`, `on_finalization`), webhooks de respuesta e indicadores de envío de e-mail. ![Configuración de NF-e por empresa con proveedor y políticas](/es/assets/images/configuracao-nfe-f03317941d5492f8b73e996873f58499.png) --- # Emisión de NF-e ## Estados de la NF-e[​](#estados-de-la-nf-e "Enlace directo al Estados de la NF-e") ``` draft → pending → processing → issued ↓ (error) → error issued → pending_cancel → canceling → canceled ↓ (error) → error ``` | Estado | Descripción | | ------------------- | ---------------------------------------------------- | | **draft** | Borrador, aún no enviada | | **pending** | En cola para emisión | | **processing** | Siendo procesada por el proveedor (async) | | **issued** | Emitida con éxito | | **pending\_cancel** | Marcada para cancelación | | **canceling** | Cancelación en procesamiento | | **canceled** | Cancelada con éxito | | **error** | Fallo en la emisión/cancelación tras agotar intentos | ## Campos de la NF-e[​](#campos-de-la-nf-e "Enlace directo al Campos de la NF-e") ### Identificación[​](#identificación "Enlace directo al Identificación") | Campo | Descripción | | ------------------- | ---------------- | | **Factura** | Factura asociada | | **Cuenta de cobro** | Cliente | | **Empresa** | Empresa emisora | ### Números y Claves[​](#números-y-claves "Enlace directo al Números y Claves") | Campo | Descripción | | -------------------------- | ----------------------------- | | **Número de la NF-e** | Número secuencial | | **Serie** | Serie de la NF-e | | **Clave** | Clave de 44 dígitos | | **Código de verificación** | Para consulta | | **Número RPS** | Recibo Provisório de Serviços | ### Servicio[​](#servicio "Enlace directo al Servicio") | Campo | Descripción | | ----------------------- | ----------------------------------- | | **Valor** | Valor del servicio | | **Código del servicio** | Código LC 116/2003 | | **Descripción** | Descripción del servicio prestado | | **Código CNAE** | Clasificación de actividad | | **Código NBS** | Nomenclatura Brasileira de Serviços | ### Impuestos[​](#impuestos "Enlace directo al Impuestos") La NF-e almacena el detalle de los impuestos calculados: * ISS (tasa y valor) * PIS, COFINS, CSLL * IRRF * INSS ### URLs[​](#urls "Enlace directo al URLs") | Campo | Descripción | | --------------- | --------------------------- | | **URL del XML** | Descarga del XML de la nota | | **URL del PDF** | Descarga del DANFE en PDF | ## Snapshot del Cliente[​](#snapshot-del-cliente "Enlace directo al Snapshot del Cliente") La NF-e almacena una **foto** de los datos del cliente en el momento de la emisión: * Nombre, documento, e-mail, teléfono * Dirección completa con código IBGE de la ciudad Esto garantiza que la nota refleje los datos correctos incluso si el cliente modifica su registro posteriormente. ## Pista de Auditoría[​](#pista-de-auditoría "Enlace directo al Pista de Auditoría") Cada solicitud HTTP realizada al proveedor se registra en `NfeRequestTry`: * Acción (emitir, cancelar, consultar) * Endpoint llamado * Request y response completos * Estado HTTP * Duración en milisegundos * Resultado (éxito/fallo) ## Capturas de pantalla[​](#capturas-de-pantalla "Enlace directo al Capturas de pantalla") ### Lista de NF-e[​](#lista-de-nf-e "Enlace directo al Lista de NF-e") La pantalla `/dashboard/nfes` lista todas las notas fiscales emitidas, con filtros por status (`pending`, `processing`, `issued`, `error`, `canceled`), empresa, cliente, rango y número. Cada fila muestra el número, el valor, los impuestos calculados, la factura/origen y acciones (descargar XML, PDF, reenviar, cancelar). ![Lista de NF-e con status, valor e impuestos](/es/assets/images/notas-fiscais-098edb710c834fcde9187bf22fcd15a7.png) ### Detalle de la NF-e[​](#detalle-de-la-nf-e "Enlace directo al Detalle de la NF-e") La página `/dashboard/nfes/[id]` reúne los datos fiscales completos: emisora, destinatario, ítems (con códigos LC 116/municipal), impuestos calculados, retenciones, XML devuelto por la alcaldía (prefeitura), PDF e historial de intentos en el proveedor. ![Detalle de una NF-e con tributos, XML e intentos en el proveedor](/es/assets/images/nota-fiscal-detalhe-9155b5b56f3b924c2d23f200e789655c.png) --- # Proveedores de NF-e El sistema abstrae la comunicación con proveedores de NF-e a través de una interfaz común. ## Proveedores Disponibles[​](#proveedores-disponibles "Enlace directo al Proveedores Disponibles") ### NFe.io (`nfe_io`)[​](#nfeio-nfe_io "Enlace directo al nfeio-nfe_io") Integración con la plataforma NFe.io para emisión de NFS-e. * **API**: * **Documentación**: * **Soporte**: NFS-e (servicios) **Mapeo de Estado:** | Estado NFe.io | Estado interno | | --------------------------------------------------------------------------- | -------------- | | Created, WaitingCalculateTaxes, WaitingSend, WaitingReturn, WaitingDownload | `processing` | | Issued | `issued` | | Cancelled | `canceled` | | Error | `error` | ### Kobana NF-e (`kobana`)[​](#kobana-nf-e-kobana "Enlace directo al kobana-nf-e-kobana") Integración con el servicio interno de NF-e de Kobana. * **API**: (configurable) * **Versión**: /api/v1 * **Soporte**: Emisión y cancelación ### Mock (`mock`)[​](#mock-mock "Enlace directo al mock-mock") Proveedor de desarrollo que simula emisiones con datos ficticios. * Sin llamadas externas * Almacenamiento en memoria * Genera claves y códigos de verificación realistas ## Interfaz Común[​](#interfaz-común "Enlace directo al Interfaz Común") Todos los proveedores implementan: | Operación | Descripción | | ------------- | ---------------------------- | | `issue` | Emitir una NF-e | | `cancel` | Cancelar una NF-e emitida | | `query` | Consultar estado de una NF-e | | `downloadXml` | Descargar XML de la nota | | `downloadPdf` | Descargar PDF (DANFE) | --- # Intentos y Reintento de NF-e El sistema implementa reintento automático para emisiones que fallan. ## Worker Automático[​](#worker-automático "Enlace directo al Worker Automático") Se ejecuta **cada 30 minutos** y realiza: 1. **Procesar reintentos**: NF-e pendientes o con error que aún tienen intentos 2. **Actualizar estado**: Consultar el proveedor para NF-e en `processing` (últimos 7 días) 3. **Auto-emisión por pago**: Emitir NF-e para facturas pagadas (política `on_full_payment`) 4. **Auto-emisión por finalización**: Emitir para facturas finalizadas (política `on_finalization`) 5. **Auto-emisión por cuota**: Emitir para cuotas pagadas (política `per_installment`) ## Lógica de Reintento[​](#lógica-de-reintento "Enlace directo al Lógica de Reintento") ### Intervalos Predeterminados[​](#intervalos-predeterminados "Enlace directo al Intervalos Predeterminados") | Intento | Intervalo | Tiempo acumulado | | ------- | --------- | ---------------- | | 1.° | Inmediato | 0 min | | 2.° | +30 min | 30 min | | 3.° | +60 min | 1h30 | | 4.° | +180 min | 4h30 | | 5.° | +360 min | \~10h30 | Los intervalos son configurables por organización vía `retryDelaysMinutes`. ### Máximo de Intentos[​](#máximo-de-intentos "Enlace directo al Máximo de Intentos") * Emisión: 5 intentos (configurable vía `maxIssueAttempts`) * Cancelación: 5 intentos (configurable vía `maxCancelAttempts`) Tras agotar los intentos, el estado cambia a `error`. ## Tratamiento de Errores[​](#tratamiento-de-errores "Enlace directo al Tratamiento de Errores") * Los errores en la auto-emisión son **no bloqueantes** (esperados cuando NF-e no está habilitada) * Logs detallados para cada intento * Contadores de procesos y errores por ejecución del worker --- ## [📄️Grupos de Planes](https://docs.billing.kobana.com.br/es/es/planos-e-produtos/grupos-de-planos/.md) [Los grupos de planes permiten organizar planes relacionados para facilitar la gestión y visualización en el dashboard.](https://docs.billing.kobana.com.br/es/es/planos-e-produtos/grupos-de-planos/.md) --- ## [📄️Grupos de Planes](https://docs.billing.kobana.com.br/es/es/planos-e-produtos/grupos-de-planos/.md) [Los grupos de planes permiten organizar planes relacionados para facilitar la gestión y visualización en el dashboard.](https://docs.billing.kobana.com.br/es/es/planos-e-produtos/grupos-de-planos/.md) --- # Grupos de Planes Los grupos de planes permiten organizar planes relacionados para facilitar la gestión y visualización en el dashboard. ## Campos[​](#campos "Enlace directo al Campos") | Campo | Descripción | | -------------------------- | -------------------------------------------------------- | | **Nombre** | Nombre del grupo (único por organización) | | **Slug** | Identificador amigable para URL (único por organización) | | **Orden de visualización** | Controla la posición del grupo en la interfaz | ## Funcionalidades[​](#funcionalidades "Enlace directo al Funcionalidades") * Auto-genera el slug a partir del nombre si no fue proporcionado * Impide el archivado si aún existen planes vinculados al grupo * El orden de visualización controla la organización de los grupos en la interfaz ## Operaciones[​](#operaciones "Enlace directo al Operaciones") * **Crear**: Informar nombre y organización * **Actualizar**: Nombre y slug editables * **Archivar**: Desactiva el grupo (soft delete) * **Desarchivar**: Reactiva el grupo * **Mover planes**: Es posible mover planes entre grupos o eliminar de un grupo (definir como `null`) --- # Grupos de Productos Los grupos de productos permiten categorizar productos para facilitar la organización, los filtros en el dashboard y la vinculación con templates de propuestas. ## Campos[​](#campos "Enlace directo al Campos") | Campo | Descripción | | -------------------------- | ----------------------------------------------------- | | **Nombre** | Nombre del grupo (único por organización) | | **Slug** | Identificador amigable para URL | | **Empresa** | Empresa específica (opcional) | | **Template de propuesta** | Template predeterminado para propuestas de este grupo | | **Ítem de servicio** | Ítem de servicio fiscal predeterminado para el grupo | | **Orden de visualización** | Posición en la interfaz | ## Operaciones[​](#operaciones "Enlace directo al Operaciones") * **Crear**: Informar nombre, organización y opcionalmente empresa/template/ítem de servicio * **Actualizar**: Todos los campos editables * **Archivar/Desarchivar**: Activa y desactiva grupos * **Reordenar**: Controlar el orden de visualización de los grupos ## Capturas de pantalla[​](#capturas-de-pantalla "Enlace directo al Capturas de pantalla") ### Lista de grupos[​](#lista-de-grupos "Enlace directo al Lista de grupos") La pantalla `/dashboard/product-groups` lista los grupos del catálogo con nombre, número de productos vinculados, status y orden de visualización. Los grupos definen cómo aparece el catálogo en el portal del cliente. ![Lista de grupos de productos con nombre y cantidad de ítems](/es/assets/images/grupos-de-produtos-2fab700d640cd5a4ae8cb8da38a4897c.png) ### Detalle del grupo[​](#detalle-del-grupo "Enlace directo al Detalle del grupo") La página `/dashboard/product-groups/[id]` permite organizar los productos del grupo, definir la descripción que se presenta en el portal, elegir el template fiscal/ítem de servicio predeterminado y archivar. ![Detalle de un grupo de productos con lista de ítems](/es/assets/images/grupo-de-produtos-detalhe-5ec79984d23ec26d3e3b3a1d210e42ea.png) --- # Ítems de Servicio Los ítems de servicio (`/dashboard/service-items`) son el catálogo de **descripciones fiscales** usadas en facturas y NF-e de servicio. Cada ítem contiene la información que la alcaldía (prefeitura) exige al momento de la emisión: código municipal de servicio, código LC 116, código tributario nacional, alícuotas predeterminadas de ISS, PIS, COFINS, IR, INSS, CSLL. A diferencia de un producto comercial, un ítem de servicio no tiene precio propio — se vincula a un producto, plan o línea de factura para aportar los metadatos fiscales correctos. Cuando se genera una NF-e, el motor fiscal consulta el ítem vinculado para completar los campos obligatorios y calcular los tributos. ## Qué almacena cada ítem[​](#qué-almacena-cada-ítem "Enlace directo al Qué almacena cada ítem") * **Nombre y descripción** — usados en el cuerpo de la nota fiscal. * **Código municipal** — código de servicio de la alcaldía emisora (varía según el municipio). * **Código LC 116** — código nacional definido por la Ley Complementaria 116/2003. * **NBS / NCM** — cuando corresponde a servicios que involucran productos. * **Alícuotas predeterminadas** — usadas como base de cálculo cuando no hay una regla tributaria específica. * **Empresa asociada** (opcional) — limita el ítem a una de las empresas registradas, útil para grupos con sucursales en municipios diferentes. ## Cuándo usarlo[​](#cuándo-usarlo "Enlace directo al Cuándo usarlo") * Catálogo SaaS con pocos servicios distintos: registra un único ítem ("Licencia de software") y reutilízalo en todos los productos. * Operación multiempresa con municipios diferentes: registra el mismo servicio una vez por empresa, con el código municipal correcto de cada una. * Ventas puntuales de consultoría, capacitación o setup: crea ítems dedicados para que la NF-e salga con la descripción y el código correctos. ## Relación con las reglas tributarias[​](#relación-con-las-reglas-tributarias "Enlace directo al Relación con las reglas tributarias") Cuando se evalúa una [regla tributaria](https://docs.billing.kobana.com.br/es/es/impostos/regras-fiscais/.md), esta puede filtrar por ítem de servicio para aplicar alícuotas específicas — por ejemplo, una retención de IR solo sobre servicios de consultoría. Esto permite mantener alícuotas predeterminadas en el ítem y excepciones en la regla. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Lista de ítems de servicio con código municipal y alícuotas](/es/assets/images/itens-de-servico-e2e38a0d1f1b04b1ea7da51c8036eb4d.png) --- # Planes Los planes son los modelos que definen cómo se cobrará a sus clientes. Cada plan agrupa productos con precios específicos y configura el ciclo de cobro, el período de prueba y las funcionalidades incluidas. ## Campos del Plan[​](#campos-del-plan "Enlace directo al Campos del Plan") | Campo | Descripción | | --------------------------------- | --------------------------------------------------------------------------------------------------- | | **Nombre** | Nombre de visualización del plan (1-255 caracteres) | | **Slug** | Identificador único amigable para URL (1-100 caracteres, solo letras minúsculas, números y guiones) | | **Descripción** | Texto descriptivo sobre lo que incluye el plan | | **Tipo** | `standard` (estándar), `custom` (negociado) o `promotional` (promocional) | | **Visibilidad** | `public` (visible en listados) o `private` (solo vía enlace directo) | | **Ciclo de cobro predeterminado** | `monthly`, `quarterly`, `semiannual` o `annual` | | **Ciclos disponibles** | Qué ciclos puede elegir el cliente al suscribirse | | **Período de prueba** | 0 a 90 días de prueba gratuita | | **Features** | Lista de funcionalidades incluidas en el plan | | **Límites** | Cuotas y restricciones (ej: usuarios, subcuentas, API requests/día) | ## Estado y Ciclo de Vida[​](#estado-y-ciclo-de-vida "Enlace directo al Estado y Ciclo de Vida") ``` draft (borrador) → active (activo) → archived (archivado) ↓ ↓ DELETE RESTORE (solo draft) (vuelve a active) ``` | Estado | Descripción | | ------------ | ----------------------------------------------------------------------------- | | **draft** | En construcción. Puede publicarse o eliminarse | | **active** | Disponible para nuevas suscripciones | | **archived** | Desactivado para nuevas suscripciones, pero las existentes siguen funcionando | ### Reglas de Transición[​](#reglas-de-transición "Enlace directo al Reglas de Transición") * **Archivar**: No es posible si existen suscripciones activas o en prueba * **Restaurar**: Disponible solo para planes archivados; vuelve al estado `active` * **Eliminar**: Disponible solo para planes en `draft` sin ninguna suscripción asociada ## Ítems del Plan[​](#ítems-del-plan "Enlace directo al Ítems del Plan") Cada plan contiene **ítems** que vinculan un producto a un precio específico: | Campo | Descripción | | ------------ | -------------------------------------------------------------- | | **Producto** | El producto incluido (solo productos raíz, sin hijos) | | **Precio** | La variante de precio seleccionada para el producto | | **Cantidad** | Cantidad incluida (mínimo 1) | | **Incluido** | Si el ítem forma parte del precio base o es un add-on opcional | ### Reglas de los Ítems[​](#reglas-de-los-ítems "Enlace directo al Reglas de los Ítems") * Solo los **productos raíz** pueden agregarse (los productos hijos se heredan automáticamente) * No se permite duplicar el mismo producto en un plan * Todos los productos deben pertenecer a la misma organización y empresa del plan ## Creación de un Plan[​](#creación-de-un-plan "Enlace directo al Creación de un Plan") 1. Acceda a **Planes** en el dashboard 2. Haga clic en **Nuevo Plan** 3. Complete los campos obligatorios (nombre, slug) 4. Agregue productos y sus precios como ítems del plan 5. Configure los ciclos de cobro disponibles 6. Opcionalmente defina un período de prueba 7. Guarde como borrador o publique directamente ## Duplicar Plan[​](#duplicar-plan "Enlace directo al Duplicar Plan") Utilice la función de duplicación para copiar todos los detalles de un plan. El sistema agrega automáticamente "(Copia)" al nombre y "-copy" al slug. El plan duplicado se crea con estado `draft`. ## Operaciones en Lote[​](#operaciones-en-lote "Enlace directo al Operaciones en Lote") * **Archivar en lote**: Archiva múltiples planes a la vez (omite los planes en uso) * **Eliminar en lote**: Elimina múltiples planes en draft (omite los planes con suscripciones) * **Mover a grupo**: Mueve múltiples planes a un grupo específico ## Empresa y Organización[​](#empresa-y-organización "Enlace directo al Empresa y Organización") * Todo plan pertenece a una **organización** (obligatorio) * Opcionalmente puede estar vinculado a una **empresa** específica (para facturación por entidad jurídica) * Todos los productos del plan deben pertenecer a la misma empresa/organización ## Capturas de pantalla[​](#capturas-de-pantalla "Enlace directo al Capturas de pantalla") ### Lista de planes[​](#lista-de-planes "Enlace directo al Lista de planes") La pantalla `/dashboard/plans` lista los planes del catálogo con nombre, ciclo, valor recurrente, número de suscripciones activas, status (`active`/`archived`) y acciones (editar, duplicar, archivar). ![Lista de planes con ciclo, valor y suscripciones activas](/es/assets/images/planos-dbf8aab20b058737af19443a1dcf68f4.png) ### Detalle del plan[​](#detalle-del-plan "Enlace directo al Detalle del plan") La página `/dashboard/plans/[id]` muestra los ítems del plan (productos, precios, cantidades), las reglas de proration, la política de cancelación, la lista de suscripciones vinculadas y la auditoría. ![Detalle de un plan con ítems, reglas y suscripciones](/es/assets/images/plano-detalhe-c2c444b5747412ae85958ab6f952972c.png) --- # Precios y Modelos de Fijación de Precios Cada producto puede tener múltiples precios, permitiendo variantes por moneda, intervalo de cobro o modelo de fijación de precios. Los precios son **en gran parte inmutables** después de su creación — solo el nombre y los metadatos pueden modificarse. Para cambiar valores, desactive el precio anterior y cree uno nuevo. ## Campos del Precio[​](#campos-del-precio "Enlace directo al Campos del Precio") | Campo | Descripción | | ---------------------------- | --------------------------------------------- | | **Nombre** | Nombre de la variante (ej: "Standard", "Pro") | | **Moneda** | Código ISO 4217 (predeterminado: BRL) | | **Activo** | Si el precio está disponible para uso | | **Billing Scheme** | Modelo de fijación de precios | | **Valor unitario** | Precio por unidad, en BRL (hasta 4 decimales) | | **Intervalo de recurrencia** | `month` o `year` | | **Conteo de intervalos** | Repeticiones (ej: 3 meses) | | **Tipo de uso** | `licensed` (fija) o `metered` (medida) | ## Valores Monetarios — Subcents[​](#valores-monetarios--subcents "Enlace directo al Valores Monetarios — Subcents") Los precios son números decimales en BRL y admiten hasta **4 decimales**, lo que permite precios unitarios fraccionados: | Valor | Significado | | ------- | ----------- | | `100` | R$ 100,00 | | `50.5` | R$ 50,50 | | `0.999` | R$ 0,999 | > **Importante**: los precios son el único lugar donde se conservan los 4 decimales. Los demás valores monetarios (factura, pago, crédito) se redondean a 2 decimales. ## Modelos de Fijación de Precios[​](#modelos-de-fijación-de-precios "Enlace directo al Modelos de Fijación de Precios") ### 1. Por Unidad (`per_unit`)[​](#1-por-unidad-per_unit "Enlace directo al 1-por-unidad-per_unit") El modelo más simple: precio fijo por unidad. ``` Precio: R$ 5,00/usuario/mes 10 usuarios = R$ 50,00/mes ``` ### 2. Escalonado — Graduated (`tiered` + `graduated`)[​](#2-escalonado--graduated-tiered--graduated "Enlace directo al 2-escalonado--graduated-tiered--graduated") Cada tramo tiene un precio diferente, y **solo las unidades dentro de cada tramo** se cobran a ese valor. ``` Tramo 1: 1-10 unidades → R$ 10,00/un Tramo 2: 11-50 unidades → R$ 8,00/un Tramo 3: 51+ unidades → R$ 5,00/un Para 25 unidades: (10 × R$ 10,00) + (15 × R$ 8,00) = R$ 220,00 ``` ### 3. Volumen (`tiered` + `volume`)[​](#3-volumen-tiered--volume "Enlace directo al 3-volumen-tiered--volume") Cuando el cliente alcanza un tramo, **todas las unidades** se cobran al valor de ese tramo. ``` Tramo 1: 1-10 unidades → R$ 10,00/un Tramo 2: 11-50 unidades → R$ 8,00/un Tramo 3: 51+ unidades → R$ 5,00/un Para 25 unidades: 25 × R$ 8,00 = R$ 200,00 (todas en el tramo 2) ``` ### 4. Paquete (`package`)[​](#4-paquete-package "Enlace directo al 4-paquete-package") Precio fijo para un paquete de ítems definido. ### Configuración de Tramos (Tiers)[​](#configuración-de-tramos-tiers "Enlace directo al Configuración de Tramos (Tiers)") Cada tramo define: | Campo | Descripción | | ------------- | ----------------------------------------------------------- | | `up_to` | Límite superior del tramo (`null` = ilimitado, tramo final) | | `unit_amount` | Precio por unidad en este tramo | | `flat_amount` | Valor fijo adicional por tramo (predeterminado: 0) | ## Tipo de Uso[​](#tipo-de-uso "Enlace directo al Tipo de Uso") | Tipo | Descripción | | ---------- | ------------------------------------------------ | | `licensed` | Cantidad fija definida en la suscripción | | `metered` | Cantidad medida y reportada a lo largo del ciclo | --- # Productos Los productos representan los servicios o recursos facturables de su organización. Cada producto puede tener múltiples precios y soporta jerarquía de un nivel (producto raíz con hijos/add-ons). ## Campos del Producto[​](#campos-del-producto "Enlace directo al Campos del Producto") | Campo | Descripción | | ---------------------- | ----------------------------------------------------------- | | **Nombre** | Nombre de visualización (1-255 caracteres) | | **Slug** | Identificador único amigable para URL | | **Descripción** | Detalles sobre el producto | | **Tipo** | Determina el modelo de uso (ver tabla abajo) | | **Visibilidad** | `public` o `private` | | **Label de la unidad** | Nombre de la unidad (ej: "usuarios", "GB") | | **Incremento** | Paso mínimo de cantidad (ej: 10 = cantidades 10, 20, 30...) | | **Obligatorio** | Si es necesario para suscribirse | | **URL del sitio** | Enlace a la documentación/página del producto | ## Tipos de Producto[​](#tipos-de-producto "Enlace directo al Tipos de Producto") | Tipo | Descripción | Recurrencia | | ------------------- | ------------------------------ | ----------------------- | | `base` | Producto estándar recurrente | Recurrente | | `addon_quantity` | Add-on con precio por cantidad | Recurrente | | `addon_fixed` | Add-on con precio fijo | Recurrente | | `metered` | Cobro basado en uso medido | Recurrente (en arrears) | | `one_time_fixed` | Cargo único fijo | Una vez | | `one_time_quantity` | Cargo único por unidad | Una vez | ## Jerarquía de Productos[​](#jerarquía-de-productos "Enlace directo al Jerarquía de Productos") Los productos soportan **un nivel** de jerarquía: ``` Producto Raíz (parentProductId = null) ├── Producto hijo 1 (add-on) ├── Producto hijo 2 (cargo de setup) └── Producto hijo 3 (módulo opcional) ``` ### Reglas de Jerarquía[​](#reglas-de-jerarquía "Enlace directo al Reglas de Jerarquía") * No es posible anidar más de 1 nivel (los hijos no pueden tener hijos) * Los productos hijos heredan la organización/empresa del padre * Solo los productos raíz pueden agregarse a planes * Los productos hijos aparecen como add-ons/opciones del producto padre ## Estado y Ciclo de Vida[​](#estado-y-ciclo-de-vida "Enlace directo al Estado y Ciclo de Vida") ``` draft (borrador) → active (activo) → archived (archivado) ↓ ↑ ↓ DELETE PUBLISH RESTORE ``` | Estado | Descripción | | ------------ | ---------------------------------------------------- | | **draft** | En desarrollo, no visible para planes | | **active** | Disponible para planes y suscripciones | | **archived** | Desactivado; no puede usarse en nuevas suscripciones | ### Reglas[​](#reglas "Enlace directo al Reglas") * **Archivar**: No es posible si es usado por suscripciones activas, en prueba o past\_due. Desactiva todos los precios automáticamente * **Restaurar**: Vuelve al estado `active` * **Publicar**: Mueve de `draft` a `active` ## Operaciones en Lote[​](#operaciones-en-lote "Enlace directo al Operaciones en Lote") * **Archivar en lote**: Archiva múltiples productos * **Eliminar en lote**: Elimina productos no utilizados en suscripciones * **Mover a grupo**: Mueve productos a un grupo de productos * **Cambiar visibilidad**: Modifica la visibilidad de múltiples productos * **Cambiar empresa**: Mueve productos a otra empresa ## Reordenación[​](#reordenación "Enlace directo al Reordenación") Los productos poseen un campo `display_order` para controlar el orden de visualización en el dashboard y portal. Es posible reordenar mediante drag-and-drop o API. ## Capturas de pantalla[​](#capturas-de-pantalla "Enlace directo al Capturas de pantalla") ### Lista de productos[​](#lista-de-productos "Enlace directo al Lista de productos") La pantalla `/dashboard/products` lista el catálogo con nombre, tipo (recurrente, único, metered), precio base, status y visibilidad en el portal. Admite reordenar con drag-and-drop y acciones masivas. ![Lista de productos con tipo, precio y visibilidad](/es/assets/images/produtos-ea412a7ad3c3c2ad67edab55fbd434d8.png) ### Detalle del producto[​](#detalle-del-producto "Enlace directo al Detalle del producto") La página `/dashboard/products/[id]` reúne los precios vinculados (con moneda y ciclo), los ítems de servicio fiscal, los planes que incluyen el producto, los eventos de uso y la auditoría. ![Detalle de un producto con precios y planes vinculados](/es/assets/images/produto-detalhe-8211adbd6847a6f91b5890caac46193e.png) --- ## [📄️Portal del Cliente](https://docs.billing.kobana.com.br/es/es/portal.md) [El Portal del Cliente es el área self-service a la que acceden los clientes finales (suscriptores) para gestionar su relación con la empresa que usa Facturación Automática. Cada portal opera en https:///portal (o en el dominio predeterminado de la plataforma) y muestra solo los datos de la cuenta de cobro autenticada.](https://docs.billing.kobana.com.br/es/es/portal.md) --- ## [📄️Portal del Cliente](https://docs.billing.kobana.com.br/es/es/portal.md) [El Portal del Cliente es el área self-service a la que acceden los clientes finales (suscriptores) para gestionar su relación con la empresa que usa Facturación Automática. Cada portal opera en https:///portal (o en el dominio predeterminado de la plataforma) y muestra solo los datos de la cuenta de cobro autenticada.](https://docs.billing.kobana.com.br/es/es/portal.md) --- # Suscripciones La página `/portal/subscriptions` lista las suscripciones vinculadas a la cuenta de cobro autenticada. Cada fila muestra el plan, el status, el valor recurrente, el próximo ciclo y las acciones disponibles. ## Información mostrada[​](#información-mostrada "Enlace directo al Información mostrada") * **Plan e ítems** — producto principal y add-ons. * **Status** — `trialing`, `active`, `past_due`, `paused` o `canceled`. * **Ciclo** — mensual, trimestral, semestral o anual. * **Valor recurrente** — en reales con el formato `R$ 1.234,56`. * **Inicio del período actual** y **próximo ciclo**. * **Método de pago** — terminación de la tarjeta, boleto o PIX. ## Acciones disponibles[​](#acciones-disponibles "Enlace directo al Acciones disponibles") Según la configuración de la organización, el cliente puede: * **Cambiar de plan** — flujo guiado con vista previa de la proration antes de confirmar. * **Cancelar** — programar la cancelación al final del ciclo o cancelar de inmediato (si está permitido). * **Pausar** — interrumpir temporalmente el cobro. * **Actualizar el método** — cambiar la tarjeta sin afectar la suscripción. ## Detalle de la suscripción[​](#detalle-de-la-suscripción "Enlace directo al Detalle de la suscripción") Al hacer clic en una suscripción, el cliente ve la página de detalle (`/portal/subscriptions/[id]`) con: * Historial de facturas generadas por la suscripción * Historial de cambios (plan, ítems, pausas) * Línea de tiempo de eventos * Documentos relacionados (contrato, propuesta original) ## Capturas de pantalla[​](#capturas-de-pantalla "Enlace directo al Capturas de pantalla") ### Lista de suscripciones[​](#lista-de-suscripciones "Enlace directo al Lista de suscripciones") ![Lista de suscripciones en el portal del cliente](/es/assets/images/portal-assinaturas-2a0184c3929a7b17348d0b285c4d0073.png) ### Detalle de la suscripción[​](#detalle-de-la-suscripción-1 "Enlace directo al Detalle de la suscripción") ![Detalle de una suscripción con historial de facturas y cambios](/es/assets/images/portal-assinatura-detalhe-2a0184c3929a7b17348d0b285c4d0073.png) --- # Configuración La página `/portal/settings` agrupa las preferencias de la cuenta de cobro que afectan **cómo el cliente recibe los cobros y las comunicaciones**. ## Preferencias de cobro[​](#preferencias-de-cobro "Enlace directo al Preferencias de cobro") * **Método de pago predeterminado** — usado en los cobros automáticos. * **Día de vencimiento preferido** (cuando el plan lo permite). * **E-mail para recibir facturas** — puede ser distinto del e-mail de inicio de sesión. * **Idioma de las comunicaciones** — `pt-BR` o `en-US`. ## Notificaciones[​](#notificaciones "Enlace directo al Notificaciones") Interruptores para habilitar/deshabilitar: * Recordatorio antes del vencimiento de la factura * Confirmación de pago * Aviso de pago fallido * Fin del trial * Cambio de plan * Tarjeta por expirar * Recibir la NF-e por e-mail Cada interruptor controla un canal (e-mail) específico. Los webhooks para integraciones se configuran en el dashboard administrativo de la organización. ## Datos de la empresa[​](#datos-de-la-empresa "Enlace directo al Datos de la empresa") Accesos directos a [Cuenta](https://docs.billing.kobana.com.br/es/es/portal/conta.md) (datos fiscales) y [Métodos de Pago](https://docs.billing.kobana.com.br/es/es/portal/metodos-de-pagamento.md). ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Configuración del portal con preferencias de cobro y notificaciones](/es/assets/images/portal-configuracoes-66269cce8dfa780f84a99fd87120b525.png) --- # Cuenta En `/portal/account` el cliente gestiona los **datos de la cuenta de cobro** (`BillingAccount`) — razón social, CNPJ/CPF, inscripción estatal y municipal, dirección, contacto financiero y e-mails para el envío de facturas. ## Datos editables[​](#datos-editables "Enlace directo al Datos editables") * **Razón social** y **nombre comercial** * **Documento** (CNPJ o CPF) * **Inscripción estatal** e **inscripción municipal** (cuando corresponden) * **Dirección completa** — usada para la emisión de NF-e y el cobro * **E-mails para recibir facturas y cobros** * **Teléfono de contacto** ## Validaciones[​](#validaciones "Enlace directo al Validaciones") * El CNPJ y el CPF se validan mediante los dígitos verificadores. * El CEP busca la dirección automáticamente cuando es posible. * Los cambios de CNPJ exigen reemitir las facturas abiertas (la organización puede bloquear este campo). ## NF-e[​](#nf-e "Enlace directo al NF-e") Cuando la NF-e está habilitada, los datos de esta página se copian al documento fiscal emitido. Mantener el registro actualizado evita rechazos por divergencia en la SEFAZ o en la alcaldía (prefeitura). ## Actualizaciones restringidas[​](#actualizaciones-restringidas "Enlace directo al Actualizaciones restringidas") Algunos campos (documento, dirección fiscal) pueden estar bloqueados para edición directa según la política de la organización — en esos casos, el cliente ve instrucciones para abrir una solicitud con soporte. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Edición de los datos de la cuenta de cobro en el portal](/es/assets/images/portal-conta-27539e59595fe295a333d823e4fb6b88.png) --- # Créditos La página `/portal/credits` muestra el **saldo de créditos** de la cuenta de cobro y el historial de aplicaciones. Los créditos surgen por diversos motivos — proration de downgrade, reembolso de factura, ajuste manual de la organización, promoción — y se aplican automáticamente en las próximas facturas. ## Saldo[​](#saldo "Enlace directo al Saldo") La parte superior de la página muestra el saldo total disponible en reales. Cuando hay créditos con fecha de expiración, la página alerta sobre los que están próximos a vencer. ## Historial[​](#historial "Enlace directo al Historial") Cada registro de crédito muestra: * **Fecha** de generación * **Origen** — `downgrade_proration`, `refund`, `manual_adjustment`, `promotion`, etc. * **Valor** * **Status** — `available`, `partially_applied`, `fully_applied`, `expired` * **Aplicaciones** — facturas en las que se consumió el crédito (parcial o totalmente) ## Cómo se aplica el crédito[​](#cómo-se-aplica-el-crédito "Enlace directo al Cómo se aplica el crédito") Cuando se finaliza una factura (`open`), el motor de cobro consume los créditos disponibles en orden FIFO (el más antiguo primero), hasta agotar el crédito o cubrir la factura. El valor consumido aparece como una línea negativa en la factura y el saldo restante sigue disponible. ## Cuándo el crédito **no** se aplica[​](#cuándo-el-crédito-no-se-aplica "Enlace directo al cuándo-el-crédito-no-se-aplica") * Facturas en status `void` o ya `paid` * Cuando la configuración del plan deshabilita el uso de crédito * Créditos expirados ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Saldo e historial de créditos en el portal](/es/assets/images/portal-creditos-0df7f0ec693604a17434bdeb40b5e832.png) --- # Facturas La página `/portal/invoices` lista todas las facturas de la cuenta de cobro, con filtros por status y período. El cliente puede verlas, descargar el PDF, copiar la línea digitable o el código QR PIX, pagar en línea y consultar la NF-e relacionada. ## Status visibles en el portal[​](#status-visibles-en-el-portal "Enlace directo al Status visibles en el portal") * **Abierta** — generada, esperando el pago. * **Pagada** — saldada (parcial o totalmente). * **Vencida** — pasó la fecha de vencimiento sin pago. * **Cancelada** — invalidada por la organización. * **En procesamiento** — pago enviado, esperando la confirmación del gateway. ## Acciones por factura[​](#acciones-por-factura "Enlace directo al Acciones por factura") * **Pagar** — abre el flujo de pago con los métodos habilitados. * **Descargar PDF** — genera el documento de la factura. * **Copiar línea digitable** (boleto) — código de barras listo para pagar. * **Copiar PIX** — copia y pega o código QR. * **Ver NF-e** — enlace a la nota fiscal vinculada, cuando fue emitida. * **Historial de pagos** — todos los intentos y reembolsos. ## Detalle de la factura[​](#detalle-de-la-factura "Enlace directo al Detalle de la factura") La página de detalle (`/portal/invoices/[id]`) muestra: * **Línea por línea** de los ítems (descripción, cantidad, valor unitario, total) * **Total bruto, descuentos, créditos aplicados, impuestos retenidos, valor a pagar** * **Historial de intentos de pago** (gateway, método, status, error) * **NF-e** cuando la hay, con enlace para descargar el XML y el PDF ## Captura de pantalla — lista[​](#captura-de-pantalla--lista "Enlace directo al Captura de pantalla — lista") ![Lista de facturas en el portal con status y acciones](/es/assets/images/portal-faturas-e570c42a062f36aebb5c7893c69ac9ef.png) ## Captura de pantalla — detalle[​](#captura-de-pantalla--detalle "Enlace directo al Captura de pantalla — detalle") ![Detalle de una factura con ítems, totales e historial de pagos](/es/assets/images/portal-fatura-detalhe-85ce29f4c5d71bf4ba1c104c6985afb4.png) --- # Métodos de Pago En `/portal/payment-methods` el cliente gestiona los medios de pago asociados a la cuenta de cobro. La página admite varios métodos a la vez y define cuál es el predeterminado para los cobros automáticos. ## Métodos soportados[​](#métodos-soportados "Enlace directo al Métodos soportados") * **Tarjeta de crédito** — marcas Visa, Mastercard, Elo, Amex e Hipercard, según el gateway. Guarda el token, la marca, los últimos 4 dígitos y la fecha de expiración. * **Boleto bancario** — se genera en cada factura cuando el cliente elige el boleto como predeterminado. * **PIX** — pago mediante código QR o copia y pega, generado factura por factura. * **Transferencia bancaria** — cuando la organización la habilita, con los datos de la cuenta para el depósito. ## Acciones[​](#acciones "Enlace directo al Acciones") * **Añadir Tarjeta** — formulario tokenizado por el gateway; los datos sensibles nunca pasan por los servidores de la plataforma. * **Definir como Predeterminado** — método usado en los cobros automáticos (charge\_automatically). * **Eliminar** — borra el token; los cobros futuros dependen de otro método. ## Tarjeta por expirar[​](#tarjeta-por-expirar "Enlace directo al Tarjeta por expirar") El worker `card-expiring` (semanal) detecta las tarjetas que están por expirar y envía una notificación para que el cliente las actualice antes de que falle el próximo cobro. ## Seguridad[​](#seguridad "Enlace directo al Seguridad") * Los tokens de tarjeta se almacenan en el gateway, no en la plataforma. * El cliente nunca ve el número completo de la tarjeta después del registro. * Las altas y bajas quedan registradas en [Auditoría](https://docs.billing.kobana.com.br/es/es/configuracoes/auditoria.md). ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Pantalla de métodos de pago con tarjetas registradas](/es/assets/images/portal-metodos-de-pagamento-f20c2eea839e1717b050bc474003c9b7.png) --- # Pagos La página `/portal/payments` presenta el **historial de pagos** ya procesados en la cuenta de cobro — sin importar el método ni la factura de origen. Es la vista del extracto, útil para la conciliación contable y las dudas sobre cobros. ## Información por pago[​](#información-por-pago "Enlace directo al Información por pago") * **Fecha** del procesamiento * **Valor** * **Método** — tarjeta, boleto, PIX, transferencia * **Status** — `succeeded`, `pending`, `failed`, `refunded`, `chargeback` * **Factura relacionada** — enlace a la factura de origen * **Gateway** — cuando es relevante (solo para soporte) ## Filtros[​](#filtros "Enlace directo al Filtros") * **Status** * **Método** * **Rango de fechas** ## Detalle del pago[​](#detalle-del-pago "Enlace directo al Detalle del pago") En `/portal/payments/[id]` el cliente ve el **recibo**: * Identificador del pago * Cliente pagador, cuenta de cobro * Factura saldada y sus ítems * Método utilizado (últimos 4 dígitos de la tarjeta, banco del boleto, clave PIX) * Status detallado y mensaje del gateway * Botón para descargar el comprobante en PDF ## Reembolsos[​](#reembolsos "Enlace directo al Reembolsos") Cuando la organización reembolsa un pago, el status pasa a `refunded` y un enlace apunta al registro del reembolso. El crédito correspondiente (si se generó) aparece en [Créditos](https://docs.billing.kobana.com.br/es/es/portal/creditos.md). ## Captura de pantalla — lista[​](#captura-de-pantalla--lista "Enlace directo al Captura de pantalla — lista") ![Historial de pagos en el portal](/es/assets/images/portal-pagamentos-ce7d7f0aeb322e95a2092b0f92527361.png) ## Captura de pantalla — detalle[​](#captura-de-pantalla--detalle "Enlace directo al Captura de pantalla — detalle") ![Detalle de un pago con recibo y factura relacionada](/es/assets/images/portal-pagamento-detalhe-cc245e323bf15fe7fa50bf0bc6e05c0d.png) --- # Perfil La página `/portal/profile` reúne las **preferencias personales del usuario** que inició sesión en el portal. A diferencia de [Cuenta](https://docs.billing.kobana.com.br/es/es/portal/conta.md), que se ocupa de la persona jurídica/física pagadora, el perfil es por cada persona que usa el portal. ## Qué puede ajustar el usuario[​](#qué-puede-ajustar-el-usuario "Enlace directo al Qué puede ajustar el usuario") * **Nombre para mostrar** * **E-mail** — usado para el inicio de sesión mágico y las notificaciones * **Tema** — claro, oscuro o automático * **Idioma** — `pt-BR` o `en-US` * **Preferencias de notificación** — qué e-mails recibir (recordatorio de factura, recibo de pago, fin del trial, etc.) ## Varios usuarios por cuenta[​](#varios-usuarios-por-cuenta "Enlace directo al Varios usuarios por cuenta") Una misma cuenta de cobro puede tener varios usuarios del portal (socios, finanzas, contador). Cada uno tiene su propio perfil y su propia preferencia de e-mail, pero todos ven los mismos datos de cobro. ## Seguridad[​](#seguridad "Enlace directo al Seguridad") * Cambiar el e-mail dispara una confirmación en el e-mail anterior y en el nuevo. * El token de confirmación se almacena cifrado (`lib/crypto.ts`). * Todo cambio queda registrado en [Auditoría](https://docs.billing.kobana.com.br/es/es/configuracoes/auditoria.md). ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Configuración del perfil del usuario del portal](/es/assets/images/portal-perfil-bf83dd2663658b0757d956b3ef439ed0.png) --- # Productos La página `/portal/products` es la **vitrina self-service** de los productos y planes que la organización publicó para la venta directa en el portal. El cliente puede contratar nuevos productos sin pasar por el equipo comercial, con un checkout integrado a los métodos de pago ya registrados. ## Qué aparece[​](#qué-aparece "Enlace directo al Qué aparece") Solo los productos marcados como **publicados** (`is_published = true`) y con al menos un precio activo. La presentación sigue la agrupación configurada en [Grupos de Productos](https://docs.billing.kobana.com.br/es/es/planos-e-produtos/grupos-de-produtos/.md), con tarjetas, descripciones y tabla de precios. ## Flujo de contratación[​](#flujo-de-contratación "Enlace directo al Flujo de contratación") 1. El cliente selecciona el producto/plan. 2. Confirma la cantidad y los add-ons. 3. Elige o registra un método de pago. 4. Confirma — se crea una suscripción (o un pedido único, según el producto). 5. Se genera la primera factura y se cobra según el método. Todo el flujo respeta las configuraciones de ciclo, trial y proration definidas por la organización. Cuando el cliente ya tiene una suscripción activa, el sistema ofrece la opción de agregar el ítem a la suscripción existente. ## Catálogo personalizado[​](#catálogo-personalizado "Enlace directo al Catálogo personalizado") La organización puede ocultar productos del portal manteniéndolos disponibles vía API o propuestas comerciales. Esto permite usar el portal solo para upsell controlado, o poner todo a disposición en self-service. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Vitrina de productos en el portal del cliente](/es/assets/images/portal-produtos-c163b631fd6817664d95ca18b8cf3a98.png) --- # Propuestas En `/portal/proposals` el cliente ve las **propuestas comerciales** enviadas por el equipo de la organización. Cada propuesta detalla planes, ítems, descuentos, plazo y condiciones — y puede aceptarse directamente en el portal, convirtiéndose en una suscripción activa. ## Estados de la propuesta[​](#estados-de-la-propuesta "Enlace directo al Estados de la propuesta") * **draft** — en edición interna; no visible en el portal. * **sent** — enviada al cliente, esperando una acción. * **viewed** — el cliente abrió la propuesta en el portal (registrado con timestamp). * **accepted** — el cliente la aceptó; genera la suscripción, la primera factura y la auditoría. * **declined** — el cliente la rechazó; motivo opcional registrado. * **expired** — pasó su vigencia. ## Contenido de la propuesta[​](#contenido-de-la-propuesta "Enlace directo al Contenido de la propuesta") * Cliente y datos de cobro * Ítems (planes, productos, add-ons) con cantidad y valor * Descuentos aplicados, valor total e impuestos * Condiciones comerciales (plazo, ciclo, trial) * PDF generado automáticamente para impresión y archivo ## Aceptar una propuesta[​](#aceptar-una-propuesta "Enlace directo al Aceptar una propuesta") 1. El cliente hace clic en **Aceptar**. 2. Confirma el método de pago (registrado o nuevo). 3. El sistema crea la suscripción, emite la primera factura y dispara el webhook `proposal.accepted`. 4. El cliente es redirigido a la suscripción recién creada. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Lista de propuestas comerciales en el portal del cliente](/es/assets/images/portal-propostas-9d0703056723f44fceb8b8f0ff8c44d4.png) --- # Uso La página `/portal/usage` muestra al cliente el **consumo medido** acumulado en el ciclo actual — cuántas llamadas a la API, mensajes enviados, eventos procesados o GB almacenados, según las métricas definidas por la organización. ## Qué se muestra[​](#qué-se-muestra "Enlace directo al Qué se muestra") * **Lista de productos metered** activos en la cuenta * **Consumo del período** con la unidad de medida correcta * **Comparativo** con el período anterior (cuando está disponible) * **Estimación del cobro** para la próxima factura, con base en el consumo hasta el momento * **Límites y alertas** cuando el producto tiene un tope o rangos configurados ## Filtros[​](#filtros "Enlace directo al Filtros") * **Rango de fechas** — por defecto, desde el inicio del ciclo actual hasta hoy * **Producto** — cuando hay varias métricas ## Actualización[​](#actualización "Enlace directo al Actualización") Los datos reflejan el mismo backend que usa el dashboard administrativo. Los eventos llegan vía la API de Usage Records, integraciones o el worker `usage-sync` (cada hora). El retraso suele ser de minutos. ## Para qué sirve[​](#para-qué-sirve "Enlace directo al Para qué sirve") * **Previsibilidad** — el cliente sabe lo que va a pagar antes del cambio de ciclo. * **Detección de anomalías** — los picos sospechosos se vuelven evidentes. * **Soporte** — las conversaciones sobre cobros parten de los mismos números que muestra el dashboard. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Métricas de uso/consumo del ciclo actual en el portal](/es/assets/images/portal-uso-38a6fb94b96a21a8f4fe76c322174049.png) --- # Vista General La página inicial del portal (`/portal`) presenta un **resumen de la relación financiera** del cliente con la organización: suscripción activa, próxima factura, último pago, créditos disponibles y accesos directos a las acciones más comunes. ## Tarjetas principales[​](#tarjetas-principales "Enlace directo al Tarjetas principales") * **Próximo cobro** — fecha, valor y método (tarjeta, boleto, PIX). * **Suscripción activa** — plan, ciclo y status. * **Último pago** — fecha, valor y status (exitoso, en procesamiento, fallido). * **Crédito disponible** — saldo total y enlace al historial. * **Facturas abiertas** — alerta cuando hay boletos vencidos o próximos a vencer. ## Accesos directos[​](#accesos-directos "Enlace directo al Accesos directos") La página ofrece accesos directos para: * Pagar la próxima factura * Cambiar el método de pago predeterminado * Actualizar los datos de cobro * Hablar con soporte ## Personalización[​](#personalización "Enlace directo al Personalización") El logo, los colores y los textos siguen la configuración definida por la organización en [Portal del Cliente](https://docs.billing.kobana.com.br/es/es/contas/portal-do-cliente/.md). El cliente puede alternar entre tema claro y oscuro. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") ![Vista general del portal del cliente con el próximo cobro y la suscripción activa](/es/assets/images/portal-visao-geral-27539e59595fe295a333d823e4fb6b88.png) --- ## [📄️Generación de PDF](https://docs.billing.kobana.com.br/es/es/propostas/geracao-de-pdf/.md) [El sistema genera PDFs de propuestas integrando con Google Docs/Slides vía Google Apps Script.](https://docs.billing.kobana.com.br/es/es/propostas/geracao-de-pdf/.md) --- ## [📄️Generación de PDF](https://docs.billing.kobana.com.br/es/es/propostas/geracao-de-pdf/.md) [El sistema genera PDFs de propuestas integrando con Google Docs/Slides vía Google Apps Script.](https://docs.billing.kobana.com.br/es/es/propostas/geracao-de-pdf/.md) --- # Generación de PDF El sistema genera PDFs de propuestas integrando con Google Docs/Slides vía Google Apps Script. ## Flujo de Generación[​](#flujo-de-generación "Enlace directo al Flujo de Generación") 1. El servicio crea un **token de datos temporal** (validez: 10 minutos) 2. Construye la URL segura con los datos de la propuesta 3. Llama al **Google Apps Script** con los datos 4. El Apps Script completa el template en Google Drive 5. Retorna el ID del documento y URLs ## Datos Enviados al Template[​](#datos-enviados-al-template "Enlace directo al Datos Enviados al Template") ### Información Básica[​](#información-básica "Enlace directo al Información Básica") * Fecha de generación y expiración * Código, título y descripción de la propuesta ### Datos del Cliente[​](#datos-del-cliente "Enlace directo al Datos del Cliente") * Nombre, documento, razón social * Contacto (e-mail, teléfono) * Responsable (usuario del portal) ### Productos[​](#productos "Enlace directo al Productos") Para cada ítem: * Nombre, descripción, cantidad * Precio unitario y total * Setup por unidad y total * Recurrente por unidad y total * Si es producto one-time ### Precios por Ciclo[​](#precios-por-ciclo "Enlace directo al Precios por Ciclo") Para cada ciclo (mensual, trimestral, semestral, anual): * Total del ciclo * Descuento y porcentaje * Primer pago * Valor mensual equivalente ### Cupón[​](#cupón "Enlace directo al Cupón") * Código, tipo y valor del descuento ### Setup[​](#setup "Enlace directo al Setup") * Si hay setup, total y primer pago ### Organización[​](#organización "Enlace directo al Organización") * Nombre y documento de la organización ## URLs Generadas[​](#urls-generadas "Enlace directo al URLs Generadas") | Tipo | Formato | | ----------------- | ----------------------------------------------------------- | | **Google Docs** | `https://docs.google.com/document/d/{id}/edit` | | **Google Slides** | `https://docs.google.com/presentation/d/{id}/edit` | | **PDF (Docs)** | `https://docs.google.com/document/d/{id}/export?format=pdf` | | **PDF (Slides)** | `https://docs.google.com/presentation/d/{id}/export/pdf` | ## Seguridad[​](#seguridad "Enlace directo al Seguridad") Los datos de la propuesta son accedidos vía token temporal de 10 minutos. Después del uso o expiración, el token es invalidado. --- # Propuestas Las propuestas son documentos comerciales enviados a clientes o prospectos con ítems, precios y condiciones de pago. ## Ciclo de Vida[​](#ciclo-de-vida "Enlace directo al Ciclo de Vida") ``` draft → sent → viewed → accepted ↓ rejected ``` | Status | Descripción | | ------------ | -------------------------------------------------------- | | **draft** | Borrador, editable | | **sent** | Enviada al cliente | | **viewed** | Visualizada por el cliente | | **accepted** | Aceptada — suscripción y factura creadas automáticamente | | **rejected** | Rechazada por el cliente (motivo almacenado) | | **expired** | Expiró sin respuesta | | **canceled** | Cancelada por la organización | ## Campos de la Propuesta[​](#campos-de-la-propuesta "Enlace directo al Campos de la Propuesta") | Campo | Descripción | | ----------------------- | -------------------------------------------------------------- | | **Código** | Identificador único generado automáticamente | | **Título** | Título de la propuesta (predeterminado: "Propuesta Comercial") | | **Descripción** | Detalles de la propuesta | | **Cuenta de cobro** | Para clientes existentes | | **Prospecto** | Para nuevos clientes (Person tipo customer) | | **Cupón** | Cupón de descuento aplicado | | **Template** | Template de documento para generación de PDF | | **Fecha de expiración** | Configurable (predeterminado: según billing settings) | | **Notas** | Observaciones internas | ## Ítems de la Propuesta[​](#ítems-de-la-propuesta "Enlace directo al Ítems de la Propuesta") Cada propuesta contiene ítems con productos y precios: | Campo | Descripción | | ------------------ | ------------------------------- | | **Producto** | Producto cotizado | | **Precio** | Variante de precio seleccionada | | **Cantidad** | Cantidad (predeterminado: 1) | | **Valor unitario** | Precio por unidad | Restricción: No se permite duplicar el mismo producto en una propuesta. ## Cálculo de Precios[​](#cálculo-de-precios "Enlace directo al Cálculo de Precios") El sistema calcula automáticamente los precios por ciclo de cobro: | Ciclo | Descuento Predeterminado | | ---------- | ------------------------ | | Mensual | 0% | | Trimestral | 5% | | Semestral | 10% | | Anual | 15% | Los descuentos por ciclo son configurables en las configuraciones de cobro de la organización. Para cada ciclo, el sistema calcula: * Subtotal (suma de los ítems recurrentes × meses) * Descuento del ciclo * Descuento del cupón * Total con descuentos * Precio por mes * Primer pago (incluyendo tarifas únicas/setup) ## Operaciones[​](#operaciones "Enlace directo al Operaciones") ### Enviar (`draft` → `sent`)[​](#enviar-draft--sent "Enlace directo al enviar-draft--sent") Requiere al menos 1 ítem. Registra `sent_at`. ### Despublicar (`sent`/`viewed` → `draft`)[​](#despublicar-sentviewed--draft "Enlace directo al despublicar-sentviewed--draft") Permite reeditar una propuesta ya enviada. ### Aceptar[​](#aceptar "Enlace directo al Aceptar") Cuando el cliente acepta: 1. El status cambia a `accepted` 2. **Se crea la suscripción** automáticamente con los ítems de la propuesta 3. **Se crea y finaliza la factura** 4. El ciclo de cobro es elegido por el cliente en el momento de la aceptación ### Rechazar[​](#rechazar "Enlace directo al Rechazar") El cliente puede rechazar informando un motivo opcional. ### Deshacer Aceptación[​](#deshacer-aceptación "Enlace directo al Deshacer Aceptación") Revierte la propuesta de `accepted` a `sent` y elimina la suscripción vinculada. ### Cancelar[​](#cancelar "Enlace directo al Cancelar") Disponible en cualquier estado excepto `accepted` y `canceled`. ## PDF y Documento[​](#pdf-y-documento "Enlace directo al PDF y Documento") ### Invalidación Automática[​](#invalidación-automática "Enlace directo al Invalidación Automática") Cuando los ítems son modificados después de la generación del PDF, el campo `pdf_outdated_at` se define, señalando que el PDF necesita ser regenerado. ## Propuestas en el Portal[​](#propuestas-en-el-portal "Enlace directo al Propuestas en el Portal") Los clientes acceden a las propuestas por el portal usando el código único. Pueden visualizar, aceptar o rechazar. ## Capturas de pantalla[​](#capturas-de-pantalla "Enlace directo al Capturas de pantalla") ### Lista de propuestas[​](#lista-de-propuestas "Enlace directo al Lista de propuestas") La pantalla `/dashboard/proposals` lista todas las propuestas comerciales con filtros por status (`draft`, `sent`, `viewed`, `accepted`, `declined`, `expired`), cliente, plazo de vigencia y valor. Cada fila muestra el cliente, el valor, los días para expirar y acciones (enviar, duplicar, cancelar, descargar PDF). ![Lista de propuestas comerciales con status y vigencia](/es/assets/images/propostas-dd81fd4236f029e66179aa5fa19aef77.png) ### Detalle de la propuesta[​](#detalle-de-la-propuesta "Enlace directo al Detalle de la propuesta") La página `/dashboard/proposals/[id]` reúne los ítems (planes y productos con cantidad y valor), descuentos, totales, condiciones, plazo de vigencia, línea de tiempo de eventos (enviada, vista, aceptada) y acciones para reenviar, duplicar o convertir manualmente en suscripción. ![Detalle de una propuesta con ítems, totales y línea de tiempo](/es/assets/images/proposta-detalhe-3658eff3f23cb9f190ed68ab99cefb42.png) --- # Templates de Propuesta Los templates definen el modelo de documento usado para generar PDFs de las propuestas. ## Campos del Template[​](#campos-del-template "Enlace directo al Campos del Template") | Campo | Descripción | | ----------------------- | ---------------------------------------------------------- | | **Nombre** | Nombre del template (único por organización) | | **Descripción** | Detalles sobre el template | | **Google Doc ID** | ID del documento template en Google Drive | | **Tipo de documento** | `google_doc` o `google_slides` | | **URL del Apps Script** | URL del deployment del Google Apps Script para generación | | **Carpeta del Drive** | ID de la carpeta donde se guardan los documentos generados | | **Predeterminado** | Si es el template predeterminado de la organización | | **Activo** | Si está disponible para uso | ## Operaciones[​](#operaciones "Enlace directo al Operaciones") * **Crear**: Informar nombre, Google Doc ID y opcionalmente Apps Script URL * **Actualizar**: Todos los campos editables * **Definir como predeterminado**: Desmarca el predeterminado anterior automáticamente * **Activar/Desactivar**: Controla disponibilidad (no se puede desactivar el único template activo) * **Eliminar**: Solo si no es utilizado por ninguna propuesta ## Integración con Google[​](#integración-con-google "Enlace directo al Integración con Google") El template es un documento de Google Docs o Google Slides que contiene placeholders para datos de la propuesta. El Google Apps Script procesa los datos y genera el documento final. ## Captura de pantalla[​](#captura-de-pantalla "Enlace directo al Captura de pantalla") La pantalla `/dashboard/proposal-templates` lista los templates de propuesta de la organización, con nombre, tipo (Google Docs, Google Slides), última actualización y número de propuestas que usan cada template. Incluye una vista previa de la estructura de placeholders y acciones para duplicar o archivar. ![Lista de templates de propuesta con placeholders](/es/assets/images/templates-de-proposta-0e95e640ee1796f1093719095ce896b1.png) --- ## [📄️Endpoints de Webhook](https://docs.billing.kobana.com.br/es/es/webhooks/endpoints/.md) [Cada organización puede configurar múltiples endpoints para recibir notificaciones de eventos.](https://docs.billing.kobana.com.br/es/es/webhooks/endpoints/.md) --- ## [📄️Endpoints de Webhook](https://docs.billing.kobana.com.br/es/es/webhooks/endpoints/.md) [Cada organización puede configurar múltiples endpoints para recibir notificaciones de eventos.](https://docs.billing.kobana.com.br/es/es/webhooks/endpoints/.md) --- # Endpoints de Webhook Cada organización puede configurar múltiples endpoints para recibir notificaciones de eventos. ## Campos del Endpoint[​](#campos-del-endpoint "Enlace directo al Campos del Endpoint") | Campo | Descripción | | --------------- | ----------------------------------------------- | | **URL** | Dirección HTTPS que recibirá las notificaciones | | **Descripción** | Descripción del endpoint (máx 255 caracteres) | | **Eventos** | Lista de tipos de eventos suscritos | | **Secreto** | Clave HMAC-SHA256 para validación de firma | | **Activo** | Si el endpoint está habilitado | ## Creando un Endpoint[​](#creando-un-endpoint "Enlace directo al Creando un Endpoint") Al crear, el sistema genera automáticamente un **secreto** (`whsec_...`) que se muestra **solo en la creación**. Almacénelo de forma segura — es necesario para validar las firmas de los webhooks. ## Firma de los Webhooks[​](#firma-de-los-webhooks "Enlace directo al Firma de los Webhooks") Cada entrega lleva los headers estándar Kobana (`X-Kobana-App`, `X-Kobana-Environment`, `X-Kobana-Webhook-Id`, `X-Kobana-Event`, `X-Kobana-Event-Id`, `X-Kobana-Delivery-Id`, `X-Kobana-Timestamp`, `X-Kobana-Signature`) más el trío `webhook-id` / `webhook-timestamp` / `webhook-signature` en el layout Standard Webhooks: ``` X-Kobana-Signature: v1, ``` ### Verificación[​](#verificación "Enlace directo al Verificación") 1. Lee `webhook-id`, `webhook-timestamp` y `webhook-signature` 2. Rechaza si el timestamp está a más de 5 minutos de tu reloj 3. Reconstruye `delivery_id.timestamp.body_crudo` y calcula el HMAC-SHA256 con la clave (secret decodificado de base64 sin el prefijo `whsec_`) 4. Compara con cada token `v1,` del header en tiempo constante El algoritmo completo, con ejemplos en Node.js y Python, está en [Referencia de la API — Webhooks](https://docs.billing.kobana.com.br/es/es/api/overview/webhooks.md#headers-y-firma-est%C3%A1ndar-kobana). El header legado `X-Signature` (`t=,v1=`) se sigue enviando, deprecado. ## Rotación de Secreto[​](#rotación-de-secreto "Enlace directo al Rotación de Secreto") Cuando sospeche que el secreto fue comprometido, use la rotación de secreto. Un nuevo secreto se genera y el anterior se invalida inmediatamente. ## Prueba de Webhook[​](#prueba-de-webhook "Enlace directo al Prueba de Webhook") Envíe un payload de prueba para verificar si el endpoint está configurado correctamente. El resultado incluye el código HTTP y la respuesta recibida. ## Desactivación Automática[​](#desactivación-automática "Enlace directo al Desactivación Automática") Después de **10 fallos consecutivos** de entrega, el endpoint se **desactiva automáticamente**. Para reactivar, corrija el problema y actualice el endpoint a activo. ## Protección contra SSRF[​](#protección-contra-ssrf "Enlace directo al Protección contra SSRF") Las URLs se validan para rechazar IPs privadas y localhost, previniendo ataques de Server-Side Request Forgery. --- # Entregas de Webhook Cada notificación enviada a un endpoint se registra como una entrega, permitiendo monitoreo y reintento. ## Estado de la Entrega[​](#estado-de-la-entrega "Enlace directo al Estado de la Entrega") | Estado | Descripción | | ----------- | ------------------------------ | | `pending` | Esperando envío | | `delivered` | Entregado con éxito (HTTP 2xx) | | `failed` | Fallo en la entrega | | `retrying` | Esperando nuevo intento | ## Campos de la Entrega[​](#campos-de-la-entrega "Enlace directo al Campos de la Entrega") | Campo | Descripción | | --------------------------- | -------------------------------------------- | | **Endpoint** | Webhook de destino | | **Evento** | Evento que generó la entrega | | **Estado HTTP** | Código de respuesta del destino | | **Headers de la solicitud** | Headers enviados | | **Body de la solicitud** | Payload enviado (JSON) | | **Headers de la respuesta** | Headers recibidos | | **Body de la respuesta** | Cuerpo de la respuesta (máx 2000 caracteres) | | **Error** | Mensaje de error (si falló) | | **Intentos** | Número de intentos | | **Próximo reintento** | Fecha/hora del próximo intento | | **Entregado en** | Timestamp de éxito | ## Pipeline de Procesamiento[​](#pipeline-de-procesamiento "Enlace directo al Pipeline de Procesamiento") ### Etapa 1: Creación del Evento[​](#etapa-1-creación-del-evento "Enlace directo al Etapa 1: Creación del Evento") ``` Operación en el recurso (ej: pago creado) → Evento creado en la base de datos → Job encolado: EVENT_DISPATCH ``` ### Etapa 2: Despacho del Evento[​](#etapa-2-despacho-del-evento "Enlace directo al Etapa 2: Despacho del Evento") ``` Worker procesa EVENT_DISPATCH → Busca webhooks activos de la organización → Filtra por eventos suscritos → Para cada webhook correspondiente: → Crea registro de WebhookDelivery → Encola job: WEBHOOK_DELIVERY ``` ### Etapa 3: Entrega[​](#etapa-3-entrega "Enlace directo al Etapa 3: Entrega") ``` Worker procesa WEBHOOK_DELIVERY → Genera payload + firma → POST a URL del webhook (timeout: 30s) → Éxito (2xx): marca como delivered, reinicia contador de fallos → Fallo: actualiza stats, programa reintento → Después de 10 fallos consecutivos: desactiva endpoint ``` ## Reintento Automático[​](#reintento-automático "Enlace directo al Reintento Automático") * Las entregas fallidas se reintentan automáticamente * Backoff exponencial (1s, 2s, 4s, 8s...) * Máximo de intentos configurable por job ## Reintento Manual[​](#reintento-manual "Enlace directo al Reintento Manual") Las entregas individuales pueden reintentarse manualmente desde el dashboard. ## Monitoreo[​](#monitoreo "Enlace directo al Monitoreo") Para cada organización: * Total de webhooks activos/inactivos * Total de entregas * Entregas con fallo * Contadores de fallos consecutivos --- # Eventos de Webhook El sistema emite eventos para todas las operaciones significativas. Cada organización puede suscribirse a los tipos relevantes. ## Formato del Payload[​](#formato-del-payload "Enlace directo al Formato del Payload") ``` { "id": "9f8b2c14-3a5d-4e77-9b10-2c6e5f0a1d33", "type": "payment.succeeded", "created_at": "2026-04-05T10:30:00.000Z", "data": { }, "changes": { "status": { "from": "open", "to": "paid" } }, "environment": "production", "version": "2026-03-01" } ``` * `id` es el UUID del evento y `created_at` es ISO 8601 (UTC). Todos los campos del envelope usan `snake_case`. * `data` trae el recurso serializado en el mismo formato de la API v1, también en `snake_case`. * `changes` es opcional: aparece en los eventos que cargan cambios de campos (`.db.updated` y `*.status_changed`), en el formato `{"campo": {"from": valorAnterior, "to": valorNuevo}}`. ## Tipos de Eventos[​](#tipos-de-eventos "Enlace directo al Tipos de Eventos") ### Suscripciones (11 tipos)[​](#suscripciones-11-tipos "Enlace directo al Suscripciones (11 tipos)") | Evento | Descripción | | ----------------------------- | ----------------------- | | `subscription.db.created` | Suscripción creada | | `subscription.db.updated` | Suscripción actualizada | | `subscription.db.deleted` | Suscripción eliminada | | `subscription.status_changed` | Estado alterado | | `subscription.canceled` | Cancelada | | `subscription.paused` | Pausada | | `subscription.resumed` | Reanudada | | `subscription.renewed` | Renovada | | `subscription.trial_ending` | Trial próximo a expirar | | `subscription.past_due` | En mora | ### Facturas (10 tipos)[​](#facturas-10-tipos "Enlace directo al Facturas (10 tipos)") | Evento | Descripción | | ------------------------ | ----------------------- | | `invoice.db.created` | Factura creada | | `invoice.db.updated` | Factura actualizada | | `invoice.db.deleted` | Factura eliminada | | `invoice.status_changed` | Estado alterado | | `invoice.finalized` | Finalizada | | `invoice.paid` | Pagada | | `invoice.payment_failed` | Pago falló | | `invoice.voided` | Anulada | | `invoice.uncollectible` | Marcada como incobrable | | `invoice.overdue` | Vencida | ### Pagos (8 tipos)[​](#pagos-8-tipos "Enlace directo al Pagos (8 tipos)") | Evento | Descripción | | ------------------------ | ---------------- | | `payment.db.created` | Pago creado | | `payment.db.updated` | Pago actualizado | | `payment.db.deleted` | Pago eliminado | | `payment.status_changed` | Estado alterado | | `payment.processing` | En procesamiento | | `payment.succeeded` | Exitoso | | `payment.failed` | Falló | | `payment.refunded` | Reembolsado | ### Métodos de Pago (5 tipos)[​](#métodos-de-pago-5-tipos "Enlace directo al Métodos de Pago (5 tipos)") | Evento | Descripción | | ------------------------------- | ------------------ | | `payment_method.db.created` | Método creado | | `payment_method.db.updated` | Método actualizado | | `payment_method.db.deleted` | Método eliminado | | `payment_method.status_changed` | Estado alterado | | `payment_method.expired` | Expirado | ### Planes (4 tipos)[​](#planes-4-tipos "Enlace directo al Planes (4 tipos)") | Evento | Descripción | | ----------------- | ---------------- | | `plan.db.created` | Plan creado | | `plan.db.updated` | Plan actualizado | | `plan.db.deleted` | Plan eliminado | | `plan.archived` | Plan archivado | ### Productos (6 tipos)[​](#productos-6-tipos "Enlace directo al Productos (6 tipos)") | Evento | Descripción | | ------------------------ | -------------------- | | `product.db.created` | Producto creado | | `product.db.updated` | Producto actualizado | | `product.db.deleted` | Producto eliminado | | `product.status_changed` | Estado alterado | | `product.archived` | Archivado | | `product.restored` | Restaurado | ### Cuentas de Cobro (5 tipos)[​](#cuentas-de-cobro-5-tipos "Enlace directo al Cuentas de Cobro (5 tipos)") | Evento | Descripción | | -------------------------------- | ------------------ | | `billing_account.db.created` | Cuenta creada | | `billing_account.db.updated` | Cuenta actualizada | | `billing_account.db.deleted` | Cuenta eliminada | | `billing_account.status_changed` | Estado alterado | | `billing_account.suspended` | Cuenta suspendida | ### Empresa, Clientes y Otros[​](#empresa-clientes-y-otros "Enlace directo al Empresa, Clientes y Otros") * `company.db.created` / `db.updated` / `db.deleted` / `status_changed` * `customer.db.created` / `db.updated` / `db.deleted` **Total: 56 tipos de eventos** --- # Facturación Automática — Documentación ![Panel de Primeros Pasos de Facturación Automática](/img/screenshots/es/primeiros-passos.png) Bienvenido a la documentación de Facturación Automática, la plataforma B2B2C de facturación, suscripciones y cobro recurrente para el mercado brasileño. ## Primeros Pasos[​](#primeros-pasos "Enlace directo al Primeros Pasos") Facturación Automática permite que las organizaciones gestionen suscripciones, facturas, pagos y cumplimiento fiscal (NF-e, factura electrónica brasileña) de sus clientes a través de una plataforma completa con dashboard, portal del cliente y backoffice administrativo. ## Navegación[​](#navegación "Enlace directo al Navegación") ### Catálogo[​](#catálogo "Enlace directo al Catálogo") * [Planes y Productos](https://docs.billing.kobana.com.br/es/es/planos-e-produtos.md) — Gestione planes de suscripción, productos, precios y grupos ### Suscripciones[​](#suscripciones "Enlace directo al Suscripciones") * [Suscripciones](https://docs.billing.kobana.com.br/es/es/assinaturas.md) — Ciclo de vida, cambio de plan, pausar, términos de cobro ### Financiero[​](#financiero "Enlace directo al Financiero") * [Facturas y Pagos](https://docs.billing.kobana.com.br/es/es/faturas-e-pagamentos.md) — Facturas, pagos, métodos de pago, créditos y pago en cuotas * [Cupones y Descuentos](https://docs.billing.kobana.com.br/es/es/cupons-e-descontos.md) — Cupones promocionales y códigos de descuento * [Gestión de Morosidad](https://docs.billing.kobana.com.br/es/es/gestao-de-inadimplencia.md) — Dunning, intentos de pago, suspensión y recuperación ### Integraciones[​](#integraciones "Enlace directo al Integraciones") * [Gateways de Pago](https://docs.billing.kobana.com.br/es/es/gateways-de-pagamento.md) — Proveedores, configuración y callbacks * [Webhooks](https://docs.billing.kobana.com.br/es/es/webhooks.md) — Endpoints, eventos y entregas ### Fiscal[​](#fiscal "Enlace directo al Fiscal") * [Factura Electrónica](https://docs.billing.kobana.com.br/es/es/nota-fiscal.md) — Configuración, emisión automática y proveedores de NF-e (factura electrónica brasileña) * [Impuestos](https://docs.billing.kobana.com.br/es/es/impostos.md) — Motor de cálculo, reglas fiscales, retenciones y Simples Nacional ### Comercial[​](#comercial "Enlace directo al Comercial") * [Propuestas Comerciales](https://docs.billing.kobana.com.br/es/es/propostas.md) — Creación, envío y aceptación de propuestas ### Administración[​](#administración "Enlace directo al Administración") * [Cuentas](https://docs.billing.kobana.com.br/es/es/contas.md) — Organizaciones, cuentas de cobro, clientes y portal * [Exportación e Importación](https://docs.billing.kobana.com.br/es/es/exportacao-e-importacao.md) — Exportar e importar datos en masa * [Configuraciones](https://docs.billing.kobana.com.br/es/es/configuracoes.md) — Empresa, cobro, rate limiting, notificaciones y correos electrónicos ---