# Faturamento Automático — Documentação > Documentação completa: assinaturas, faturas, pagamentos, NF-e, gateways, dunning e portal do cliente. ## pt Bem-vindo à documentação do Faturamento Automático, a plataforma B2B2C de faturamento, assinaturas e cobrança recorrente para o mercado brasileiro. - [Faturamento Automático — Documentação](https://docs.billing.kobana.com.br/pt/index.md): Bem-vindo à documentação do Faturamento Automático, a plataforma B2B2C de faturamento, assinaturas e cobrança recorrente para o mercado brasileiro. ### search - [Buscar na documentação](https://docs.billing.kobana.com.br/pt/search.md) ### api - [Referência da API](https://docs.billing.kobana.com.br/pt/api.md) #### overview - [Autenticação](https://docs.billing.kobana.com.br/pt/api/overview/authentication.md): A API do Faturamento Automático usa um access token da Conta Kobana para autenticar todas as requisições. - [Retenção de Dados](https://docs.billing.kobana.com.br/pt/api/overview/data-retention.md): Esta página descreve por quanto tempo cada tipo de dado é mantido no Faturamento Automático. - [Endpoints](https://docs.billing.kobana.com.br/pt/api/overview/endpoints.md): Plataforma (acesso web) - [Idempotência](https://docs.billing.kobana.com.br/pt/api/overview/idempotency.md): A API suporta idempotência para repetir solicitações com segurança, sem executar a mesma operação duas vezes. Útil quando uma chamada é interrompida em trânsito e você não recebe resposta — por exemplo, uma requisição para criar uma assinatura que cai por erro de rede pode ser repetida com a mesma chave, garantindo que apenas uma assinatura seja criada. - [Introdução](https://docs.billing.kobana.com.br/pt/api/overview/introduction.md): Você que é dev, divirta-se! ✨ - [OpenAPI](https://docs.billing.kobana.com.br/pt/api/overview/openapi.md): Mantemos publicamente os arquivos de especificações da API do Faturamento Automático em formato aberto para que você possa baixar e usar na ferramenta de sua preferência. - [Listagem e Paginação](https://docs.billing.kobana.com.br/pt/api/overview/pagination.md): Todos os endpoints GET que retornam coleções (/v1/customers, /v1/subscriptions, /v1/invoices, etc.) usam paginação por número de página. - [Postman](https://docs.billing.kobana.com.br/pt/api/overview/postman.md): Se preferir testar a API pelo Postman, baixe a coleção no idioma de sua preferência e importe — ou abra a versão online direto no workspace público da Kobana. - [Limite de Requisições](https://docs.billing.kobana.com.br/pt/api/overview/rate-limit.md): Quando um cliente excede o limite associado a ele, as requisições seguintes são bloqueadas. - [User-Agent](https://docs.billing.kobana.com.br/pt/api/overview/user-agent.md): Você pode incluir o cabeçalho User-Agent com o nome da sua aplicação e um endereço de e-mail válido, para que possamos entrar em contato caso: - [Webhooks](https://docs.billing.kobana.com.br/pt/api/overview/webhooks.md): Webhooks são notificações HTTP enviadas pela API do Faturamento Automático sempre que um evento relevante ocorre na sua Organização — assinatura criada, fatura paga, NF-e emitida, etc. - [billing_account.suspended](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/billing-account-suspended.md): Disparado quando uma BillingAccount é suspensa por inadimplência ou ação manual do operador. - [company.db.updated](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/company-updated.md): Disparado a cada update em qualquer campo de uma empresa (Company). - [coupon.redeemed](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/coupon-redeemed.md): Disparado quando um cupom é resgatado em uma assinatura ou fatura. - [credit.applied](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/credit-applied.md): Disparado quando um crédito existente é aplicado em uma fatura, reduzindo o valor devido. - [customer.db.created](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/customer-created.md): Disparado quando um novo cliente (pessoa física ou jurídica) é cadastrado na Organização. - [invoice.paid](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/invoice-paid.md): Disparado quando uma fatura tem seu pagamento confirmado e seu status passa para paid. - [nfe.issued](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/nfe-issued.md): Disparado quando a NF-e é emitida com sucesso pelo provedor fiscal integrado. - [payment_method.expired](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/payment-method-expired.md): Disparado quando um método de pagamento expira (cartão vencido, mandato cancelado, etc.). - [payment.succeeded](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/payment-succeeded.md): Disparado quando um pagamento é confirmado pelo gateway com status succeeded. - [plan.db.updated](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/plan-updated.md): Disparado a cada update em qualquer campo de um Plano. - [product.archived](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/product-archived.md): Disparado quando um produto é arquivado e removido do catálogo ativo. - [proposal.accepted](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/proposal-accepted.md): Disparado quando o cliente aceita uma proposta comercial enviada. - [service_item.db.updated](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/service-item-updated.md): Disparado a cada update em itens de serviço (códigos de CNAE, ISS, descrição fiscal). - [subscription.status_changed](https://docs.billing.kobana.com.br/pt/api/overview/webhooks/subscription-status-changed.md): Disparado sempre que o status de uma assinatura muda (active, trialing, past_due, paused, canceled). ### assinaturas - [Assinaturas](https://docs.billing.kobana.com.br/pt/assinaturas.md) #### ciclo-de-vida Estados - [Ciclo de Vida da Assinatura](https://docs.billing.kobana.com.br/pt/assinaturas/ciclo-de-vida.md): Estados #### mudanca-de-plano O sistema permite que clientes alterem o plano da assinatura com cálculo automático de proration (rateio proporcional). - [Mudança de Plano (Upgrade/Downgrade)](https://docs.billing.kobana.com.br/pt/assinaturas/mudanca-de-plano.md): O sistema permite que clientes alterem o plano da assinatura com cálculo automático de proration (rateio proporcional). #### mudancas-de-itens Além das mudanças de plano (upgrade/downgrade), o Faturamento Automático suporta mudanças nos itens individuais de uma assinatura — alterar quantidades, adicionar add-ons, trocar um produto avulso ou um item metered sem precisar trocar o plano principal. A tela /dashboard/subscription-changes agrupa o histórico dessas mudanças e a configuração padrão de proration. - [Mudanças de Itens da Assinatura](https://docs.billing.kobana.com.br/pt/assinaturas/mudancas-de-itens.md): Além das mudanças de plano (upgrade/downgrade), o Faturamento Automático suporta mudanças nos itens individuais de uma assinatura — alterar quantidades, adicionar add-ons, trocar um produto avulso ou um item metered sem precisar trocar o plano principal. A tela /dashboard/subscription-changes agrupa o histórico dessas mudanças e a configuração padrão de proration. #### pausar-assinatura A funcionalidade de pausar assinaturas permite suspender temporariamente a cobrança de um cliente sem cancelar a assinatura. É uma ferramenta estratégica de retenção. - [Pausar Assinatura](https://docs.billing.kobana.com.br/pt/assinaturas/pausar-assinatura.md): A funcionalidade de pausar assinaturas permite suspender temporariamente a cobrança de um cliente sem cancelar a assinatura. É uma ferramenta estratégica de retenção. #### termos-de-cobranca Os termos de cobrança definem como e quando o cliente é cobrado pela assinatura. - [Termos de Cobrança](https://docs.billing.kobana.com.br/pt/assinaturas/termos-de-cobranca.md): Os termos de cobrança definem como e quando o cliente é cobrado pela assinatura. ### cli #### overview - [Autenticação](https://docs.billing.kobana.com.br/pt/cli/overview/authentication.md): KOBANA_TOKEN guarda a credencial de um produto por vez. Um token do Faturamento Automático não autentica em nenhum outro produto Kobana, e vice-versa. - [Variáveis de ambiente](https://docs.billing.kobana.com.br/pt/cli/overview/environment-variables.md): Todas as variáveis também podem ser definidas em um arquivo .env (carregado via dotenvy). - [Códigos de saída](https://docs.billing.kobana.com.br/pt/cli/overview/exit-codes.md): Toda execução do kobana termina com um destes códigos, para que um script decida o que fazer sem precisar interpretar o corpo JSON do erro. - [Instalação](https://docs.billing.kobana.com.br/pt/cli/overview/installation.md): Homebrew (macOS e Linux) - [Introdução](https://docs.billing.kobana.com.br/pt/cli/overview/introduction.md): kobana é uma ferramenta de linha de comando única para as APIs de todos os produtos Kobana — o Faturamento Automático incluído. Ela é construída e mantida em repositório próprio (kobana-cli), não por este produto, e não tem endpoint algum escrito à mão: na inicialização ela lê as specs OpenAPI 3.1 embutidas no binário e monta a árvore de comandos a partir delas. Atualizar a superfície da API é questão de atualizar a spec embutida e publicar um build novo — nenhum código por endpoint. #### resources - [Contas de cobrança](https://docs.billing.kobana.com.br/pt/cli/resources/billing-accounts.md): A conta que acumula assinaturas, faturas e créditos de um cliente. Suspender interrompe a cobrança sem encerrar o relacionamento; fechar encerra. - [Certificados digitais](https://docs.billing.kobana.com.br/pt/cli/resources/certificates.md): Os certificados A1 usados para assinar a emissão fiscal. O arquivo é enviado uma vez e nunca volta na resposta. - [Empresas](https://docs.billing.kobana.com.br/pt/cli/resources/companies.md): As empresas emissoras — quem cobra. Carregam o perfil fiscal usado na emissão de nota, e uma delas é a padrão. - [Cupons](https://docs.billing.kobana.com.br/pt/cli/resources/coupons.md): Descontos com regra de validade e limite de uso. redemptions mostra onde cada cupom foi efetivamente aplicado. - [Créditos](https://docs.billing.kobana.com.br/pt/cli/resources/credits.md): Saldo a favor do cliente, aplicável a faturas futuras. Aplicar e remover créditos são comandos da própria fatura. - [Clientes](https://docs.billing.kobana.com.br/pt/cli/resources/customers.md): Quem é cobrado, seus usuários de portal e o extrato consolidado. recalculate-mrr recalcula a receita recorrente do cliente. - [Usuários do painel](https://docs.billing.kobana.com.br/pt/cli/resources/dashboard-users.md): Quem tem acesso ao painel da sua organização — os operadores, não os clientes. - [Faturas](https://docs.billing.kobana.com.br/pt/cli/resources/invoices.md): O documento a cobrar, do rascunho ao pago. finalize sela o rascunho, pay registra a liquidação, void anula, e as parcelas vivem em installments. - [Notas fiscais](https://docs.billing.kobana.com.br/pt/cli/resources/nfes.md): A emissão fiscal de uma fatura: emitir, cancelar, baixar PDF e XML, e acompanhar cada tentativa junto à prefeitura. Barueri tem comandos próprios. - [Organização](https://docs.billing.kobana.com.br/pt/cli/resources/organization.md): As configurações no topo da hierarquia, comuns a todas as empresas da conta. - [Recursos](https://docs.billing.kobana.com.br/pt/cli/resources/overview.md): Todo recurso de billing abaixo é gerado a partir da mesma spec OpenAPI documentada na Referência da API — o CLI chama exatamente os mesmos endpoints, então filtros, validação e comportamento de exclusão são idênticos. Recorra à introspecção de schema sempre que os parâmetros exatos de um comando não estiverem óbvios nos exemplos destas páginas. - [Meios de pagamento](https://docs.billing.kobana.com.br/pt/cli/resources/payment-methods.md): Os cartões e demais meios salvos de um cliente, e qual deles é o padrão. - [Pagamentos](https://docs.billing.kobana.com.br/pt/cli/resources/payments.md): As tentativas de liquidação de uma fatura: retentativa, troca de cartão, mudança de vencimento, estorno e reenvio do e-mail de cobrança. - [Mudanças de plano](https://docs.billing.kobana.com.br/pt/cli/resources/plan-changes.md): Upgrades e downgrades: as regras que definem o que pode virar o quê, a configuração do proporcional e as estatísticas do que foi trocado. - [Grupos de planos](https://docs.billing.kobana.com.br/pt/cli/resources/plan-groups.md): A prateleira em que os planos são exibidos e ordenados. reorder muda a ordem; archive tira o grupo de circulação sem apagá-lo. - [Planos](https://docs.billing.kobana.com.br/pt/cli/resources/plans.md): O que se assina: preço, periodicidade e a lista de itens que o plano entrega. As operações bulk-* agem sobre vários planos de uma vez. - [Grupos de produtos](https://docs.billing.kobana.com.br/pt/cli/resources/product-groups.md): O agrupamento do catálogo de produtos, com ordenação e arquivamento próprios. - [Produtos](https://docs.billing.kobana.com.br/pt/cli/resources/products.md): O catálogo do que se cobra, item a item, antes de virar plano ou item de fatura. Publicar, arquivar e restaurar controlam a visibilidade sem destruir histórico. - [Modelos de proposta](https://docs.billing.kobana.com.br/pt/cli/resources/proposal-templates.md): Os modelos de onde as propostas nascem, com um marcado como padrão. - [Propostas](https://docs.billing.kobana.com.br/pt/cli/resources/proposals.md): O orçamento antes da assinatura: publicar, enviar, gerar PDF e aceitar. Aceitar é o que converte a proposta em assinatura — e undo-accept desfaz. - [Itens de serviço](https://docs.billing.kobana.com.br/pt/cli/resources/service-items.md): Os serviços da lista municipal usados para descrever o que a nota fiscal está cobrando. - [Mudanças de assinatura](https://docs.billing.kobana.com.br/pt/cli/resources/subscription-changes.md): A configuração de como mudanças de assinatura são aplicadas — imediatamente, no próximo ciclo, com ou sem proporcional. - [Mudanças de itens](https://docs.billing.kobana.com.br/pt/cli/resources/subscription-item-changes.md): O histórico de alterações nos itens de uma assinatura, e o cancelamento de uma mudança ainda agendada. - [Assinaturas](https://docs.billing.kobana.com.br/pt/cli/resources/subscriptions.md): O contrato vivo entre um cliente e um plano: ativar, pausar, retomar, trocar de plano e cancelar. create-invoice força uma fatura fora do ciclo. - [Períodos fiscais](https://docs.billing.kobana.com.br/pt/cli/resources/tax-periods.md): As competências fiscais que agrupam as notas emitidas. - [Regras de imposto](https://docs.billing.kobana.com.br/pt/cli/resources/tax-rules.md): Que tributo incide sobre o quê, e com qual alíquota — o que a emissão de nota consulta. - [Papéis de equipe](https://docs.billing.kobana.com.br/pt/cli/resources/team-roles.md): Os papéis que definem o que cada usuário do painel pode fazer. - [Consumo](https://docs.billing.kobana.com.br/pt/cli/resources/usage.md): Os eventos de consumo que alimentam a cobrança por uso, com fotografias diárias e mensais e um resumo consolidado. - [Retenções](https://docs.billing.kobana.com.br/pt/cli/resources/withholdings.md): Os valores retidos na fonte pelo cliente, que podem ser convertidos em crédito. #### usage - [Flags globais](https://docs.billing.kobana.com.br/pt/cli/usage/global-flags.md): | Flag | Descrição | - [Helpers](https://docs.billing.kobana.com.br/pt/cli/usage/helpers.md): Helpers são comandos prefixados com + que entregam fluxos de vários passos que os comandos dinâmicos sozinhos não dão: interfaces simplificadas, operações em lote ou chamadas compostas por vários endpoints. Eles não embrulham uma única chamada de API já disponível pelos comandos dinâmicos — cada flag de helper controla lógica de orquestração, não uma versão remodelada de --params/--json. - [Uso](https://docs.billing.kobana.com.br/pt/cli/usage/overview.md): Sintaxe - [Introspecção de schema](https://docs.billing.kobana.com.br/pt/cli/usage/schema.md): Devolve parâmetros, campos obrigatórios, tipos e respostas — tudo derivado da spec OpenAPI embutida, então está sempre em sincronia com o que o comando de fato aceita. O caminho segue a mesma forma do comando: ... ### configuracoes - [Configurações](https://docs.billing.kobana.com.br/pt/configuracoes.md) #### analytics A área de Analytics (/dashboard/analytics) traduz os dados operacionais do faturamento em métricas SaaS consumíveis pelo time de finanças e produto: MRR, ARR, churn, LTV, ARPU, retenção por coorte e funil de cobrança. - [Analytics](https://docs.billing.kobana.com.br/pt/configuracoes/analytics.md): A área de Analytics (/dashboard/analytics) traduz os dados operacionais do faturamento em métricas SaaS consumíveis pelo time de finanças e produto: MRR, ARR, churn, LTV, ARPU, retenção por coorte e funil de cobrança. #### api-keys Em /dashboard/api a organização gerencia as chaves de API. Cada chave - [API Keys](https://docs.billing.kobana.com.br/pt/configuracoes/api-keys.md): Em /dashboard/api a organização gerencia as chaves de API. Cada chave #### auditoria A trilha de auditoria (/dashboard/audit) registra toda alteração de dados feita no dashboard ou via API. Cada entrada captura quem fez, o que foi alterado, valores antes e depois, IP, User-Agent e horário, formando um histórico imutável para compliance, debug e análise de incidentes. - [Auditoria](https://docs.billing.kobana.com.br/pt/configuracoes/auditoria.md): A trilha de auditoria (/dashboard/audit) registra toda alteração de dados feita no dashboard ou via API. Cada entrada captura quem fez, o que foi alterado, valores antes e depois, IP, User-Agent e horário, formando um histórico imutável para compliance, debug e análise de incidentes. #### configuracoes-de-cobranca Configurações que afetam a precificação e comportamento de cobrança da organização. - [Configurações de Cobrança](https://docs.billing.kobana.com.br/pt/configuracoes/configuracoes-de-cobranca.md): Configurações que afetam a precificação e comportamento de cobrança da organização. #### empresa Empresas representam as entidades jurídicas que emitem faturas e notas fiscais. Uma organização pode ter múltiplas empresas (matriz e filiais). - [Empresa (Entidade Fiscal)](https://docs.billing.kobana.com.br/pt/configuracoes/empresa.md): Empresas representam as entidades jurídicas que emitem faturas e notas fiscais. Uma organização pode ter múltiplas empresas (matriz e filiais). #### eventos A tela de eventos (/dashboard/events) expõe o stream interno de eventos de domínio gerados pelo sistema toda vez que um estado relevante muda — invoice.created, payment.succeeded, subscription.canceled, nfe.issued e dezenas de outros. É a mesma fila que alimenta os Webhooks e o histórico do cliente no portal. - [Eventos](https://docs.billing.kobana.com.br/pt/configuracoes/eventos.md): A tela de eventos (/dashboard/events) expõe o stream interno de eventos de domínio gerados pelo sistema toda vez que um estado relevante muda — invoice.created, payment.succeeded, subscription.canceled, nfe.issued e dezenas de outros. É a mesma fila que alimenta os Webhooks e o histórico do cliente no portal. #### feriados Os feriados são os dias em que os bancos não funcionam. Servem a dois propósitos: - [Feriados](https://docs.billing.kobana.com.br/pt/configuracoes/feriados.md): Os feriados são os dias em que os bancos não funcionam. Servem a dois propósitos: #### membros A página de membros (/dashboard/members) lista todas as pessoas com acesso ao dashboard da organização. Cada membro tem um e-mail vinculado à autenticação Kobana e um ou mais papéis que definem o que pode ver e modificar. - [Membros e Papéis](https://docs.billing.kobana.com.br/pt/configuracoes/membros.md): A página de membros (/dashboard/members) lista todas as pessoas com acesso ao dashboard da organização. Cada membro tem um e-mail vinculado à autenticação Kobana e um ou mais papéis que definem o que pode ver e modificar. #### notificacoes O sistema de notificações envia comunicações multicanal para clientes sobre eventos importantes. - [Notificações](https://docs.billing.kobana.com.br/pt/configuracoes/notificacoes.md): O sistema de notificações envia comunicações multicanal para clientes sobre eventos importantes. #### perfil A página /dashboard/profile reúne as preferências pessoais do operador logado: tema, idioma, fuso horário e configurações de notificação. Diferente das configurações da organização (que afetam todos os membros), as preferências de perfil são por usuário e ficam armazenadas localmente e no servidor. - [Perfil do Usuário](https://docs.billing.kobana.com.br/pt/configuracoes/perfil.md): A página /dashboard/profile reúne as preferências pessoais do operador logado: tema, idioma, fuso horário e configurações de notificação. Diferente das configurações da organização (que afetam todos os membros), as preferências de perfil são por usuário e ficam armazenadas localmente e no servidor. #### rate-limiting O sistema implementa limites de requisições da API para proteger a plataforma e garantir uso justo. - [Rate Limiting](https://docs.billing.kobana.com.br/pt/configuracoes/rate-limiting.md): O sistema implementa limites de requisições da API para proteger a plataforma e garantir uso justo. #### relatorios A central de relatórios (/dashboard/reports) é o lugar onde times de finanças, operações e atendimento geram extrações tabulares dos dados da organização. Diferente de Analytics, que agrega métricas, os relatórios entregam dados linha-a-linha prontos para conciliar, auditar ou compor planilhas externas. - [Relatórios](https://docs.billing.kobana.com.br/pt/configuracoes/relatorios.md): A central de relatórios (/dashboard/reports) é o lugar onde times de finanças, operações e atendimento geram extrações tabulares dos dados da organização. Diferente de Analytics, que agrega métricas, os relatórios entregam dados linha-a-linha prontos para conciliar, auditar ou compor planilhas externas. #### templates-de-email Templates de e-mail permitem personalizar as comunicações transacionais enviadas aos clientes. - [Templates de E-mail](https://docs.billing.kobana.com.br/pt/configuracoes/templates-de-email.md): Templates de e-mail permitem personalizar as comunicações transacionais enviadas aos clientes. #### uso A tela /dashboard/usage consolida o consumo medido (metered) de todos os clientes da organização: eventos de API, mensagens enviadas, transações processadas, armazenamento — qualquer métrica que o catálogo defina como "uso" e que seja cobrada por consumo. - [Uso e Consumo](https://docs.billing.kobana.com.br/pt/configuracoes/uso.md): A tela /dashboard/usage consolida o consumo medido (metered) de todos os clientes da organização: eventos de API, mensagens enviadas, transações processadas, armazenamento — qualquer métrica que o catálogo defina como "uso" e que seja cobrada por consumo. #### usuarios A página /dashboard/users lista os usuários do portal do cliente — pessoas físicas vinculadas a uma conta de cobrança (BillingAccount) que conseguem entrar no portal para ver faturas, pagar boletos, gerenciar cartões e atualizar dados. - [Usuários](https://docs.billing.kobana.com.br/pt/configuracoes/usuarios.md): A página /dashboard/users lista os usuários do portal do cliente — pessoas físicas vinculadas a uma conta de cobrança (BillingAccount) que conseguem entrar no portal para ver faturas, pagar boletos, gerenciar cartões e atualizar dados. ### contas - [Contas](https://docs.billing.kobana.com.br/pt/contas.md) #### clientes Clientes são representados pelo modelo Pessoa (Person) com diferentes tipos conforme o contexto. - [Clientes (Pessoas)](https://docs.billing.kobana.com.br/pt/contas/clientes.md): Clientes são representados pelo modelo Pessoa (Person) com diferentes tipos conforme o contexto. #### contas-de-cobranca Contas de cobrança (BillingAccount) representam o relacionamento financeiro entre uma organização e seu cliente. Cada conta possui assinaturas, faturas, pagamentos e métodos de pagamento. - [Contas de Cobrança](https://docs.billing.kobana.com.br/pt/contas/contas-de-cobranca.md): Contas de cobrança (BillingAccount) representam o relacionamento financeiro entre uma organização e seu cliente. Cada conta possui assinaturas, faturas, pagamentos e métodos de pagamento. #### empresas Em /dashboard/companies a organização cadastra as pessoas jurídicas emissoras — empresas que assinam contratos, faturas e NF-e. Uma organização pode ter várias empresas (matriz, filiais ou CNPJs diferentes do mesmo grupo) e definir uma como padrão para cobranças. - [Empresas](https://docs.billing.kobana.com.br/pt/contas/empresas.md): Em /dashboard/companies a organização cadastra as pessoas jurídicas emissoras — empresas que assinam contratos, faturas e NF-e. Uma organização pode ter várias empresas (matriz, filiais ou CNPJs diferentes do mesmo grupo) e definir uma como padrão para cobranças. #### organizacoes Organizações são os tenants (inquilinos) da plataforma. Cada organização é um negócio que usa o Faturamento Automático para cobrar seus próprios clientes. - [Organizações](https://docs.billing.kobana.com.br/pt/contas/organizacoes.md): Organizações são os tenants (inquilinos) da plataforma. Cada organização é um negócio que usa o Faturamento Automático para cobrar seus próprios clientes. #### portal-do-cliente O portal do cliente permite que os clientes finais de cada organização gerenciem suas assinaturas, faturas e métodos de pagamento de forma autônoma. - [Portal do Cliente](https://docs.billing.kobana.com.br/pt/contas/portal-do-cliente.md): O portal do cliente permite que os clientes finais de cada organização gerenciem suas assinaturas, faturas e métodos de pagamento de forma autônoma. ### cupons-e-descontos - [Cupons e Descontos](https://docs.billing.kobana.com.br/pt/cupons-e-descontos.md) #### codigos-de-desconto Códigos de desconto são aplicados diretamente a assinaturas no momento da criação, oferecendo descontos recorrentes ou pontuais. - [Códigos de Desconto](https://docs.billing.kobana.com.br/pt/cupons-e-descontos/codigos-de-desconto.md): Códigos de desconto são aplicados diretamente a assinaturas no momento da criação, oferecendo descontos recorrentes ou pontuais. #### cupons Cupons são códigos promocionais que os clientes podem resgatar para obter descontos em compras e faturas. - [Cupons](https://docs.billing.kobana.com.br/pt/cupons-e-descontos/cupons.md): Cupons são códigos promocionais que os clientes podem resgatar para obter descontos em compras e faturas. ### docs-mcp Esta documentação tem um servidor MCP próprio. Com ele, um assistente de IA - [MCP da Documentação](https://docs.billing.kobana.com.br/pt/docs-mcp.md): Esta documentação tem um servidor MCP próprio. Com ele, um assistente de IA ### exportacao-e-importacao - [Exportação e Importação](https://docs.billing.kobana.com.br/pt/exportacao-e-importacao.md) #### exportacoes Exporte dados da plataforma em diferentes formatos para relatórios e integrações. - [Exportações](https://docs.billing.kobana.com.br/pt/exportacao-e-importacao/exportacoes.md): Exporte dados da plataforma em diferentes formatos para relatórios e integrações. #### importacoes Importe dados em massa para a plataforma via upload de arquivos. - [Importações](https://docs.billing.kobana.com.br/pt/exportacao-e-importacao/importacoes.md): Importe dados em massa para a plataforma via upload de arquivos. ### faturas-e-pagamentos - [Faturas e Pagamentos](https://docs.billing.kobana.com.br/pt/faturas-e-pagamentos.md) #### creditos O sistema de créditos permite adicionar saldo na conta do cliente que é automaticamente aplicado em faturas futuras. - [Créditos](https://docs.billing.kobana.com.br/pt/faturas-e-pagamentos/creditos.md): O sistema de créditos permite adicionar saldo na conta do cliente que é automaticamente aplicado em faturas futuras. #### faturas Faturas representam cobranças enviadas aos clientes. Cada fatura contém line items detalhando os produtos e valores cobrados. - [Faturas](https://docs.billing.kobana.com.br/pt/faturas-e-pagamentos/faturas.md): Faturas representam cobranças enviadas aos clientes. Cada fatura contém line items detalhando os produtos e valores cobrados. #### metodos-de-pagamento Cada conta de cobrança pode ter múltiplos métodos de pagamento armazenados. Um deles é marcado como padrão para cobranças automáticas. - [Métodos de Pagamento](https://docs.billing.kobana.com.br/pt/faturas-e-pagamentos/metodos-de-pagamento.md): Cada conta de cobrança pode ter múltiplos métodos de pagamento armazenados. Um deles é marcado como padrão para cobranças automáticas. #### pagamentos Pagamentos representam tentativas de cobrança associadas a faturas. Cada pagamento rastreia o status, método, gateway utilizado e resposta do provedor. - [Pagamentos](https://docs.billing.kobana.com.br/pt/faturas-e-pagamentos/pagamentos.md): Pagamentos representam tentativas de cobrança associadas a faturas. Cada pagamento rastreia o status, método, gateway utilizado e resposta do provedor. #### parcelamento Faturas podem ser divididas em múltiplas parcelas com datas de vencimento individuais. - [Parcelamento](https://docs.billing.kobana.com.br/pt/faturas-e-pagamentos/parcelamento.md): Faturas podem ser divididas em múltiplas parcelas com datas de vencimento individuais. ### gateways-de-pagamento - [Gateways de Pagamento](https://docs.billing.kobana.com.br/pt/gateways-de-pagamento.md) #### callbacks Os provedores de gateway enviam notificações ao sistema quando o status de pagamentos muda. Essas notificações são processadas de forma assíncrona. - [Callbacks (Webhooks dos Provedores)](https://docs.billing.kobana.com.br/pt/gateways-de-pagamento/callbacks.md): Os provedores de gateway enviam notificações ao sistema quando o status de pagamentos muda. Essas notificações são processadas de forma assíncrona. #### configuracao Cada organização pode configurar múltiplos gateways e definir padrões por método de pagamento. - [Configuração de Gateways](https://docs.billing.kobana.com.br/pt/gateways-de-pagamento/configuracao.md): Cada organização pode configurar múltiplos gateways e definir padrões por método de pagamento. #### provedores O sistema suporta três provedores de pagamento, cada um com capacidades específicas. - [Provedores de Gateway](https://docs.billing.kobana.com.br/pt/gateways-de-pagamento/provedores.md): O sistema suporta três provedores de pagamento, cada um com capacidades específicas. ### gestao-de-inadimplencia - [Gestão de Inadimplência](https://docs.billing.kobana.com.br/pt/gestao-de-inadimplencia.md) #### configuracao-de-dunning A configuração de dunning define como o sistema trata pagamentos em atraso: quantas tentativas, intervalo entre elas e comportamento após esgotamento. - [Configuração de Dunning](https://docs.billing.kobana.com.br/pt/gestao-de-inadimplencia/configuracao-de-dunning.md): A configuração de dunning define como o sistema trata pagamentos em atraso: quantas tentativas, intervalo entre elas e comportamento após esgotamento. #### juros-e-multa Uma fatura vencida pode acumular multa (cobrada uma única vez) e juros de mora (que correm por dia de atraso). A política de juros e multa define esses valores, e vale para toda a organização — com a possibilidade de trocar por cliente, por assinatura ou por fatura. - [Juros e Multa](https://docs.billing.kobana.com.br/pt/gestao-de-inadimplencia/juros-e-multa.md): Uma fatura vencida pode acumular multa (cobrada uma única vez) e juros de mora (que correm por dia de atraso). A política de juros e multa define esses valores, e vale para toda a organização — com a possibilidade de trocar por cliente, por assinatura ou por fatura. #### recuperacao-de-receita O sistema rastreia toda receita recuperada via dunning para análise de eficiência. - [Recuperação de Receita](https://docs.billing.kobana.com.br/pt/gestao-de-inadimplencia/recuperacao-de-receita.md): O sistema rastreia toda receita recuperada via dunning para análise de eficiência. #### suspensao Contas inadimplentes são automaticamente suspensas quando o período de carência é excedido. - [Suspensão de Contas](https://docs.billing.kobana.com.br/pt/gestao-de-inadimplencia/suspensao.md): Contas inadimplentes são automaticamente suspensas quando o período de carência é excedido. #### tentativas-de-pagamento O sistema de retry processa automaticamente tentativas de cobrança para faturas em atraso. - [Tentativas de Pagamento (Payment Retry)](https://docs.billing.kobana.com.br/pt/gestao-de-inadimplencia/tentativas-de-pagamento.md): O sistema de retry processa automaticamente tentativas de cobrança para faturas em atraso. ### getting-started A página Getting Started (/dashboard/getting-started) é o ponto de partida para novas organizações. Ela apresenta uma sequência guiada das tarefas necessárias para começar a cobrar de forma recorrente: cadastrar a empresa, configurar gateways e NF-e, criar planos e produtos, importar clientes e ativar a primeira assinatura. - [Primeiros Passos](https://docs.billing.kobana.com.br/pt/getting-started.md): A página Getting Started (/dashboard/getting-started) é o ponto de partida para novas organizações. Ela apresenta uma sequência guiada das tarefas necessárias para começar a cobrar de forma recorrente: cadastrar a empresa, configurar gateways e NF-e, criar planos e produtos, importar clientes e ativar a primeira assinatura. ### impostos - [Impostos](https://docs.billing.kobana.com.br/pt/impostos.md) #### motor-de-calculo O motor de cálculo determina todos os impostos aplicáveis com base nas regras fiscais, perfil da empresa e tipo fiscal do cliente. - [Motor de Cálculo de Impostos](https://docs.billing.kobana.com.br/pt/impostos/motor-de-calculo.md): O motor de cálculo determina todos os impostos aplicáveis com base nas regras fiscais, perfil da empresa e tipo fiscal do cliente. #### perfil-fiscal O perfil fiscal define a configuração tributária de cada empresa (entidade jurídica) da organização. - [Perfil Fiscal](https://docs.billing.kobana.com.br/pt/impostos/perfil-fiscal.md): O perfil fiscal define a configuração tributária de cada empresa (entidade jurídica) da organização. #### periodos-fiscais Períodos fiscais agregam as faturas para apuração mensal ou trimestral de impostos. - [Períodos Fiscais](https://docs.billing.kobana.com.br/pt/impostos/periodos-fiscais.md): Períodos fiscais agregam as faturas para apuração mensal ou trimestral de impostos. #### regras-fiscais Regras fiscais permitem configurar alíquotas de impostos com diferentes níveis de especificidade. - [Regras Fiscais](https://docs.billing.kobana.com.br/pt/impostos/regras-fiscais.md): Regras fiscais permitem configurar alíquotas de impostos com diferentes níveis de especificidade. #### relatorios-fiscais A área de relatórios fiscais (/dashboard/fiscal/reports) consolida as informações necessárias para fechamento contábil e geração de obrigações acessórias. Os dados são gerados a partir das faturas pagas, NF-e emitidas, retenções e períodos fiscais já fechados pela organização. - [Relatórios Fiscais](https://docs.billing.kobana.com.br/pt/impostos/relatorios-fiscais.md): A área de relatórios fiscais (/dashboard/fiscal/reports) consolida as informações necessárias para fechamento contábil e geração de obrigações acessórias. Os dados são gerados a partir das faturas pagas, NF-e emitidas, retenções e períodos fiscais já fechados pela organização. #### retencoes Retenções são impostos retidos pelo pagador (cliente) que devem ser rastreados, reportados e compensados. - [Retenções na Fonte](https://docs.billing.kobana.com.br/pt/impostos/retencoes.md): Retenções são impostos retidos pelo pagador (cliente) que devem ser rastreados, reportados e compensados. #### simples-nacional O sistema calcula automaticamente o DAS (Documento de Arrecadação do Simples Nacional) com base na receita e no anexo correto. - [Simples Nacional](https://docs.billing.kobana.com.br/pt/impostos/simples-nacional.md): O sistema calcula automaticamente o DAS (Documento de Arrecadação do Simples Nacional) com base na receita e no anexo correto. ### mcp #### overview - [Autenticação](https://docs.billing.kobana.com.br/pt/mcp/overview/authentication.md): O servidor MCP aceita um Bearer token no cabeçalho Authorization, e nada além disso — sem cookie, sem certificado de cliente. - [Clientes](https://docs.billing.kobana.com.br/pt/mcp/overview/clients.md): Qualquer cliente que fale Streamable HTTP MCP e saiba fazer o fluxo OAuth 2.1 do MCP consegue conectar. Você só informa a URL; o cliente descobre sozinho onde autenticar, abre o login da Kobana no navegador e guarda o token — veja Autenticação. - [Endpoints](https://docs.billing.kobana.com.br/pt/mcp/overview/endpoints.md): Servidor MCP - [Erros](https://docs.billing.kobana.com.br/pt/mcp/overview/errors.md): As falhas chegam por dois canais diferentes, e a distinção importa: um é requisição quebrada, o outro é algo que o modelo deve ler e reagir. - [Idempotência](https://docs.billing.kobana.com.br/pt/mcp/overview/idempotency.md): As tools que criam um recurso ou movem dinheiro aceitam um argumento opcional idempotency_key. Ele é enviado ao endpoint como o cabeçalho X-Idempotency-Key que a API REST já honra. - [Introdução](https://docs.billing.kobana.com.br/pt/mcp/overview/introduction.md): O servidor MCP do Faturamento Automático é um servidor Model Context Protocol remoto que expõe as operações da API pública — clientes, assinaturas, faturas, pagamentos, notas fiscais, propostas e consumo — como tools que um cliente de IA pode chamar. Você o conecta por URL; não há nada para instalar. - [Listagem, Ordenação e Campos](https://docs.billing.kobana.com.br/pt/mcp/overview/pagination.md): As tools _list usam a mesma paginação da API REST: por número de página*. - [Limite de Requisições](https://docs.billing.kobana.com.br/pt/mcp/overview/rate-limit.md): O servidor MCP compartilha os mesmos limites da API REST, contados por pessoa e organização — o sub e o org do token, não o token em si. - [Resources e prompts](https://docs.billing.kobana.com.br/pt/mcp/overview/resources-and-prompts.md): Além das tools, o servidor oferece três coisas que o cliente usa por conta própria: resources (documentos que o usuário anexa à conversa), prompts (roteiros prontos que o usuário escolhe) e completions (autocomplete dos argumentos dos dois). Na era 2026-07-28, ele também pede confirmação antes de rodar uma tool destrutiva. - [Transporte](https://docs.billing.kobana.com.br/pt/mcp/overview/transport.md): Streamable HTTP, stateless. Uma mensagem JSON-RPC 2.0 por POST, uma resposta JSON. Não há Mcp-Session-Id, não há resumabilidade e não há stream servidor→cliente: a aplicação roda várias réplicas, e toda operação longa já responde de imediato e termina num worker em segundo plano, não no canal MCP. #### tools - [Catálogo](https://docs.billing.kobana.com.br/pt/mcp/tools/catalog.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Clientes e acessos](https://docs.billing.kobana.com.br/pt/mcp/tools/customers.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Fiscal](https://docs.billing.kobana.com.br/pt/mcp/tools/fiscal.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Faturas e recebimentos](https://docs.billing.kobana.com.br/pt/mcp/tools/invoices.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Organização e schemas](https://docs.billing.kobana.com.br/pt/mcp/tools/organization.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Tools](https://docs.billing.kobana.com.br/pt/mcp/tools/overview.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Propostas](https://docs.billing.kobana.com.br/pt/mcp/tools/proposals.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Assinaturas](https://docs.billing.kobana.com.br/pt/mcp/tools/subscriptions.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} - [Consumo](https://docs.billing.kobana.com.br/pt/mcp/tools/usage.md): {/ Página gerada a partir do registry de tools. Os nomes, permissões e endpoints abaixo são os mesmos que tools/list devolve. /} ### nota-fiscal - [Nota Fiscal](https://docs.billing.kobana.com.br/pt/nota-fiscal.md) #### certificados A página /dashboard/certificates gerencia os certificados digitais A1 usados para assinar NF-e e se autenticar nos webservices das prefeituras. Cada certificado é vinculado a uma empresa cadastrada e fica armazenado de forma criptografada em repouso. - [Certificados Digitais](https://docs.billing.kobana.com.br/pt/nota-fiscal/certificados.md): A página /dashboard/certificates gerencia os certificados digitais A1 usados para assinar NF-e e se autenticar nos webservices das prefeituras. Cada certificado é vinculado a uma empresa cadastrada e fica armazenado de forma criptografada em repouso. #### configuracao Cada organização pode habilitar e configurar a emissão automática de notas fiscais. - [Configuração de NF-e](https://docs.billing.kobana.com.br/pt/nota-fiscal/configuracao.md): Cada organização pode habilitar e configurar a emissão automática de notas fiscais. #### emissao Estados da NF-e - [Emissão de NF-e](https://docs.billing.kobana.com.br/pt/nota-fiscal/emissao.md): Estados da NF-e #### provedores O sistema abstrai a comunicação com provedores de NF-e através de uma interface comum. - [Provedores de NF-e](https://docs.billing.kobana.com.br/pt/nota-fiscal/provedores.md): O sistema abstrai a comunicação com provedores de NF-e através de uma interface comum. #### tentativas O sistema implementa retry automático para emissões que falham. - [Tentativas e Retry de NF-e](https://docs.billing.kobana.com.br/pt/nota-fiscal/tentativas.md): O sistema implementa retry automático para emissões que falham. ### planos-e-produtos - [Planos e Produtos](https://docs.billing.kobana.com.br/pt/planos-e-produtos.md) #### grupos-de-planos Grupos de planos permitem organizar planos relacionados para facilitar a gestão e visualização no dashboard. - [Grupos de Planos](https://docs.billing.kobana.com.br/pt/planos-e-produtos/grupos-de-planos.md): Grupos de planos permitem organizar planos relacionados para facilitar a gestão e visualização no dashboard. #### grupos-de-produtos Grupos de produtos permitem categorizar produtos para facilitar a organização, filtros no dashboard e vinculação com templates de propostas. - [Grupos de Produtos](https://docs.billing.kobana.com.br/pt/planos-e-produtos/grupos-de-produtos.md): Grupos de produtos permitem categorizar produtos para facilitar a organização, filtros no dashboard e vinculação com templates de propostas. #### itens-de-servico Itens de serviço (/dashboard/service-items) são o catálogo de descrições fiscais usadas em faturas e NF-e de serviço. Cada item carrega informações que a prefeitura exige na hora da emissão: código municipal de serviço, código LC 116, código tributário nacional, alíquotas padrão de ISS, PIS, COFINS, IR, INSS, CSLL. - [Itens de Serviço](https://docs.billing.kobana.com.br/pt/planos-e-produtos/itens-de-servico.md): Itens de serviço (/dashboard/service-items) são o catálogo de descrições fiscais usadas em faturas e NF-e de serviço. Cada item carrega informações que a prefeitura exige na hora da emissão: código municipal de serviço, código LC 116, código tributário nacional, alíquotas padrão de ISS, PIS, COFINS, IR, INSS, CSLL. #### planos Planos são os modelos que definem como seus clientes serão cobrados. Cada plano agrupa produtos com preços específicos e configura ciclo de cobrança, período de trial e funcionalidades incluídas. - [Planos](https://docs.billing.kobana.com.br/pt/planos-e-produtos/planos.md): Planos são os modelos que definem como seus clientes serão cobrados. Cada plano agrupa produtos com preços específicos e configura ciclo de cobrança, período de trial e funcionalidades incluídas. #### precos Cada produto pode ter múltiplos preços, permitindo variantes por moeda, intervalo de cobrança ou modelo de precificação. Os preços são em grande parte imutáveis após criação — apenas nome e metadados podem ser alterados. Para mudar valores, desative o preço antigo e crie um novo. - [Preços e Modelos de Precificação](https://docs.billing.kobana.com.br/pt/planos-e-produtos/precos.md): Cada produto pode ter múltiplos preços, permitindo variantes por moeda, intervalo de cobrança ou modelo de precificação. Os preços são em grande parte imutáveis após criação — apenas nome e metadados podem ser alterados. Para mudar valores, desative o preço antigo e crie um novo. #### produtos Produtos representam os serviços ou recursos cobráveis da sua organização. Cada produto pode ter múltiplos preços e suporta hierarquia de um nível (produto raiz com filhos/add-ons). - [Produtos](https://docs.billing.kobana.com.br/pt/planos-e-produtos/produtos.md): Produtos representam os serviços ou recursos cobráveis da sua organização. Cada produto pode ter múltiplos preços e suporta hierarquia de um nível (produto raiz com filhos/add-ons). ### portal - [Portal do Cliente](https://docs.billing.kobana.com.br/pt/portal.md) #### assinaturas A página /portal/subscriptions lista as assinaturas vinculadas à conta de cobrança autenticada. Cada linha mostra o plano, status, valor recorrente, próximo ciclo e ações disponíveis. - [Assinaturas](https://docs.billing.kobana.com.br/pt/portal/assinaturas.md): A página /portal/subscriptions lista as assinaturas vinculadas à conta de cobrança autenticada. Cada linha mostra o plano, status, valor recorrente, próximo ciclo e ações disponíveis. #### configuracoes A página /portal/settings agrupa preferências da conta de cobrança que afetam como o cliente recebe cobranças e comunicações. - [Configurações](https://docs.billing.kobana.com.br/pt/portal/configuracoes.md): A página /portal/settings agrupa preferências da conta de cobrança que afetam como o cliente recebe cobranças e comunicações. #### conta Em /portal/account o cliente gerencia os dados da conta de cobrança (BillingAccount) — razão social, CNPJ/CPF, inscrição estadual e municipal, endereço, contato financeiro e e-mails para envio de fatura. - [Conta](https://docs.billing.kobana.com.br/pt/portal/conta.md): Em /portal/account o cliente gerencia os dados da conta de cobrança (BillingAccount) — razão social, CNPJ/CPF, inscrição estadual e municipal, endereço, contato financeiro e e-mails para envio de fatura. #### creditos A página /portal/credits exibe o saldo de créditos da conta de cobrança e o histórico de aplicações. Créditos surgem por diversos motivos — proration de downgrade, estorno de fatura, ajuste manual da organização, promoção — e são automaticamente aplicados nas próximas faturas. - [Créditos](https://docs.billing.kobana.com.br/pt/portal/creditos.md): A página /portal/credits exibe o saldo de créditos da conta de cobrança e o histórico de aplicações. Créditos surgem por diversos motivos — proration de downgrade, estorno de fatura, ajuste manual da organização, promoção — e são automaticamente aplicados nas próximas faturas. #### faturas A página /portal/invoices lista todas as faturas da conta de cobrança, com filtros por status e período. O cliente pode visualizar, baixar PDF, copiar linha digitável ou QR Code PIX, pagar online e consultar NF-e relacionada. - [Faturas](https://docs.billing.kobana.com.br/pt/portal/faturas.md): A página /portal/invoices lista todas as faturas da conta de cobrança, com filtros por status e período. O cliente pode visualizar, baixar PDF, copiar linha digitável ou QR Code PIX, pagar online e consultar NF-e relacionada. #### metodos-de-pagamento Em /portal/payment-methods o cliente gerencia os meios de pagamento associados à conta de cobrança. A página suporta múltiplos métodos simultaneamente e define qual é o padrão para cobranças automáticas. - [Métodos de Pagamento](https://docs.billing.kobana.com.br/pt/portal/metodos-de-pagamento.md): Em /portal/payment-methods o cliente gerencia os meios de pagamento associados à conta de cobrança. A página suporta múltiplos métodos simultaneamente e define qual é o padrão para cobranças automáticas. #### pagamentos A página /portal/payments traz o histórico de pagamentos já processados na conta de cobrança — independente do método ou da fatura de origem. É a visão do extrato, útil para conferência contábil e dúvidas de cobrança. - [Pagamentos](https://docs.billing.kobana.com.br/pt/portal/pagamentos.md): A página /portal/payments traz o histórico de pagamentos já processados na conta de cobrança — independente do método ou da fatura de origem. É a visão do extrato, útil para conferência contábil e dúvidas de cobrança. #### perfil A página /portal/profile reúne as preferências pessoais do usuário logado no portal. Diferente de Conta, que cuida da pessoa jurídica/física pagadora, o perfil é por pessoa que usa o portal. - [Perfil](https://docs.billing.kobana.com.br/pt/portal/perfil.md): A página /portal/profile reúne as preferências pessoais do usuário logado no portal. Diferente de Conta, que cuida da pessoa jurídica/física pagadora, o perfil é por pessoa que usa o portal. #### produtos A página /portal/products é a vitrine self-service dos produtos e planos que a organização publicou para venda direta no portal. O cliente pode contratar novos produtos sem passar pelo time comercial, com checkout integrado aos métodos de pagamento já cadastrados. - [Produtos](https://docs.billing.kobana.com.br/pt/portal/produtos.md): A página /portal/products é a vitrine self-service dos produtos e planos que a organização publicou para venda direta no portal. O cliente pode contratar novos produtos sem passar pelo time comercial, com checkout integrado aos métodos de pagamento já cadastrados. #### propostas Em /portal/proposals o cliente vê as propostas comerciais enviadas pelo time da organização. Cada proposta detalha planos, itens, descontos, prazo e condições — e pode ser aceita diretamente no portal, transformando-se em assinatura ativa. - [Propostas](https://docs.billing.kobana.com.br/pt/portal/propostas.md): Em /portal/proposals o cliente vê as propostas comerciais enviadas pelo time da organização. Cada proposta detalha planos, itens, descontos, prazo e condições — e pode ser aceita diretamente no portal, transformando-se em assinatura ativa. #### uso A página /portal/usage mostra ao cliente o consumo medido acumulado no ciclo atual — quantas chamadas de API, mensagens enviadas, eventos processados ou GBs armazenados, conforme as métricas definidas pela organização. - [Uso](https://docs.billing.kobana.com.br/pt/portal/uso.md): A página /portal/usage mostra ao cliente o consumo medido acumulado no ciclo atual — quantas chamadas de API, mensagens enviadas, eventos processados ou GBs armazenados, conforme as métricas definidas pela organização. #### visao-geral A página inicial do portal (/portal) traz um resumo da relação financeira do cliente com a organização: assinatura ativa, próxima fatura, último pagamento, créditos disponíveis e atalhos para as ações mais comuns. - [Visão Geral](https://docs.billing.kobana.com.br/pt/portal/visao-geral.md): A página inicial do portal (/portal) traz um resumo da relação financeira do cliente com a organização: assinatura ativa, próxima fatura, último pagamento, créditos disponíveis e atalhos para as ações mais comuns. ### propostas - [Propostas](https://docs.billing.kobana.com.br/pt/propostas.md) #### geracao-de-pdf O sistema gera PDFs de propostas integrando com Google Docs/Slides via Google Apps Script. - [Geração de PDF](https://docs.billing.kobana.com.br/pt/propostas/geracao-de-pdf.md): O sistema gera PDFs de propostas integrando com Google Docs/Slides via Google Apps Script. #### propostas Propostas são documentos comerciais enviados a clientes ou prospects com itens, preços e condições de pagamento. - [Propostas](https://docs.billing.kobana.com.br/pt/propostas/propostas.md): Propostas são documentos comerciais enviados a clientes ou prospects com itens, preços e condições de pagamento. #### templates Templates definem o modelo de documento usado para gerar PDFs das propostas. - [Templates de Proposta](https://docs.billing.kobana.com.br/pt/propostas/templates.md): Templates definem o modelo de documento usado para gerar PDFs das propostas. ### webhooks - [Webhooks](https://docs.billing.kobana.com.br/pt/webhooks.md) #### endpoints Cada organização pode configurar múltiplos endpoints para receber notificações de eventos. - [Endpoints de Webhook](https://docs.billing.kobana.com.br/pt/webhooks/endpoints.md): Cada organização pode configurar múltiplos endpoints para receber notificações de eventos. #### entregas Cada notificação enviada a um endpoint é registrada como uma entrega, permitindo monitoramento e retry. - [Entregas de Webhook](https://docs.billing.kobana.com.br/pt/webhooks/entregas.md): Cada notificação enviada a um endpoint é registrada como uma entrega, permitindo monitoramento e retry. #### eventos O sistema emite eventos para todas as operações significativas. Cada organização pode se inscrever nos tipos relevantes. - [Eventos de Webhook](https://docs.billing.kobana.com.br/pt/webhooks/eventos.md): O sistema emite eventos para todas as operações significativas. Cada organização pode se inscrever nos tipos relevantes. --- # Full Documentation Content [Pular para o conteúdo principal](#__docusaurus_skipToContent_fallback) [![Kobana](/pt/img/kobana-logo-hor-positivo.png)![Kobana](/pt/img/kobana-logo-hor-negativo.png)](https://docs.billing.kobana.com.br/pt/pt/.md) [**Faturamento Automático**](https://docs.billing.kobana.com.br/pt/pt/.md) Documentação [Documentação](https://docs.billing.kobana.com.br/pt/pt/.md)[API](https://docs.billing.kobana.com.br/pt/pt/api/overview/introduction.md)[MCP](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/introduction.md)[CLI](https://docs.billing.kobana.com.br/pt/pt/cli/overview/introduction.md) Perguntar à IA [](#) * [🇧🇷 Português](https://docs.billing.kobana.com.br/pt/pt/search.md) * [🇺🇸 English](https://docs.billing.kobana.com.br/pt/en/search) * [🇪🇸 Español](https://docs.billing.kobana.com.br/pt/es/search) Buscar # Buscar na documentação ![Empresa Neutra em Carbono](/pt/img/badge-neutra-carbono.webp)![Empresa Parceira da Natureza](/pt/img/badge-parceira-natureza.webp) Comercial[3003-0386](tel:+551130030386) [](https://wa.me/551130030386)[](mailto:comercial@kobana.com.br) ![Kobana](/pt/img/kobana-logo-site.webp)![](/pt/img/kobana-cegonha.webp) © 2008/2026 Kobana Tecnologia Ltda. | CNPJ: 05.813.794/0001-26 | Calçada das Margaridas, 163, Sala 02 — Centro Comercial Alphaville — Barueri, SP — 06453-038 --- # Referência da API --- # Autenticação A API do Faturamento Automático usa um **access token da Conta Kobana** para autenticar todas as requisições. ## O token[​](#o-token "Link direto para O token") O token é um JWT `RS256` emitido pelo **Authorization Server da Kobana** (`account.kobana.com.br`). Esta API apenas o **verifica**, contra a chave pública que aquele servidor publica — ela não guarda chave de assinatura e não consegue emitir token nenhum. A claim **`org`** identifica a sua organização: todos os dados retornados são automaticamente escopados a ela. Requisitos conferidos a cada requisição: | Claim | Exigência | | ----- | ------------------------------------------------------------------------------------------------------------------------ | | `iss` | O identificador do Authorization Server, como URL: `https://account[.{env}].kobana.com.br` | | `aud` | A URL desta API: `https://api.billing[.{env}].kobana.com.br`. Pode ser uma **lista** — a regra é *contém*, não igualdade | | `exp` | **Obrigatória.** Token sem expiração é recusado | | `org` | **A conta Kobana** em cujo nome o token age — é ela que resolve a organização aqui, e é **obrigatória** | | `sub` | **A pessoa** (`users.public_id`). Vai para auditoria e atribuição; não escopa nada | | `jti` | Id único do token — base da auditoria | :::caution Mudança em relação à chave de API Até setembro de 2026 a credencial era uma chave criada no dashboard (`kb_…`), com prefix público e secret exibido uma única vez. A chave era ao mesmo tempo a credencial e o que a verificava — quem lesse o repositório de chaves agia como qualquer organização, e cada rotação era uma conversa com um cliente. Agora quem emite é o Authorization Server, e a plataforma só verifica. **Uma chave criada em Configurações → API não autentica mais esta API.** ::: Confira o ambiente O token é **diferente** entre Sandbox e Produção — o `aud` de um não vale no outro. Não reutilize entre ambientes. ## Como enviar o token[​](#como-enviar-o-token "Link direto para Como enviar o token") Inclua o cabeçalho `Authorization: Bearer ` em cada requisição. ``` export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx curl -i \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H 'Content-Type: application/json' \ -H 'User-Agent: Meu Nome (meunome@example.com)' \ -X GET 'https://api.billing.sandbox.kobana.com.br/v1/organization' ``` ## Requisição válida[​](#requisição-válida "Link direto para Requisição válida") Com um token válido, a resposta traz dados da Organização 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" } ``` ## Requisição inválida[​](#requisição-inválida "Link direto para Requisição inválida") Token ausente, malformado ou expirado retorna `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." } } ``` Códigos finos ajudam a achar o erro na hora: `invalid_token` (ausente, malformado ou assinatura inválida), `invalid_audience` (token de outro app Kobana) e `unknown_organization` — este último é `403`: o token é válido, a organização é que não está aqui. **Se o nosso Authorization Server estiver fora do ar**, a resposta é `5xx`, não `401`. Isso é deliberado: um `401` mandaria você depurar uma credencial perfeita durante a nossa queda. Tente de novo em instantes. :::note `sub` não é o tenant `sub` é a pessoa e `org` é o cliente — são uuids de tabelas diferentes, então trocá-los não dá erro de formato. Um token sem `org` é recusado em vez de cair no `sub`: esse fallback não casaria com organização nenhuma e responderia `403` em tudo, com o sintoma apontando para permissão e não para a claim lida. ::: ## Escopos[​](#escopos "Link direto para Escopos") Os escopos são **cobrados em toda requisição**, e cada requisição exige **um nível de acesso só**: o que o método pede (`GET` lê, `DELETE` exclui, `POST`/`PUT`/`PATCH` escrevem), ou o que o endpoint declara quando nenhum método o diz (importação e exportação em massa). Há dois formatos de token, e cada um é lido de um jeito. ### Os seis níveis de acesso[​](#os-seis-níveis-de-acesso "Link direto para Os seis níveis de acesso") | Nível | Concede | | -------- | ------------------------------------------ | | `read` | Leitura (`GET`, `HEAD`) | | `write` | Leitura e escrita (`POST`, `PUT`, `PATCH`) | | `delete` | Exclusão (`DELETE`), individual ou em lote | | `import` | Importação em massa | | `export` | Exportação em massa | | `all` | Tudo | **Um nível nunca substitui outro.** `write` não exclui, não importa e não exporta; `delete`, `import` e `export` não leem nem escrevem. Combine os níveis de que a integração precisa — `read delete` lista e exclui, `read write delete` faz as três coisas. ### O nível que cada endpoint exige[​](#o-nível-que-cada-endpoint-exige "Link direto para O nível que cada endpoint exige") | Endpoint | Nível | | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | `GET` / `HEAD` | `read` | | `POST` / `PUT` / `PATCH` | `write` | | `DELETE` — toda exclusão é um `DELETE`, inclusive a em lote (`DELETE /v1/{recurso}/bulk`) e a que só marca o registro como excluído | `delete` | | `POST /v1/nfes/import-barueri` | `import` | | Exportação em massa — esta API ainda não tem nenhuma; o PDF ou o XML de **um** documento (`/invoices/{id}/pdf`, `/nfes/{id}/xml`) é leitura | `export` | | `GET /v1/me` | Qualquer token válido | Todo `DELETE` é uma exclusão, e nada além de uma exclusão é um `DELETE`: arquivar (`POST …/archive`), desarquivar (`POST …/unarchive`), desativar (`POST …/deactivate`), fechar (`POST …/close`) e cancelar (`POST …/cancel`) são escritas. Uma exclusão é **soft delete** sempre que o registro tem histórico a preservar: ele ganha `deleted_at` e some de toda leitura (listagens, `GET` por id, filtros), enquanto faturas, pagamentos e NFS-e que o citam guardam a referência. :::caution Mudança de outubro de 2026 * **`DELETE` exige `delete`** (ou `all`). Antes um `DELETE` aceitava também `write`; um token só com `write` agora recebe `403 insufficient_scope` ao excluir. Peça o nível `delete` na Conta Kobana para as integrações que excluem. * **`POST /v1/nfes/import-barueri` exige `import`** (ou `all`); `write` não basta. * **`DELETE` passou a excluir** (soft delete, `deleted_at`) onde antes só mudava um status. Quem usava o `DELETE` para arquivar, desativar ou fechar deve chamar a rota própria: | Endpoint | Antes | Agora | Para o efeito antigo | | ------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `DELETE /v1/products/{id}` | arquivava | exclui | `POST /v1/products/{id}/archive` | | `DELETE /v1/plans/{id}` | arquivava; `?hard=true` excluía um rascunho | exclui (o parâmetro `hard` deixou de existir) | `POST /v1/plans/{id}/archive` (nova) | | `DELETE /v1/companies/{id}` | desativava | exclui | `POST /v1/companies/{id}/deactivate` | | `DELETE /v1/billing_accounts/{id}` | fechava (`?reason=`) e respondia a conta | exclui, com métodos de pagamento, cartões, usuários do portal e arquivos, e responde `{ "deleted": true }` | `POST /v1/billing_accounts/{id}/close` | | `DELETE /v1/customers/{id}/users/{user_id}` | apagava o convite pendente; suspendia o usuário ativo | exclui os dois | — | | `DELETE /v1/service_items/{id}` | apagava, ou só desativava se uma regra tributária o usava | exclui | `PATCH` com `is_active=false` | | `DELETE /v1/payment_methods/{id}` | marcava `removed` | exclui (e continua `removed` onde aparece por relação) | — | | `DELETE /v1/{products,plans}/bulk` | excluía em definitivo | exclui (soft delete), mesmas regras do `DELETE` individual | — | Um registro excluído não aparece mais em `GET` nenhum — nem com filtro de status. Para continuar consultando-o, arquive em vez de excluir. * **Endpoints que mudaram de método** — mesmo corpo JSON, mesma resposta; o endpoint antigo deixou de existir: | Antes | Agora | | ----------------------------------------------------------------------- | ------------------------------------------------ | | `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` (desarquivar) | `POST /v1/product_groups/{id}/unarchive` | | `DELETE /v1/subscription_item_changes/{id}` (cancelar mudança agendada) | `POST /v1/subscription_item_changes/{id}/cancel` | | ::: | | ### Token só com nível de acesso[​](#token-só-com-nível-de-acesso "Link direto para Token só com nível de acesso") Um token sem nenhum escopo `billing/…` (o de uma integração REST) é lido só pelos **níveis de acesso** que carrega, e eles valem em todos os recursos: `read write` lê e escreve tudo, e não exclui nada. ### Token com escopos de recurso[​](#token-com-escopos-de-recurso "Link direto para Token com escopos de recurso") Um token que carrega escopos `billing/…` (o token pessoal criado no assistente da Conta Kobana, ou o de um cliente MCP) tem **dois eixos ortogonais**: o **recurso**, sempre prefixado pelo app (`billing/subscriptions`), e o **nível**, um escopo global sem prefixo (`write`, `delete`, `import`, `export`). **Os recursos definem o alcance, e os níveis só valem dentro dele.** Ler exige o recurso; qualquer outra coisa exige o recurso *e* o nível. | Grupo | Escopos de recurso | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Clientes e acesso | `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` | | Assinaturas | `billing/subscriptions`, `billing/subscription_changes`, `billing/subscription_item_changes`, `billing/plan_changes` | | Faturamento | `billing/invoices`, `billing/payments`, `billing/payment_methods`, `billing/credits`, `billing/coupons` | | Fiscal | `billing/nfes`, `billing/tax_rules`, `billing/tax_periods`, `billing/withholdings`, `billing/certificates` | | Propostas | `billing/proposals`, `billing/proposal_templates` | | Conta e consumo | `billing/organization`, `billing/billing_accounts`, `billing/usage` | | **Coringa do recurso** | `billing/all` — alcança **todos** os recursos, inclusive os que não estão na lista, e **não concede nível nenhum** | | **Níveis globais** | `write` (`POST`, `PUT`, `PATCH`), `delete` (`DELETE`), `import` (importação em massa), `export` (exportação em massa) — valem nos recursos que o token alcança; `all` concede todos | Três exemplos: `billing/invoices` lê faturas e não escreve; `billing/invoices write` também cria, altera e cancela, e continua sem excluir nem alcançar assinaturas; `billing/products write delete` mantém o catálogo de produtos, exclusão em lote incluída. Contas bancárias, bancos, chaves Pix, feriados, políticas de multa e compras de crédito (`/bank_accounts`, `/banks`, `/pix_keys`, `/holidays`, `/late_fee_policies`, `/credit_purchases`) não têm escopo de recurso próprio: um token com escopos de recurso só os alcança com `billing/all`. A forma granular `billing/invoices:write` é **exceção** da gramática, não o formato padrão: satisfaz os dois eixos para aquele recurso só, e existe para "lê um recurso, escreve outro". `billing/*` é curinga de **cadastro** e nunca é emitido num token — a comparação aqui é sempre literal. Um token que não traz nenhum escopo que esta API reconheça — nem nível de acesso, nem `billing/…` — não alcança nada além de `GET /v1/me`. ### Escopo insuficiente[​](#escopo-insuficiente "Link direto para Escopo insuficiente") Faltar escopo responde `403 insufficient_scope`, com os níveis que teriam bastado e os escopos que o token carrega: ``` 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 qualquer token válido, seja qual for o escopo — é como conferir o token que você tem. ## Boas práticas[​](#boas-práticas "Link direto para Boas práticas") * **Nunca** versione tokens em git. Use variáveis de ambiente ou cofres (AWS Secrets Manager, Vault, etc.). * Use tokens distintos por integração (CRM, ERP, frontend, etc.) — facilita trocar um sem derrubar os outros, e a auditoria por `jti` fica legível. * Peça os escopos mínimos necessários (princípio do menor privilégio) — recurso sem verbo quando a integração só lê. * Prefira tokens de vida curta: esta API não consulta lista de revogação, então um token vazado vale até o `exp`. Troque a credencial na Conta Kobana assim que souber do vazamento. * HTTPS obrigatório — chamadas em HTTP são rejeitadas. --- # Retenção de Dados Esta página descreve por quanto tempo cada tipo de dado é mantido no Faturamento Automático. ## Clientes Ativos[​](#clientes-ativos "Link direto para Clientes Ativos") Tempo de guarda para Organizações com assinaturas ativas e pagamento em dia. | Tipo de dado | Tempo (em meses) | | --------------------------- | ---------------- | | Eventos | 12 | | Entregas de Webhooks | 12 | | Envios de E-mails | 12 | | Envios de SMS | 12 | | Logs de Auditoria | 12 | | Requests da API | 3 | | Faturas | Indefinidamente | | Pagamentos | Indefinidamente | | Assinaturas | Indefinidamente | | Planos e Produtos | Indefinidamente | | Clientes (Billing Accounts) | Indefinidamente | | NF-e emitidas | Indefinidamente | | Cupons e Créditos | Indefinidamente | | Qualquer dado não listado | Indefinidamente | ## Clientes Inativos[​](#clientes-inativos "Link direto para Clientes Inativos") Tempo de guarda para Organizações com assinaturas canceladas, suspensas ou contas inadimplentes acima do período de tolerância. | Tipo de dado | Tempo (em meses) | | ------------------------------- | --------------------- | | Eventos | 1 | | Entregas de Webhooks | 1 | | Envios de E-mails | 1 | | Envios de SMS | 1 | | Logs de Auditoria | 3 | | Faturas | 3 | | Pagamentos | 3 | | Assinaturas | 3 | | Planos e Produtos | 3 | | Clientes (Billing Accounts) | 3 | | NF-e emitidas | 60 (obrigação fiscal) | | Cupons e Créditos | 3 | | Qualquer outro dado não listado | 3 | NF-e tem retenção mínima de 5 anos conforme legislação fiscal brasileira, mesmo após a Organização tornar-se inativa. Os tempos acima podem ser alterados a qualquer momento. ## Sandbox[​](#sandbox "Link direto para Sandbox") Dados em Sandbox podem ser limpos a qualquer momento sem aviso prévio. Não dependa do Sandbox para retenção de dados de teste de longo prazo. --- # Endpoints ## Plataforma (acesso web)[​](#plataforma-acesso-web "Link direto para Plataforma (acesso web)") | Ambiente | URL | | -------- | ------------------------------------------- | | Sandbox | | | Produção | | ## API (v1)[​](#api-v1 "Link direto para API (v1)") | Ambiente | URL | | -------- | ------------------------------------------- | | Sandbox | | | Produção | | ## Documentação[​](#documentação "Link direto para Documentação") | Ambiente | URL | | ------------ | ------------------------------------ | | Documentação | | --- # Idempotência A API suporta idempotência para repetir solicitações com segurança, sem executar a mesma operação duas vezes. Útil quando uma chamada é interrompida em trânsito e você não recebe resposta — por exemplo, uma requisição para criar uma assinatura que cai por erro de rede pode ser repetida com a mesma chave, garantindo que apenas uma assinatura seja criada. ## Como usar[​](#como-usar "Link direto para Como usar") Envie o cabeçalho `X-Idempotency-Key: ` em qualquer requisição `POST`, `PUT` ou `PATCH`. A chave é livre, gerada pelo seu lado. Recomendamos `UUID v4` ou outra string aleatória com entropia suficiente para evitar colisões. ``` 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' ``` ## Como funciona[​](#como-funciona "Link direto para Como funciona") Quando o servidor recebe uma requisição com `X-Idempotency-Key`: 1. **Reserva a chave** atomicamente, escopada à sua **organização**. Duas organizações diferentes podem usar a mesma chave sem conflito. 2. **Calcula a impressão digital da requisição** — SHA-256 de `método + caminho + corpo bruto`. Esse hash é guardado junto com a chave. 3. **Executa o handler**. Se ele retornar uma resposta, o servidor grava `status_code`, corpo e cabeçalhos relevantes vinculados à chave. 4. **Marca a chave como completa**. Qualquer nova requisição com a mesma chave dentro de **24 horas** recebe a resposta original verbatim — mesmo `status_code`, mesmo corpo, mesmos cabeçalhos — acrescida do cabeçalho `X-Idempotent-Replay: true` para indicar que se trata de uma reexecução. A camada salva o resultado **independentemente de ter sido sucesso ou falha**. Retries com a mesma chave retornam o mesmo resultado, **incluindo erros `5xx`**. ### Limites[​](#limites "Link direto para Limites") * Tamanho máximo da chave: **255 caracteres**. * Retenção: chaves expiram automaticamente **24 horas** após a criação. Após expirar, uma nova solicitação com a mesma chave gera um novo resultado. * Escopo: por organização. Uma chave usada em uma organização não interfere em outra. * Caracteres aceitos: qualquer string UTF-8 imprimível. ## Quando o resultado **não** é salvo[​](#quando-o-resultado-não-é-salvo "Link direto para quando-o-resultado-não-é-salvo") A camada só grava o resultado quando o handler começou a executar. Não há registro nos seguintes casos — é seguro reenviar a requisição: * A chave está vazia ou passou de **255 caracteres** → resposta `400 bad_request`. * O parser do envelope da API rejeita a requisição antes do handler (por exemplo, JSON inválido ou autenticação ausente). * O handler **lança uma exceção** durante a execução — a reserva é liberada para que o próximo retry possa rodar limpo. * Outra requisição com a mesma chave está em execução simultânea → resposta `409 conflict` com `details.reason = "idempotency_request_in_progress"`. ## Conflitos[​](#conflitos "Link direto para Conflitos") Se a mesma chave for reutilizada com uma requisição diferente (qualquer mudança em método, caminho ou corpo), a API responde `409 conflict` com `details.reason = "idempotency_key_reused"`. Isso protege contra reuso acidental — por exemplo, persistir a chave junto com a operação no seu lado e tentar criar dois recursos diferentes com o mesmo identificador. ### Resposta de erro[​](#resposta-de-erro "Link direto para Resposta de erro") ``` { "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" } } } ``` ### Outras respostas possíveis[​](#outras-respostas-possíveis "Link direto para Outras respostas possíveis") | Cenário | Status | `error.code` | `details.reason` | | ---------------------------------------------- | ------ | ------------- | --------------------------------- | | Outra requisição com a mesma chave em execução | `409` | `conflict` | `idempotency_request_in_progress` | | Mesma chave reutilizada com payload diferente | `409` | `conflict` | `idempotency_key_reused` | | Chave vazia ou maior que 255 caracteres | `400` | `bad_request` | `invalid_idempotency_key` | ## Métodos aceitos[​](#métodos-aceitos "Link direto para Métodos aceitos") | Método | Aceita `X-Idempotency-Key`? | | -------- | --------------------------------------- | | `POST` | ✅ Sim | | `PUT` | ✅ Sim | | `PATCH` | ✅ Sim | | `GET` | ❌ Não (já é idempotente por definição) | | `DELETE` | ❌ Não (já é idempotente por definição) | Enviar a chave em `GET` ou `DELETE` não tem efeito — a API processa a requisição normalmente, sem gravar registro. ## Identificando uma reexecução[​](#identificando-uma-reexecução "Link direto para Identificando uma reexecução") Toda resposta servida a partir do registro carrega o cabeçalho: ``` X-Idempotent-Replay: true ``` Você pode usar esse cabeçalho para distinguir, no seu lado, entre a primeira execução e um retry replicado pelo servidor. ## Boas práticas[​](#boas-práticas "Link direto para Boas práticas") * **Uma chave por operação lógica**. Não reutilize a mesma chave para criar dois recursos diferentes — você receberá `409 conflict`. * **Persista a chave junto com o estado da operação** no seu lado, para que o retry depois de crash ou reinício use a mesma chave. * **Combine com backoff exponencial** ao receber `5xx` ou timeout — a chave garante que o retry não duplica o recurso. Como o resultado é gravado também para falhas, você pode parar de tentar assim que vier o status code esperado. * **Limpe a chave depois de 24 horas**. Não há ganho em mantê-la no seu lado após esse prazo: o servidor já descartou o registro. * **Não envie a chave em métodos que não a aceitam**. Em `GET`/`DELETE` ela é silenciosamente ignorada — preferimos que o cliente nem a inclua para deixar claro o que é idempotente por contrato e o que depende da chave. --- # Introdução Você que é dev, divirta-se! ✨ ## Formato[​](#formato "Link direto para Formato") A API aceita apenas o formato `JSON`. Todas as requisições devem usar `Content-Type: application/json`. Todas as respostas usam `snake_case`. | Tipo de Campo | Formato | | ------------- | -------------------------------------------------------------------------------------------------------------------------- | | **DateTime** | Formato [ISO8601](https://pt.wikipedia.org/wiki/ISO_8601). Exemplos — Data: `2026-01-24`. Data e Hora: `2026-01-24T10:07Z` | | **Money** | Número decimal em reais (BRL), com até 4 casas decimais. Ex.: `100.5` = R$ 100,50 | | **UUID** | Identificadores de recursos no formato UUID v4 | ## Convenções[​](#convenções "Link direto para Convenções") Convenções usadas nesta documentação: | Convenção | Descrição | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`:variable`** | Nome de variável que precisa ser substituída em uma URL. | | **`#{variable}`** | Nome de variável que precisa ser substituída por valores da sua conta. | | **`...`** | Conteúdo da resposta truncado para facilitar a leitura. | | **`$KOBANA_TOKEN`** | Token de acesso. Para testes em linha de comando, exporte-o: `export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx` e cole os comandos da documentação no terminal. | ## Códigos de Retorno[​](#códigos-de-retorno "Link direto para Códigos de Retorno") A API retorna códigos HTTP padrão: | | Código | Descrição | | -- | ----------------------------- | ------------------------------------------------------------------------------------------------ | | ✅ | **200 OK** | Requisição bem-sucedida com corpo de resposta. | | ✅ | **201 Created** | Recurso criado com sucesso. | | ✅ | **204 No Content** | Requisição bem-sucedida, sem corpo de resposta. | | ❌ | **400 Bad Request** | Requisição inválida, em geral conteúdo mal formado. | | ❌ | **401 Unauthorized** | Token de acesso ausente ou inválido. | | ❌ | **403 Forbidden** | Acesso à API bloqueado ou usuário sem permissão. | | ❌ | **404 Not Found** | Endereço acessado não existe. | | ❌ | **422 Unprocessable Entity** | Requisição válida, mas os dados enviados não são. | | ❌ | **429 Too Many Requests** | Limite de requisições atingido. | | ❌ | **500 Internal Server Error** | Erro interno no processamento. Consulte o [status dos servidores](https://status.kobana.com.br). | ## ID das Requisições (Request ID)[​](#id-das-requisições-request-id "Link direto para ID das Requisições (Request ID)") Cada requisição possui um identificador associado, disponível no cabeçalho `Request-Id` da resposta. Esse valor ajuda na depuração e auditoria — as requisições e seus IDs podem ser consultadas no painel do sistema. O log de requisições fica disponível por **30 dias**. Ao abrir um chamado de suporte sobre uma requisição específica, informe o `Request-Id` para acelerar a investigação. ## Segurança[​](#segurança "Link direto para Segurança") A API da Kobana usa certificados **SSL 2048 bits**. Toda requisição deve ser feita via **HTTPS** — chamadas na porta 80 são redirecionadas para 443. Os clientes devem suportar `TLSv1.2` ou `TLSv1.3` com uma das cifras: `TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES128-SHA256`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-RSA-CHACHA20-POLY1305`, `ECDHE-RSA-AES256-SHA384`. `TLSv1` e `TLSv1.1` não são suportados. ## Cache HTTP[​](#cache-http "Link direto para Cache HTTP") Use os cabeçalhos HTTP de cache para reduzir carga e ganhar velocidade. A maioria das respostas inclui `ETag` e/ou `Last-Modified` — armazene esses valores e reenvie nas próximas requisições via `If-None-Match` e `If-Modified-Since`. Se o recurso não mudou, a resposta será `304 Not Modified`, sem corpo e sem reprocessamento. Mais informações: [HTTP Cache Docs](http://www.mnot.net/cache_docs/). ## Tratamento de Erros[​](#tratamento-de-erros "Link direto para Tratamento de Erros") Erros 5xx indicam falhas no servidor: **500 Internal Server Error** (aplicação indisponível), **502 Bad Gateway**, **503 Service Unavailable** e **504 Gateway Timeout** (falhas pontuais de infraestrutura). Sua aplicação deve identificar esses códigos e reagendar a requisição após alguns minutos com backoff. Status dos servidores: . ## Valores monetários[​](#valores-monetários "Link direto para Valores monetários") Todo valor monetário — na requisição e na resposta — é um número decimal em reais (BRL), com até 4 casas decimais. Não há campos em centavos: envie `100.5` para R$ 100,50 e `0.0125` para R$ 0,0125. Campos de precificação aceitam as 4 casas; os demais são arredondados para 2. ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Especificações](https://docs.billing.kobana.com.br/pt/pt/api/overview/openapi.md) — OpenAPI 3.1 em YAML para download. * [Endpoints](https://docs.billing.kobana.com.br/pt/pt/api/overview/endpoints.md) — URLs de Sandbox e Produção. * [User-Agent](https://docs.billing.kobana.com.br/pt/pt/api/overview/user-agent.md) — cabeçalho recomendado para identificar sua aplicação. * [Limite de Requisições](https://docs.billing.kobana.com.br/pt/pt/api/overview/rate-limit.md) — throttling e headers de resposta. * [Idempotência](https://docs.billing.kobana.com.br/pt/pt/api/overview/idempotency.md) — `X-Idempotency-Key` para retries seguros. * [Webhooks](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks.md) — eventos disparados em tempo real. * [Retenção de Dados](https://docs.billing.kobana.com.br/pt/pt/api/overview/data-retention.md) — política de guarda por tipo de recurso. --- # OpenAPI Mantemos publicamente os arquivos de especificações da API do Faturamento Automático em formato aberto para que você possa baixar e usar na ferramenta de sua preferência. ## OpenAPI 3.1[​](#openapi-31 "Link direto para OpenAPI 3.1") | Versão | Idioma | Arquivo | | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | v1 | Português | [openapi-v1-pt.yaml](https://docs.billing.kobana.com.br/pt/pt/assets/files/openapi-v1-pt-c96fdd39d7e5abca6e9821296fdaf848.yaml) | | v1 | English | [openapi-v1-en.yaml](https://docs.billing.kobana.com.br/pt/pt/assets/files/openapi-v1-en-62097be868d8fc203d6bd3082589d316.yaml) | | v1 | Español | [openapi-v1-es.yaml](https://docs.billing.kobana.com.br/pt/pt/assets/files/openapi-v1-es-4e3188d5390aab00d50f977b7fc5600a.yaml) | ## Coleção do Postman[​](#coleção-do-postman "Link direto para Coleção do Postman") Disponível também como coleção pronta para importar no Postman. Detalhes e arquivos em [Postman](https://docs.billing.kobana.com.br/pt/pt/api/overview/postman.md). --- # Listagem e Paginação Todos os endpoints `GET` que retornam coleções (`/v1/customers`, `/v1/subscriptions`, `/v1/invoices`, etc.) usam paginação por **número de página**. ## Parâmetros[​](#parâmetros "Link direto para Parâmetros") Enviados via query string: | Parâmetro | Tipo | Default | Descrição | | ------------ | --------------- | ----------------- | ------------------------------------------------------------- | | `page` | inteiro ≥ 1 | `1` | Página solicitada (começa em 1). | | `per_page` | inteiro 1–100 | `20` | Quantidade de itens por página. Máximo **100**. | | `sort_by` | string | varia por recurso | Campo usado para ordenar. Aceita os mesmos nomes da resposta. | | `sort_order` | `asc` ou `desc` | `desc` | Direção da ordenação. | Valores fora dos limites são clampados (ex.: `per_page=999` vira `100`; `page=0` vira `1`). ## Resposta[​](#resposta "Link direto para Resposta") Toda listagem segue 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 | Descrição | | ------------------ | -------------------------------------------------------------- | | `data` | Array com os itens da página atual. | | `meta.total` | Total de itens que atendem aos filtros (não só os retornados). | | `meta.page` | Página atual. | | `meta.per_page` | Itens por página efetivamente aplicado. | | `meta.total_pages` | Número total de páginas (`ceil(total / per_page)`). | A última página pode conter menos que `per_page` itens. Quando `page > total_pages`, `data` vem vazio (não é erro). ## Exemplos[​](#exemplos "Link direto para Exemplos") ### Primeira página, padrão[​](#primeira-página-padrão "Link direto para Primeira página, padrão") ``` curl -H "Authorization: Bearer $KOBANA_TOKEN" \ 'https://api.billing.sandbox.kobana.com.br/v1/customers' ``` ### Página 3 com 50 itens[​](#página-3-com-50-itens "Link direto para Página 3 com 50 itens") ``` 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 "Link direto para 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 + paginação[​](#filtros--paginação "Link direto para Filtros + paginação") Filtros específicos do recurso convivem com `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 as páginas[​](#iterando-todas-as-páginas "Link direto para Iterando todas as páginas") Padrão recomendado em pseudo-código: ``` async function fetchAll(url, token) { const out = []; let 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; } ``` ## Boas práticas[​](#boas-práticas "Link direto para Boas práticas") * Para sincronização incremental, prefira filtrar por `updated_at_gte` (ou similar disponível no endpoint) ao invés de varrer todas as páginas. * `per_page=100` minimiza o número de requisições e consome menos do [limite de requisições](https://docs.billing.kobana.com.br/pt/pt/api/overview/rate-limit.md). * Faça **cache** de `meta.total` quando estiver renderizando paginadores; não recalcule a cada navegação. * Evite assumir ordem estável sem `sort_by` explícito — a ordem padrão pode mudar entre recursos. --- # Postman Se preferir testar a API pelo Postman, baixe a coleção no idioma de sua preferência e importe — ou abra a versão online direto no workspace público da Kobana. ## Workspace público[​](#workspace-público "Link direto para Workspace público") Mantemos as coleções v1 da API do Faturamento Automático publicadas no workspace [**universokobana/kobana-billing-api**](https://www.postman.com/universokobana/kobana-billing-api/overview), com uma coleção por idioma. [![Workspace Kobana Billing API no Postman](/pt/assets/images/postman-workspace-kobana-billing-api-90ee622934c0c69710b5d26a95ef41c5.png)](https://www.postman.com/universokobana/kobana-billing-api/overview) ## Coleção[​](#coleção "Link direto para Coleção") Abra direto no Postman (web ou app): [**API do Faturamento Automático (v1.0.0) — Português**](https://www.postman.com/universokobana/kobana-billing-api/collection/p8ia1w4/api-do-faturamento-automtico-v1-0-0-portugus). ## Coleções para download[​](#coleções-para-download "Link direto para Coleções para download") Prefere importar localmente? Baixe o arquivo `.json`: | Versão | Idioma | Arquivo | | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | v1 | Português | [postman-v1-pt.json](https://docs.billing.kobana.com.br/pt/pt/assets/files/postman-v1-pt-237ab7a2a047fb07c78b74c423d5230a.json) | | v1 | English | [postman-v1-en.json](https://docs.billing.kobana.com.br/pt/pt/assets/files/postman-v1-en-68ac75a8e45a054be700f9028be4bf62.json) | | v1 | Español | [postman-v1-es.json](https://docs.billing.kobana.com.br/pt/pt/assets/files/postman-v1-es-a877a62f36fd3e5dd48fe2d3b6976c8d.json) | ## Usando[​](#usando "Link direto para Usando") 1. Importe o arquivo `.json` baixado no Postman (**File → Import**) — ou abra direto pela [coleção online](#cole%C3%A7%C3%A3o). 2. Abra a aba **Variables** da coleção e preencha: * `baseUrl` — produção ou sandbox (`https://api.billing.sandbox.kobana.com.br`). * `bearerToken` — seu JWT, gerado em **Integrações → API Kobana → Token de API**. 3. A autenticação `Bearer` já vem configurada no nível da coleção apontando pra `{{bearerToken}}`. 4. Abra qualquer request, ajuste parâmetros se necessário e clique em **Send**. --- # Limite de Requisições Quando um cliente excede o limite associado a ele, as requisições seguintes são bloqueadas. O servidor responde com informações sobre os limites utilizados e o tempo de espera necessário para enviar uma nova requisição, anexadas aos cabeçalhos da resposta: | Header | Exemplo | Descrição | | --------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `ratelimit-limit` | `60` | Limite de requisições para o cliente. | | `ratelimit-name` | `throttle_authenticated_web` | Nome do throttle utilizado. | | `ratelimit-remaining` | `0` | Número de requisições disponíveis. | | `ratelimit-reset` | `1609844400` | [Unix time](https://en.wikipedia.org/wiki/Unix_time) — quando a contagem reinicia. | | `retry-after` | `30` | Segundos até a contagem reiniciar. Ver [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). | Existem dois tipos de limites: requisições `GET` e requisições `POST`. Em ambos os casos a contagem é feita por **hora**. Limites máximos: * **60 requisições/hora** para `GET` * **1000 requisições/hora** para `POST` Caso sua operação precise de um número maior, fale com o suporte ou comercial. A contagem é zerada no primeiro minuto de cada hora. A cada requisição, o servidor retorna `ratelimit-limit` e `ratelimit-remaining`. ### Exemplo de resposta em sucesso[​](#exemplo-de-resposta-em-sucesso "Link direto para Exemplo de resposta em sucesso") ``` Date: Fri, 05 Nov 2010 12:00:00 GMT Content-Type: application/json; charset=utf-8 ratelimit-limit: 1000 ratelimit-remaining: 486 ``` ### Exemplo de resposta em bloqueio[​](#exemplo-de-resposta-em-bloqueio "Link direto para Exemplo de resposta em bloqueio") Quando o limite é atingido, o servidor retorna `HTTP 429 Too Many Requests`. Aguarde o número de segundos do header `retry-after` antes da próxima requisição. ``` HTTP/1.1 429 Too Many Requests Date: Fri, 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 Você pode incluir o cabeçalho `User-Agent` com o nome da sua aplicação e um endereço de e-mail válido, para que possamos entrar em contato caso: 1. Você esteja fazendo algo errado, e possamos avisá-lo antes de bloquear; 2. Esteja fazendo algo muito legal, e possamos dar os parabéns 🙂 Exemplo: ``` User-Agent: Meu Nome (meunome@example.com) ``` Exemplo de como passar esse cabeçalho usando cURL: ``` curl -i \ -H "Authorization: Bearer <>" \ -H 'Content-Type: application/json' \ -H 'User-Agent: Meu Nome (meunome@example.com)' \ -X GET 'https://api.billing.sandbox.kobana.com.br/v1/me' ``` Esse cabeçalho é **opcional** em todas as requisições, mas recomendado. --- # Webhooks Webhooks são notificações HTTP enviadas pela API do Faturamento Automático sempre que um evento relevante ocorre na sua Organização — assinatura criada, fatura paga, NF-e emitida, etc. Em vez de fazer polling, você cadastra um **endpoint HTTP público** e recebe um `POST` com o payload do evento assim que ele acontece. ## Cadastro[​](#cadastro "Link direto para Cadastro") Gerencie endpoints em **Dashboard → Configurações → API → Webhooks**. Cada endpoint tem: * **URL** — destino HTTPS público do seu servidor. * **Eventos assinados** — lista dos `event types` que deseja receber. Se vazia, recebe todos. * **Status** — `active` ou `inactive`. * **Secret** — string secreta usada para assinar cada entrega (HMAC-SHA256). Gerada automaticamente; pode ser rotacionada. * **Auth headers** — opcionalmente, cabeçalhos extras (Basic, Bearer, custom) injetados em cada requisição. ## Entrega[​](#entrega "Link direto para Entrega") Cada evento dispara uma requisição `POST` para a URL cadastrada: ``` 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...} ``` Os cabeçalhos estão descritos em [Headers e assinatura](#headers-e-assinatura-padr%C3%A3o-kobana), abaixo. ### Sucesso[​](#sucesso "Link direto para Sucesso") Qualquer resposta `2xx` em até **30 segundos** marca a entrega como bem-sucedida. Qualquer outra coisa (timeout, `4xx`, `5xx`) é tratada como falha. ### Retry[​](#retry "Link direto para Retry") Falhas são reentregues com backoff exponencial: | Tentativa | Atraso | | --------- | -------- | | 1 | imediato | | 2 | +1 min | | 3 | +5 min | | 4 | +30 min | | 5 | +2 h | | 6 | +6 h | | 7 | +24 h | Após **7 tentativas**, a entrega é marcada como `failed` permanentemente. Eventos órfãos ficam disponíveis no dashboard para reenvio manual. ## Headers e assinatura (padrão Kobana)[​](#headers-e-assinatura-padrão-kobana "Link direto para Headers e assinatura (padrão Kobana)") Toda entrega é um `POST` com `Content-Type: application/json` e os headers abaixo — **os mesmos em todos os produtos Kobana**, então um único receptor atende vários produtos e ambientes e roteia com segurança: | Header | Valor | | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `X-Kobana-App` | `billing` — o produto Kobana que enviou a entrega. | | `X-Kobana-Environment` | `development`, `sandbox` ou `production`. Nunca deixe uma entrega `sandbox` tocar dados de produção. | | `X-Kobana-Webhook-Id` | Id do endpoint cadastrado a que a entrega pertence. | | `X-Kobana-Event` | Slug do evento (ex.: `invoice.paid`). | | `X-Kobana-Event-Id` | Id do evento. Retries do mesmo evento repetem este valor — use-o para deduplicar. | | `X-Kobana-Delivery-Id` | Id único desta tentativa de entrega. Faz parte do conteúdo assinado. | | `X-Kobana-Timestamp` | Unix time (segundos) em que a entrega foi assinada. Faz parte do conteúdo assinado. | | `X-Kobana-Signature` | `v1,` — um ou mais tokens separados por espaço. | | `webhook-id`, `webhook-timestamp`, `webhook-signature` | Os mesmos três valores acima, no layout [Standard Webhooks](https://www.standardwebhooks.com) — verificáveis com uma biblioteca de prateleira. | Os headers legados `X-Signature` (`t=,v1=` sobre `"{t}.{body}"`), `X-Delivery-Id`, `X-Event-Id`, `X-Event-Type`, `X-Timestamp`, `X-App` e `X-Environment` continuam sendo enviados, **deprecados**, para integrações existentes. Migre para os `X-Kobana-*`: eles serão removidos numa próxima versão do contrato. ### Como a assinatura é calculada[​](#como-a-assinatura-é-calculada "Link direto para Como a assinatura é calculada") ``` chave = base64_decode(secret sem o prefixo "whsec_") conteúdo = delivery_id + "." + timestamp + "." + body_cru assinatura = "v1," + base64(HMAC_SHA256(chave, conteúdo)) ``` * `body_cru` é o corpo da requisição **exatamente como recebido**, byte a byte. Não parseie e re-serialize: ordem de chaves, espaços ou escapes mudariam e a assinatura deixaria de bater. * Amarrar o `delivery_id` ao conteúdo assinado impede que uma requisição capturada seja reapresentada com outro id para furar a sua deduplicação; o timestamp limita o replay no tempo. * O secret tem a forma `whsec_` + base64 de 32 bytes aleatórios e é exibido **uma única vez**. Secrets antigos (sem o prefixo, ou com hexadecimal após ele) continuam válidos: a chave é o base64 decodificado após o prefixo, ou os bytes UTF-8 do secret quando não há prefixo. * Durante uma rotação de secret o header carrega um token por secret ainda válido (`v1,AAA… v1,BBB…`). A entrega é válida se **qualquer** token casar com **qualquer** secret que você tenha. ### Verificando uma entrega[​](#verificando-uma-entrega "Link direto para Verificando uma entrega") 1. Leia `webhook-id`, `webhook-timestamp` e `webhook-signature` (ou os equivalentes `X-Kobana-*`). Rejeite a requisição se algum faltar. 2. Rejeite se `|agora − timestamp| > 300` segundos: cinco minutos absorvem diferença de relógio e limitam replays. 3. Monte o conteúdo assinado com o body cru e calcule o HMAC esperado para cada secret que você confia. 4. Compare com cada token `v1,` em **tempo constante** — nunca com `==`, que devolve no primeiro byte diferente e vaza o digest por timing. 5. Deduplique por `X-Kobana-Event-Id` para processar cada evento uma vez, ou por `webhook-id` para registrar cada tentativa. 6. Responda `2xx` rápido e faça o trabalho pesado de forma assíncrona. Qualquer outra resposta entra no ciclo de retry. ``` const crypto = require('node:crypto'); /** * @param headers headers da requisição, com nomes em minúsculas * @param rawBody body cru (string ou Buffer), ANTES de qualquer JSON.parse * @param secrets secret atual (e o anterior, durante uma rotação) */ 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") ``` Com Express, mantenha o body cru montando `express.raw({ type: 'application/json' })` na rota do webhook (não `express.json()`), verifique e só então faça `JSON.parse`. Com Django/Flask, use `request.body`/`request.get_data()` — nunca o objeto já parseado. ## Estrutura do payload[​](#estrutura-do-payload "Link direto para Estrutura do payload") Todos os eventos compartilham o mesmo 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 | Descrição | | ------------- | -------------------------------------------------------------------------------------------------------------------------- | | `id` | ID único do evento. | | `type` | Tipo do evento (ex.: `invoice.paid`). | | `created_at` | Timestamp ISO 8601 (UTC) em que o evento foi gerado. | | `environment` | `production` ou `sandbox`. | | `version` | Versão do schema do payload (string `YYYY-MM-DD`). | | `data` | O recurso completo no estado atual. | | `changes` | Para eventos `*.updated` e `*.status_changed`, mapa `campo: {from, to}`. Pode estar ausente em eventos de criação/deleção. | ## Exemplos de payload por evento[​](#exemplos-de-payload-por-evento "Link direto para Exemplos de payload por evento") Veja os exemplos completos navegando pelas páginas abaixo: * [`customer.db.created`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/customer-created.md) * [`company.db.updated`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/company-updated.md) * [`billing_account.suspended`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/billing-account-suspended.md) * [`subscription.status_changed`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/subscription-status-changed.md) * [`invoice.paid`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/invoice-paid.md) * [`payment.succeeded`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/payment-succeeded.md) * [`payment_method.expired`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/payment-method-expired.md) * [`nfe.issued`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/nfe-issued.md) * [`credit.applied`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/credit-applied.md) * [`proposal.accepted`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/proposal-accepted.md) * [`plan.db.updated`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/plan-updated.md) * [`product.archived`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/product-archived.md) * [`coupon.redeemed`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/coupon-redeemed.md) * [`service_item.db.updated`](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks/service-item-updated.md) ## Boas práticas[​](#boas-práticas "Link direto para Boas práticas") * **Idempotência**: use `X-Event-Id` para evitar processar duplicatas em caso de retry. * **Resposta rápida**: responda `2xx` em até 30s. Enfile o trabalho pesado em fila assíncrona. * **Versionamento**: o campo `version` indica o schema. Trate campos novos como aditivos. * **Validação obrigatória**: sempre valide a assinatura antes de confiar no payload. * **HTTPS**: use TLS no endpoint. Endpoints HTTP são rejeitados em produção. * **Lista de eventos**: prefira assinar apenas os eventos que você processa, não `*`. --- # `billing_account.suspended` Disparado quando uma BillingAccount é suspensa por inadimplência ou ação manual do operador. **Grupo:** Customers ## Payload[​](#payload "Link direto para 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` Disparado a cada update em qualquer campo de uma empresa (Company). **Grupo:** Customers ## Payload[​](#payload "Link direto para 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` Disparado quando um cupom é resgatado em uma assinatura ou fatura. **Grupo:** Catálogo ## Payload[​](#payload "Link direto para 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` Disparado quando um crédito existente é aplicado em uma fatura, reduzindo o valor devido. **Grupo:** Faturamento ## Payload[​](#payload "Link direto para 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` Disparado quando um novo cliente (pessoa física ou jurídica) é cadastrado na Organização. **Grupo:** Customers ## Payload[​](#payload "Link direto para 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` Disparado quando uma fatura tem seu pagamento confirmado e seu status passa para `paid`. **Grupo:** Faturamento ## Payload[​](#payload "Link direto para 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 a conta e o produto[​](#identificando-a-conta-e-o-produto "Link direto para Identificando a conta e o produto") O payload traz **identificadores internos e públicos lado a lado**: | Campo | Use quando | | --------------------------- | --------------------------------------------------------------------------------------------------------- | | `billing_account_id` | você guarda o id interno da Kobana | | `billing_account_public_id` | você identifica a conta pelo **uid público** — o mesmo que a API aceita para resolver uma billing account | | `line_items[].product_id` | id interno do produto | | `line_items[].product_slug` | **slug** do produto, estável e legível — o modo recomendado de reconhecer *o que* foi comprado | Um assinante externo normalmente roteia por `billing_account_public_id` e reconhece o produto por `product_slug`: são os dois valores que existem fora desta base. `product_slug` vem `null` quando a relação do produto não estava carregada no momento da emissão — `null` significa *"não sei"*, nunca *"outro produto"*. --- # `nfe.issued` Disparado quando a NF-e é emitida com sucesso pelo provedor fiscal integrado. **Grupo:** Faturamento ## Payload[​](#payload "Link direto para 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` Disparado quando um método de pagamento expira (cartão vencido, mandato cancelado, etc.). **Grupo:** Faturamento ## Payload[​](#payload "Link direto para 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` Disparado quando um pagamento é confirmado pelo gateway com status `succeeded`. **Grupo:** Faturamento ## Payload[​](#payload "Link direto para 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` Disparado a cada update em qualquer campo de um Plano. **Grupo:** Catálogo ## Payload[​](#payload "Link direto para 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` Disparado quando um produto é arquivado e removido do catálogo ativo. **Grupo:** Catálogo ## Payload[​](#payload "Link direto para 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` Disparado quando o cliente aceita uma proposta comercial enviada. **Grupo:** Comercial ## Payload[​](#payload "Link direto para 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` Disparado a cada update em itens de serviço (códigos de CNAE, ISS, descrição fiscal). **Grupo:** Catálogo ## Payload[​](#payload "Link direto para 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` Disparado sempre que o `status` de uma assinatura muda (`active`, `trialing`, `past_due`, `paused`, `canceled`). **Grupo:** Faturamento ## Payload[​](#payload "Link direto para 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 da Assinatura](https://docs.billing.kobana.com.br/pt/pt/assinaturas/ciclo-de-vida/.md) [Estados](https://docs.billing.kobana.com.br/pt/pt/assinaturas/ciclo-de-vida/.md) --- ## [📄️Ciclo de Vida da Assinatura](https://docs.billing.kobana.com.br/pt/pt/assinaturas/ciclo-de-vida/.md) [Estados](https://docs.billing.kobana.com.br/pt/pt/assinaturas/ciclo-de-vida/.md) --- # Ciclo de Vida da Assinatura ## Estados[​](#estados "Link direto para Estados") ``` draft → confirmed → trialing → active ↔ past_due → canceled ↕ paused ``` | Estado | Descrição | | ------------- | ------------------------------------------------------------- | | **draft** | Rascunho. Pode ser editada livremente antes de ser confirmada | | **confirmed** | Confirmada, aguardando ativação | | **trialing** | Em período de trial gratuito | | **active** | Ativa, gerando cobranças recorrentes | | **past\_due** | Com pagamento atrasado | | **paused** | Pausada temporariamente (sem cobranças) | | **canceled** | Cancelada (estado terminal) | ## Criando uma Assinatura[​](#criando-uma-assinatura "Link direto para Criando uma Assinatura") Para criar uma assinatura, informe: | Campo | Obrigatório | Descrição | | ---------------------- | ----------- | ----------------------------------------------------------- | | **Conta de cobrança** | Sim | A conta do cliente que será cobrada | | **Plano** | Não | Plano pré-configurado (ou itens avulsos) | | **Ciclo de cobrança** | Sim | `monthly`, `quarterly`, `semiannual` ou `annual` | | **Método de cobrança** | Sim | `charge_automatically`, `manual_charge` ou `manual_invoice` | | **Período de trial** | Não | 0 a 90 dias de teste gratuito | | **Código de desconto** | Não | Desconto a ser aplicado | | **Itens** | Não | Produtos, preços e quantidades (se não usar plano) | | **Empresa** | Não | Empresa emissora (para multi-empresa) | ### Fluxo de Criação[​](#fluxo-de-criação "Link direto para Fluxo de Criação") 1. A assinatura é criada no status `draft` 2. Os itens são criados a partir dos itens fornecidos ou dos itens do plano 3. O uso do código de desconto é incrementado (se fornecido) 4. Um evento `subscription.db.created` é emitido ## Confirmação e Ativação[​](#confirmação-e-ativação "Link direto para Confirmação e Ativação") ### Confirmar (`draft` → `confirmed`)[​](#confirmar-draft--confirmed "Link direto para confirmar-draft--confirmed") Confirma a assinatura, opcionalmente criando a primeira fatura. ### Ativar (`draft`/`confirmed` → `trialing`/`active`)[​](#ativar-draftconfirmed--trialingactive "Link direto para ativar-draftconfirmed--trialingactive") * Se tiver período de trial: status muda para `trialing`, com `trial_start` e `trial_end` definidos * Se não tiver trial: status muda diretamente para `active` * Define as datas do período de cobrança (`current_period_start`, `current_period_end`) ### Preview da Ativação[​](#preview-da-ativação "Link direto para Preview da Ativação") Antes de ativar, é possível visualizar: * Data de início, se haverá trial, duração do trial * Datas do período de cobrança * Data da primeira fatura * Totais de setup e recorrentes ## Renovação[​](#renovação "Link direto para Renovação") A renovação é automática via worker diário (00:00 UTC): 1. Busca assinaturas ativas com `currentPeriodEnd ≤ agora` 2. Se `cancelAtPeriodEnd = true`: cancela a assinatura 3. Caso contrário: avança para o próximo período de cobrança 4. Usa lock otimista para prevenir renovações duplicadas ### Cálculo dos Períodos[​](#cálculo-dos-períodos "Link direto para Cálculo dos Períodos") | Ciclo | Duração | | ------------ | -------- | | `monthly` | +1 mês | | `quarterly` | +3 meses | | `semiannual` | +6 meses | | `annual` | +1 ano | ## Cancelamento[​](#cancelamento "Link direto para Cancelamento") ### Cancelar no Fim do Período (`cancelAtPeriodEnd: true`)[​](#cancelar-no-fim-do-período-cancelatperiodend-true "Link direto para cancelar-no-fim-do-período-cancelatperiodend-true") * Define a flag `cancel_at_period_end` * A assinatura continua ativa até o fim do período atual * Na renovação, o status muda para `canceled` * Pode ser revertido antes da data de cancelamento ### Cancelar Imediatamente (`cancelAtPeriodEnd: false`)[​](#cancelar-imediatamente-cancelatperiodend-false "Link direto para cancelar-imediatamente-cancelatperiodend-false") * Status muda para `canceled` imediatamente * A data de cancelamento é registrada * O motivo do cancelamento é armazenado ## Reverter para Confirmado[​](#reverter-para-confirmado "Link direto para Reverter para Confirmado") Assinaturas ativas podem ser revertidas para `confirmed` para permitir edição antes de reativar. Útil para corrigir erros antes da próxima renovação. ## Deleção[​](#deleção "Link direto para Deleção") Apenas assinaturas em `draft`, `confirmed` ou `canceled` podem ser deletadas, e somente se não houver faturas com pagamentos. ## Cálculo do MRR[​](#cálculo-do-mrr "Link direto para Cálculo do MRR") O MRR (Monthly Recurring Revenue) é calculado normalizando o valor total para mensal: | Ciclo | Fórmula | | ------------ | --------------- | | `monthly` | Total dos itens | | `quarterly` | Total ÷ 3 | | `semiannual` | Total ÷ 6 | | `annual` | Total ÷ 12 | ## Eventos Emitidos[​](#eventos-emitidos "Link direto para Eventos Emitidos") | Evento | Quando | | ----------------------------------- | --------------------------------------- | | `subscription.db.created` | Assinatura criada | | `subscription.confirmed` | Confirmada | | `subscription.activated` | Ativada | | `subscription.renewed` | Renovada | | `subscription.paused` | Pausada | | `subscription.resumed` | Retomada | | `subscription.canceled` | Cancelada | | `subscription.pending_cancellation` | Marcada para cancelar no fim do período | | `subscription.plan_changed` | Plano alterado | | `subscription_status_changed` | Qualquer mudança de status | --- # Mudança de Plano (Upgrade/Downgrade) O sistema permite que clientes alterem o plano da assinatura com cálculo automático de proration (rateio proporcional). ## Tipos de Mudança[​](#tipos-de-mudança "Link direto para Tipos de Mudança") | Tipo | Descrição | | ------------- | ---------------------------------- | | **upgrade** | Novo plano mais caro que o atual | | **downgrade** | Novo plano mais barato que o atual | | **lateral** | Mesmo valor (mudança de features) | ## Timing da Mudança[​](#timing-da-mudança "Link direto para Timing da Mudança") | Timing | Descrição | | ------------------- | ------------------------------------------------------------ | | **immediate** | Aplica imediatamente, cobra/credita a diferença proporcional | | **end\_of\_period** | Agenda a mudança para o início do próximo período | ## Proration (Rateio Proporcional)[​](#proration-rateio-proporcional "Link direto para Proration (Rateio Proporcional)") ### Métodos de Proration[​](#métodos-de-proration "Link direto para Métodos de Proration") | Método | Descrição | | ------------------- | --------------------------------------------------------- | | `full_proration` | Credita o plano antigo e cobra o novo pelo tempo restante | | `partial_proration` | Cobra apenas a diferença (somente para upgrade) | | `no_proration` | Sem ajuste de valor no meio do ciclo | ### Fórmula de Cálculo[​](#fórmula-de-cálculo "Link direto para Fórmula de Cálculo") ``` dias_restantes = max(0, teto((fim_período - agora) / 86400000)) total_dias_período = teto((fim_período - início_período) / 86400000)) Full proration: crédito = (preço_antigo × dias_restantes) / total_dias_período cobrança = (preço_novo × dias_restantes) / total_dias_período Partial proration (apenas upgrade): diferença = preço_novo - preço_antigo cobrança = (diferença × dias_restantes) / total_dias_período Cobrança líquida = cobrança - crédito ``` ## Configuração Padrão[​](#configuração-padrão "Link direto para Configuração Padrão") A configuração de mudança de plano define o comportamento padrão: | Configuração | Padrão | | --------------------------- | ---------------- | | Permitir upgrade | Sim | | Permitir downgrade | Sim | | Proration no upgrade | `full_proration` | | Proration no downgrade | `no_proration` | | Timing do upgrade | `immediate` | | Timing do downgrade | `end_of_period` | | Reembolso no downgrade | Não | | Crédito no downgrade | Sim | | Aplicar desconto na mudança | Sim | ## Regras de Mudança de Plano[​](#regras-de-mudança-de-plano "Link direto para Regras de Mudança de Plano") É possível criar regras específicas para controlar transições entre planos: | Campo | Descrição | | ----------------------- | ------------------------------- | | **Plano de origem** | Plano atual (null = qualquer) | | **Plano de destino** | Novo plano (null = qualquer) | | **Tipo de mudança** | upgrade, downgrade ou lateral | | **Permitido** | Se a transição é permitida | | **Timing** | Sobrescreve o timing padrão | | **Método de proration** | Sobrescreve o método padrão | | **Desconto (%)** | Desconto percentual na cobrança | | **Dias bônus** | Extensão do trial | | **Mensagem** | Razão se não permitido | | **Prioridade** | Maior prioridade prevalece | ### Ordem de Prioridade das Regras[​](#ordem-de-prioridade-das-regras "Link direto para Ordem de Prioridade das Regras") 1. Regra com plano de origem **E** plano de destino (mais específica) 2. Regra com apenas plano de origem 3. Regra com apenas plano de destino 4. Regra global (ambos null) ## Preview da Mudança[​](#preview-da-mudança "Link direto para Preview da Mudança") Antes de executar, é possível visualizar: * Se a mudança é permitida * Tipo (upgrade/downgrade/lateral) * Valores de crédito e cobrança proratados * Cobrança líquida final * Data efetiva * Dias restantes no período ## Executando a Mudança[​](#executando-a-mudança "Link direto para Executando a Mudança") ### Mudança Imediata[​](#mudança-imediata "Link direto para Mudança Imediata") 1. Validação e preview são calculados 2. Registro de PlanChange é criado (status: `pending`) 3. Crédito gerado se `prorationCreditSubcents > 0` 4. Fatura gerada se `netChargeSubcents > 0` 5. Assinatura atualizada com o novo plano 6. PlanChange marcado como `completed` ### Mudança Agendada[​](#mudança-agendada "Link direto para Mudança Agendada") 1. Registro de PlanChange criado (status: `scheduled`) 2. Na data efetiva, o worker processa a mudança 3. Assinatura atualizada com o novo plano 4. PlanChange marcado como `completed` > **Limitação**: O sistema mantém apenas **uma mudança agendada** por vez. Uma nova mudança agendada cancela a anterior. ## Cancelar Mudança Agendada[​](#cancelar-mudança-agendada "Link direto para Cancelar Mudança Agendada") Mudanças agendadas podem ser canceladas antes da data efetiva. O status muda para `canceled` e o motivo é registrado. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") A tela `/dashboard/plan-changes` traz o histórico de mudanças de plano da organização, com filtros por status, tipo (upgrade/downgrade/lateral), plano de origem e destino. A aba de configuração centraliza o comportamento padrão de proration e regras por par de planos. ![Histórico e configuração de mudanças de plano](/pt/assets/images/mudancas-de-plano-0a8cced4dbfaeb6c59c35304957b1c36.png) --- # Mudanças de Itens da Assinatura Além das mudanças de plano (upgrade/downgrade), o Faturamento Automático suporta **mudanças nos itens individuais** de uma assinatura — alterar quantidades, adicionar add-ons, trocar um produto avulso ou um item metered sem precisar trocar o plano principal. A tela `/dashboard/subscription-changes` agrupa o histórico dessas mudanças e a configuração padrão de proration. ## Aba Histórico[​](#aba-histórico "Link direto para Aba Histórico") Mostra todas as mudanças de itens registradas na organização. Cada linha corresponde a um registro de `SubscriptionItemChange` e exibe: * **ID da assinatura** afetada * **Status**: `pending`, `scheduled`, `completed`, `canceled` ou `failed` * **Timing**: `immediate` (aplica agora) ou `end_of_period` (aplica no próximo ciclo) * **Mudanças**: itens adicionados, removidos ou alterados (com quantidade e preço) * **Crédito gerado** (`proration_credit`) e **cobrança gerada** (`proration_charge`) * **Data efetiva** e **data de criação** As mudanças `completed` já foram processadas; `scheduled` aguardam o worker da renovação executar na virada do ciclo. ## Aba Configuração[​](#aba-configuração "Link direto para Aba Configuração") Define o comportamento padrão quando um item é adicionado, removido ou tem quantidade alterada: * **Permitir aumento de quantidade** e **permitir redução** — controla quem pode alterar o que. * **Timing padrão** — quando a mudança é aplicada (imediata ou no fim do período). * **Método de proration** — `full_proration`, `partial_proration` ou `no_proration`. * **Crédito em redução** — se gera saldo na conta do cliente ao reduzir quantidade. * **Reembolso em redução** — se devolve via gateway em vez de gerar crédito. A configuração é resolvida por organização e pode ser sobrescrita por regras específicas no momento da mudança via API. ## Diferença entre mudança de itens e mudança de plano[​](#diferença-entre-mudança-de-itens-e-mudança-de-plano "Link direto para Diferença entre mudança de itens e mudança de plano") | Cenário | Tela | | ----------------------------------------------- | --------------------------------------------------------------------------------------------- | | Trocar de **Starter** para **Growth** | [Mudança de Plano](https://docs.billing.kobana.com.br/pt/pt/assinaturas/mudanca-de-plano/.md) | | Adicionar 10 usuários extras ao plano atual | Mudanças de Itens | | Trocar add-on `Email Premium` por `SMS Premium` | Mudanças de Itens | | Reduzir quantidade de licenças no fim do ciclo | Mudanças de Itens | Ambos os fluxos geram proration quando aplicável, e ambos disparam eventos e webhooks (`subscription.updated`, `subscription_item.changed`). ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Histórico e configuração de mudanças de itens de assinatura](/pt/assets/images/mudancas-de-itens-2197d883ab5bb0a47a9f43ce879a6103.png) --- # Pausar Assinatura A funcionalidade de pausar assinaturas permite suspender temporariamente a cobrança de um cliente sem cancelar a assinatura. É uma ferramenta estratégica de retenção. ## Benefícios[​](#benefícios "Link direto para Benefícios") * **Reduzir churn**: Evita cancelamentos oferecendo uma alternativa temporária * **Manter receita**: O serviço continua ativo pelo período já pago * **Flexibilidade**: Atende situações como férias, restrições orçamentárias ou uso sazonal * **Experiência do cliente**: Demonstra comprometimento com as necessidades do assinante ## Pré-requisitos[​](#pré-requisitos "Link direto para Pré-requisitos") Para pausar uma assinatura, ela deve: * Estar com status `active` ou `past_due` * Não pode ser uma assinatura futura, em trial ou cancelada ## Comportamento da Pausa[​](#comportamento-da-pausa "Link direto para Comportamento da Pausa") Ao pausar uma assinatura, você configura: | Campo | Descrição | | --------------- | ------------------------------------ | | **Behavior** | Como tratar faturas pendentes | | **Retomada em** | Data opcional de retomada automática | ### Comportamento para Faturas Pendentes[​](#comportamento-para-faturas-pendentes "Link direto para Comportamento para Faturas Pendentes") | Behavior | Descrição | | -------------------- | ---------------------------------------- | | `mark_uncollectible` | Marca faturas pendentes como incobráveis | | `keep_as_draft` | Mantém faturas futuras como rascunho | | `void` | Anula faturas pendentes | ## Efeitos da Pausa[​](#efeitos-da-pausa "Link direto para Efeitos da Pausa") * Status muda para `paused` * **Nenhuma fatura é gerada** durante a pausa * **Nenhuma cobrança** é realizada * O período atual não é alterado * **Cupons continuam expirando** normalmente (não pausam junto) * **MRR**: Contribuição zero durante a pausa * **Analytics**: Assinaturas pausadas contam como "ativas" (não como churn) ## Retomada[​](#retomada "Link direto para Retomada") ### Retomada Manual[​](#retomada-manual "Link direto para Retomada Manual") 1. Acesse a assinatura no dashboard 2. Clique em "Retomar" 3. O status volta para `active` 4. O campo de pausa é limpo 5. Um novo ciclo de cobrança se inicia ### Retomada Automática[​](#retomada-automática "Link direto para Retomada Automática") Se uma data de retomada (`pause_collection.resumes_at`) foi definida, a assinatura é retomada automaticamente nessa data. ## Eventos[​](#eventos "Link direto para Eventos") | Evento | Descrição | | ---------------------- | ------------------- | | `subscription.paused` | Assinatura pausada | | `subscription.resumed` | Assinatura retomada | ## Considerações[​](#considerações "Link direto para Considerações") * Cada pausa deve ser concluída antes de iniciar outra * Mudanças na assinatura durante a pausa cancelam a pausa agendada * Fechar a conta do cliente encerra imediatamente todas as assinaturas pausadas * Assinaturas pausadas não aparecem na listagem de "pendentes de faturamento" --- # Termos de Cobrança Os termos de cobrança definem como e quando o cliente é cobrado pela assinatura. ## Ciclos de Cobrança[​](#ciclos-de-cobrança "Link direto para Ciclos de Cobrança") | Ciclo | Frequência | Duração | | ------------ | ---------- | -------- | | `monthly` | Mensal | 1 mês | | `quarterly` | Trimestral | 3 meses | | `semiannual` | Semestral | 6 meses | | `annual` | Anual | 12 meses | ### Âncora de Cobrança[​](#âncora-de-cobrança "Link direto para Âncora de Cobrança") Os períodos de cobrança são calculados inteiramente a partir de `current_period_start` e `current_period_end`, que avançam a cada renovação. O dia de cobrança do ciclo fica em `cycle_billing_date`, definido na ativação da assinatura. ### Período Atual[​](#período-atual "Link direto para Período Atual") * `current_period_start`: Início do período de cobrança atual * `current_period_end`: Fim do período de cobrança atual ## Métodos de Cobrança[​](#métodos-de-cobrança "Link direto para Métodos de Cobrança") | Método | Geração de Fatura | Cobrança | | ---------------------- | ----------------- | ---------- | | `charge_automatically` | Automática | Automática | | `manual_charge` | Automática | Manual | | `manual_invoice` | Manual | Manual | ### Cobrança Automática (`charge_automatically`)[​](#cobrança-automática-charge_automatically "Link direto para cobrança-automática-charge_automatically") * A fatura é gerada automaticamente pelo worker * Na finalização, o sistema tenta cobrar automaticamente usando o método de pagamento padrão do cliente * Para cartão: cobrança imediata * Para boleto/PIX: gera a cobrança e aguarda confirmação via webhook * Em caso de falha: agenda tentativas de retry (dunning) ### Cobrança Manual com Fatura Automática (`manual_charge`)[​](#cobrança-manual-com-fatura-automática-manual_charge "Link direto para cobrança-manual-com-fatura-automática-manual_charge") * A fatura é criada automaticamente pelo worker * O cliente recebe a fatura por e-mail * O pagamento é realizado manualmente (boleto, PIX) ou o operador aciona a cobrança ### Fatura e Cobrança Manual (`manual_invoice`)[​](#fatura-e-cobrança-manual-manual_invoice "Link direto para fatura-e-cobrança-manual-manual_invoice") * Nenhuma fatura é gerada automaticamente * O operador cria as faturas manualmente quando necessário * Útil para cobranças avulsas ou faturamento irregular ## Comportamento de Proration[​](#comportamento-de-proration "Link direto para Comportamento de Proration") Configura como a mudança de plano no meio do ciclo é tratada: | Comportamento | Descrição | | ------------------- | ------------------------------------------------ | | `create_prorations` | Cria créditos e cobranças proporcionais (padrão) | | `none` | Nenhum ajuste proporcional | | `always_invoice` | Sempre gera fatura para a diferença | ## Período de Trial[​](#período-de-trial "Link direto para Período de Trial") * Configurável de 0 a 90 dias * Durante o trial, a assinatura fica no status `trialing` * Ao fim do trial, a assinatura muda para `active` e o período de cobrança começa ## Permissões da Assinatura[​](#permissões-da-assinatura "Link direto para Permissões da Assinatura") | Configuração | Descrição | | -------------- | --------------------------------------- | | `allow_pause` | Se o cliente pode pausar a assinatura | | `allow_cancel` | Se o cliente pode cancelar a assinatura | Essas configurações podem ser definidas por assinatura e controlam as opções disponíveis no portal do cliente. --- # Autenticação :::caution Produtos não compartilham credenciais `KOBANA_TOKEN` guarda a credencial **de um produto por vez**. Um token do Faturamento Automático não autentica em nenhum outro produto Kobana, e vice-versa. ::: ## O token[​](#o-token "Link direto para O token") O Faturamento Automático autentica com um **JWT assinado em RS256** pelo servidor de autorização da Kobana, enviado como `Authorization: Bearer `. Veja [Autenticação da API](https://docs.billing.kobana.com.br/pt/pt/api/overview/authentication.md) para como esse token é emitido e quais escopos ele carrega — `kobana auth login`, que é do Gateway Bancário, **não** produz esse token. Coloque o JWT em `KOBANA_TOKEN` antes de chamar o produto: ``` export KOBANA_TOKEN=$JWT_BILLING kobana billing subscriptions list --fields "id,status,plan_id" ``` Como a variável é a mesma para todos os produtos, exporte-a por comando (ou use um `.env` por projeto) se você alterna entre produtos na mesma sessão: ``` KOBANA_TOKEN=$JWT_BILLING kobana billing subscriptions list --fields "id,status,plan_id" ``` ## Escopos[​](#escopos "Link direto para Escopos") Cada comando exige do token o mesmo nível de acesso que o endpoint por trás dele — um nível por comando, e nenhum substitui outro: | Comando | Nível | | -------------------------------------------------------------------------- | -------- | | `list`, `get` e as outras leituras | `read` | | `create`, `update` e as outras ações (`archive`, `unarchive`, `cancel`, …) | `write` | | `delete` e `bulk delete` | `delete` | | `nfes import-barueri create` | `import` | `all` vale por todos. Um token só com `write` recebe `403 insufficient_scope` em `delete`: peça também o nível `delete` na Conta Kobana se a sua automação exclui. Veja [Autenticação da API](https://docs.billing.kobana.com.br/pt/pt/api/overview/authentication.md) para os seis níveis e os endpoints que mudaram de método — as exclusões em lote, por exemplo, viraram `bulk delete` (`DELETE /v1/{recurso}/bulk`). ## Prioridade de resolução[​](#prioridade-de-resolução "Link direto para Prioridade de resolução") | Prioridade | Método | Configuração | | ---------- | ---------------------- | ----------------------------------------- | | 1 | Token direto | `KOBANA_TOKEN` | | 2 | Arquivo de credenciais | `KOBANA_CREDENTIALS_FILE` | | 3 | Credenciais salvas | `kobana auth login` (só Gateway Bancário) | ## Ambientes[​](#ambientes "Link direto para Ambientes") O CLI opera em três ambientes, e cada produto tem os seus próprios hosts. **Produção é o padrão.** | Ambiente | API | `--env` | | -------- | ----------------------------------- | --------------------- | | Produção | `api.billing.kobana.com.br` | `production` (padrão) | | Sandbox | `api.billing.sandbox.kobana.com.br` | `sandbox` | O Faturamento Automático não tem host de desenvolvimento próprio: com `--env development` o CLI cai em produção. ``` # Produção (padrão — sem flag) kobana billing subscriptions list # Sandbox kobana billing subscriptions list --env sandbox # Via variável de ambiente export KOBANA_ENVIRONMENT=sandbox kobana billing subscriptions list ``` Os tokens são **diferentes entre ambientes** — um token de sandbox não funciona em produção, e vice-versa. ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Uso](https://docs.billing.kobana.com.br/pt/pt/cli/usage/overview.md) — sintaxe, recursos, exemplos. * [Variáveis de ambiente](https://docs.billing.kobana.com.br/pt/pt/cli/overview/environment-variables.md) — a referência completa, incluindo configuração e logs. --- # Variáveis de ambiente Todas as variáveis também podem ser definidas em um arquivo `.env` (carregado via `dotenvy`). ## Autenticação[​](#autenticação "Link direto para Autenticação") | Variável | Descrição | | -------------------------- | --------------------------------------------------------------------------------- | | `KOBANA_TOKEN` | Token do produto que você vai chamar (Bearer). Não é compartilhado entre produtos | | `KOBANA_CREDENTIALS_FILE` | Caminho para um arquivo JSON de credenciais OAuth | | `KOBANA_CLIENT_ID` | OAuth client ID (Gateway Bancário) | | `KOBANA_CLIENT_SECRET` | OAuth client secret (Gateway Bancário) | | `KOBANA_INBOX_CLIENT_CERT` | Caminho para o PEM (certificado + chave) usado no mTLS do `inbox` | ## Configuração[​](#configuração "Link direto para Configuração") | Variável | Descrição | | -------------------- | ------------------------------------------------------ | | `KOBANA_CONFIG_DIR` | Diretório de configuração (padrão: `~/.config/kobana`) | | `KOBANA_ENVIRONMENT` | `production` (padrão), `sandbox` ou `development` | ## Logs[​](#logs "Link direto para Logs") | Variável | Descrição | | ----------------- | ----------------------------------------------------------------------------- | | `KOBANA_LOG` | Nível de log no stderr (ex.: `kobana=debug`). Desligado por padrão. | | `KOBANA_LOG_FILE` | Diretório para arquivos de log JSON com rotação diária. Desligado por padrão. | ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Autenticação](https://docs.billing.kobana.com.br/pt/pt/cli/overview/authentication.md) — prioridade de resolução e credenciais por produto. * [Códigos de saída](https://docs.billing.kobana.com.br/pt/pt/cli/overview/exit-codes.md) — códigos de saída do processo, para scripts. --- # Códigos de saída Toda execução do `kobana` termina com um destes códigos, para que um script decida o que fazer sem precisar interpretar o corpo JSON do erro. | Código | Significado | | ------ | --------------------- | | `0` | Sucesso | | `1` | Erro de API (4xx/5xx) | | `2` | Erro de autenticação | | `3` | Erro de validação | | `4` | Erro de schema | | `5` | Erro interno | ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Uso](https://docs.billing.kobana.com.br/pt/pt/cli/usage/overview.md) — sintaxe, recursos, exemplos. * [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) — `--dry-run`, `--output-format` e as demais. --- # Instalação ### Homebrew (macOS e Linux)[​](#homebrew-macos-e-linux "Link direto para Homebrew (macOS e Linux)") ``` brew tap universokobana/tap brew install kobana ``` Para atualizar: ``` brew update && brew upgrade kobana ``` ### Binários pré-compilados[​](#binários-pré-compilados "Link direto para Binários pré-compilados") Baixe o binário da sua plataforma na [página de Releases](https://github.com/universokobana/kobana-cli/releases/latest) e coloque no seu `PATH`. | Plataforma | Arquivo | | ------------------- | -------------------------- | | Linux x86\_64 | `kobana-linux-amd64` | | Linux ARM64 | `kobana-linux-arm64` | | macOS Intel | `kobana-darwin-amd64` | | macOS Apple Silicon | `kobana-darwin-arm64` | | Windows x86\_64 | `kobana-windows-amd64.exe` | ### Nix[​](#nix "Link direto para Nix") ``` # Rodar direto do GitHub nix run github:universokobana/kobana-cli # Instalar no perfil nix profile install github:universokobana/kobana-cli ``` ### Build a partir do source[​](#build-a-partir-do-source "Link direto para Build a partir do source") ``` git clone https://github.com/universokobana/kobana-cli.git cd kobana-cli cargo install --path crates/kobana-cli ``` Requer [Rust](https://rustup.rs/) 1.70+. ## Completions de shell[​](#completions-de-shell "Link direto para Completions de shell") ``` # Bash kobana completions bash > /etc/bash_completion.d/kobana # Zsh kobana completions zsh > ~/.zfunc/_kobana # Fish kobana completions fish > ~/.config/fish/completions/kobana.fish # PowerShell kobana completions powershell > kobana.ps1 ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Autenticação](https://docs.billing.kobana.com.br/pt/pt/cli/overview/authentication.md) — tokens e ambientes. * [Uso](https://docs.billing.kobana.com.br/pt/pt/cli/usage/overview.md) — sintaxe, recursos, exemplos. --- # Introdução **`kobana`** é uma ferramenta de linha de comando única para as APIs de todos os produtos Kobana — o Faturamento Automático incluído. Ela é construída e mantida em repositório próprio ([`kobana-cli`](https://github.com/universokobana/kobana-cli)), não por este produto, e não tem endpoint algum escrito à mão: na inicialização ela lê as specs OpenAPI 3.1 embutidas no binário e monta a árvore de comandos a partir delas. Atualizar a superfície da API é questão de atualizar a spec embutida e publicar um build novo — nenhum código por endpoint. ``` kobana [flags] ``` Pensada tanto para pessoas quanto para agentes de IA: saída JSON estruturada por padrão, introspecção de schema, `--dry-run` e paginação automática. ## Produtos[​](#produtos "Link direto para Produtos") | Produto | Descrição | | ------------ | -------------------------------------------------------------------------------- | | `banking` | Gateway Bancário — cobranças, pagamentos, transferências (API v1 e v2) | | `finance` | Financeiro Inteligente — contas a pagar e a receber, lançamentos, fluxo de caixa | | `billing` | Faturamento Automático — assinaturas, planos, faturas, notas fiscais | | `inbox` | Inbox Autônomo — caixas de entrada, agentes, e-mails, webhooks | | `dunning` | Régua de Cobrança — clientes, cobranças, réguas, acordos, negativações | | `dashboards` | Dashboard Mágico — fontes de dados, entidades, portal, workspaces | O produto `billing` fala com a mesma API documentada neste site. Os recursos dele — veja o [catálogo completo](https://docs.billing.kobana.com.br/pt/pt/cli/resources/overview.md) — apontam para os mesmos endpoints da [Referência da API](https://docs.billing.kobana.com.br/pt/pt/api/v1); o CLI é só mais um jeito de chamá-la. Ele não compartilha credenciais com os outros produtos: veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/cli/overview/authentication.md). ## Começando[​](#começando "Link direto para Começando") 1. **Instale** — veja [Instalação](https://docs.billing.kobana.com.br/pt/pt/cli/overview/installation.md). 2. **Autentique-se** no produto que você vai usar. Veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/cli/overview/authentication.md). 3. **Faça a primeira chamada**: ``` kobana billing subscriptions list --fields "id,status,plan_id" ``` 4. **Explore a superfície** — todo comando aceita `--help`, e `kobana schema` mostra parâmetros e corpo de qualquer endpoint sem sair do terminal. ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Instalação](https://docs.billing.kobana.com.br/pt/pt/cli/overview/installation.md) — Homebrew, binários prontos, Nix, build a partir do source. * [Autenticação](https://docs.billing.kobana.com.br/pt/pt/cli/overview/authentication.md) — tokens, ambientes e as credenciais próprias do `billing`. * [Uso](https://docs.billing.kobana.com.br/pt/pt/cli/usage/overview.md) — sintaxe, recursos, exemplos. * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — `kobana schema` para parâmetros e formato de requisição e resposta. * [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) — as flags que todo comando aceita. * [Helpers](https://docs.billing.kobana.com.br/pt/pt/cli/usage/helpers.md) — atalhos `+verbo` para fluxos comuns. * [Variáveis de ambiente](https://docs.billing.kobana.com.br/pt/pt/cli/overview/environment-variables.md) — autenticação, configuração e logs. * [Códigos de saída](https://docs.billing.kobana.com.br/pt/pt/cli/overview/exit-codes.md) — códigos de saída do processo, para scripts. --- # Contas de cobrança A conta que acumula assinaturas, faturas e créditos de um cliente. Suspender interrompe a cobrança sem encerrar o relacionamento; fechar encerra. | Comando | HTTP | Descrição | | -------------------------------- | --------------------------------------------- | --------------------------------------- | | `billing-accounts list` | `GET /v1/billing_accounts` | Listar contas de cobrança | | `billing-accounts create` | `POST /v1/billing_accounts` | Criar conta de cobrança | | `billing-accounts get` | `GET /v1/billing_accounts/{id}` | Obter conta de cobrança | | `billing-accounts update` | `PATCH /v1/billing_accounts/{id}` | Atualizar conta de cobrança | | `billing-accounts delete` | `DELETE /v1/billing_accounts/{id}` | Excluir conta de cobrança (soft delete) | | `billing-accounts close` | `POST /v1/billing_accounts/{id}/close` | Fechar conta de cobrança (POST /close) | | `billing-accounts credits` | `GET /v1/billing_accounts/{id}/credits` | Listar créditos da conta | | `billing-accounts entitlements` | `GET /v1/billing_accounts/{id}/entitlements` | Listar produtos contratados da conta | | `billing-accounts invoices` | `GET /v1/billing_accounts/{id}/invoices` | Listar faturas da conta | | `billing-accounts reactivate` | `POST /v1/billing_accounts/{id}/reactivate` | Reativar conta de cobrança | | `billing-accounts subscriptions` | `GET /v1/billing_accounts/{id}/subscriptions` | Listar assinaturas da conta | | `billing-accounts suspend` | `POST /v1/billing_accounts/{id}/suspend` | Suspender conta de cobrança | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar contas de cobrança kobana billing billing-accounts list \ --fields "id,public_id,external_id,currency,billing_email" # Obter conta de cobrança kobana billing billing-accounts get --params '{"id": "BILLING_ACCOUNT_ID"}' # Criar conta de cobrança kobana billing billing-accounts create --json '{"customer": "CUSTOMER"}' # Atualizar conta de cobrança kobana billing billing-accounts update \ --params '{"id": "BILLING_ACCOUNT_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "name": "NAME", "email": "EMAIL"}' # Fechar conta de cobrança (POST /close) kobana billing billing-accounts close \ --params '{"id": "BILLING_ACCOUNT_ID"}' \ --json '{"reason": "REASON"}' # Excluir conta de cobrança (soft delete) kobana billing billing-accounts delete \ --params '{"id": "BILLING_ACCOUNT_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Faturas](https://docs.billing.kobana.com.br/pt/pt/cli/resources/invoices.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Certificados digitais Os certificados A1 usados para assinar a emissão fiscal. O arquivo é enviado uma vez e nunca volta na resposta. | Comando | HTTP | Descrição | | --------------------- | ------------------------------ | ---------------------------- | | `certificates list` | `GET /v1/certificates` | Listar certificados digitais | | `certificates create` | `POST /v1/certificates` | Enviar certificado digital | | `certificates get` | `GET /v1/certificates/{id}` | Obter certificado | | `certificates delete` | `DELETE /v1/certificates/{id}` | Remover certificado | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar certificados digitais kobana billing certificates list \ --fields "id,public_id,external_id,person_id,name" # Obter certificado kobana billing certificates get --params '{"id": "CERTIFICATE_ID"}' # Enviar certificado digital kobana billing certificates create # Remover certificado kobana billing certificates delete \ --params '{"id": "CERTIFICATE_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Consumo](https://docs.billing.kobana.com.br/pt/pt/cli/resources/usage.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Empresas As empresas emissoras — quem cobra. Carregam o perfil fiscal usado na emissão de nota, e uma delas é a padrão. | Comando | HTTP | Descrição | | --------------------------------- | ----------------------------------------- | ------------------------------------ | | `companies list` | `GET /v1/companies` | Listar empresas | | `companies create` | `POST /v1/companies` | Criar empresa | | `companies get` | `GET /v1/companies/{id}` | Obter empresa por ID | | `companies update` | `PATCH /v1/companies/{id}` | Atualizar empresa | | `companies delete` | `DELETE /v1/companies/{id}` | Excluir empresa (soft delete) | | `companies deactivate` | `POST /v1/companies/{id}/deactivate` | Desativar empresa (POST /deactivate) | | `companies reactivate` | `POST /v1/companies/{id}/reactivate` | Reativar empresa | | `companies set-default` | `POST /v1/companies/{id}/set-default` | Definir empresa padrão | | `companies fiscal get` | `GET /v1/companies/{id}/fiscal` | Obter perfil fiscal | | `companies fiscal update` | `PATCH /v1/companies/{id}/fiscal` | Atualizar perfil fiscal | | `companies fiscal-profile get` | `GET /v1/companies/{id}/fiscal-profile` | Obter perfil fiscal (alias) | | `companies fiscal-profile update` | `PATCH /v1/companies/{id}/fiscal-profile` | Atualizar perfil fiscal (alias) | | `companies matriz list` | `GET /v1/companies/matriz` | Listar matrizes | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar empresas kobana billing companies list \ --fields "id,public_id,external_id,organization_id,person_id" # Obter empresa por ID kobana billing companies get --params '{"id": "COMPANIE_ID"}' # Criar empresa kobana billing companies create \ --json '{"name": "NAME", "document_type": "cpf", "document_number": "DOCUMENT_NUMBER", "email": "EMAIL"}' # Atualizar empresa kobana billing companies update \ --params '{"id": "COMPANIE_ID"}' \ --json '{"name": "NAME", "external_id": "EXTERNAL_ID", "legal_name": "LEGAL_NAME"}' # Desativar empresa (POST /deactivate) kobana billing companies deactivate --params '{"id": "COMPANIE_ID"}' # Excluir empresa kobana billing companies delete --params '{"id": "COMPANIE_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Organização](https://docs.billing.kobana.com.br/pt/pt/cli/resources/organization.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Cupons Descontos com regra de validade e limite de uso. `redemptions` mostra onde cada cupom foi efetivamente aplicado. | Comando | HTTP | Descrição | | --------------------- | ---------------------------------- | ------------------------ | | `coupons list` | `GET /v1/coupons` | Listar cupons | | `coupons create` | `POST /v1/coupons` | Criar cupom | | `coupons get` | `GET /v1/coupons/{id}` | Obter cupom | | `coupons update` | `PATCH /v1/coupons/{id}` | Atualizar cupom | | `coupons delete` | `DELETE /v1/coupons/{id}` | Excluir cupom | | `coupons deactivate` | `POST /v1/coupons/{id}/deactivate` | Desativar cupom | | `coupons redemptions` | `GET /v1/coupons/{id}/redemptions` | Listar resgates do cupom | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar cupons kobana billing coupons list --fields "id,public_id,external_id,code,name" # Obter cupom kobana billing coupons get --params '{"id": "COUPON_ID"}' # Criar cupom kobana billing coupons create \ --json '{"code": "CODE", "name": "NAME", "discount_type": "percentage", "discount_value": 0}' # Atualizar cupom kobana billing coupons update \ --params '{"id": "COUPON_ID"}' \ --json '{"name": "NAME", "external_id": "EXTERNAL_ID", "description": "DESCRIPTION"}' # Desativar cupom kobana billing coupons deactivate --params '{"id": "COUPON_ID"}' # Excluir cupom kobana billing coupons delete --params '{"id": "COUPON_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Clientes](https://docs.billing.kobana.com.br/pt/pt/cli/resources/customers.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Créditos Saldo a favor do cliente, aplicável a faturas futuras. Aplicar e remover créditos são comandos da própria fatura. | Comando | HTTP | Descrição | | ---------------- | ------------------------- | ----------------- | | `credits list` | `GET /v1/credits` | Listar créditos | | `credits create` | `POST /v1/credits` | Adicionar crédito | | `credits get` | `GET /v1/credits/{id}` | Obter crédito | | `credits update` | `PATCH /v1/credits/{id}` | Atualizar crédito | | `credits delete` | `DELETE /v1/credits/{id}` | Excluir crédito | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar créditos kobana billing credits list \ --fields "id,public_id,external_id,billing_account_id,organization_id" # Obter crédito kobana billing credits get --params '{"id": "CREDIT_ID"}' # Adicionar crédito kobana billing credits create \ --json '{"billing_account_id": "BILLING_ACCOUNT_ID", "type": "promotional", "amount_cents": 10000}' # Atualizar crédito kobana billing credits update \ --params '{"id": "CREDIT_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "type": "promotional", "amount_cents": 100}' # Excluir crédito kobana billing credits delete --params '{"id": "CREDIT_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Retenções](https://docs.billing.kobana.com.br/pt/pt/cli/resources/withholdings.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Clientes Quem é cobrado, seus usuários de portal e o extrato consolidado. `recalculate-mrr` recalcula a receita recorrente do cliente. | Comando | HTTP | Descrição | | --------------------------------- | ------------------------------------------------------ | ------------------------------------------- | | `customers list` | `GET /v1/customers` | Listar clientes | | `customers create` | `POST /v1/customers` | Criar cliente | | `customers get` | `GET /v1/customers/{id}` | Obter cliente | | `customers update` | `PATCH /v1/customers/{id}` | Atualizar cliente | | `customers delete` | `DELETE /v1/customers/{id}` | Remover cliente (soft delete) | | `customers recalculate-mrr` | `POST /v1/customers/{id}/recalculate-mrr` | Recalcular o MRR do cliente | | `customers statement list` | `GET /v1/customers/{id}/statement` | Listar extrato financeiro do cliente | | `customers statement sync create` | `POST /v1/customers/{id}/statement/sync` | Reconstruir o extrato a partir do histórico | | `customers users list` | `GET /v1/customers/{id}/users` | Listar usuários do portal do cliente | | `customers users get` | `GET /v1/customers/{id}/users/{user_id}` | Obter usuário do portal | | `customers users create` | `POST /v1/customers/{id}/users` | Convidar usuário do portal | | `customers users update` | `PATCH /v1/customers/{id}/users/{user_id}` | Atualizar usuário do portal | | `customers users delete` | `DELETE /v1/customers/{id}/users/{user_id}` | Excluir usuário do portal (soft delete) | | `customers users email-preview` | `GET /v1/customers/{id}/users/{user_id}/email-preview` | Pré-visualizar e-mail do usuário do portal | | `customers users resend` | `POST /v1/customers/{id}/users/{user_id}/resend` | Reenviar e-mail de convite ou verificação | | `customers users invite create` | `POST /v1/customers/{id}/users/invite` | Convidar usuário do portal (verbo) | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar clientes kobana billing customers list \ --fields "id,public_id,external_id,name,nickname" # Obter cliente kobana billing customers get --params '{"id": "CUSTOMER_ID"}' # Criar cliente kobana billing customers create --json '{"name": "NAME"}' # Atualizar cliente kobana billing customers update \ --params '{"id": "CUSTOMER_ID"}' \ --json '{"name": "NAME", "external_id": "EXTERNAL_ID", "nickname": "NICKNAME"}' # Recalcular o MRR do cliente kobana billing customers recalculate-mrr --params '{"id": "CUSTOMER_ID"}' # Remover cliente (soft delete) kobana billing customers delete --params '{"id": "CUSTOMER_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Empresas](https://docs.billing.kobana.com.br/pt/pt/cli/resources/companies.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Usuários do painel Quem tem acesso ao painel da sua organização — os operadores, não os clientes. | Comando | HTTP | Descrição | | ------------------------ | --------------------------------- | ------------------------------ | | `dashboard-users list` | `GET /v1/dashboard_users` | Listar usuários do dashboard | | `dashboard-users create` | `POST /v1/dashboard_users` | Convidar usuário do dashboard | | `dashboard-users get` | `GET /v1/dashboard_users/{id}` | Obter usuário do dashboard | | `dashboard-users update` | `PATCH /v1/dashboard_users/{id}` | Atualizar usuário do dashboard | | `dashboard-users delete` | `DELETE /v1/dashboard_users/{id}` | Remover usuário do dashboard | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar usuários do dashboard kobana billing dashboard-users list \ --fields "id,public_id,organization_id,person_id,external_id" # Obter usuário do dashboard kobana billing dashboard-users get --params '{"id": "DASHBOARD_USER_ID"}' # Convidar usuário do dashboard kobana billing dashboard-users create \ --json '{"email": "EMAIL", "role_ids": []}' # Atualizar usuário do dashboard kobana billing dashboard-users update \ --params '{"id": "DASHBOARD_USER_ID"}' \ --json '{"name": "NAME", "picture": "PICTURE", "status": "active"}' # Remover usuário do dashboard kobana billing dashboard-users delete \ --params '{"id": "DASHBOARD_USER_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Papéis de equipe](https://docs.billing.kobana.com.br/pt/pt/cli/resources/team-roles.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Faturas O documento a cobrar, do rascunho ao pago. `finalize` sela o rascunho, `pay` registra a liquidação, `void` anula, e as parcelas vivem em `installments`. | Comando | HTTP | Descrição | | --------------------------------- | --------------------------------------------------------------- | --------------------------------------- | | `invoices list` | `GET /v1/invoices` | Listar faturas | | `invoices create` | `POST /v1/invoices` | Criar fatura | | `invoices get` | `GET /v1/invoices/{id}` | Obter fatura | | `invoices update` | `PATCH /v1/invoices/{id}` | Atualizar fatura | | `invoices delete` | `DELETE /v1/invoices/{id}` | Excluir fatura | | `invoices apply-credits` | `POST /v1/invoices/{id}/apply-credits` | Aplicar créditos na fatura | | `invoices finalize` | `POST /v1/invoices/{id}/finalize` | Finalizar fatura | | `invoices issue-nfe` | `POST /v1/invoices/{id}/issue-nfe` | Emitir NFe para fatura | | `invoices pay` | `POST /v1/invoices/{id}/pay` | Pagar fatura | | `invoices payment-methods` | `GET /v1/invoices/{id}/payment-methods` | Listar métodos de pagamento disponíveis | | `invoices pdf` | `GET /v1/invoices/{id}/pdf` | Baixar PDF da fatura | | `invoices remove-credits` | `POST /v1/invoices/{id}/remove-credits` | Remover créditos aplicados | | `invoices send-reminder` | `POST /v1/invoices/{id}/send-reminder` | Enviar lembrete de cobrança | | `invoices undo-payment` | `POST /v1/invoices/{id}/undo-payment` | Desfazer pagamento da fatura | | `invoices void` | `POST /v1/invoices/{id}/void` | Cancelar (void) fatura | | `invoices installments get` | `GET /v1/invoices/{id}/installments` | Listar parcelas da fatura | | `invoices installments create` | `POST /v1/invoices/{id}/installments` | Criar/atualizar parcelamento | | `invoices installments mark-paid` | `POST /v1/invoices/{id}/installments/{installmentId}/mark-paid` | Marcar parcela como paga | | `invoices installments pay` | `POST /v1/invoices/{id}/installments/{installmentId}/pay` | Pagar parcela | | `invoices pending-nfe list` | `GET /v1/invoices/pending-nfe` | Listar faturas com NFe pendente | | `invoices pending-payment list` | `GET /v1/invoices/pending-payment` | Listar faturas com pagamento pendente | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar faturas kobana billing invoices list \ --fields "id,public_id,external_id,number,billing_account_id" # Obter fatura kobana billing invoices get --params '{"id": "INVOICE_ID"}' # Criar fatura kobana billing invoices create \ --json '{"billing_account_id": "BILLING_ACCOUNT_ID", "line_items": []}' # Atualizar fatura kobana billing invoices update \ --params '{"id": "INVOICE_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "company_id": "COMPANY_ID", "collection_method": "charge_automatically"}' # Aplicar créditos na fatura kobana billing invoices apply-credits \ --params '{"id": "INVOICE_ID"}' \ --json '{"credit_ids": []}' # Excluir fatura kobana billing invoices delete --params '{"id": "INVOICE_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Pagamentos](https://docs.billing.kobana.com.br/pt/pt/cli/resources/payments.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Notas fiscais A emissão fiscal de uma fatura: emitir, cancelar, baixar PDF e XML, e acompanhar cada tentativa junto à prefeitura. Barueri tem comandos próprios. | Comando | HTTP | Descrição | | ------------------------------ | ---------------------------------------- | --------------------------------------------- | | `nfes list` | `GET /v1/nfes` | Listar NFes | | `nfes create` | `POST /v1/nfes` | Criar NFe (rascunho) | | `nfes get` | `GET /v1/nfes/{id}` | Obter NFe | | `nfes update` | `PATCH /v1/nfes/{id}` | Atualizar NFe (rascunho) | | `nfes delete` | `DELETE /v1/nfes/{id}` | Excluir NFe | | `nfes cancel` | `POST /v1/nfes/{id}/cancel` | Cancelar NFe | | `nfes issue` | `POST /v1/nfes/{id}/issue` | Emitir NFe | | `nfes pdf` | `GET /v1/nfes/{id}/pdf` | Baixar PDF da NFe | | `nfes retry-cancel` | `POST /v1/nfes/{id}/retry-cancel` | Retentar cancelamento da NFe | | `nfes validate-barueri` | `POST /v1/nfes/{id}/validate-barueri` | Validar NFS-e Barueri | | `nfes xml` | `GET /v1/nfes/{id}/xml` | Baixar XML da NFe | | `nfes bulk create` | `POST /v1/nfes/bulk` | Atualizar NFes em lote | | `nfes bulk delete` | `DELETE /v1/nfes/bulk` | Excluir NFes em lote | | `nfes fetch-barueri create` | `POST /v1/nfes/fetch-barueri` | Buscar NFS-e em Barueri | | `nfes fetch-from-sefaz create` | `POST /v1/nfes/fetch-from-sefaz` | Buscar NFS-e no ADN (SEFAZ) | | `nfes import-barueri create` | `POST /v1/nfes/import-barueri` | Importar NFS-e Barueri | | `nfes request-tries list` | `GET /v1/nfes/request-tries` | Listar tentativas de requisição (organização) | | `nfes request-tries get` | `GET /v1/nfes/{id}/request-tries` | Listar tentativas de requisição da NFe | | `nfes requests list` | `GET /v1/nfes/{id}/requests` | Listar requisições externas da NFe | | `nfes requests get` | `GET /v1/nfes/{id}/requests/{requestId}` | Obter requisição externa | | `nfes sync create` | `POST /v1/nfes/sync` | Sincronizar NFes da organização | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar NFes kobana billing nfes list \ --fields "id,public_id,external_id,invoice_id,transaction_id" # Obter NFe kobana billing nfes get --params '{"id": "NFE_ID"}' # Criar NFe (rascunho) kobana billing nfes create \ --json '{"billing_account_id": "BILLING_ACCOUNT_ID", "amount_cents": 100, "customer": {}}' # Atualizar NFe (rascunho) kobana billing nfes update \ --params '{"id": "NFE_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "service_code": "SERVICE_CODE", "service_description": "SERVICE_DESCRIPTION"}' # Cancelar NFe kobana billing nfes cancel \ --params '{"id": "NFE_ID"}' \ --json '{"reason": "REASON"}' # Excluir NFe kobana billing nfes delete --params '{"id": "NFE_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Regras de imposto](https://docs.billing.kobana.com.br/pt/pt/cli/resources/tax-rules.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Organização As configurações no topo da hierarquia, comuns a todas as empresas da conta. | Comando | HTTP | Descrição | | --------------------- | ------------------------ | --------------------------- | | `organization list` | `GET /v1/organization` | Obter organização atual | | `organization update` | `PATCH /v1/organization` | Atualizar organização atual | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Obter organização atual kobana billing organization list \ --fields "id,public_id,external_id,status,created_at" # Atualizar organização atual kobana billing organization update \ --json '{"name": "NAME", "email": "EMAIL", "phone": "PHONE"}' ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Propostas](https://docs.billing.kobana.com.br/pt/pt/cli/resources/proposals.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Recursos Todo recurso de `billing` abaixo é gerado a partir da mesma spec OpenAPI documentada na [Referência da API](https://docs.billing.kobana.com.br/pt/pt/api/v1) — o CLI chama exatamente os mesmos endpoints, então filtros, validação e comportamento de exclusão são idênticos. Recorra à [introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) sempre que os parâmetros exatos de um comando não estiverem óbvios nos exemplos destas páginas. ``` kobana billing [flags] ``` ## Como ler estas páginas[​](#como-ler-estas-páginas "Link direto para Como ler estas páginas") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. Veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/cli/overview/authentication.md) para as credenciais próprias do `billing`. ## O catálogo[​](#o-catálogo "Link direto para O catálogo") | Recurso | Comando | Métodos | | -------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Planos](https://docs.billing.kobana.com.br/pt/pt/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 planos](https://docs.billing.kobana.com.br/pt/pt/cli/resources/plan-groups.md) | `plan-groups` | list, create, get, update, delete, archive, reorder create | | [Produtos](https://docs.billing.kobana.com.br/pt/pt/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 produtos](https://docs.billing.kobana.com.br/pt/pt/cli/resources/product-groups.md) | `product-groups` | list, create, get, update, delete, archive, unarchive, reorder create, reorder update | | [Itens de serviço](https://docs.billing.kobana.com.br/pt/pt/cli/resources/service-items.md) | `service-items` | list, create, get, update, delete | | [Assinaturas](https://docs.billing.kobana.com.br/pt/pt/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 | | [Mudanças de assinatura](https://docs.billing.kobana.com.br/pt/pt/cli/resources/subscription-changes.md) | `subscription-changes` | config list, config update | | [Mudanças de itens](https://docs.billing.kobana.com.br/pt/pt/cli/resources/subscription-item-changes.md) | `subscription-item-changes` | list, get, cancel | | [Mudanças de plano](https://docs.billing.kobana.com.br/pt/pt/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 | | [Contas de cobrança](https://docs.billing.kobana.com.br/pt/pt/cli/resources/billing-accounts.md) | `billing-accounts` | list, create, get, update, delete, close, credits, entitlements, invoices, reactivate, subscriptions, suspend | | [Faturas](https://docs.billing.kobana.com.br/pt/pt/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 | | [Pagamentos](https://docs.billing.kobana.com.br/pt/pt/cli/resources/payments.md) | `payments` | list, create, get, delete, cancel, change-card, change-due-date, refund, retry, send-email, sync, bulk-update-invoice create | | [Meios de pagamento](https://docs.billing.kobana.com.br/pt/pt/cli/resources/payment-methods.md) | `payment-methods` | list, create, get, update, delete, set-default | | [Créditos](https://docs.billing.kobana.com.br/pt/pt/cli/resources/credits.md) | `credits` | list, create, get, update, delete | | [Retenções](https://docs.billing.kobana.com.br/pt/pt/cli/resources/withholdings.md) | `withholdings` | list, get, convert-to-credit, convert-to-credits create | | [Cupons](https://docs.billing.kobana.com.br/pt/pt/cli/resources/coupons.md) | `coupons` | list, create, get, update, delete, deactivate, redemptions | | [Clientes](https://docs.billing.kobana.com.br/pt/pt/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/pt/pt/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 | | [Organização](https://docs.billing.kobana.com.br/pt/pt/cli/resources/organization.md) | `organization` | list, update | | [Propostas](https://docs.billing.kobana.com.br/pt/pt/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 | | [Modelos de proposta](https://docs.billing.kobana.com.br/pt/pt/cli/resources/proposal-templates.md) | `proposal-templates` | list, create, get, update, delete, activate, deactivate, duplicate | | [Notas fiscais](https://docs.billing.kobana.com.br/pt/pt/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 | | [Regras de imposto](https://docs.billing.kobana.com.br/pt/pt/cli/resources/tax-rules.md) | `tax-rules` | list, create, get, update, delete | | [Períodos fiscais](https://docs.billing.kobana.com.br/pt/pt/cli/resources/tax-periods.md) | `tax-periods` | list, create, get, update, delete | | [Certificados digitais](https://docs.billing.kobana.com.br/pt/pt/cli/resources/certificates.md) | `certificates` | list, create, get, delete | | [Consumo](https://docs.billing.kobana.com.br/pt/pt/cli/resources/usage.md) | `usage` | list, create, snapshots daily list, snapshots daily create, snapshots monthly list, snapshots monthly create, summary list | | [Usuários do painel](https://docs.billing.kobana.com.br/pt/pt/cli/resources/dashboard-users.md) | `dashboard-users` | list, create, get, update, delete | | [Papéis de equipe](https://docs.billing.kobana.com.br/pt/pt/cli/resources/team-roles.md) | `team-roles` | list, create, get, update, delete | --- # Meios de pagamento Os cartões e demais meios salvos de um cliente, e qual deles é o padrão. | Comando | HTTP | Descrição | | ----------------------------- | ------------------------------------------- | ----------------------------------------- | | `payment-methods list` | `GET /v1/payment_methods` | Listar métodos de pagamento | | `payment-methods create` | `POST /v1/payment_methods` | Criar método de pagamento | | `payment-methods get` | `GET /v1/payment_methods/{id}` | Obter método de pagamento | | `payment-methods update` | `PATCH /v1/payment_methods/{id}` | Atualizar validade do cartão | | `payment-methods delete` | `DELETE /v1/payment_methods/{id}` | Excluir método de pagamento (soft delete) | | `payment-methods set-default` | `POST /v1/payment_methods/{id}/set-default` | Definir método como padrão | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar métodos de pagamento kobana billing payment-methods list \ --fields "id,public_id,external_id,billing_account_id,credit_card_id" # Obter método de pagamento kobana billing payment-methods get --params '{"id": "PAYMENT_METHOD_ID"}' # Criar método de pagamento kobana billing payment-methods create \ --json '{"billingAccountId": "BILLINGACCOUNTID", "type": "card"}' # Atualizar validade do cartão kobana billing payment-methods update \ --params '{"id": "PAYMENT_METHOD_ID"}' \ --json '{"exp_month": 0, "exp_year": 0}' # Definir método como padrão kobana billing payment-methods set-default \ --params '{"id": "PAYMENT_METHOD_ID"}' # Remover método de pagamento kobana billing payment-methods delete \ --params '{"id": "PAYMENT_METHOD_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Créditos](https://docs.billing.kobana.com.br/pt/pt/cli/resources/credits.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Pagamentos As tentativas de liquidação de uma fatura: retentativa, troca de cartão, mudança de vencimento, estorno e reenvio do e-mail de cobrança. | Comando | HTTP | Descrição | | ------------------------------------- | ---------------------------------------- | ------------------------------------ | | `payments list` | `GET /v1/payments` | Listar pagamentos | | `payments create` | `POST /v1/payments` | Processar pagamento | | `payments get` | `GET /v1/payments/{id}` | Obter pagamento | | `payments delete` | `DELETE /v1/payments/{id}` | Excluir pagamento | | `payments cancel` | `POST /v1/payments/{id}/cancel` | Cancelar pagamento | | `payments change-card` | `POST /v1/payments/{id}/change-card` | Trocar cartão do pagamento | | `payments change-due-date` | `POST /v1/payments/{id}/change-due-date` | Alterar vencimento do boleto | | `payments refund` | `POST /v1/payments/{id}/refund` | Estornar pagamento | | `payments retry` | `POST /v1/payments/{id}/retry` | Tentar pagamento novamente | | `payments send-email` | `POST /v1/payments/{id}/send-email` | Enviar boleto por e-mail | | `payments sync` | `POST /v1/payments/{id}/sync` | Sincronizar pagamento com gateway | | `payments bulk-update-invoice create` | `POST /v1/payments/bulk-update-invoice` | Reatribuir pagamentos a outra fatura | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar pagamentos kobana billing payments list \ --fields "id,public_id,external_id,invoice_id,billing_account_id" # Obter pagamento kobana billing payments get --params '{"id": "PAYMENT_ID"}' # Processar pagamento kobana billing payments create --json '{"invoiceId": "INVOICEID"}' # Cancelar pagamento kobana billing payments cancel \ --params '{"id": "PAYMENT_ID"}' \ --json '{"reason": "REASON", "cancel_on_gateway": true}' # Excluir pagamento kobana billing payments delete --params '{"id": "PAYMENT_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Meios de pagamento](https://docs.billing.kobana.com.br/pt/pt/cli/resources/payment-methods.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Mudanças de plano Upgrades e downgrades: as regras que definem o que pode virar o quê, a configuração do proporcional e as estatísticas do que foi trocado. | Comando | HTTP | Descrição | | ---------------------------- | ------------------------------------ | ------------------------------------------ | | `plan-changes list` | `GET /v1/plan_changes` | Listar mudanças de plano | | `plan-changes create` | `POST /v1/plan_changes` | Executar mudança de plano | | `plan-changes get` | `GET /v1/plan_changes/{id}` | Obter mudança de plano | | `plan-changes config list` | `GET /v1/plan_changes/config` | Obter configuração de mudança de plano | | `plan-changes config update` | `PATCH /v1/plan_changes/config` | Atualizar configuração de mudança de plano | | `plan-changes rules list` | `GET /v1/plan_changes/rules` | Listar regras de mudança de plano | | `plan-changes rules create` | `POST /v1/plan_changes/rules` | Criar regra de mudança de plano | | `plan-changes rules get` | `GET /v1/plan_changes/rules/{id}` | Obter regra de mudança de plano | | `plan-changes rules update` | `PATCH /v1/plan_changes/rules/{id}` | Atualizar regra de mudança de plano | | `plan-changes rules delete` | `DELETE /v1/plan_changes/rules/{id}` | Excluir regra de mudança de plano | | `plan-changes stats list` | `GET /v1/plan_changes/stats` | Estatísticas de mudanças de plano | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar mudanças de plano kobana billing plan-changes list \ --fields "id,public_id,external_id,subscription_id,billing_account_id" # Obter mudança de plano kobana billing plan-changes get --params '{"id": "PLAN_CHANGE_ID"}' # Executar mudança de plano kobana billing plan-changes create \ --json '{"subscription_id": "SUBSCRIPTION_ID", "to_plan_id": "TO_PLAN_ID"}' # Atualizar configuração de mudança de plano kobana billing plan-changes config update \ --json '{"allow_upgrade": true, "allow_downgrade": true, "upgrade_proration": "full_proration"}' # Excluir regra de mudança de plano kobana billing plan-changes rules delete \ --params '{"id": "RULE_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Contas de cobrança](https://docs.billing.kobana.com.br/pt/pt/cli/resources/billing-accounts.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Grupos de planos A prateleira em que os planos são exibidos e ordenados. `reorder` muda a ordem; `archive` tira o grupo de circulação sem apagá-lo. | Comando | HTTP | Descrição | | ---------------------------- | ----------------------------------- | -------------------------- | | `plan-groups list` | `GET /v1/plan_groups` | Listar grupos de planos | | `plan-groups create` | `POST /v1/plan_groups` | Criar grupo de planos | | `plan-groups get` | `GET /v1/plan_groups/{id}` | Obter grupo de planos | | `plan-groups update` | `PATCH /v1/plan_groups/{id}` | Atualizar grupo de planos | | `plan-groups delete` | `DELETE /v1/plan_groups/{id}` | Remover grupo de planos | | `plan-groups archive` | `POST /v1/plan_groups/{id}/archive` | Arquivar grupo de planos | | `plan-groups reorder create` | `POST /v1/plan_groups/reorder` | Reordenar grupos de planos | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar grupos de planos kobana billing plan-groups list \ --fields "id,public_id,external_id,organization_id,company_id" # Obter grupo de planos kobana billing plan-groups get --params '{"id": "PLAN_GROUP_ID"}' # Criar grupo de planos kobana billing plan-groups create --json '{"name": "NAME"}' # Atualizar grupo de planos kobana billing plan-groups update \ --params '{"id": "PLAN_GROUP_ID"}' \ --json '{"name": "NAME", "slug": "SLUG", "external_id": "EXTERNAL_ID"}' # Arquivar grupo de planos kobana billing plan-groups archive --params '{"id": "PLAN_GROUP_ID"}' # Remover grupo de planos kobana billing plan-groups delete --params '{"id": "PLAN_GROUP_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Produtos](https://docs.billing.kobana.com.br/pt/pt/cli/resources/products.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Planos O que se assina: preço, periodicidade e a lista de itens que o plano entrega. As operações `bulk-*` agem sobre vários planos de uma vez. | Comando | HTTP | Descrição | | ------------------------------ | -------------------------------- | ------------------------------------- | | `plans list` | `GET /v1/plans` | Listar planos | | `plans create` | `POST /v1/plans` | Criar plano | | `plans get` | `GET /v1/plans/{id}` | Obter plano | | `plans update` | `PATCH /v1/plans/{id}` | Atualizar plano | | `plans delete` | `DELETE /v1/plans/{id}` | Excluir plano (soft delete) | | `plans archive` | `POST /v1/plans/{id}/archive` | Arquivar plano | | `plans duplicate` | `POST /v1/plans/{id}/duplicate` | Duplicar plano | | `plans bulk-archive create` | `POST /v1/plans/bulk-archive` | Arquivar planos em lote | | `plans bulk delete` | `DELETE /v1/plans/bulk` | Excluir planos em lote | | `plans bulk-move-group create` | `POST /v1/plans/bulk-move-group` | Mover planos para outro grupo em lote | | `plans items get` | `GET /v1/plans/{id}/items` | Listar itens do plano | | `plans items update` | `PUT /v1/plans/{id}/items` | Substituir itens do plano | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar planos kobana billing plans list \ --fields "id,public_id,external_id,organization_id,company_id" # Obter plano kobana billing plans get --params '{"id": "PLAN_ID"}' # Criar plano kobana billing plans create --json '{"name": "NAME", "slug": "SLUG"}' # Atualizar plano kobana billing plans update \ --params '{"id": "PLAN_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "company_id": "COMPANY_ID", "plan_group_id": "PLAN_GROUP_ID"}' # Duplicar plano kobana billing plans duplicate --params '{"id": "PLAN_ID"}' # Arquivar plano (reversível) kobana billing plans archive --params '{"id": "PLAN_ID"}' # Excluir plano (soft delete) kobana billing plans delete --params '{"id": "PLAN_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Grupos de planos](https://docs.billing.kobana.com.br/pt/pt/cli/resources/plan-groups.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Grupos de produtos O agrupamento do catálogo de produtos, com ordenação e arquivamento próprios. | Comando | HTTP | Descrição | | ------------------------------- | ---------------------------------------- | --------------------------------------- | | `product-groups list` | `GET /v1/product_groups` | Listar grupos de produto | | `product-groups create` | `POST /v1/product_groups` | Criar grupo de produto | | `product-groups get` | `GET /v1/product_groups/{id}` | Obter grupo de produto | | `product-groups update` | `PATCH /v1/product_groups/{id}` | Atualizar grupo de produto | | `product-groups delete` | `DELETE /v1/product_groups/{id}` | Remover grupo de produto | | `product-groups archive` | `POST /v1/product_groups/{id}/archive` | Arquivar grupo de produto | | `product-groups unarchive` | `POST /v1/product_groups/{id}/unarchive` | Desarquivar grupo de produto | | `product-groups reorder create` | `POST /v1/product_groups/reorder` | Reordenar grupos de produto | | `product-groups reorder update` | `PUT /v1/product_groups/reorder` | Reordenar grupos de produto (alias PUT) | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar grupos de produto kobana billing product-groups list \ --fields "id,public_id,external_id,organization_id,company_id" # Obter grupo de produto kobana billing product-groups get --params '{"id": "PRODUCT_GROUP_ID"}' # Criar grupo de produto kobana billing product-groups create --json '{"name": "NAME"}' # Atualizar grupo de produto kobana billing product-groups update \ --params '{"id": "PRODUCT_GROUP_ID"}' \ --json '{"name": "NAME", "slug": "SLUG", "company_id": "COMPANY_ID"}' # Remover grupo de produto kobana billing product-groups delete \ --params '{"id": "PRODUCT_GROUP_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Itens de serviço](https://docs.billing.kobana.com.br/pt/pt/cli/resources/service-items.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Produtos O catálogo do que se cobra, item a item, antes de virar plano ou item de fatura. Publicar, arquivar e restaurar controlam a visibilidade sem destruir histórico. | Comando | HTTP | Descrição | | ------------------------------------- | --------------------------------------- | -------------------------------------------------------------------- | | `products list` | `GET /v1/products` | Listar produtos | | `products create` | `POST /v1/products` | Criar produto | | `products get` | `GET /v1/products/{id}` | Obter produto | | `products update` | `PATCH /v1/products/{id}` | Atualizar produto | | `products delete` | `DELETE /v1/products/{id}` | Excluir produto (soft delete: some de toda leitura e sai dos planos) | | `products archive` | `POST /v1/products/{id}/archive` | Arquivar produto | | `products publish` | `POST /v1/products/{id}/publish` | Publicar produto | | `products restore` | `POST /v1/products/{id}/restore` | Restaurar produto arquivado | | `products bulk-archive create` | `POST /v1/products/bulk-archive` | Arquivar produtos em lote | | `products bulk-change-company create` | `POST /v1/products/bulk-change-company` | Trocar empresa de produtos em lote | | `products bulk delete` | `DELETE /v1/products/bulk` | Excluir produtos em lote | | `products bulk-move-group create` | `POST /v1/products/bulk-move-group` | Mover produtos para outro grupo | | `products bulk-visibility create` | `POST /v1/products/bulk-visibility` | Alterar visibilidade em lote | | `products reorder create` | `POST /v1/products/reorder` | Reordenar produtos | | `products reorder update` | `PUT /v1/products/reorder` | Reordenar produtos (PUT /reorder) | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar produtos kobana billing products list \ --fields "id,public_id,external_id,organization_id,company_id" # Obter produto kobana billing products get --params '{"id": "PRODUCT_ID"}' # Criar produto kobana billing products create --json '{"name": "NAME", "slug": "SLUG"}' # Atualizar produto kobana billing products update \ --params '{"id": "PRODUCT_ID"}' \ --json '{"name": "NAME", "slug": "SLUG", "description": "DESCRIPTION"}' # Arquivar produto kobana billing products archive --params '{"id": "PRODUCT_ID"}' # Excluir produto (soft delete) kobana billing products delete --params '{"id": "PRODUCT_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Grupos de produtos](https://docs.billing.kobana.com.br/pt/pt/cli/resources/product-groups.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Modelos de proposta Os modelos de onde as propostas nascem, com um marcado como padrão. | Comando | HTTP | Descrição | | ------------------------------- | --------------------------------------------- | ------------------------------ | | `proposal-templates list` | `GET /v1/proposal_templates` | Listar templates de proposta | | `proposal-templates create` | `POST /v1/proposal_templates` | Criar template de proposta | | `proposal-templates get` | `GET /v1/proposal_templates/{id}` | Obter template de proposta | | `proposal-templates update` | `PATCH /v1/proposal_templates/{id}` | Atualizar template de proposta | | `proposal-templates delete` | `DELETE /v1/proposal_templates/{id}` | Excluir template de proposta | | `proposal-templates activate` | `POST /v1/proposal_templates/{id}/activate` | Ativar template de proposta | | `proposal-templates deactivate` | `POST /v1/proposal_templates/{id}/deactivate` | Desativar template de proposta | | `proposal-templates duplicate` | `POST /v1/proposal_templates/{id}/duplicate` | Duplicar template de proposta | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar templates de proposta kobana billing proposal-templates list \ --fields "id,public_id,external_id,name,description" # Obter template de proposta kobana billing proposal-templates get \ --params '{"id": "PROPOSAL_TEMPLATE_ID"}' # Criar template de proposta kobana billing proposal-templates create \ --json '{"name": "NAME", "googleDocId": "GOOGLEDOCID"}' # Atualizar template de proposta kobana billing proposal-templates update \ --params '{"id": "PROPOSAL_TEMPLATE_ID"}' \ --json '{"name": "NAME", "description": "DESCRIPTION", "documentType": "google_doc"}' # Ativar template de proposta kobana billing proposal-templates activate \ --params '{"id": "PROPOSAL_TEMPLATE_ID"}' # Excluir template de proposta kobana billing proposal-templates delete \ --params '{"id": "PROPOSAL_TEMPLATE_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Notas fiscais](https://docs.billing.kobana.com.br/pt/pt/cli/resources/nfes.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Propostas O orçamento antes da assinatura: publicar, enviar, gerar PDF e aceitar. Aceitar é o que converte a proposta em assinatura — e `undo-accept` desfaz. | Comando | HTTP | Descrição | | ------------------------------ | ------------------------------------------ | ---------------------------------- | | `proposals list` | `GET /v1/proposals` | Listar propostas | | `proposals create` | `POST /v1/proposals` | Criar proposta | | `proposals get` | `GET /v1/proposals/{id}` | Obter proposta | | `proposals update` | `PATCH /v1/proposals/{id}` | Atualizar proposta | | `proposals delete` | `DELETE /v1/proposals/{id}` | Excluir proposta | | `proposals accept` | `POST /v1/proposals/{id}/accept` | Aceitar proposta | | `proposals cancel` | `POST /v1/proposals/{id}/cancel` | Cancelar proposta | | `proposals duplicate` | `POST /v1/proposals/{id}/duplicate` | Duplicar proposta | | `proposals generate-pdf` | `POST /v1/proposals/{id}/generate-pdf` | Gerar PDF da proposta | | `proposals json` | `GET /v1/proposals/{id}/json` | Obter snapshot JSON da proposta | | `proposals pricing` | `GET /v1/proposals/{id}/pricing` | Obter cálculo de preço da proposta | | `proposals publish` | `POST /v1/proposals/{id}/publish` | Publicar proposta | | `proposals send` | `POST /v1/proposals/{id}/send` | Enviar proposta por e-mail | | `proposals undo-accept` | `POST /v1/proposals/{id}/undo-accept` | Desfazer aceite da proposta | | `proposals unpublish` | `POST /v1/proposals/{id}/unpublish` | Despublicar proposta | | `proposals bulk-cancel create` | `POST /v1/proposals/bulk-cancel` | Cancelar propostas em lote | | `proposals bulk delete` | `DELETE /v1/proposals/bulk` | Excluir propostas em lote | | `proposals bulk-send create` | `POST /v1/proposals/bulk-send` | Enviar propostas em lote | | `proposals items get` | `GET /v1/proposals/{id}/items` | Listar itens da proposta | | `proposals items create` | `POST /v1/proposals/{id}/items` | Adicionar item à proposta | | `proposals items update` | `PATCH /v1/proposals/{id}/items/{itemId}` | Atualizar item da proposta | | `proposals items delete` | `DELETE /v1/proposals/{id}/items/{itemId}` | Excluir item da proposta | | `proposals stats list` | `GET /v1/proposals/stats` | Obter estatísticas de propostas | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar propostas kobana billing proposals list \ --fields "id,public_id,external_id,company_id,code" # Obter proposta kobana billing proposals get --params '{"id": "PROPOSAL_ID"}' # Criar proposta kobana billing proposals create \ --json '{"company_id": "COMPANY_ID", "title": "TITLE", "description": "DESCRIPTION"}' # Atualizar proposta kobana billing proposals update \ --params '{"id": "PROPOSAL_ID"}' \ --json '{"company_id": "COMPANY_ID", "title": "TITLE", "description": "DESCRIPTION"}' # Aceitar proposta kobana billing proposals accept \ --params '{"id": "PROPOSAL_ID"}' \ --json '{"cycle": "monthly"}' # Excluir proposta kobana billing proposals delete --params '{"id": "PROPOSAL_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Modelos de proposta](https://docs.billing.kobana.com.br/pt/pt/cli/resources/proposal-templates.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Itens de serviço Os serviços da lista municipal usados para descrever o que a nota fiscal está cobrando. | Comando | HTTP | Descrição | | ---------------------- | ------------------------------- | ------------------------------------- | | `service-items list` | `GET /v1/service_items` | Listar itens de serviço | | `service-items create` | `POST /v1/service_items` | Criar item de serviço | | `service-items get` | `GET /v1/service_items/{id}` | Obter item de serviço | | `service-items update` | `PATCH /v1/service_items/{id}` | Atualizar item de serviço | | `service-items delete` | `DELETE /v1/service_items/{id}` | Excluir item de serviço (soft delete) | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar itens de serviço kobana billing service-items list \ --fields "id,public_id,external_id,organization_id,company_id" # Obter item de serviço kobana billing service-items get --params '{"id": "SERVICE_ITEM_ID"}' # Criar item de serviço kobana billing service-items create \ --json '{"name": "NAME", "internal_code": "INTERNAL_CODE", "lc116_code": "01.05"}' # Atualizar item de serviço kobana billing service-items update \ --params '{"id": "SERVICE_ITEM_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "company_id": "COMPANY_ID", "name": "NAME"}' # Excluir item de serviço kobana billing service-items delete \ --params '{"id": "SERVICE_ITEM_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Assinaturas](https://docs.billing.kobana.com.br/pt/pt/cli/resources/subscriptions.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Mudanças de assinatura A configuração de como mudanças de assinatura são aplicadas — imediatamente, no próximo ciclo, com ou sem proporcional. | Comando | HTTP | Descrição | | ------------------------------------ | ------------------------------------- | ------------------------------------------------ | | `subscription-changes config list` | `GET /v1/subscription_changes/config` | Obter configuração de mudanças de assinatura | | `subscription-changes config update` | `PUT /v1/subscription_changes/config` | Atualizar configuração de mudanças de assinatura | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Obter configuração de mudanças de assinatura kobana billing subscription-changes config list \ --fields "id,publicId,organizationId,externalId,allowItemAdd" # Atualizar configuração de mudanças de assinatura kobana billing subscription-changes config update \ --json '{"allow_item_add": true, "allow_item_remove": true, "allow_quantity_change": true}' ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Mudanças de itens](https://docs.billing.kobana.com.br/pt/pt/cli/resources/subscription-item-changes.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Mudanças de itens O histórico de alterações nos itens de uma assinatura, e o cancelamento de uma mudança ainda agendada. | Comando | HTTP | Descrição | | ---------------------------------- | ------------------------------------------------ | -------------------------------------- | | `subscription-item-changes list` | `GET /v1/subscription_item_changes` | Listar mudanças de itens de assinatura | | `subscription-item-changes get` | `GET /v1/subscription_item_changes/{id}` | Obter mudança de item de assinatura | | `subscription-item-changes cancel` | `POST /v1/subscription_item_changes/{id}/cancel` | Cancelar uma mudança ainda agendada | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar mudanças de itens de assinatura kobana billing subscription-item-changes list \ --fields "id,publicId,organizationId,subscriptionId,billingAccountId" # Obter mudança de item de assinatura kobana billing subscription-item-changes get \ --params '{"id": "SUBSCRIPTION_ITEM_CHANGE_ID"}' ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Mudanças de plano](https://docs.billing.kobana.com.br/pt/pt/cli/resources/plan-changes.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Assinaturas O contrato vivo entre um cliente e um plano: ativar, pausar, retomar, trocar de plano e cancelar. `create-invoice` força uma fatura fora do ciclo. | Comando | HTTP | Descrição | | ----------------------------------- | ------------------------------------------------- | -------------------------------------------- | | `subscriptions list` | `GET /v1/subscriptions` | Listar assinaturas | | `subscriptions create` | `POST /v1/subscriptions` | Criar assinatura | | `subscriptions get` | `GET /v1/subscriptions/{id}` | Obter assinatura | | `subscriptions update` | `PATCH /v1/subscriptions/{id}` | Atualizar assinatura | | `subscriptions delete` | `DELETE /v1/subscriptions/{id}` | Cancelar e remover assinatura (soft delete) | | `subscriptions activate` | `POST /v1/subscriptions/{id}/activate` | Ativar assinatura em rascunho/confirmada | | `subscriptions cancel` | `POST /v1/subscriptions/{id}/cancel` | Cancelar assinatura | | `subscriptions change-plan` | `POST /v1/subscriptions/{id}/change-plan` | Trocar o plano da assinatura | | `subscriptions create-invoice` | `POST /v1/subscriptions/{id}/create-invoice` | Gerar uma fatura avulsa para a assinatura | | `subscriptions items get` | `GET /v1/subscriptions/{id}/items` | Listar itens da assinatura | | `subscriptions pause` | `POST /v1/subscriptions/{id}/pause` | Pausar assinatura | | `subscriptions resume` | `POST /v1/subscriptions/{id}/resume` | Retomar assinatura pausada | | `subscriptions revert-to-confirmed` | `POST /v1/subscriptions/{id}/revert-to-confirmed` | Reverter assinatura para o estado confirmado | | `subscriptions sync-plan-items` | `POST /v1/subscriptions/{id}/sync-plan-items` | Ressincronizar itens com o plano atual | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar assinaturas kobana billing subscriptions list \ --fields "id,public_id,external_id,billing_account_id,company_id" # Obter assinatura kobana billing subscriptions get --params '{"id": "SUBSCRIPTION_ID"}' # Criar assinatura kobana billing subscriptions create \ --json '{"billing_account_id": "BILLING_ACCOUNT_ID"}' # Atualizar assinatura kobana billing subscriptions update \ --params '{"id": "SUBSCRIPTION_ID"}' \ --json '{"external_id": "EXTERNAL_ID", "plan_id": "PLAN_ID", "billing_cycle": "monthly"}' # Ativar assinatura em rascunho/confirmada kobana billing subscriptions activate --params '{"id": "SUBSCRIPTION_ID"}' # Cancelar e remover assinatura (soft delete) kobana billing subscriptions delete \ --params '{"id": "SUBSCRIPTION_ID"}' \ --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Mudanças de assinatura](https://docs.billing.kobana.com.br/pt/pt/cli/resources/subscription-changes.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Períodos fiscais As competências fiscais que agrupam as notas emitidas. | Comando | HTTP | Descrição | | -------------------- | ----------------------------- | ----------------------------------- | | `tax-periods list` | `GET /v1/tax_periods` | Listar períodos tributários | | `tax-periods create` | `POST /v1/tax_periods` | Processar período tributário mensal | | `tax-periods get` | `GET /v1/tax_periods/{id}` | Obter período tributário | | `tax-periods update` | `PATCH /v1/tax_periods/{id}` | Executar ação no período tributário | | `tax-periods delete` | `DELETE /v1/tax_periods/{id}` | Excluir período tributário | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar períodos tributários kobana billing tax-periods list \ --fields "id,public_id,external_id,company_id,period_type" # Obter período tributário kobana billing tax-periods get --params '{"id": "TAX_PERIOD_ID"}' # Processar período tributário mensal kobana billing tax-periods create --json '{"year": 2026, "month": 6}' # Executar ação no período tributário kobana billing tax-periods update \ --params '{"id": "TAX_PERIOD_ID"}' \ --json '{"action": "recalculate"}' # Excluir período tributário kobana billing tax-periods delete --params '{"id": "TAX_PERIOD_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Certificados digitais](https://docs.billing.kobana.com.br/pt/pt/cli/resources/certificates.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Regras de imposto Que tributo incide sobre o quê, e com qual alíquota — o que a emissão de nota consulta. | Comando | HTTP | Descrição | | ------------------ | --------------------------- | -------------------------- | | `tax-rules list` | `GET /v1/tax_rules` | Listar regras tributárias | | `tax-rules create` | `POST /v1/tax_rules` | Criar regra tributária | | `tax-rules get` | `GET /v1/tax_rules/{id}` | Obter regra tributária | | `tax-rules update` | `PATCH /v1/tax_rules/{id}` | Atualizar regra tributária | | `tax-rules delete` | `DELETE /v1/tax_rules/{id}` | Excluir regra tributária | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar regras tributárias kobana billing tax-rules list \ --fields "id,public_id,external_id,scope,priority" # Obter regra tributária kobana billing tax-rules get --params '{"id": "TAX_RULE_ID"}' # Criar regra tributária kobana billing tax-rules create \ --json '{"name": "NAME", "scope": "global", "items": []}' # Atualizar regra tributária kobana billing tax-rules update \ --params '{"id": "TAX_RULE_ID"}' \ --json '{"name": "NAME", "description": "DESCRIPTION", "priority": 0}' # Excluir regra tributária kobana billing tax-rules delete --params '{"id": "TAX_RULE_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Períodos fiscais](https://docs.billing.kobana.com.br/pt/pt/cli/resources/tax-periods.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Papéis de equipe Os papéis que definem o que cada usuário do painel pode fazer. | Comando | HTTP | Descrição | | ------------------- | ---------------------------- | ----------------------- | | `team-roles list` | `GET /v1/team_roles` | Listar papéis do time | | `team-roles create` | `POST /v1/team_roles` | Criar papel customizado | | `team-roles get` | `GET /v1/team_roles/{id}` | Obter papel | | `team-roles update` | `PATCH /v1/team_roles/{id}` | Atualizar papel | | `team-roles delete` | `DELETE /v1/team_roles/{id}` | Remover papel | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar papéis do time kobana billing team-roles list \ --fields "id,public_id,organization_id,name,slug" # Obter papel kobana billing team-roles get --params '{"id": "TEAM_ROLE_ID"}' # Criar papel customizado kobana billing team-roles create \ --json '{"name": "NAME", "slug": "billing_manager", "permissions": []}' # Atualizar papel kobana billing team-roles update \ --params '{"id": "TEAM_ROLE_ID"}' \ --json '{"name": "NAME", "slug": "SLUG", "description": "DESCRIPTION"}' # Remover papel kobana billing team-roles delete --params '{"id": "TEAM_ROLE_ID"}' --dry-run ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Consumo Os eventos de consumo que alimentam a cobrança por uso, com fotografias diárias e mensais e um resumo consolidado. | Comando | HTTP | Descrição | | -------------------------------- | ---------------------------------- | ------------------------------- | | `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 snapshots diários de uso | | `usage snapshots daily create` | `POST /v1/usage/snapshots/daily` | Criar snapshots diários de uso | | `usage snapshots monthly list` | `GET /v1/usage/snapshots/monthly` | Listar snapshots mensais de uso | | `usage snapshots monthly create` | `POST /v1/usage/snapshots/monthly` | Criar snapshots mensais de uso | | `usage summary list` | `GET /v1/usage/summary` | Resumo de uso do período | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência 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 passos[​](#próximos-passos "Link direto para Próximos passos") * [Usuários do painel](https://docs.billing.kobana.com.br/pt/pt/cli/resources/dashboard-users.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Retenções Os valores retidos na fonte pelo cliente, que podem ser convertidos em crédito. | Comando | HTTP | Descrição | | ---------------------------------------- | ---------------------------------------------- | --------------------------------------------------- | | `withholdings list` | `GET /v1/withholdings` | Listar retenções | | `withholdings get` | `GET /v1/withholdings/{id}` | Obter retenção | | `withholdings convert-to-credit` | `POST /v1/withholdings/{id}/convert-to-credit` | Converter retenção em crédito | | `withholdings convert-to-credits create` | `POST /v1/withholdings/convert-to-credits` | Converter retenções pendentes em créditos (em lote) | ## Exemplos[​](#exemplos "Link direto para Exemplos") `--params` carrega parâmetros de query e de caminho (id, página, filtros); `--json` carrega o corpo da requisição; `--fields` limita os campos que voltam — vale a pena em todo `list`/`get`, para economizar contexto. Veja [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) para a referência completa. ``` # Listar retenções kobana billing withholdings list \ --fields "id,public_id,external_id,organization_id,invoice_id" # Obter retenção kobana billing withholdings get --params '{"id": "WITHHOLDING_ID"}' # Converter retenções pendentes em créditos (em lote) kobana billing withholdings convert-to-credits create \ --json '{"tax_type": "iss", "competence_year": 0, "competence_month": 0}' # Converter retenção em crédito kobana billing withholdings convert-to-credit \ --params '{"id": "WITHHOLDING_ID"}' \ --json '{"amount_cents": 100}' ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Cupons](https://docs.billing.kobana.com.br/pt/pt/cli/resources/coupons.md) * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — todos os parâmetros que este recurso aceita. --- # Flags globais | Flag | Descrição | | ------------------------- | --------------------------------------------------------------- | | `--params ''` | Parâmetros de query e de URL (id, página, filtros) | | `--json ''` | Corpo da requisição (POST/PUT/PATCH) | | `--fields ''` | Limita os campos que voltam na resposta | | `--dry-run` | Mostra a requisição sem executá-la | | `--page-all` | Paginação automática, com saída em NDJSON | | `--page-limit ` | Máximo de páginas (padrão: 10) | | `--page-delay ` | Intervalo entre páginas (padrão: 100ms) | | `--env ` | Ambiente: `production` (padrão), `sandbox`, `development` | | `--verbose` | Detalhes da requisição no stderr | | `--output ` | Salva a resposta em arquivo | | `--output-format ` | Formato: `json`, `table`, `csv` | | `--idempotency-key ` | Chave de idempotência customizada | | `--lang ` | Idioma das mensagens: `pt`, `en` ou `es` (padrão: o do sistema) | ## Idioma[​](#idioma "Link direto para Idioma") O CLI fala português, inglês ou espanhol: ajuda, mensagens, erros e as descrições dos comandos. O idioma vem, nesta ordem, de `--lang`, da variável `KOBANA_LANG`, das variáveis de idioma do terminal (`LC_ALL`, `LC_MESSAGES`, `LANG`) e, por fim, do idioma do sistema. ``` kobana --lang en billing --help export KOBANA_LANG=es ``` Nomes de comandos e flags, chaves do JSON e códigos de saída não mudam com o idioma. Disponível a partir da versão 0.6.0. ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Uso](https://docs.billing.kobana.com.br/pt/pt/cli/usage/overview.md) — sintaxe, recursos, exemplos. * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — parâmetros, campos obrigatórios, tipos e respostas. --- # Helpers Helpers são comandos prefixados com `+` que entregam fluxos de vários passos que os comandos dinâmicos sozinhos não dão: interfaces simplificadas, operações em lote ou chamadas compostas por vários endpoints. Eles não embrulham uma única chamada de API já disponível pelos comandos dinâmicos — cada flag de helper controla lógica de orquestração, não uma versão remodelada de `--params`/`--json`. Os helpers de hoje são do **Gateway Bancário**, e valem para qualquer produto no mesmo binário: | Helper | Descrição | | ---------------- | -------------------------------------------------------- | | `+emitir` | Emissão simplificada de boleto, com flags nomeadas | | `+cancelar-lote` | Cancelamento em lote de vários boletos por id | | `+cobrar` | Criação simplificada de cobrança Pix, com flags nomeadas | ``` # Emitir um boleto kobana +emitir --valor 150.50 --vencimento 2026-05-01 \ --nome "Maria Silva" --cpf-cnpj "012.345.678-90" --carteira 1 # Criar uma cobrança Pix kobana +cobrar --valor 99.90 --conta-pix "UID" \ --nome "João" --cpf-cnpj "012.345.678-90" # Cancelar boletos em lote kobana +cancelar-lote --ids "123,456,789" ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Uso](https://docs.billing.kobana.com.br/pt/pt/cli/usage/overview.md) — os comandos dinâmicos ao lado dos quais estes helpers vivem. * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — inspecione os endpoints que um helper chama por baixo. --- # Uso ## Sintaxe[​](#sintaxe "Link direto para Sintaxe") ``` kobana [flags] ``` * **``** — `banking`, `finance`, `billing` ou `inbox`. * **``** — pode ser aninhado: `subscriptions`, `invoices installments`, `customers users`. * **``** — a ação: `list`, `get`, `create`, `update`, `delete`, ou uma ação específica do recurso. A versão da API nunca entra no comando — o CLI resolve a URL a partir da spec OpenAPI embutida. Parâmetros de URL e de query vão em `--params`; o corpo da requisição vai em `--json`. Toda a superfície é descoberta pelo `--help`, em qualquer nível: ``` kobana --help # produtos kobana billing --help # recursos do Faturamento Automático kobana billing plans --help # métodos de um recurso ``` ## Recursos de `billing`[​](#recursos-de-billing "Link direto para recursos-de-billing") | Recurso | Descrição | | --------------------------- | ---------------------- | | `plans` | Planos | | `plan-groups` | Grupos de planos | | `products` | Produtos | | `product-groups` | Grupos de produtos | | `service-items` | Itens de serviço | | `subscriptions` | Assinaturas | | `subscription-changes` | Mudanças de assinatura | | `subscription-item-changes` | Mudanças de itens | | `plan-changes` | Mudanças de plano | | `billing-accounts` | Contas de cobrança | | `invoices` | Faturas | | `payments` | Pagamentos | | `payment-methods` | Meios de pagamento | | `credits` | Créditos | | `withholdings` | Retenções | | `coupons` | Cupons | | `customers` | Clientes | | `companies` | Empresas | | `organization` | Organização | | `proposals` | Propostas | | `proposal-templates` | Modelos de proposta | | `nfes` | Notas fiscais | | `tax-rules` | Regras de imposto | | `tax-periods` | Períodos fiscais | | `certificates` | Certificados digitais | | `usage` | Consumo | | `dashboard-users` | Usuários do painel | | `team-roles` | Papéis de equipe | Cada recurso tem a sua própria página, com a tabela completa de comandos e exemplos — veja o [catálogo](https://docs.billing.kobana.com.br/pt/pt/cli/resources/overview.md). ## Exemplos[​](#exemplos "Link direto para Exemplos") ``` # Assinaturas ativas kobana billing subscriptions list \ --params '{"status": "active"}' \ --fields "id,status,plan_id,next_billing_at" # Pausar e retomar uma assinatura kobana billing subscriptions pause --params '{"id": "SUBSCRIPTION_ID"}' kobana billing subscriptions resume --params '{"id": "SUBSCRIPTION_ID"}' # Fechar uma fatura e emitir a NF-e kobana billing invoices finalize --dry-run --params '{"id": "INVOICE_ID"}' kobana billing invoices issue-nfe --dry-run --params '{"id": "INVOICE_ID"}' # Criar um plano kobana billing plans create --json '{"name": "Pro", "slug": "pro"}' # Listar com paginação automática (NDJSON) kobana billing invoices list --page-all --fields "id,status,total" # Saída em tabela kobana billing plans list --output-format table # Salvar a resposta em arquivo kobana billing invoices get --params '{"id": "INVOICE_ID"}' --output fatura.json ``` ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Introspecção de schema](https://docs.billing.kobana.com.br/pt/pt/cli/usage/schema.md) — inspecione parâmetros e corpo de qualquer endpoint. * [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) — todas as flags que um comando aceita. * [Helpers](https://docs.billing.kobana.com.br/pt/pt/cli/usage/helpers.md) — atalhos `+verbo` para fluxos comuns. * [Recursos](https://docs.billing.kobana.com.br/pt/pt/cli/resources/overview.md) — o catálogo completo, recurso a recurso. --- # Introspecção de schema ``` # Listar todos os produtos e seus recursos kobana schema --list # Ver o schema de um endpoint específico kobana schema billing.subscriptions.list kobana schema billing.subscriptions.create kobana schema billing.invoices.finalize ``` Devolve parâmetros, campos obrigatórios, tipos e respostas — tudo derivado da spec OpenAPI embutida, então está sempre em sincronia com o que o comando de fato aceita. O caminho segue a mesma forma do comando: `..`. Este é o primeiro passo recomendado para um agente de IA que ainda não conhece o formato exato de um payload: inspecione o schema antes de disparar uma chamada que altera dados, em vez de adivinhar. ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Flags globais](https://docs.billing.kobana.com.br/pt/pt/cli/usage/global-flags.md) — `--params`, `--json`, `--dry-run` e as demais. * [Uso](https://docs.billing.kobana.com.br/pt/pt/cli/usage/overview.md) — sintaxe, recursos, exemplos. --- ## [📄️Analytics](https://docs.billing.kobana.com.br/pt/pt/configuracoes/analytics.md) [A área de Analytics (/dashboard/analytics) traduz os dados operacionais do faturamento em métricas SaaS consumíveis pelo time de finanças e produto: MRR, ARR, churn, LTV, ARPU, retenção por coorte e funil de cobrança.](https://docs.billing.kobana.com.br/pt/pt/configuracoes/analytics.md) --- ## [📄️Analytics](https://docs.billing.kobana.com.br/pt/pt/configuracoes/analytics.md) [A área de Analytics (/dashboard/analytics) traduz os dados operacionais do faturamento em métricas SaaS consumíveis pelo time de finanças e produto: MRR, ARR, churn, LTV, ARPU, retenção por coorte e funil de cobrança.](https://docs.billing.kobana.com.br/pt/pt/configuracoes/analytics.md) --- # Analytics A área de Analytics (`/dashboard/analytics`) traduz os dados operacionais do faturamento em **métricas SaaS** consumíveis pelo time de finanças e produto: MRR, ARR, churn, LTV, ARPU, retenção por coorte e funil de cobrança. ## Métricas principais[​](#métricas-principais "Link direto para Métricas principais") * **MRR** (Monthly Recurring Revenue) — soma normalizada das assinaturas ativas no mês. * **ARR** — projeção anualizada do MRR. * **MRR Movement** — quanto da variação veio de **novos**, **expansão**, **contração**, **reativação** e **churn**. * **Churn** — número e percentual de assinaturas canceladas no período. * **NRR** (Net Revenue Retention) — quanto a base existente cresceu ou encolheu, sem contar novos clientes. * **ARPU** (Average Revenue Per User) — receita média por conta de cobrança. * **LTV** (Lifetime Value) — estimativa de receita por cliente ao longo do tempo. ## Visualizações[​](#visualizações "Link direto para Visualizações") A página usa gráficos do Vega/Vega-Lite para apresentar: * **Série temporal de MRR** com waterfall de movimento mensal. * **Funil de cobrança** — emitidas → enviadas → pagas → falhadas. * **Retenção por coorte** — heatmap mostrando a sobrevivência de cada coorte de clientes. * **Distribuição por plano** — quantas assinaturas em cada plano e MRR por plano. ## Filtros[​](#filtros "Link direto para Filtros") * **Intervalo de datas** — padrão últimos 12 meses. * **Plano** — recortar por um ou mais planos. * **Moeda** — quando a organização opera em mais de uma. ## De onde vêm os dados[​](#de-onde-vêm-os-dados "Link direto para De onde vêm os dados") Analytics consulta diretamente as tabelas operacionais (`subscriptions`, `subscription_versions`, `invoices`, `payments`) filtradas por `organization_id`. Não há ETL: os números refletem o estado atual do banco em tempo real. ## Exportação[​](#exportação "Link direto para Exportação") Cada gráfico pode ser exportado em CSV ou PNG. Para extrações brutas (linha por linha), use [Relatórios](https://docs.billing.kobana.com.br/pt/pt/configuracoes/relatorios.md) ou [Exportações](https://docs.billing.kobana.com.br/pt/pt/exportacao-e-importacao/exportacoes/.md). ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Painel de Analytics com MRR, churn, retenção por coorte e distribuição por plano](/pt/assets/images/analytics-12fe89165e57d4b28c206873ee4755ef.png) --- # API Keys Em `/dashboard/api` a organização gerencia as **chaves de API**. Cada chave pertence a uma organização, tem um conjunto de escopos e pode ser revogada a qualquer momento. :::caution A API pública não usa mais chave de API A `/api/v1` passou a aceitar **apenas** o access token do Authorization Server da Kobana (`Authorization: Bearer `), verificado contra a chave pública que ele publica. Uma chave criada aqui **não** autentica a API pública. O motivo é que a chave era ao mesmo tempo a credencial e o que a verificava: quem lesse o repositório de chaves agia como qualquer organização, e cada rotação era uma conversa com um cliente. Com o token, quem emite é o Authorization Server e a plataforma só consegue verificar. ::: ## Tipos de chave[​](#tipos-de-chave "Link direto para Tipos de chave") * **Live** (`sk_live_...`) — usadas em produção. Operam contra dados reais e geram cobranças reais. * **Test** (`sk_test_...`) — apontam para o sandbox; ideal para integração inicial e testes automatizados. ## Criar uma chave[​](#criar-uma-chave "Link direto para Criar uma chave") 1. Clicar em **Nova chave**. 2. Dar um nome descritivo (ex.: "Backend produção", "Worker de importação"). 3. Selecionar os escopos: * `subscriptions:read` / `subscriptions:write` * `invoices:read` / `invoices:write` * `payments:read` / `payments:write` * `customers:read` / `customers:write` * `nfes:read` / `nfes:write` * `webhooks:manage` 4. Opcionalmente restringir por **IP** (lista de prefixos CIDR). 5. A chave é exibida **uma única vez** após criada. Copiar e guardar em cofre. ## Boas práticas[​](#boas-práticas "Link direto para Boas práticas") * **Uma chave por aplicação** — facilita revogar acesso sem impactar outros sistemas. * **Escopos mínimos** — conceder apenas o que a aplicação precisa. * **Rotação periódica** — gerar nova chave, atualizar a aplicação e revogar a antiga. * **Nunca commitar** — chaves devem viver em variáveis de ambiente ou cofre de segredos. ## Rate limits[​](#rate-limits "Link direto para Rate limits") Cada chave respeita os limites configurados em [Rate Limiting](https://docs.billing.kobana.com.br/pt/pt/configuracoes/rate-limiting/.md). Excedentes retornam `429 Too Many Requests` com header `Retry-After`. ## Auditoria e uso[​](#auditoria-e-uso "Link direto para Auditoria e uso") A página mostra: * **Status** — `active` ou `revoked` * **Último uso** — data, IP e endpoint chamado * **Volume** — requisições nas últimas 24h e nos últimos 30 dias Toda criação ou revogação é registrada em [Auditoria](https://docs.billing.kobana.com.br/pt/pt/configuracoes/auditoria.md). ## Documentação da API[​](#documentação-da-api "Link direto para Documentação da API") A referência completa dos endpoints está disponível na seção **API** do menu lateral. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Lista de API keys com nome, escopos, último uso e status](/pt/assets/images/api-f22a031f0fd529077aaab8fbf6930830.png) --- # Auditoria A trilha de auditoria (`/dashboard/audit`) registra **toda alteração de dados** feita no dashboard ou via API. Cada entrada captura quem fez, o que foi alterado, valores antes e depois, IP, User-Agent e horário, formando um histórico imutável para compliance, debug e análise de incidentes. ## O que é registrado[​](#o-que-é-registrado "Link direto para O que é registrado") Toda operação sensível passa pelo `auditService`. Entre as ações registradas: * Criação, atualização, suspensão e ativação de **contas de cobrança** e **clientes** * Mudanças de **plano**, **itens**, **status de assinatura**, **pausa** e **cancelamento** * Operações em **faturas**, **pagamentos**, **estornos** e **créditos** * Emissão, cancelamento e erros de **NF-e** * Alterações em **empresas**, **gateways**, **webhooks** e **API keys** * Mudanças em **membros**, **papéis**, **configurações** e **templates** * Logins e logouts administrativos A lista completa de ações está definida em `lib/services/audit.service.ts` (`AuditActions`). ## Filtros[​](#filtros "Link direto para Filtros") A interface permite filtrar por: * **Ação** (por exemplo, `subscription.canceled`, `invoice.paid`) * **Tipo de recurso** (subscription, invoice, customer, nfe, etc.) * **Usuário** que executou * **Intervalo de datas** * **Busca textual** por ID ou nome de recurso ## Detalhe de uma entrada[​](#detalhe-de-uma-entrada "Link direto para Detalhe de uma entrada") Cada linha pode ser expandida em um modal que mostra: * **previous\_values** — JSON com o estado anterior * **new\_values** — JSON com o estado após a alteração * **metadata** — contexto adicional (origem, motivo, idempotency key) * **IP** e **User-Agent** capturados na requisição ## Retenção e exportação[​](#retenção-e-exportação "Link direto para Retenção e exportação") Entradas de auditoria são imutáveis. Para análises externas ou retenção em longo prazo, use [Exportações](https://docs.billing.kobana.com.br/pt/pt/exportacao-e-importacao/exportacoes/.md) para baixar em CSV. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Trilha de auditoria com ações, recursos e detalhes da alteração](/pt/assets/images/auditoria-dd81b8c39d18173da8e9ddc48666278e.png) --- # Configurações de Cobrança Configurações que afetam a precificação e comportamento de cobrança da organização. ## Campos[​](#campos "Link direto para Campos") | Campo | Padrão | Descrição | | ------------------------------- | --------- | ----------------------------------- | | **Desconto trimestral (%)** | 5% | Desconto para ciclo trimestral | | **Desconto semestral (%)** | 10% | Desconto para ciclo semestral | | **Desconto anual (%)** | 15% | Desconto para ciclo anual | | **Validade da proposta (dias)** | 30 | Dias até a proposta expirar | | **Ciclo de cobrança padrão** | `monthly` | Ciclo padrão para novas assinaturas | ## Descontos por Ciclo[​](#descontos-por-ciclo "Link direto para Descontos por Ciclo") Os descontos são aplicados automaticamente ao calcular preços de propostas e ao apresentar opções de ciclo ao cliente: | Ciclo | Desconto Padrão | Exemplo (plano R$ 100/mês) | | ---------- | --------------- | ---------------------------- | | Mensal | 0% | R$ 100/mês | | Trimestral | 5% | R$ 285/trimestre (R$ 95/mês) | | Semestral | 10% | R$ 540/semestre (R$ 90/mês) | | Anual | 15% | R$ 1.020/ano (R$ 85/mês) | ## Onde São Usados[​](#onde-são-usados "Link direto para Onde São Usados") * **Propostas**: Cálculo de preços por ciclo * **Assinaturas**: Definição do ciclo padrão * **Portal**: Apresentação de opções de ciclo ao cliente --- # Empresa (Entidade Fiscal) Empresas representam as entidades jurídicas que emitem faturas e notas fiscais. Uma organização pode ter múltiplas empresas (matriz e filiais). ## Campos[​](#campos "Link direto para Campos") | Campo | Descrição | | ----------------------- | ------------------------------------ | | **Nome** | Nome fantasia | | **Razão social** | Nome legal completo | | **Tipo de documento** | CPF ou CNPJ | | **Número do documento** | CPF ou CNPJ | | **Padrão** | Se é a empresa padrão da organização | | **Status** | `active` ou `inactive` | | **Empresa matriz** | Para filiais, referência à matriz | ## Hierarquia[​](#hierarquia "Link direto para Hierarquia") ``` Matriz (CNPJ principal) ├── Filial 1 (mesmo prefixo CNPJ) └── Filial 2 (mesmo prefixo CNPJ) ``` ### Regras de Filiais[​](#regras-de-filiais "Link direto para Regras de Filiais") * A matriz deve ter CNPJ para ter filiais * O CNPJ da filial deve ter o mesmo prefixo da matriz * Filiais não podem ser marcadas como padrão ## Empresa Padrão[​](#empresa-padrão "Link direto para Empresa Padrão") Uma empresa por organização é marcada como padrão. Usada automaticamente quando a empresa não é especificada em operações. Ao desativar a empresa padrão, outra é automaticamente promovida. ## Perfil Fiscal[​](#perfil-fiscal "Link direto para Perfil Fiscal") Cada empresa possui um perfil fiscal vinculado que define: * Regime tributário (Simples Nacional, Lucro Presumido, Lucro Real) * Alíquotas de impostos * Configuração do Simples Nacional * Configuração CBS/IBS ## Operações[​](#operações "Link direto para Operações") * **Criar**: Criar empresa ou filial * **Atualizar**: Editar dados cadastrais * **Definir como padrão**: Marca como empresa padrão * **Desativar**: Não é possível se houver assinaturas ativas ou se for a única empresa ativa * **Reativar**: Volta ao status `active` --- # Eventos A tela de eventos (`/dashboard/events`) expõe o **stream interno de eventos de domínio** gerados pelo sistema toda vez que um estado relevante muda — `invoice.created`, `payment.succeeded`, `subscription.canceled`, `nfe.issued` e dezenas de outros. É a mesma fila que alimenta os [Webhooks](https://docs.billing.kobana.com.br/pt/pt/webhooks.md) e o histórico do cliente no portal. ## Por que isso importa[​](#por-que-isso-importa "Link direto para Por que isso importa") Diferente da [Auditoria](https://docs.billing.kobana.com.br/pt/pt/configuracoes/auditoria.md), que registra alterações feitas por humanos, **eventos** representam o que aconteceu do ponto de vista do domínio do negócio — independentemente da origem (UI, API, worker, webhook recebido de gateway). Eventos são úteis para: * **Debug**: descobrir por que um webhook não chegou ao destino ou por que uma assinatura foi cancelada inesperadamente. * **Replays**: reenviar eventos para um endpoint que estava fora do ar. * **Integrações**: confirmar que um evento esperado foi de fato gerado. ## Estrutura do evento[​](#estrutura-do-evento "Link direto para Estrutura do evento") Cada evento contém: * **type** — nome no padrão `recurso.acao` (ex.: `invoice.paid`) * **resource\_type** e **resource\_id** — a entidade afetada * **payload** — JSON com o estado relevante no momento do evento * **created\_at** — quando o evento foi emitido * **delivery\_status** — agregado das tentativas de entrega para os endpoints assinantes ## Filtros e busca[​](#filtros-e-busca "Link direto para Filtros e busca") A lista oferece filtros por tipo de evento, recurso, intervalo de datas e status de entrega. Cada linha pode ser expandida para mostrar o payload completo e o histórico de tentativas em cada endpoint inscrito. ## Catálogo de eventos[​](#catálogo-de-eventos "Link direto para Catálogo de eventos") A referência completa dos tipos de evento (e quando cada um é disparado) está em [Webhooks > Eventos](https://docs.billing.kobana.com.br/pt/pt/webhooks/eventos/.md). ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Lista de eventos com tipo, recurso, payload e status de entrega](/pt/assets/images/eventos-708ac6569a387a1d7985b2ac602eb30d.png) --- # Feriados Os feriados são os dias em que os bancos não funcionam. Servem a dois propósitos: * **Achar o vencimento efetivo**: uma fatura que vence em fim de semana ou feriado pode ser paga no próximo dia útil sem multa nem juros. * **Contar dias úteis** quando a política de juros e multa cobra juros por dia útil em vez de por dia corrido. Cada organização tem sua própria lista. Um feriado municipal move o dia útil para um cliente e não para outro, e remover um feriado na sua conta não afeta nenhuma outra. ## Onde configurar[​](#onde-configurar "Link direto para Onde configurar") `Sistema` → **Feriados**. A tela mostra os feriados do ano selecionado, com o dia da semana e a origem de cada linha. ## Importação automática[​](#importação-automática "Link direto para Importação automática") Toda organização criada na plataforma já vem com os **feriados nacionais** do ano corrente e dos dois seguintes, importados da [BrasilAPI](https://brasilapi.com.br/docs#tag/Feriados-Nacionais). Para trazer outro ano, ou preencher o que faltou, use **Importar nacionais** com o ano selecionado. A importação inclui Carnaval, Sexta-feira Santa, Páscoa e Corpus Christi. Tecnicamente Carnaval e Corpus Christi são pontos facultativos, não feriados nacionais — mas os bancos fecham neles, e é o fechamento do banco que interessa para contar dia útil. :::note A importação não desfaz uma remoção Se você remover um feriado, importar os nacionais de novo **não** o traz de volta. A linha removida fica registrada exatamente para que a importação saiba respeitar a sua decisão. Quando isso acontece, a tela avisa quantos feriados removidos ficaram de fora. ::: ## Cadastrar à mão[​](#cadastrar-à-mão "Link direto para Cadastrar à mão") Use **Novo feriado** para feriados estaduais, municipais, pontos facultativos da sua operação ou datas próprias. | Campo | Descrição | | --------------- | ---------------------------------------------------------------------------------------- | | **Data** | O dia no calendário. Sem hora — um feriado é uma data, não um instante | | **Nome** | Junto com a data, identifica a linha. Um municipal e um nacional podem cair no mesmo dia | | **Abrangência** | Nacional, estadual, municipal, ponto facultativo ou próprio | | **Observações** | Texto livre — a cidade de um feriado municipal, por exemplo | Um feriado que cai em sábado ou domingo não muda nada na contagem: aqueles dias já não eram úteis. A tela sinaliza isso para poupar a dúvida. ## Como afeta os juros[​](#como-afeta-os-juros "Link direto para Como afeta os juros") Na política de juros e multa, o campo **Contagem de dias** decide o que conta: * **Dias corridos** — todos os dias, incluindo fins de semana e feriados. * **Dias úteis** — só os dias em que o banco funciona, segundo esta lista. Com R$ 1.000,00 a 1% ao mês vencidos numa quinta-feira e olhados na segunda seguinte: | Contagem | Dias | Juros | | -------------------------- | ------------------- | ------- | | Corridos | 4 | R$ 1,33 | | Úteis | 2 (sexta e segunda) | R$ 0,67 | | Úteis, com a sexta feriado | 1 (segunda) | R$ 0,33 | A **multa** não é afetada: ela incide uma vez, contada em dias corridos. O registro bancário também trata a multa assim — não existe instrução de "dias úteis para multa". :::caution Sem feriados cadastrados, a conta fica errada Se a política cobra por dia útil e a lista está vazia, o cálculo desconta apenas os fins de semana. O banco desconta os feriados também, então ele vai recolher menos do que apuramos — e a diferença aparece como crédito na conta do cliente, junto com o evento `invoice.late_charges_unexplained`. Importe os nacionais antes de ligar a cobrança por dia útil. ::: ## Vencimento em fim de semana ou feriado[​](#vencimento-em-fim-de-semana-ou-feriado "Link direto para Vencimento em fim de semana ou feriado") Um boleto que vence num dia sem expediente bancário pode ser pago no próximo dia útil sem encargos — é a regra da Febraban, e o boleto já é registrado com essa data. A multa e os juros seguem o vencimento do boleto: contam a partir do **próximo dia útil**, qualquer que seja a contagem de dias da política. Uma fatura que vence no sábado e é paga na segunda não paga multa nem juros. Paga na terça, conta um dia de atraso, a partir de segunda. Para que a própria fatura já mostre essa data — e não só o boleto —, ligue **Vencimento sempre em dia útil** em `Configurações` → **Faturamento**. Com a opção ligada, todo vencimento que cair em fim de semana ou feriado passa para o próximo dia útil: o calculado pelo prazo de pagamento, o digitado à mão e o de cada parcela. Faturas importadas mantêm a data do arquivo. ## Pela API[​](#pela-api "Link direto para Pela API") O recurso é `/v1/holidays`. As datas são dias civis (`YYYY-MM-DD`), nunca instantes. ``` # Listar os feriados de um ano curl "https://api.kobana.com.br/billing/v1/holidays?year=2026" \ -H "Authorization: Bearer $TOKEN" # Cadastrar um 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 os nacionais 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]}' ``` A resposta da importação traz `created`, `existing` e `skipped_removed` — o último conta os feriados que estavam removidos e foram deixados de fora. ## Perguntas frequentes[​](#perguntas-frequentes "Link direto para Perguntas frequentes") **Preciso cadastrar feriados se cobro juros por dia corrido?** Sim. Mesmo com dias corridos, um vencimento que cai em feriado passa para o dia útil seguinte, e só a lista diz quais dias são feriados. Sem ela, apenas os fins de semana movem o vencimento. **Os feriados valem para todas as minhas empresas?** A lista é por organização, então vale para todas as empresas dentro dela. Se uma empresa fica num município com feriado próprio, cadastre-o com abrangência municipal e anote a cidade nas observações. **Por que a Páscoa aparece na lista, se cai sempre num domingo?** A BrasilAPI a devolve, e guardá-la é inofensivo: um feriado em fim de semana não altera a contagem. **Quem pode editar?** Quem tem permissão de atualizar configurações — a mesma de `Configurações`. --- # Membros e Papéis A página de membros (`/dashboard/members`) lista todas as pessoas com acesso ao dashboard da organização. Cada membro tem um e-mail vinculado à autenticação Kobana e um ou mais **papéis** que definem o que pode ver e modificar. ## Convidar um membro[​](#convidar-um-membro "Link direto para Convidar um membro") 1. Clicar em **Convidar membro** e informar o e-mail. 2. Selecionar um ou mais papéis (ex.: `admin`, `fiscal`, `financeiro`, `read_only`). 3. O usuário recebe um link de aceite por e-mail. 4. Após aceitar, o membro aparece com status `active` e pode entrar pelo SSO. ## Status do membro[​](#status-do-membro "Link direto para Status do membro") * **invited** — convite enviado, aguardando aceite. * **active** — acesso liberado. * **suspended** — acesso bloqueado temporariamente, sem remover o histórico. * **removed** — membro removido (mantém auditoria das ações anteriores). ## Papéis (Roles)[​](#papéis-roles "Link direto para Papéis (Roles)") Os papéis são gerenciados em `/dashboard/members/roles`. Cada papel é um conjunto de permissões granulares — por exemplo, "pode emitir NF-e", "pode estornar pagamento", "pode alterar plano". A organização pode criar papéis customizados além dos papéis padrão. ### Papéis padrão[​](#papéis-padrão "Link direto para Papéis padrão") | Papel | Acesso típico | | -------------- | -------------------------------------------------------- | | **Owner** | Acesso total, inclusive faturamento da plataforma | | **Admin** | Configurações, membros, faturas, planos, NF-e | | **Financeiro** | Faturas, pagamentos, créditos, dunning, exportações | | **Fiscal** | NF-e, regras tributárias, períodos fiscais, certificados | | **Comercial** | Clientes, planos, assinaturas, propostas | | **Read-only** | Visualização de todas as áreas, sem ações | ### Permissões customizadas[​](#permissões-customizadas "Link direto para Permissões customizadas") Ao criar um papel novo, é possível ativar/desativar permissões individualmente por recurso (clientes, assinaturas, faturas, NF-e, regras fiscais, gateways, webhooks etc.). Cada permissão pode ser de leitura, criação, edição ou exclusão. ## Auditoria[​](#auditoria "Link direto para Auditoria") Toda alteração em membros e papéis é registrada em [Auditoria](https://docs.billing.kobana.com.br/pt/pt/configuracoes/auditoria.md): quem convidou, quem aceitou, quem alterou um papel, IP e User-Agent. ## Capturas de tela[​](#capturas-de-tela "Link direto para Capturas de tela") ### Lista de membros[​](#lista-de-membros "Link direto para Lista de membros") ![Lista de membros com e-mail, papéis e status](/pt/assets/images/membros-8f6e4b2054f0c2ef64ffed2a2bf6ae96.png) ### Gerenciamento de papéis[​](#gerenciamento-de-papéis "Link direto para Gerenciamento de papéis") ![Tela de configuração de papéis e permissões granulares](/pt/assets/images/membros-papeis-fe36d1e25cb9be326a76cdb5ed451473.png) --- # Notificações O sistema de notificações envia comunicações multicanal para clientes sobre eventos importantes. ## Canais[​](#canais "Link direto para Canais") | Canal | Descrição | | ----------- | ------------------------------------------- | | **email** | Envio via SMTP | | **in\_app** | Armazenada no banco para exibição no portal | | **webhook** | Enviada ao endpoint configurado | ## Tipos de Notificação[​](#tipos-de-notificação "Link direto para Tipos de Notificação") ### Assinaturas[​](#assinaturas "Link direto para Assinaturas") * `subscription_renewal` — Assinatura renovada * `subscription_created` — Nova assinatura * `subscription_canceled` — Assinatura cancelada ### Pagamentos[​](#pagamentos "Link direto para Pagamentos") * `payment_succeeded` — Pagamento processado * `payment_failed` — Pagamento falhou ### Faturas[​](#faturas "Link direto para Faturas") * `invoice_created` — Fatura gerada * `invoice_overdue` — Fatura vencida ### Conta[​](#conta "Link direto para Conta") * `trial_ending` — Trial expirando * `plan_changed` — Plano alterado * `account_suspended` — Conta suspensa * `account_activated` — Conta reativada ### Portal[​](#portal "Link direto para Portal") * `portal_invitation` — Convite para o portal * `portal_signup_verification` — Verificação de e-mail ### Propostas[​](#propostas "Link direto para Propostas") * `proposal_sent` — Proposta enviada * `proposal_reminder` — Lembrete de proposta * `proposal_expired` — Proposta expirada * `proposal_accepted` — Proposta aceita * `proposal_rejected` — Proposta rejeitada ## Status da Notificação[​](#status-da-notificação "Link direto para Status da Notificação") | Status | Descrição | | ----------- | ------------------------ | | `pending` | Aguardando envio | | `sent` | Enviada/enfileirada | | `delivered` | Confirmada como entregue | | `failed` | Falha no envio | | `read` | Lida (apenas in\_app) | ## Preferências[​](#preferências "Link direto para Preferências") Cada conta de cobrança pode configurar preferências por tipo de notificação: * Habilitar/desabilitar e-mail * Habilitar/desabilitar in-app * Habilitar/desabilitar webhook O sistema verifica as preferências antes de enviar. ## Retry[​](#retry "Link direto para Retry") Notificações falhas podem ser retentadas manualmente. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") A tela `/dashboard/notifications` reúne configuração de canais (e-mail, in-app, webhook), templates por evento, histórico de envios com status (`sent`, `delivered`, `bounced`, `failed`), gráficos de entregas no período e filtros por canal, destinatário e tipo de notificação. ![Configuração e histórico de notificações multicanal](/pt/assets/images/notificacoes-643a769713189ce94665b3a9e50ea54e.png) --- # Perfil do Usuário A página `/dashboard/profile` reúne as **preferências pessoais** do operador logado: tema, idioma, fuso horário e configurações de notificação. Diferente das configurações da organização (que afetam todos os membros), as preferências de perfil são por usuário e ficam armazenadas localmente e no servidor. ## Dados da conta[​](#dados-da-conta "Link direto para Dados da conta") Mostra informações vindas do provedor de autenticação (Kobana OAuth): * **Nome** e **e-mail** * **Organizações** às quais o usuário tem acesso * **Papéis** atribuídos em cada organização ## Aparência[​](#aparência "Link direto para Aparência") * **Tema** — claro, escuro ou automático (segue o sistema operacional). * **Idioma** — `pt-BR` ou `en-US`. A troca atualiza imediatamente as mensagens da interface. ## Onboarding[​](#onboarding "Link direto para Onboarding") O perfil também expõe controles do onboarding interativo: reativar dicas, marcar etapas como vistas e revisitar o checklist inicial do dashboard. ## Editor de assinatura de e-mail[​](#editor-de-assinatura-de-e-mail "Link direto para Editor de assinatura de e-mail") Inclui um editor rich-text usado para personalizar a assinatura aplicada em comunicações enviadas em nome do operador (negrito, itálico, links, imagens, listas, tabelas, etc.). ## Como as preferências são persistidas[​](#como-as-preferências-são-persistidas "Link direto para Como as preferências são persistidas") * **localStorage** — `kobana-billing-preferences` guarda tema e idioma para hidratação imediata. * **Servidor** — alterações persistem na conta do usuário para sincronizar entre dispositivos. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Perfil do usuário com aparência, idioma e assinatura de e-mail](/pt/assets/images/perfil-5eb425dced19c2893af38371839605ee.png) --- # Rate Limiting O sistema implementa limites de requisições da API para proteger a plataforma e garantir uso justo. ## Limites Padrão[​](#limites-padrão "Link direto para Limites Padrão") | Tipo | Por Minuto | Por Hora | | ----------------------------------- | ---------- | -------- | | **Leitura (GET)** | 200 | 5.000 | | **Escrita (POST/PUT/PATCH/DELETE)** | 60 | 1.000 | ### Limite de Burst[​](#limite-de-burst "Link direto para Limite de Burst") | Campo | Padrão | Descrição | | ------------------- | ---------- | --------------------------------- | | **Burst limit** | 20 | Máximo de requisições simultâneas | | **Janela de burst** | 5 segundos | Janela para contagem de burst | ## Configuração por Organização[​](#configuração-por-organização "Link direto para Configuração por Organização") Cada organização pode ter limites personalizados. Se não configurado, usa os limites globais. ## Hierarquia[​](#hierarquia "Link direto para Hierarquia") 1. Configuração da organização (se existir) 2. Configuração global padrão (se existir) 3. Valores hardcoded do sistema ## Operações[​](#operações "Link direto para Operações") * **Visualizar**: Ver limites atuais da organização * **Personalizar**: Definir limites customizados * **Remover**: Voltar aos limites globais * **Desabilitar**: Desativar rate limiting (não recomendado) --- # Relatórios A central de relatórios (`/dashboard/reports`) é o lugar onde times de finanças, operações e atendimento geram **extrações tabulares** dos dados da organização. Diferente de [Analytics](https://docs.billing.kobana.com.br/pt/pt/configuracoes/analytics.md), que agrega métricas, os relatórios entregam dados linha-a-linha prontos para conciliar, auditar ou compor planilhas externas. ## Relatórios disponíveis[​](#relatórios-disponíveis "Link direto para Relatórios disponíveis") * **Faturas no período** — todas as faturas com cliente, status, valor, datas e meio de pagamento. * **Pagamentos no período** — pagamentos recebidos, com gateway, método, taxa e líquido. * **Estornos e reembolsos** — operações de reversão, com motivo e operador. * **Assinaturas ativas** — snapshot da base ativa com plano, MRR, próximo ciclo e método de cobrança. * **Churn detalhado** — assinaturas canceladas no período, com motivo e LTV final. * **Inadimplência** — contas com fatura em aberto, agrupadas por faixa (1-30, 31-60, 61-90, 90+). * **Conciliação de gateway** — comparativo entre o que a plataforma registrou e o que o gateway confirmou. ## Como gerar[​](#como-gerar "Link direto para Como gerar") 1. Escolher o tipo de relatório. 2. Definir filtros (intervalo de datas, empresa, plano, status, gateway). 3. Selecionar o formato (CSV ou XLSX). 4. Confirmar — a geração entra na fila de exportações. 5. Quando pronto, o arquivo fica disponível em [Exportações](https://docs.billing.kobana.com.br/pt/pt/exportacao-e-importacao/exportacoes/.md) e é enviado por e-mail. Relatórios pesados rodam em background para não travar o navegador. O status (`pending`, `processing`, `completed`, `failed`) é atualizado em tempo real. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Central de relatórios com filtros e formato de exportação](/pt/assets/images/relatorios-aaa0a95fdbfa3e35d23aecdcdf14c84d.png) --- # Templates de E-mail Templates de e-mail permitem personalizar as comunicações transacionais enviadas aos clientes. ## Campos do Template[​](#campos-do-template "Link direto para Campos do Template") | Campo | Descrição | | --------------- | ------------------------------------------- | | **Nome** | Nome do template | | **Slug** | Identificador único | | **Tipo** | Tipo de notificação associada | | **Assunto** | Linha de assunto (suporta variáveis) | | **Corpo HTML** | Conteúdo HTML do e-mail (suporta variáveis) | | **Corpo texto** | Versão em texto puro (fallback) | | **Variáveis** | Lista de variáveis utilizadas | | **Padrão** | Um template padrão por tipo de notificação | | **Ativo** | Se o template está disponível | ## Variáveis[​](#variáveis "Link direto para Variáveis") Variáveis são substituídas no assunto e corpo usando a sintaxe `{{ nome_variavel }}`: | Variável | Descrição | | ------------------------- | ----------------------------- | | `{{ customer_name }}` | Nome do cliente | | `{{ invoice_number }}` | Número da fatura | | `{{ amount }}` | Valor em moeda | | `{{ due_date }}` | Data de vencimento | | `{{ verification_url }}` | Link de verificação de e-mail | | `{{ reset_url }}` | Link de reset de senha | | `{{ subscription_name }}` | Nome do plano | | `{{ trial_end_date }}` | Data de fim do trial | ## Operações[​](#operações "Link direto para Operações") * **Criar**: Novo template com nome, slug, tipo e conteúdo * **Atualizar**: Editar assunto, corpo e variáveis * **Duplicar**: Copiar template com novo slug * **Deletar**: Não é possível deletar o template padrão * **Preview**: Visualizar o template com dados de exemplo * **Definir como padrão**: Marca como template padrão para o tipo ## Renderização[​](#renderização "Link direto para Renderização") 1. Obtém o template por ID ou pelo tipo (usa o padrão) 2. Carrega todas as variáveis do contexto 3. Substitui todos os padrões `{{ chave }}` pelos valores 4. Retorna assunto e corpo HTML renderizados ## Segurança[​](#segurança "Link direto para Segurança") * Caracteres especiais são escapados via regex para prevenir ReDoS * Input do usuário é sanitizado antes da renderização --- # Uso e Consumo A tela `/dashboard/usage` consolida o **consumo medido** (metered) de todos os clientes da organização: eventos de API, mensagens enviadas, transações processadas, armazenamento — qualquer métrica que o catálogo defina como "uso" e que seja cobrada por consumo. ## Visão consolidada[​](#visão-consolidada "Link direto para Visão consolidada") A tabela principal agrupa o consumo por produto e por conta de cobrança, com: * **Produto** (com unidade de medida — chamadas, eventos, mensagens, GB) * **Cliente / conta de cobrança** * **Quantidade no período** * **Último evento registrado** — com tempo relativo * **Valor estimado** — projeção de cobrança para a próxima fatura ## Filtros[​](#filtros "Link direto para Filtros") * **Intervalo de datas** — padrão do início do mês atual até hoje. * **Cliente** — combobox de contas de cobrança. * **Mostrar zeros** — alterna se contas sem consumo aparecem na lista. ## De onde vêm os dados[​](#de-onde-vêm-os-dados "Link direto para De onde vêm os dados") Eventos de uso chegam por: 1. **API de Usage Records** — `POST /v1/subscription_items/{id}/usage_records` (padrão Stripe-like). 2. **Worker `usage-sync`** — executado a cada hora, agrega contadores externos quando configurado. 3. **Importação CSV** — para cargas batch, via [Importações](https://docs.billing.kobana.com.br/pt/pt/exportacao-e-importacao/importacoes/.md). Cada registro de uso é vinculado a um `SubscriptionItem` com produto **metered**. Na virada do ciclo, o worker `invoice-generation` materializa o consumo do período em uma linha de fatura. ## Limpeza[​](#limpeza "Link direto para Limpeza") Operadores com permissão podem zerar registros de uso de um cliente (útil em casos de teste). A ação fica registrada em [Auditoria](https://docs.billing.kobana.com.br/pt/pt/configuracoes/auditoria.md). ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Painel de uso consolidado com consumo por produto e cliente](/pt/assets/images/uso-06327a3a57be8a23643e4ca5c2ff1461.png) --- # Usuários A página `/dashboard/users` lista os **usuários do portal do cliente** — pessoas físicas vinculadas a uma conta de cobrança (`BillingAccount`) que conseguem entrar no portal para ver faturas, pagar boletos, gerenciar cartões e atualizar dados. Diferente de [Membros](https://docs.billing.kobana.com.br/pt/pt/configuracoes/membros.md), que são operadores internos da organização, usuários do portal são clientes finais (B2B2C). Eles autenticam via link mágico ou OAuth Kobana e veem apenas os dados da própria conta de cobrança. ## O que a lista mostra[​](#o-que-a-lista-mostra "Link direto para O que a lista mostra") * **E-mail** do usuário * **Conta de cobrança** vinculada (razão social ou nome do cliente) * **Status** — `pending`, `active`, `suspended` * **Último acesso** — data e horário da última sessão * **Convites pendentes** — links que ainda não foram aceitos ## Convidar um usuário[​](#convidar-um-usuário "Link direto para Convidar um usuário") A partir do detalhe de uma [conta de cobrança](https://docs.billing.kobana.com.br/pt/pt/contas/contas-de-cobranca/.md) ou diretamente nesta tela, é possível: 1. Inserir o e-mail do contato responsável. 2. Definir permissões dentro do portal (visualizar, pagar, alterar plano, gerenciar métodos). 3. Enviar o convite — o usuário recebe um link de ativação. O token de ativação é armazenado criptografado (`lib/crypto.ts`) e expira após o uso ou prazo configurado. ## Reenviar e revogar[​](#reenviar-e-revogar "Link direto para Reenviar e revogar") * **Reenviar convite** — gera novo token e dispara novo e-mail. * **Suspender** — bloqueia o login sem apagar dados. * **Remover** — desativa em definitivo. O histórico de auditoria permanece. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Lista de usuários do portal com e-mail, conta de cobrança e status](/pt/assets/images/usuarios-do-portal-f3d3e33507f88c65cd6220db265d45a2.png) --- ## [📄️Clientes (Pessoas)](https://docs.billing.kobana.com.br/pt/pt/contas/clientes/.md) [Clientes são representados pelo modelo Pessoa (Person) com diferentes tipos conforme o contexto.](https://docs.billing.kobana.com.br/pt/pt/contas/clientes/.md) --- ## [📄️Clientes (Pessoas)](https://docs.billing.kobana.com.br/pt/pt/contas/clientes/.md) [Clientes são representados pelo modelo Pessoa (Person) com diferentes tipos conforme o contexto.](https://docs.billing.kobana.com.br/pt/pt/contas/clientes/.md) --- # Clientes (Pessoas) Clientes são representados pelo modelo **Pessoa** (`Person`) com diferentes tipos conforme o contexto. ## Tipos de Pessoa[​](#tipos-de-pessoa "Link direto para Tipos de Pessoa") | Tipo | Descrição | | -------------- | --------------------------------------- | | `organization` | Tenant/organização que usa a plataforma | | `customer` | Cliente de uma organização | | `contact` | Contato secundário | ## Campos do Cliente[​](#campos-do-cliente "Link direto para Campos do Cliente") | Campo | Descrição | | ------------------------ | ---------------------------------------------------------- | | **Nome** | Nome ou razão social | | **Apelido** | Nome fantasia | | **Nome legal** | Razão social completa | | **Tipo de documento** | CPF ou CNPJ | | **Número do documento** | Normalizado (apenas dígitos) | | **Natureza** | `natural` (pessoa física) ou `juridical` (pessoa jurídica) | | **Data de nascimento** | Opcional | | **Endereços** | Lista de endereços (JSON) | | **Telefones** | Lista de telefones (JSON) | | **E-mails** | Lista de e-mails (JSON) | | **Sites** | Lista de websites (JSON) | | **Tags** | Lista de tags para categorização | | **Notas** | Observações internas | | **Dados personalizados** | Campos customizados (JSON) | ## Hierarquia[​](#hierarquia "Link direto para Hierarquia") Clientes pertencem a uma organização via o campo `parent_id`: ``` Organização (type=organization, parentId=null) ├── Cliente A (type=customer, parentId=org_id) ├── Cliente B (type=customer, parentId=org_id) └── Contato (type=contact, parentId=org_id) ``` ## Validações[​](#validações "Link direto para Validações") * Número de documento único dentro da organização * Código externo (`external_id`) único por organização * Restrições no formato do documento: CPF (11 dígitos) ou CNPJ (14 dígitos) ## Capturas de tela[​](#capturas-de-tela "Link direto para Capturas de tela") ### Lista de clientes[​](#lista-de-clientes "Link direto para Lista de clientes") A tela `/dashboard/customers` lista clientes da organização com busca por nome, documento ou e-mail. A tabela mostra documento, e-mail, total de contas de cobrança vinculadas e MRR consolidado. ![Lista de clientes com nome, documento e contas de cobrança](/pt/assets/images/clientes-2bbf4854035d5a9d08e58398a4eb6cff.png) ### Detalhe do cliente[​](#detalhe-do-cliente "Link direto para Detalhe do cliente") A página `/dashboard/customers/[id]` reúne dados cadastrais, contas de cobrança vinculadas, assinaturas, faturas, pagamentos, NF-e e auditoria — tudo em um único contexto para suporte e financeiro. ![Detalhe de um cliente com abas de cobrança, assinaturas e faturas](/pt/assets/images/cliente-detalhe-623e0e75b788cb25baeb0443201209ec.png) --- # Contas de Cobrança Contas de cobrança (BillingAccount) representam o relacionamento financeiro entre uma organização e seu cliente. Cada conta possui assinaturas, faturas, pagamentos e métodos de pagamento. ## Campos[​](#campos "Link direto para Campos") | Campo | Descrição | | ---------------------- | ------------------------------------------------------ | | **Organização** | Organização proprietária (obrigatório) | | **Pessoa** | Cliente associado (tipo=customer) | | **ID externo** | Identificador para integrações (único por organização) | | **Moeda** | Moeda de cobrança (padrão: BRL) | | **E-mail de cobrança** | E-mail para receber faturas | | **Dias de prazo** | Prazo de pagamento em dias (padrão: 10) | | **Auto-cobrança** | Se faturas são cobradas automaticamente | | **Saldo** | Saldo de créditos/débitos da conta | | **Status** | `active`, `suspended` ou `closed` | ### Configuração Fiscal[​](#configuração-fiscal "Link direto para Configuração Fiscal") | Campo | Descrição | | -------------------------- | ----------------------------- | | **Isento de impostos** | Se o cliente é isento | | **Certificado de isenção** | Documento de isenção | | **Tipo fiscal do cliente** | Classificação tributária | | **Reter ISS** | Flag de retenção de ISS | | **Reter IRRF** | Flag de retenção de IRRF | | **Reter CSRF** | Flag de retenção de CSRF | | **Reter INSS** | Flag de retenção de INSS | | **Inscrição municipal** | Número de inscrição municipal | ## Status e Ciclo de Vida[​](#status-e-ciclo-de-vida "Link direto para Status e Ciclo de Vida") ``` active → suspended ↔ active ↓ closed ``` | Status | Descrição | | ------------- | --------------------------------------------------------------- | | **active** | Conta operacional | | **suspended** | Suspensa por inadimplência ou manualmente. Assinaturas pausadas | | **closed** | Encerrada permanentemente | ### Suspensão[​](#suspensão "Link direto para Suspensão") * Define `suspended_at` e `suspension_reason` * Todas as assinaturas ativas são pausadas * Notificação enviada ao cliente * Pode ser reativada manualmente ### Encerramento[​](#encerramento "Link direto para Encerramento") * Todas as assinaturas devem estar inativas/canceladas * Permanente (soft delete via `deletedAt`) ## Unicidade[​](#unicidade "Link direto para Unicidade") * Uma conta de cobrança por cliente por organização * ID externo único por organização * Documento do cliente único por organização ## Estatísticas[​](#estatísticas "Link direto para Estatísticas") O dashboard exibe contadores por status: * Total de contas * Contas ativas * Contas suspensas * Contas com assinatura ativa --- # Empresas Em `/dashboard/companies` a organização cadastra as **pessoas jurídicas emissoras** — empresas que assinam contratos, faturas e NF-e. Uma organização pode ter várias empresas (matriz, filiais ou CNPJs diferentes do mesmo grupo) e definir uma como padrão para cobranças. ## Dados de cadastro[​](#dados-de-cadastro "Link direto para Dados de cadastro") Cada empresa concentra: * **Razão social e nome fantasia** * **CNPJ** e inscrições municipal e estadual * **Endereço completo** (CEP, logradouro, número, complemento, bairro, cidade, UF) * **Regime tributário** — Simples Nacional, Lucro Presumido, Lucro Real, MEI * **Anexo do Simples Nacional** (quando aplicável) e fator R * **Contato fiscal** — e-mail e telefone para envio de NF-e e comunicações fiscais * **Status** — ativa ou desativada ## Empresa padrão[​](#empresa-padrão "Link direto para Empresa padrão") Uma das empresas é marcada como padrão. Toda nova fatura ou NF-e usa essa empresa como emissora, exceto quando o cliente, o plano ou a assinatura especificam outra. Trocar a empresa padrão não altera faturas ou assinaturas já existentes. ## Multi-empresa[​](#multi-empresa "Link direto para Multi-empresa") O suporte multi-empresa permite que um grupo opere CNPJs distintos no mesmo painel: * **Catálogo separado por empresa** — cada empresa pode ter seus próprios produtos, itens de serviço e regras tributárias. * **Apuração fiscal isolada** — períodos fiscais e DAS são calculados por empresa. * **Faturas emitidas pela empresa correta** — o cliente vê o CNPJ certo na fatura e no boleto. ## Desativação[​](#desativação "Link direto para Desativação") Empresas podem ser desativadas (não excluídas) para parar de receber novas faturas mantendo o histórico fiscal acessível. A ação é registrada em [Auditoria](https://docs.billing.kobana.com.br/pt/pt/configuracoes/auditoria.md). ## Captura de tela — lista[​](#captura-de-tela--lista "Link direto para Captura de tela — lista") ![Lista de empresas cadastradas com CNPJ e regime tributário](/pt/assets/images/empresas-65bc1eea7c2461c10863f06309a65bba.png) ## Captura de tela — detalhe[​](#captura-de-tela--detalhe "Link direto para Captura de tela — detalhe") A página de detalhe (`/dashboard/companies/[id]`) reúne dados fiscais, contatos, endereço e o histórico de faturas e NF-e emitidas pela empresa. ![Detalhe de uma empresa com dados fiscais e abas de faturas e NF-e](/pt/assets/images/empresa-detalhe-b287b7e4d83cfc6fb91fbacea8731c9d.png) --- # Organizações Organizações são os tenants (inquilinos) da plataforma. Cada organização é um negócio que usa o Faturamento Automático para cobrar seus próprios clientes. ## Campos da Organização[​](#campos-da-organização "Link direto para Campos da Organização") | Campo | Descrição | | ----------------------- | --------------------------------------------- | | **ID externo** | Identificador único para integrações externas | | **Nome** | Nome da organização | | **Tipo de documento** | CPF ou CNPJ | | **Número do documento** | CPF ou CNPJ (normalizado, apenas dígitos) | | **E-mail** | E-mail principal de contato | | **Telefone** | Telefone de contato | | **Endereços** | Lista de endereços | | **Status** | `active` (padrão) | ## Bootstrap Automático[​](#bootstrap-automático "Link direto para Bootstrap Automático") Ao criar uma organização, o sistema automaticamente: 1. **Cria a empresa padrão** com os mesmos dados cadastrais 2. **Cria os papéis de dashboard** padrão (owner, admin, viewer) 3. **Cria o usuário proprietário** com o e-mail da organização ## Ciclo de Vida[​](#ciclo-de-vida "Link direto para Ciclo de Vida") * **Criar**: Fornece dados cadastrais, recebe organização pronta com empresa e usuários * **Atualizar**: Nome, contato e endereços editáveis * **Deletar**: Soft delete (apenas se não houver contas de cobrança ativas) ## Modelo de Dados[​](#modelo-de-dados "Link direto para Modelo de Dados") A organização utiliza uma **Pessoa** (`Person` com `type=organization`) para armazenar os dados cadastrais. Isso permite que organizações e clientes compartilhem o mesmo modelo flexível de dados. --- # Portal do Cliente O portal do cliente permite que os clientes finais de cada organização gerenciem suas assinaturas, faturas e métodos de pagamento de forma autônoma. ## Acesso[​](#acesso "Link direto para Acesso") O portal é acessado via URL personalizada da organização. Cada organização configura seu portal com branding, domínio e funcionalidades específicas. ## Funcionalidades do Portal[​](#funcionalidades-do-portal "Link direto para Funcionalidades do Portal") * Visualizar e pagar faturas * Gerenciar assinaturas (pausar, cancelar, se permitido) * Atualizar métodos de pagamento * Visualizar histórico de transações * Aceitar/rejeitar propostas comerciais ## Usuário do Portal (PortalUser)[​](#usuário-do-portal-portaluser "Link direto para Usuário do Portal (PortalUser)") | Campo | Descrição | | --------------------- | ------------------------------ | | **E-mail** | Único por conta de cobrança | | **Conta de cobrança** | Vínculo com a conta financeira | | **Apenas SSO** | Se true, login apenas via SSO | | **Status** | Estado do usuário | ### Status do Usuário[​](#status-do-usuário "Link direto para Status do Usuário") | Status | Descrição | | ---------------------- | ----------------------------------------- | | `active` | Usuário ativo com acesso completo | | `pending_verification` | Aguardando verificação de e-mail (signup) | | `pending_invitation` | Aguardando aceitar convite | | `suspended` | Conta suspensa | | `locked` | Bloqueado por tentativas de login falhas | ### Segurança[​](#segurança "Link direto para Segurança") * Senhas hasheadas com bcrypt * Tokens de verificação/reset baseados em HMAC * Bloqueio automático após tentativas de login falhas * Tokens de verificação expiram em 24 horas * Tokens de convite expiram em 7 dias ## Convites[​](#convites "Link direto para Convites") O sistema de convites permite que a organização envie convites por e-mail: 1. O convite é enviado com um token temporário (7 dias) 2. O destinatário aceita e define sua senha 3. O status muda para `active` 4. Convites pendentes podem ser cancelados ou reenviados ## Cadastro Self-Service[​](#cadastro-self-service "Link direto para Cadastro Self-Service") Organizações podem habilitar cadastro público: 1. O cliente acessa a página de signup via slug único 2. Informa CNPJ (validado na Receita Federal via API minhareceita.org) 3. Preenche dados da empresa e administrador 4. Um e-mail de verificação é enviado 5. Após verificação, o acesso é liberado ### Validação de CNPJ[​](#validação-de-cnpj "Link direto para Validação de CNPJ") * CNPJ deve estar com situação cadastral "Ativa" * CNPJ não pode já estar cadastrado na organização * CNPJs com situação "Baixada" são bloqueados ## Configuração do Portal[​](#configuração-do-portal "Link direto para Configuração do Portal") | Configuração | Descrição | | ------------------- | ------------------------------------------ | | **Nome da empresa** | Nome exibido no portal | | **Logo** | Logotipo claro e escuro | | **Cores** | Tema claro e escuro (HSL) | | **Idiomas** | Idiomas disponíveis (padrão: pt-BR, en-US) | | **Pagamentos** | Métodos habilitados (cartão, boleto, PIX) | | **Assinaturas** | Permitir pausar/cancelar | | **Convites** | Habilitar convites e domínios permitidos | | **Signup** | Slug e habilitar cadastro público | | **SSO** | Chave pública, algoritmo e emissor | ### SSO (Single Sign-On)[​](#sso-single-sign-on "Link direto para SSO (Single Sign-On)") O portal suporta SSO via JWT: * Algoritmos suportados: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 * Configurar chave pública PEM e emissor (iss claim) * Usuários SSO-only não precisam de senha ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") A tela `/dashboard/portal` reúne a configuração visual e funcional do portal do cliente: logo, paleta de cores para tema claro e escuro, idiomas suportados, domínio customizado, texto do e-mail de convite, métodos de pagamento habilitados, autenticação (link mágico, OAuth, JWT SSO) e quais áreas o cliente pode ver/editar. ![Configuração visual e funcional do portal do cliente](/pt/assets/images/portal-do-cliente-0540d5533460054d51981c59c1933ead.png) Para a documentação das telas vistas pelo cliente final, consulte [Portal do Cliente](https://docs.billing.kobana.com.br/pt/pt/portal.md). --- ## [📄️Códigos de Desconto](https://docs.billing.kobana.com.br/pt/pt/cupons-e-descontos/codigos-de-desconto/.md) [Códigos de desconto são aplicados diretamente a assinaturas no momento da criação, oferecendo descontos recorrentes ou pontuais.](https://docs.billing.kobana.com.br/pt/pt/cupons-e-descontos/codigos-de-desconto/.md) --- ## [📄️Códigos de Desconto](https://docs.billing.kobana.com.br/pt/pt/cupons-e-descontos/codigos-de-desconto/.md) [Códigos de desconto são aplicados diretamente a assinaturas no momento da criação, oferecendo descontos recorrentes ou pontuais.](https://docs.billing.kobana.com.br/pt/pt/cupons-e-descontos/codigos-de-desconto/.md) --- # Códigos de Desconto Códigos de desconto são aplicados diretamente a assinaturas no momento da criação, oferecendo descontos recorrentes ou pontuais. ## Campos[​](#campos "Link direto para Campos") | Campo | Descrição | | ---------------------- | ----------------------------------------------- | | **Código** | Código único, maiúsculas | | **Nome** | Nome do desconto | | **Descrição** | Detalhes do desconto | | **Tipo** | `percentage` ou `fixed_amount` | | **Valor fixo** | Para tipo `fixed_amount` | | **Percentual** | Para tipo `percentage` (máx 100%) | | **Duração** | `once`, `repeating` ou `forever` | | **Duração em meses** | Para `repeating`, quantos meses o desconto dura | | **Máximo de resgates** | Total global de usos permitidos | | **Vezes resgatado** | Contador de usos | | **Válido de / até** | Período de validade | | **Status** | `active`, `expired` ou `depleted` | ## Duração do Desconto[​](#duração-do-desconto "Link direto para Duração do Desconto") | Duração | Descrição | | ----------- | ------------------------------------------------------------ | | `once` | Aplicado apenas na primeira fatura | | `repeating` | Aplicado por N meses consecutivos | | `forever` | Aplicado indefinidamente enquanto a assinatura estiver ativa | ## Restrições[​](#restrições "Link direto para Restrições") | Restrição | Descrição | | ----------------------- | ------------------------------------------ | | **Valor mínimo** | Valor mínimo da assinatura para usar | | **Apenas primeiro uso** | Válido apenas para novos clientes | | **Ciclos válidos** | Quais ciclos de cobrança aceita o desconto | ## Aplicação[​](#aplicação "Link direto para Aplicação") | Filtro | Descrição | | ------------ | ------------------------------------------- | | **Produtos** | Lista de produtos onde o desconto se aplica | | **Planos** | Lista de planos onde o desconto se aplica | ## Status[​](#status "Link direto para Status") | Status | Descrição | | ---------- | --------------------------- | | `active` | Válido e utilizável | | `expired` | Fora do período de validade | | `depleted` | Limite de resgates atingido | --- # Cupons Cupons são códigos promocionais que os clientes podem resgatar para obter descontos em compras e faturas. ## Campos do Cupom[​](#campos-do-cupom "Link direto para Campos do Cupom") | Campo | Descrição | | ----------------------- | -------------------------------------------------------- | | **Código** | Código único, armazenado em maiúsculas | | **Nome** | Nome interno do cupom | | **Descrição** | Detalhes da promoção | | **Tipo de desconto** | `percentage` (percentual) ou `fixed_amount` (valor fixo) | | **Valor do desconto** | Percentual (0–100) ou valor em reais, conforme o tipo | | **Moeda** | Padr��o: BRL | | **Compra mínima** | Valor mínimo do pedido para usar o cupom | | **Desconto máximo** | Teto do desconto (para cupons percentuais) | | **Limite de uso total** | Máximo de resgates permitidos | | **Limite por cliente** | Máximo de resgates por conta de cobrança | | **Válido de / até** | Período de validade | | **Aplica-se a** | Planos e/ou produtos específicos (JSON) | | **Exclui** | Planos e/ou produtos excluídos (JSON) | | **Ativo** | Se o cupom está habilitado | ## Validação de Cupom[​](#validação-de-cupom "Link direto para Validação de Cupom") Ao validar um cupom, o sistema verifica: 1. O cupom existe e o código confere 2. O cupom está ativo (`isActive = true`) 3. Está dentro do período de validade 4. O limite de uso total não foi atingido 5. O limite de uso por cliente não foi atingido 6. A compra atinge o valor mínimo ### Cálculo do Desconto[​](#cálculo-do-desconto "Link direto para Cálculo do Desconto") ``` Se percentual: desconto = subtotal × percentual / 100 Se fixo: desconto = valor_do_desconto Aplica teto: desconto = min(desconto, maxDiscountCents) Não excede subtotal: desconto = min(desconto, subtotal) ``` ## Resgatando um Cupom[​](#resgatando-um-cupom "Link direto para Resgatando um Cupom") Ao aplicar um cupom: 1. Valida todas as condições 2. Cria um registro de `CouponRedemption` com o valor do desconto 3. Incrementa o contador de uso do cupom 4. Retorna o resgate com o valor descontado O processo é **atômico** (transação) para prevenir condições de corrida. ## Operações[​](#operações "Link direto para Operações") * **Ativar/Desativar**: Controla se o cupom pode ser validado * **Deletar**: Apenas se nunca utilizado (nenhum resgate registrado) * **Atualizar**: Código, nome, limites, datas e valores editáveis ## Relatório de Resgates[​](#relatório-de-resgates "Link direto para Relatório de Resgates") Para cada cupom, o sistema rastreia: * Quem resgatou (conta de cobrança) * Quando resgatou * Valor do desconto aplicado * Fatura associada (opcional) ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") A tela `/dashboard/coupons` lista todos os cupons da organização, com código, tipo de desconto, valor, validade, número de resgates e status. A interface permite criar cupons percentuais ou de valor fixo, com limite total e por cliente. ![Lista de cupons com tipo de desconto, validade e resgates](/pt/assets/images/cupons-9ccdb48172debe47fc16ac4e8cdd8683.png) --- # MCP da Documentação Esta documentação tem um **servidor MCP próprio**. Com ele, um assistente de IA (Claude, ChatGPT, Cursor, VS Code, Claude Code) busca e lê as páginas deste site sem que você precise copiar e colar nada. Assim, as respostas sobre o Faturamento Automático saem do conteúdo publicado, no idioma que você escolher. ``` https://docs.billing.kobana.com.br/mcp ``` > **Não é o MCP do produto:** O MCP da Documentação só **lê a documentação**. Ele não acessa sua conta, não vê clientes, assinaturas nem faturas e não altera nada. Para um agente operar o Faturamento Automático, use o **MCP do produto** (`mcp.billing.kobana.com.br`), que pede login e respeita as suas permissões. Veja [MCP › Clientes](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/clients.md). ## Como funciona[​](#como-funciona "Link direto para Como funciona") * **Público e só de leitura:** não pede login nem token. Expõe o mesmo conteúdo que qualquer pessoa vê no site. * **Sempre atualizado:** lê a versão publicada da documentação. Uma página nova ou alterada aparece no MCP assim que o site é publicado. * **Três idiomas:** português (`pt`), inglês (`en`) e espanhol (`es`). Sem idioma informado, usa o português. * **Transporte:** Streamable HTTP, sem sessão. Qualquer cliente MCP que conecte a um servidor remoto por URL funciona. ## Tools[​](#tools "Link direto para Tools") | Tool | O que faz | Parâmetros | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | `search_docs` | Busca páginas por palavras-chave, no título, no caminho e no resumo, sem diferenciar acento nem maiúsculas. Devolve as melhores páginas com caminho e resumo | `query` (obrigatório), `locale`, `limit` (1 a 25, padrão 8) | | `get_page` | Devolve o conteúdo completo de uma página em Markdown | `path`: o caminho que `search_docs` ou `list_pages` devolveu (por exemplo, `/pt/assinaturas`) ou a URL completa | | `list_pages` | Lista todas as páginas, com caminho e resumo | `locale` | O assistente decide sozinho quando chamar cada tool. Normalmente ele busca com `search_docs` e lê com `get_page` as páginas que interessam. ## Como instalar[​](#como-instalar "Link direto para Como instalar") O jeito mais rápido é pelo menu **Copiar página**, no topo de cada página deste site. Em **MCP da Documentação**, você encontra: * **Conectar ao Cursor** e **Conectar ao VS Code:** instalam o servidor com um clique. * **Copiar config do MCP:** copia o bloco JSON para clientes configurados por arquivo. * **Copiar comando do MCP:** copia o comando de instalação para o terminal. Se preferir configurar à mão, os passos de cada cliente estão abaixo. ### Qualquer cliente, pelo terminal[​](#qualquer-cliente-pelo-terminal "Link direto para Qualquer cliente, pelo terminal") O [`add-mcp`](https://www.npmjs.com/package/add-mcp) detecta os clientes instalados na máquina e adiciona o servidor a eles: ``` npx add-mcp "https://docs.billing.kobana.com.br/mcp" ``` ### Claude Code[​](#claude-code "Link direto para Claude Code") ``` claude mcp add --transport http kobana-billing-docs https://docs.billing.kobana.com.br/mcp ``` ### Cursor[​](#cursor "Link direto para Cursor") Use **Conectar ao Cursor** no menu da página, ou adicione ao `~/.cursor/mcp.json` (para todos os projetos) ou ao `.cursor/mcp.json` do projeto: ``` { "mcpServers": { "kobana-billing-docs": { "url": "https://docs.billing.kobana.com.br/mcp" } } } ``` ### VS Code[​](#vs-code "Link direto para VS Code") Use **Conectar ao VS Code** no menu da página, ou crie o `.vscode/mcp.json` no projeto. No VS Code a chave é `servers`, não `mcpServers`: ``` { "servers": { "kobana-billing-docs": { "type": "http", "url": "https://docs.billing.kobana.com.br/mcp" } } } ``` ### Claude e ChatGPT[​](#claude-e-chatgpt "Link direto para Claude e ChatGPT") Em **Configurações › Conectores**, adicione um conector personalizado e cole a URL `https://docs.billing.kobana.com.br/mcp`. Não há login a fazer. ### Outros clientes configurados por arquivo[​](#outros-clientes-configurados-por-arquivo "Link direto para Outros clientes configurados por arquivo") ``` { "mcpServers": { "kobana-billing-docs": { "type": "http", "url": "https://docs.billing.kobana.com.br/mcp" } } } ``` ## Exemplos de perguntas[​](#exemplos-de-perguntas "Link direto para Exemplos de perguntas") Com o servidor conectado, pergunte normalmente. O assistente consulta a documentação antes de responder: * "Como funciona o proration quando um cliente troca de plano no meio do ciclo?" * "Quais eventos de webhook existem para faturas e como valido a assinatura?" * "Como configuro a emissão de NF-e com certificado digital?" * "Monte um exemplo de chamada à API para criar uma assinatura, com base na documentação." ## Testar sem cliente[​](#testar-sem-cliente "Link direto para Testar sem 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":"pt"}}}' ``` ## Limites[​](#limites "Link direto para Limites") * As páginas de referência de cada endpoint da API (`/api/v1/...`) ficam fora do MCP. A fonte para ler a API por máquina é a especificação OpenAPI, em [API › OpenAPI](https://docs.billing.kobana.com.br/pt/pt/api/overview/openapi.md). * A busca é por palavras-chave, não semântica. Se não encontrar, tente outros termos ou peça ao assistente para usar `list_pages`. * Também dá para ler qualquer página como Markdown acrescentando `.md` à URL, ou baixar a documentação inteira em [`llms-full.txt`](https://docs.billing.kobana.com.br/pt/llms-full.txt). --- ## [📄️Exportações](https://docs.billing.kobana.com.br/pt/pt/exportacao-e-importacao/exportacoes/.md) [Exporte dados da plataforma em diferentes formatos para relatórios e integrações.](https://docs.billing.kobana.com.br/pt/pt/exportacao-e-importacao/exportacoes/.md) --- ## [📄️Exportações](https://docs.billing.kobana.com.br/pt/pt/exportacao-e-importacao/exportacoes/.md) [Exporte dados da plataforma em diferentes formatos para relatórios e integrações.](https://docs.billing.kobana.com.br/pt/pt/exportacao-e-importacao/exportacoes/.md) --- # Exportações Exporte dados da plataforma em diferentes formatos para relatórios e integrações. ## Recursos Exportáveis[​](#recursos-exportáveis "Link direto para Recursos Exportáveis") | Recurso | Descrição | | ---------------- | ------------------------------------ | | `products` | Catálogo de produtos com preços | | `customers` | Lista de clientes/contas de cobrança | | `invoices` | Faturas com line items | | `subscriptions` | Assinaturas ativas | | `plans` | Definições de planos | | `service_items` | Itens de serviço (fiscal) | | `coupons` | Códigos de cupom | | `product_groups` | Grupos de produtos | ## Formatos Suportados[​](#formatos-suportados "Link direto para Formatos Suportados") | Formato | Descrição | | ------- | -------------------------------------- | | `csv` | Valores separados por vírgula (padrão) | | `xlsx` | Planilha Excel | | `json` | JSON estruturado | ## Status da Exportação[​](#status-da-exportação "Link direto para Status da Exportação") | Status | Descrição | | ------------ | -------------------------- | | `pending` | Na fila para processamento | | `processing` | Sendo processado | | `completed` | Pronto para download | | `failed` | Erro durante processamento | ## Fluxo[​](#fluxo "Link direto para Fluxo") 1. Crie uma exportação informando o tipo de recurso e formato 2. O job é enfileirado para processamento assíncrono 3. O worker busca os dados, aplica filtros e gera o arquivo 4. O arquivo é armazenado no S3 com validade de **7 dias** 5. A exportação é atualizada com a URL de download ## Campos da Exportação[​](#campos-da-exportação "Link direto para Campos da Exportação") | Campo | Descrição | | ------------------- | ----------------------- | | **Tipo de recurso** | O que exportar | | **Formato** | CSV, XLSX ou JSON | | **Status** | Estado do processamento | | **Nome do arquivo** | Gerado automaticamente | | **URL do arquivo** | Link para download | | **Tamanho** | Tamanho em bytes | | **Total de linhas** | Registros exportados | | **Filtros** | Filtros aplicados | | **Expira em** | 7 dias após conclusão | ## Limpeza Automática[​](#limpeza-automática "Link direto para Limpeza Automática") Exportações expiradas são automaticamente removidas (arquivo no S3 + registro no banco). --- # Importações Importe dados em massa para a plataforma via upload de arquivos. ## Recursos Importáveis[​](#recursos-importáveis "Link direto para Recursos Importáveis") Os mesmos recursos suportados nas exportações: produtos, clientes, faturas, assinaturas, planos, itens de serviço, cupons e grupos de produtos. ## Status da Importação[​](#status-da-importação "Link direto para Status da Importação") | Status | Descrição | | ----------------------- | ------------------------------------------ | | `pending` | Na fila | | `processing` | Sendo processado | | `completed` | Sucesso, sem erros | | `completed_with_errors` | Sucesso parcial, alguns registros falharam | | `failed` | Erro crítico, processamento abortado | ## Fluxo[​](#fluxo "Link direto para Fluxo") 1. Faça upload do arquivo (CSV, XLSX ou JSON) 2. O arquivo é armazenado no S3 3. O job é enfileirado para processamento assíncrono 4. O worker lê o arquivo, valida cada linha e cria/atualiza os registros 5. Erros são rastreados por linha 6. A importação é atualizada com o resultado ## Acompanhamento de Progresso[​](#acompanhamento-de-progresso "Link direto para Acompanhamento de Progresso") | Campo | Descrição | | ---------------------- | -------------------------------- | | **Total de linhas** | Total no arquivo | | **Linhas processadas** | Progresso atual | | **Sucesso** | Registros importados com sucesso | | **Erros** | Registros com falha | | **Detalhes dos erros** | Linha e motivo de cada erro | ## Exemplo de Erros[​](#exemplo-de-erros "Link direto para Exemplo de Erros") ``` [ { "row": 5, "error": "Nome do produto inválido" }, { "row": 12, "error": "CNPJ duplicado" } ] ``` --- ## [📄️Créditos](https://docs.billing.kobana.com.br/pt/pt/faturas-e-pagamentos/creditos/.md) [O sistema de créditos permite adicionar saldo na conta do cliente que é automaticamente aplicado em faturas futuras.](https://docs.billing.kobana.com.br/pt/pt/faturas-e-pagamentos/creditos/.md) --- ## [📄️Créditos](https://docs.billing.kobana.com.br/pt/pt/faturas-e-pagamentos/creditos/.md) [O sistema de créditos permite adicionar saldo na conta do cliente que é automaticamente aplicado em faturas futuras.](https://docs.billing.kobana.com.br/pt/pt/faturas-e-pagamentos/creditos/.md) --- # Créditos O sistema de créditos permite adicionar saldo na conta do cliente que é automaticamente aplicado em faturas futuras. ## Tipos de Crédito[​](#tipos-de-crédito "Link direto para Tipos de Crédito") | Tipo | Descrição | | ------------- | ------------------------------------- | | `promotional` | Créditos promocionais (podem expirar) | | `adjustment` | Ajustes administrativos de saldo | | `refund` | Crédito gerado por reembolso | | `manual` | Adição manual de crédito | ## Campos do Crédito[​](#campos-do-crédito "Link direto para Campos do Crédito") | Campo | Descrição | | --------------------- | ------------------------------------------- | | **Conta de cobrança** | Cliente que recebe o crédito | | **Empresa** | Empresa emissora (para escopo de aplicação) | | **Tipo** | Tipo do crédito | | **Valor** | Valor total do crédito | | **Valor restante** | Saldo ainda não utilizado | | **Descrição** | Motivo ou descrição do crédito | | **Expira em** | Data de expiração (null = nunca expira) | ## Aplicação Automática de Créditos[​](#aplicação-automática-de-créditos "Link direto para Aplicação Automática de Créditos") Quando uma fatura é **finalizada**, o sistema aplica créditos automaticamente usando a estratégia **FIFO**: ### Ordem de Aplicação[​](#ordem-de-aplicação "Link direto para Ordem de Aplicação") 1. Créditos que expiram mais cedo (prioridade para evitar perda) 2. Créditos mais antigos (quando a data de expiração é igual) ### Regras de Escopo por Empresa[​](#regras-de-escopo-por-empresa "Link direto para Regras de Escopo por Empresa") * Se a fatura tem empresa: aplica créditos da mesma empresa **e** créditos sem empresa * Se a fatura não tem empresa: aplica apenas créditos sem empresa ### Processo (em transação atômica)[​](#processo-em-transação-atômica "Link direto para Processo (em transação atômica)") 1. Busca créditos não expirados com saldo disponível 2. Para cada crédito: aplica o mínimo entre (saldo do crédito, valor restante da fatura) 3. Cria registro de `CreditApplication` para rastreabilidade 4. Atualiza o saldo do crédito e da fatura 5. Se a fatura for totalmente paga: marca como `paid` 6. Atualiza o `balance` da conta de cobrança ## Restauração de Créditos[​](#restauração-de-créditos "Link direto para Restauração de Créditos") Quando uma fatura é **anulada** (void), todos os créditos aplicados são restaurados: * Cada crédito tem seu saldo restante aumentado * Os registros de `CreditApplication` são removidos * A fatura volta ao status `open` * O saldo da conta de cobrança é atualizado ## Expiração de Créditos[​](#expiração-de-créditos "Link direto para Expiração de Créditos") Créditos com data de expiração são automaticamente zerados quando a data passa: * O `amount_remaining` é definido como 0 * O saldo da conta de cobrança é reduzido ## Operações[​](#operações "Link direto para Operações") * **Adicionar crédito**: Cria crédito e incrementa o saldo da conta * **Ajustar saldo**: Adiciona ou subtrai créditos * **Crédito de reembolso**: Cria crédito do tipo `refund` * **Crédito promocional**: Cria crédito com expiração opcional * **Deletar crédito**: Apenas se nunca utilizado (saldo restante = valor total) * **Consultar saldo disponível**: Retorna total disponível, créditos ativos e créditos expirando ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") A tela `/dashboard/credits` lista todos os créditos da organização, com filtros por status, origem (downgrade, refund, ajuste manual, promoção), conta de cobrança e período. A interface também permite criar créditos avulsos e ver o saldo agregado por cliente. ![Lista de créditos com origem, saldo e aplicações](/pt/assets/images/creditos-36c8e95385baccb301ae30bb0461f2d5.png) --- # Faturas Faturas representam cobranças enviadas aos clientes. Cada fatura contém line items detalhando os produtos e valores cobrados. ## Estados da Fatura[​](#estados-da-fatura "Link direto para Estados da Fatura") ``` draft → open → paid ↓ ↓ void uncollectible ``` | Status | Descrição | | ----------------- | ---------------------------------------------------------------------- | | **draft** | Rascunho. Pode ser editada, ter itens adicionados/removidos | | **open** | Finalizada. Cobrável, pode receber pagamentos e ter créditos aplicados | | **paid** | Totalmente paga | | **void** | Anulada. Créditos aplicados são restaurados, parcelas canceladas | | **uncollectible** | Marcada como incobrável (write-off) | ## Campos da Fatura[​](#campos-da-fatura "Link direto para Campos da Fatura") ### Identificação[​](#identificação "Link direto para Identificação") | Campo | Descrição | | --------------------- | -------------------------------------------------- | | **Número** | Número sequencial único (formato: INV-YYYY-NNNNNN) | | **Conta de cobrança** | Cliente que receberá a fatura | | **Assinatura** | Assinatura associada (opcional) | | **Empresa** | Empresa emissora (para multi-empresa) | ### Valores (em reais)[​](#valores-em-reais "Link direto para Valores (em reais)") | Campo | Descrição | | ------------------ | ------------------------------------------------- | | **Subtotal** | Soma dos line items antes de descontos e impostos | | **Desconto** | Total de desconto aplicado | | **Impostos** | Total de impostos calculados | | **Total retido** | Impostos retidos (PIS/COFINS/IRPJ) | | **Valor líquido** | Valor líquido após retenções | | **Total** | Valor final (subtotal - desconto + impostos) | | **Valor devido** | Montante total a pagar | | **Valor pago** | Montante já recebido | | **Valor restante** | Saldo pendente | ### Configuração[​](#configuração "Link direto para Configuração") | Campo | Descrição | | ---------------------- | ------------------------------------------------------------------------------ | | **Método de cobrança** | `charge_automatically`, `manual_charge` ou `manual_invoice` | | **Razão de cobrança** | `subscription_cycle`, `subscription_create`, `subscription_update` ou `manual` | | **Política de NF-e** | `disabled`, `on_finalization`, `on_full_payment` ou `per_installment` | | **Data de vencimento** | Calculada a partir dos dias de prazo do cliente | ## Line Items[​](#line-items "Link direto para Line Items") Cada fatura contém itens de linha que detalham as cobranças: | Campo | Descrição | | ------------------ | ---------------------------------- | | **Tipo** | `subscription` ou `invoiceitem` | | **Descrição** | Texto descritivo | | **Quantidade** | Quantidade cobrada | | **Valor unitário** | Preço por unidade | | **Valor total** | Quantidade × valor unitário | | **Proration** | Se o item é um rateio proporcional | | **Período** | Início e fim do período cobrado | ## Operações[​](#operações "Link direto para Operações") ### Criar Fatura[​](#criar-fatura "Link direto para Criar Fatura") Ao criar uma fatura, informe: * Conta de cobrança (obrigatório) * Line items com descrição, quantidade e valor * Data de vencimento (ou usa os dias de prazo do cliente) * Parcelas (opcional, mínimo 2, soma deve ser igual ao total) * Política de NF-e (opcional) O número da fatura é gerado automaticamente usando lock advisory do PostgreSQL para prevenir duplicação. ### Editar Fatura[​](#editar-fatura "Link direto para Editar Fatura") Faturas `draft` e `open` aceitam a edição de todos os campos. Depois de liquidada — `paid`, `void` ou `uncollectible` — a fatura mantém as condições travadas: | Status | Campos editáveis | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **draft**, **open** | Todos | | **paid** | ID público, assinatura, descrição, itens, metadados, ID externo, política de emissão da NF-e e linha de descrição da NF-e | | **void**, **uncollectible** | ID público, assinatura, descrição, itens, metadados e ID externo | Empresa, método de cobrança, política de juros e multa, vencimento, competência e rodapé ficam travados. Os itens podem ser corrigidos (no formulário via API ou na edição inline da aba de itens, depois de um aviso), mas não enquanto a fatura tiver NF-e emitida ou em processamento — cancele a nota antes. A regra vale no dashboard, na API e no MCP: mudar um campo travado responde `422` com o código `INVOICE_FIELD_LOCKED`, listando os campos recusados. Reenviar um campo travado com o mesmo valor já gravado não é considerado mudança. ### Finalizar (`draft` → `open`)[​](#finalizar-draft--open "Link direto para finalizar-draft--open") Ao finalizar uma fatura: 1. Valida que existe pelo menos 1 line item 2. Valida que a soma das parcelas = total (se parcelada) 3. Calcula impostos automaticamente 4. **Aplica créditos automaticamente** (FIFO: expiração mais próxima primeiro, depois mais antigo) 5. Se o método for `charge_automatically`: tenta cobrar imediatamente ### Marcar como Paga[​](#marcar-como-paga "Link direto para Marcar como Paga") * Suporta pagamentos parciais * Ao receber o valor total, o status muda para `paid` * Cria um registro de transação ### Anular (Void)[​](#anular-void "Link direto para Anular (Void)") Ao anular uma fatura: * Créditos aplicados são restaurados automaticamente * Parcelas pendentes são canceladas * O motivo da anulação é armazenado ### Desfazer Pagamento[​](#desfazer-pagamento "Link direto para Desfazer Pagamento") Reverte uma fatura de `paid` para `open`: * Reseta o valor pago para zero * Cria uma transação de ajuste (valor negativo) * Armazena o motivo no metadata ### Marcar como Incobrável[​](#marcar-como-incobrável "Link direto para Marcar como Incobrável") Marca a fatura como write-off. Irreversível. Nenhuma tentativa automática de pagamento será feita. ## Geração Automática de Números[​](#geração-automática-de-números "Link direto para Geração Automática de Números") Os números de fatura são gerados sequencialmente por ano usando advisory locks do PostgreSQL. Formato: `INV-{ano}-{sequencial com 6 dígitos}`. Exemplo: `INV-2026-000147` ## Capturas de tela[​](#capturas-de-tela "Link direto para Capturas de tela") ### Lista de faturas[​](#lista-de-faturas "Link direto para Lista de faturas") A tela `/dashboard/invoices` lista todas as faturas com filtros por status, conta de cobrança, empresa emissora, período e meio de pagamento. Cada linha mostra número, cliente, valor, vencimento, status e ações rápidas (baixar PDF, copiar boleto/PIX, marcar como paga). ![Lista de faturas do dashboard com filtros e ações](/pt/assets/images/faturas-72267f7e26141d86fe8aede46bef6106.png) ### Detalhe da fatura[​](#detalhe-da-fatura "Link direto para Detalhe da fatura") A página `/dashboard/invoices/[id]` mostra a fatura completa: itens (com quantidade e valor unitário), totais, descontos, créditos aplicados, impostos retidos, histórico de pagamentos, NF-e vinculada e linha do tempo de eventos. ![Detalhe de uma fatura com itens, totais e histórico](/pt/assets/images/fatura-detalhe-64c6b78b9ab703e8ca2b1895d82cceed.png) --- # Métodos de Pagamento Cada conta de cobrança pode ter múltiplos métodos de pagamento armazenados. Um deles é marcado como **padrão** para cobranças automáticas. ## Tipos Suportados[​](#tipos-suportados "Link direto para Tipos Suportados") | Tipo | Descrição | Cobrança Automática | | ------------------ | ------------------------------- | ------------------- | | **card** | Cartão de crédito/débito | Sim | | **bank\_slip** | Boleto bancário | Não | | **pix** | PIX (transferência instantânea) | Não | | **bank\_transfer** | Transferência bancária | Não | > **Nota**: Apenas cartão de crédito suporta cobrança automática (`charge_automatically`). ## Cartão de Crédito[​](#cartão-de-crédito "Link direto para Cartão de Crédito") ### Dados Armazenados[​](#dados-armazenados "Link direto para Dados Armazenados") * Bandeira (Visa, Mastercard, Elo, Amex, Hipercard) * Primeiros 6 dígitos (BIN) * Últimos 4 dígitos * Nome do titular * Mês e ano de validade * Fingerprint (identificador único do cartão no gateway) ### Tokenização[​](#tokenização "Link direto para Tokenização") O cartão é tokenizado no lado do cliente via SDK do gateway e armazenado de forma segura: 1. Cliente envia dados do cartão pelo formulário do gateway 2. Gateway retorna um token de cartão temporário (enviado à API como `card_token`) 3. O servidor usa o token para criar o cliente e cartão no gateway (Pagar.me) 4. Apenas os tokens do gateway e dados mascarados são armazenados ### Monitoramento de Validade[​](#monitoramento-de-validade "Link direto para Monitoramento de Validade") O sistema verifica automaticamente cartões que vencem nos próximos 30 dias e pode enviar notificações proativas ao cliente. ## Boleto Bancário (`bank_slip`)[​](#boleto-bancário-bank_slip "Link direto para boleto-bancário-bank_slip") * Gerado para cada cobrança individual * Possui código de barras e URL para download do PDF * Prazo de vencimento configurável (padrão: 3 dias) * Confirmação via webhook do gateway quando pago ## PIX[​](#pix "Link direto para PIX") * QR Code gerado para cada cobrança * Formato EMV com imagem PNG/base64 * Expiração padrão: 30 minutos * Confirmação em tempo real via webhook ## Transferência Bancária (`bank_transfer`)[​](#transferência-bancária-bank_transfer "Link direto para transferência-bancária-bank_transfer") Dados armazenados: * Código do banco, nome do banco * Agência e conta * Tipo: corrente ou poupança * Nome e documento do titular A confirmação é manual — o operador precisa verificar o recebimento. ## Método Padrão[​](#método-padrão "Link direto para Método Padrão") * Cada conta de cobrança tem **um** método padrão * O primeiro método criado é automaticamente definido como padrão * Ao remover o método padrão, o próximo método ativo é promovido ## Remoção[​](#remoção "Link direto para Remoção") Ao remover um método de pagamento: * Valida que não há pagamentos pendentes/processando com este método * Para cartões: deleta o cartão do gateway * Se era o padrão: reatribui para outro método ativo * Status muda para `removed` --- # Pagamentos Pagamentos representam tentativas de cobrança associadas a faturas. Cada pagamento rastreia o status, método, gateway utilizado e resposta do provedor. ## Estados do Pagamento[​](#estados-do-pagamento "Link direto para Estados do Pagamento") ``` pending → processing → succeeded → refunded ↓ ↓ failed partially_refunded ↓ canceled ``` | Status | Descrição | | ----------------------- | --------------------------------------- | | **pending** | Aguardando processamento | | **processing** | Enviado ao gateway, aguardando resposta | | **succeeded** | Confirmado como pago | | **failed** | Recusado pelo gateway ou erro | | **canceled** | Cancelado manualmente | | **partial** | Pagamento parcial recebido | | **refunded** | Totalmente reembolsado | | **partially\_refunded** | Parcialmente reembolsado | ## Fluxo de Pagamento[​](#fluxo-de-pagamento "Link direto para Fluxo de Pagamento") ### 1. Cobrança Automática (`charge_automatically`)[​](#1-cobrança-automática-charge_automatically "Link direto para 1-cobrança-automática-charge_automatically") ``` Fatura finalizada → Aplica créditos automaticamente → Se créditos pagam tudo: fatura = paid → Se não: → Obtém método de pagamento padrão → Processa pagamento via gateway → Cartão: resposta imediata → Boleto/PIX: aguarda webhook do gateway → Sucesso: fatura = paid → Falha: agenda retry (dunning) ``` ### 2. Pagamento Manual[​](#2-pagamento-manual "Link direto para 2. Pagamento Manual") O operador ou cliente aciona o pagamento via dashboard ou portal. ## Processando um Pagamento[​](#processando-um-pagamento "Link direto para Processando um Pagamento") Ao processar, o sistema: 1. Valida que a fatura está `open` 2. Determina o método de pagamento (fornecido, salvo ou padrão) 3. Obtém o gateway da organização para o tipo de pagamento 4. Cria registro do pagamento com chave de idempotência 5. Envia cobrança ao gateway 6. Atualiza o pagamento com a resposta ### Idempotência[​](#idempotência "Link direto para Idempotência") Cada pagamento tem uma chave de idempotência única. Requisições duplicadas retornam o resultado existente sem processar novamente. ## Cenários Especiais[​](#cenários-especiais "Link direto para Cenários Especiais") ### Pagamento Parcial[​](#pagamento-parcial "Link direto para Pagamento Parcial") * O valor recebido é menor que o total * A fatura permanece `open` com o saldo atualizado * O cliente pode pagar o restante com outro pagamento ### Pagamento Excedente (Overpayment)[​](#pagamento-excedente-overpayment "Link direto para Pagamento Excedente (Overpayment)") Quando o valor pago excede o saldo da fatura: 1. O valor da fatura é aplicado normalmente 2. O **excedente vira crédito** automaticamente na conta do cliente 3. O crédito é do tipo `adjustment` com descrição "Crédito de pagamento excedente na fatura {número}" 4. O crédito será aplicado automaticamente em faturas futuras ### Fatura Já Paga[​](#fatura-já-paga "Link direto para Fatura Já Paga") Se a fatura já estava paga quando o pagamento é processado, o valor total vira crédito na conta do cliente. ## Operações[​](#operações "Link direto para Operações") ### Cancelar Pagamento[​](#cancelar-pagamento "Link direto para Cancelar Pagamento") Apenas pagamentos `pending` podem ser cancelados. Para boleto/PIX, o cancelamento é enviado ao gateway. ### Reembolsar[​](#reembolsar "Link direto para Reembolsar") Pagamentos `succeeded` ou `partially_refunded` podem ser reembolsados: * **Reembolso total**: Status muda para `refunded` * **Reembolso parcial**: Status muda para `partially_refunded` * A requisição é enviada ao gateway quando disponível ### Tentar Novamente[​](#tentar-novamente "Link direto para Tentar Novamente") Pagamentos `failed` podem ser retentados. Um novo pagamento é criado com o mesmo valor, fatura e método. ## Capturas de tela[​](#capturas-de-tela "Link direto para Capturas de tela") ### Lista de pagamentos[​](#lista-de-pagamentos "Link direto para Lista de pagamentos") A tela `/dashboard/payments` agrega todos os pagamentos recebidos, com filtros por status, método, gateway, cliente e período. Cada linha mostra fatura relacionada, valor, taxa do gateway, valor líquido e mensagem de retorno. ![Lista de pagamentos com filtros por gateway e método](/pt/assets/images/pagamentos-921f6ac637fb88a56b6173546d0e9134.png) ### Detalhe do pagamento[​](#detalhe-do-pagamento "Link direto para Detalhe do pagamento") A página `/dashboard/payments/[id]` traz o registro completo: gateway, transação no provedor, fatura quitada, método (com últimos 4 dígitos do cartão ou banco do boleto), histórico de tentativas, estornos e webhooks recebidos. ![Detalhe de um pagamento com gateway, método e histórico](/pt/assets/images/pagamento-detalhe-b5c9448d3ba8255ea10e9b63c5d4e8e4.png) --- # Parcelamento Faturas podem ser divididas em múltiplas parcelas com datas de vencimento individuais. ## Estados da Parcela[​](#estados-da-parcela "Link direto para Estados da Parcela") ``` scheduled → pending → paid ↓ overdue ↓ canceled ``` | Status | Descrição | | ------------- | ------------------------------------------- | | **scheduled** | Vencimento futuro, aguardando processamento | | **pending** | Vencimento chegou, aguardando pagamento | | **paid** | Parcela paga | | **overdue** | Vencida e não paga | | **canceled** | Cancelada (fatura anulada) | ## Criando Parcelas[​](#criando-parcelas "Link direto para Criando Parcelas") Ao criar ou editar uma fatura, informe as parcelas: | Campo | Descrição | | ---------------------- | -------------------------- | | **Valor** | Montante da parcela | | **Data de vencimento** | Data de pagamento esperada | ### Regras de Validação[​](#regras-de-validação "Link direto para Regras de Validação") * Mínimo de **2 parcelas** * As datas devem ser **estritamente crescentes** * A soma dos valores deve ser **igual ao total da fatura** * A data de vencimento da fatura é definida como a data da última parcela ## Cobrança de Parcelas[​](#cobrança-de-parcelas "Link direto para Cobrança de Parcelas") ### Processamento Sequencial[​](#processamento-sequencial "Link direto para Processamento Sequencial") Parcelas são processadas sequencialmente — cada parcela só é cobrada quando a anterior está paga: 1. O worker busca parcelas com vencimento ≤ hoje 2. Verifica se a parcela anterior está paga (ou se é a primeira) 3. Para `charge_automatically`: cobra o método de pagamento padrão 4. Vincula o pagamento à parcela 5. Se for a última parcela: fatura marcada como `paid` ### Política de NF-e por Parcela[​](#política-de-nf-e-por-parcela "Link direto para Política de NF-e por Parcela") Quando a política de NF-e é `per_installment`, uma nota fiscal é emitida para cada parcela paga individualmente. ## Cancelamento[​](#cancelamento "Link direto para Cancelamento") Quando a fatura é anulada: * Todas as parcelas com status `scheduled` ou `pending` são canceladas * Parcelas já pagas não são afetadas --- ## [📄️Callbacks (Webhooks dos Provedores)](https://docs.billing.kobana.com.br/pt/pt/gateways-de-pagamento/callbacks/.md) [Os provedores de gateway enviam notificações ao sistema quando o status de pagamentos muda. Essas notificações são processadas de forma assíncrona.](https://docs.billing.kobana.com.br/pt/pt/gateways-de-pagamento/callbacks/.md) --- ## [📄️Callbacks (Webhooks dos Provedores)](https://docs.billing.kobana.com.br/pt/pt/gateways-de-pagamento/callbacks/.md) [Os provedores de gateway enviam notificações ao sistema quando o status de pagamentos muda. Essas notificações são processadas de forma assíncrona.](https://docs.billing.kobana.com.br/pt/pt/gateways-de-pagamento/callbacks/.md) --- # Callbacks (Webhooks dos Provedores) Os provedores de gateway enviam notificações ao sistema quando o status de pagamentos muda. Essas notificações são processadas de forma assíncrona. ## Endpoints de Callback[​](#endpoints-de-callback "Link direto para Endpoints de Callback") ### Kobana[​](#kobana "Link direto para Kobana") ``` POST /api/callbacks/kobana ``` **Header de Assinatura:** `X-Kobana-Signature: sha256=` **Eventos recebidos:** * `pix.register.confirmed` / `error` / `failed` / `requested` * `pix.paid` * `bank_billet.register.confirmed` / `error` / `failed` / `requested` * `bank_billet.paid` ### Pagar.me[​](#pagarme "Link direto para Pagar.me") ``` POST /api/callbacks/pagarme ``` **Header de Assinatura:** `x-hub-signature: sha256=` **Eventos recebidos:** * `order.*` (paid, payment\_failed, created, canceled, closed, updated) * `charge.*` (paid, payment\_failed, refunded, pending, processing, etc.) * `card.*` (created, updated, deleted, expired) ## Fluxo de Processamento[​](#fluxo-de-processamento "Link direto para Fluxo de Processamento") ``` Recebe POST do provedor → Valida assinatura HMAC-SHA256 → Verifica chave de idempotência (ignora duplicados) → Cria registro de Callback (status=pending) → Enfileira job para processamento assíncrono → Retorna 200 imediatamente ``` ### Processamento Assíncrono[​](#processamento-assíncrono "Link direto para Processamento Assíncrono") ``` Worker processa a fila → Roteia para o handler do provedor → Mapeia status do provedor para status interno → Atualiza registro de pagamento → Cria evento para notificação → Atualiza Callback (status=completed) ``` ## Segurança[​](#segurança "Link direto para Segurança") * **Validação de assinatura**: HMAC-SHA256 com comparação timing-safe * **Idempotência**: Chave única `[provider, idempotencyKey]` previne duplicação * **Retries**: Máximo de 5 tentativas com backoff exponencial * **Retenção**: Callbacks falhos mantidos por 7 dias ## Registro de Callback[​](#registro-de-callback "Link direto para Registro de Callback") Cada callback recebido é registrado com: * Provedor de origem * Chave de idempotência * Headers e payload completos * Status de processamento * Número de tentativas * Resultado ou mensagem de erro --- # Configuração de Gateways Cada organização pode configurar múltiplos gateways e definir padrões por método de pagamento. ## Campos do Gateway[​](#campos-do-gateway "Link direto para Campos do Gateway") | Campo | Descrição | | ---------------------- | ------------------------------------------------------ | | **Provedor** | MOCK, KOBANA ou PAGARME | | **Nome** | Nome de exibição | | **Ambiente** | SANDBOX ou PRODUCTION | | **Ativo** | Se o gateway está habilitado | | **Credenciais** | Configurações específicas do provedor (criptografadas) | | **Padrão para cartão** | Se é o gateway padrão para pagamentos com cartão | | **Padrão para boleto** | Se é o gateway padrão para boletos | | **Padrão para PIX** | Se é o gateway padrão para PIX | ## Gateway Padrão[​](#gateway-padrão "Link direto para Gateway Padrão") Cada organização define **um gateway padrão por método de pagamento**: * Um gateway padrão para cartão * Um gateway padrão para boleto * Um gateway padrão para PIX Ao definir um gateway como padrão, o anterior é automaticamente desmarcado. O sistema usa transações para garantir consistência. ## Operações[​](#operações "Link direto para Operações") ### Criar Gateway[​](#criar-gateway "Link direto para Criar Gateway") 1. Selecione o provedor 2. Informe as credenciais 3. Escolha o ambiente (sandbox/produção) 4. Defina se será padrão para algum método **Kobana**: Requer autorização OAuth antes de ativar **Pagar.me**: Requer teste de conexão antes de ativar **Mock**: Ativado automaticamente ### Atualizar Gateway[​](#atualizar-gateway "Link direto para Atualizar Gateway") Atualize nome, credenciais, status ou configuração de padrão. Valores mascarados são filtrados para evitar sobrescrita acidental. ### Deletar Gateway[​](#deletar-gateway "Link direto para Deletar Gateway") Apenas se não houver pagamentos associados. ## Monitoramento[​](#monitoramento "Link direto para Monitoramento") Para cada gateway, o sistema rastreia: * Total de gateways (ativos/inativos) * Contagem por provedor * Pagamentos processados por gateway * Falhas consecutivas de entrega --- # Provedores de Gateway O sistema suporta três provedores de pagamento, cada um com capacidades específicas. ## Provedores Disponíveis[​](#provedores-disponíveis "Link direto para Provedores Disponíveis") ### Pagar.me (`PAGARME`)[​](#pagarme-pagarme "Link direto para pagarme-pagarme") * **Propósito**: Processamento de cartões de crédito * **Métodos suportados**: Cartão de crédito apenas * **API**: Pagar.me v5 () * **Ambiente**: Sandbox e Produção **Credenciais necessárias:** | Campo | Obrigatório | Descrição | | ------------ | ----------- | ------------------------------ | | `secretKey` | Sim | Chave secreta da API | | `publicKey` | Não | Chave pública para tokenização | | `merchantId` | Não | ID do merchant | | `accountId` | Não | ID da conta | **Funcionalidades:** * Tokenização de cartões (cliente → token → gateway) * Autorização e captura * Reembolsos totais e parciais * Gerenciamento de clientes e cartões no gateway ### Kobana (`KOBANA`)[​](#kobana-kobana "Link direto para kobana-kobana") * **Propósito**: Métodos de pagamento brasileiros * **Métodos suportados**: Boleto bancário e PIX * **Ambiente**: Sandbox e Produção **Credenciais necessárias:** | Campo | Obrigatório | Descrição | | ----------------- | ----------- | --------------------------------------- | | `accessToken` | Sim | Token de acesso à API | | `billetAccountId` | Não | ID da conta de boletos | | `pixAccountUid` | Não | UID da conta PIX (obrigatório para PIX) | | `webhookSecret` | Não | Segredo para validação de webhooks | **Funcionalidades:** * Emissão de boletos com código de barras e PDF * Geração de QR Code PIX (EMV) * Cancelamento de cobranças * Webhooks para confirmação de pagamento ### Mock (`MOCK`)[​](#mock-mock "Link direto para mock-mock") * **Propósito**: Desenvolvimento e testes * **Métodos suportados**: Cartão, Boleto e PIX * **Credenciais**: Nenhuma necessária * **Ativação**: Automática ao criar Simula todos os tipos de pagamento para ambiente de desenvolvimento. ## Métodos de Pagamento por Provedor[​](#métodos-de-pagamento-por-provedor "Link direto para Métodos de Pagamento por Provedor") | Método | Pagar.me | Kobana | Mock | | ----------------- | -------- | ------ | ---- | | Cartão de crédito | Sim | - | Sim | | Boleto bancário | - | Sim | Sim | | PIX | - | Sim | Sim | | Transferência | - | - | - | ## Segurança de Credenciais[​](#segurança-de-credenciais "Link direto para Segurança de Credenciais") * Todas as credenciais são **criptografadas** em repouso usando AES-256-GCM * Credenciais são descriptografadas apenas no momento da chamada à API * Respostas da API mascaram credenciais (formato: `****[últimos 4]`) * Campos sensíveis são filtrados dos logs --- ## [📄️Configuração de Dunning](https://docs.billing.kobana.com.br/pt/pt/gestao-de-inadimplencia/configuracao-de-dunning/.md) [A configuração de dunning define como o sistema trata pagamentos em atraso: quantas tentativas, intervalo entre elas e comportamento após esgotamento.](https://docs.billing.kobana.com.br/pt/pt/gestao-de-inadimplencia/configuracao-de-dunning/.md) --- ## [📄️Configuração de Dunning](https://docs.billing.kobana.com.br/pt/pt/gestao-de-inadimplencia/configuracao-de-dunning/.md) [A configuração de dunning define como o sistema trata pagamentos em atraso: quantas tentativas, intervalo entre elas e comportamento após esgotamento.](https://docs.billing.kobana.com.br/pt/pt/gestao-de-inadimplencia/configuracao-de-dunning/.md) --- # Configuração de Dunning A configuração de dunning define como o sistema trata pagamentos em atraso: quantas tentativas, intervalo entre elas e comportamento após esgotamento. ## Campos de Configuração[​](#campos-de-configuração "Link direto para Campos de Configuração") | Campo | Padrão | Faixa | Descrição | | ------------------------------------- | --------------------- | ----- | ----------------------------------------------- | | **Máximo de tentativas** | 3 | 1-10 | Total de tentativas permitidas | | **Intervalo entre tentativas (dias)** | \[2, 5, 7] | - | Dias de espera entre cada tentativa | | **Período de carência (dias)** | 3 | 1-90 | Dias antes da suspensão | | **Retry automático** | Sim | - | Se as tentativas são disparadas automaticamente | | **Suspender após tentativas** | Sim | - | Se a conta é suspensa após esgotar tentativas | | **Métodos de pagamento para retry** | pix, bank\_slip, card | - | Quais métodos usar nas tentativas | ## Hierarquia de Configuração[​](#hierarquia-de-configuração "Link direto para Hierarquia de Configuração") 1. **Configuração da organização**: Cada organização pode personalizar suas regras 2. **Configuração global padrão**: Usada quando a organização não tem config personalizada 3. **Padrões do sistema**: Valores hardcoded como fallback final ## Exemplo de Timeline[​](#exemplo-de-timeline "Link direto para Exemplo de Timeline") Com a configuração padrão (tentativas: \[2, 5, 7], carência: 3 dias): ``` Dia 0: Fatura vence Dia 2: 1ª tentativa de retry Dia 5: 2ª tentativa de retry (se 1ª falhou) Dia 7: 3ª tentativa de retry (se 2ª falhou) Dia 10: Período de carência encerra → conta suspensa ``` ## Estágios de Dunning[​](#estágios-de-dunning "Link direto para Estágios de Dunning") A conta inadimplente progride pelos seguintes estágios: | Estágio | Dias em atraso | Descrição | | ----------- | -------------- | --------------------------- | | `initial` | 1-7 dias | Atraso recente | | `reminder` | 8-15 dias | Lembretes enviados | | `warning` | 16-30 dias | Aviso de suspensão iminente | | `final` | 30+ dias | Última chance antes de ação | | `suspended` | Após carência | Conta suspensa | ## Gerenciamento[​](#gerenciamento "Link direto para Gerenciamento") ### Pausar Dunning[​](#pausar-dunning "Link direto para Pausar Dunning") Use "Parar Dunning" para suspender as comunicações temporariamente mantendo a fatura como past-due. ### Cancelar Tentativas[​](#cancelar-tentativas "Link direto para Cancelar Tentativas") Cancela todas as tentativas pendentes para uma fatura específica e limpa a data da próxima tentativa. ### Retry Manual[​](#retry-manual "Link direto para Retry Manual") O operador pode disparar uma tentativa manual a qualquer momento, independente do agendamento automático. --- # Juros e Multa Uma fatura vencida pode acumular **multa** (cobrada uma única vez) e **juros de mora** (que correm por dia de atraso). A política de juros e multa define esses valores, e vale para toda a organização — com a possibilidade de trocar por cliente, por assinatura ou por fatura. Por padrão, toda organização começa com uma política que **não cobra nada**. Ligar a cobrança é uma decisão comercial explícita, porque muda o que seus clientes devem. ## Onde configurar[​](#onde-configurar "Link direto para Onde configurar") `Configurações` → aba **Juros e multa**. A tela mostra a lista de políticas e um simulador ao vivo: ao editar os valores, você vê o efeito sobre uma fatura de R$ 1.000,00 vencida há 15 dias antes de aplicar a regra a clientes reais. ## Campos[​](#campos "Link direto para Campos") ### Multa[​](#multa "Link direto para Multa") | Campo | Descrição | | -------------------------- | --------------------------------------------------------------------------- | | **Tipo de multa** | `Sem cobrança`, `Percentual do saldo` ou `Valor fixo` | | **Percentual / Valor** | Só aparece o campo que o tipo escolhido usa | | **Dias após o vencimento** | Quando a multa passa a incidir. O padrão é 1 — o dia seguinte ao vencimento | A multa incide **uma única vez**, não por dia. ### Juros de mora[​](#juros-de-mora "Link direto para Juros de mora") | Campo | Descrição | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | **Tipo de juros** | `Sem cobrança`, percentual por dia, por mês ou por ano, ou valor fixo por dia | | **Percentual / Valor por dia** | Só aparece o campo que o tipo escolhido usa | | **Dias após o vencimento** | Quando os juros passam a correr. O padrão é 1 | | **Contagem de dias** | Dias corridos ou dias úteis. Os dias úteis vêm do cadastro de [Feriados](https://docs.billing.kobana.com.br/pt/pt/configuracoes/feriados.md) | O percentual mensal é dividido *pro rata die* por 30, e o anual por 360 — a prática que o registro bancário usa. Uma taxa de 1% ao mês sobre R$ 1.000,00 rende R$ 0,33 por dia de atraso. Os juros incidem **sobre o saldo devedor**, nunca sobre o saldo mais a multa. ### Limites[​](#limites "Link direto para Limites") | Campo | Descrição | | ------------------------------- | ----------------------------------------------------------------------------------- | | **Máximo de meses de juros** | Interrompe o acúmulo. Vazio = sem limite | | **Teto do encargo total** | Percentual do saldo. Ao bater no teto, a multa é preservada e os juros são aparados | | **Respeitar os limites legais** | Recusa multa acima de 2% e juros acima de 1% ao mês | O limite legal vem do art. 52 do Código de Defesa do Consumidor e vale para **relação de consumo**. Contratos entre empresas podem pactuar acima, e para isso a trava pode ser desligada — a decisão fica registrada na auditoria, separada da alteração comum da política. ### Comportamento[​](#comportamento "Link direto para Comportamento") | Campo | Descrição | | ------------------------------------ | ------------------------------------------------------------------------------- | | **Pagamento parcial abate primeiro** | `Juros e multa` (padrão) ou `O valor da fatura` | | **Registrar a instrução no banco** | O boleto ou Pix recolhe os encargos por conta própria após o vencimento | | **Recalcular em cartão e 2ª via** | No cartão não existe instrução bancária, então o encargo entra no valor cobrado | | **Instruções impressas no boleto** | Texto livre | O padrão `Juros e multa` segue o art. 354 do Código Civil: um pagamento parcial imputa primeiro nos juros, depois na multa, e só o que sobra abate o valor da fatura. Assim a dívida não para de render silenciosamente. ## Hierarquia: qual política vale para uma fatura[​](#hierarquia-qual-política-vale-para-uma-fatura "Link direto para Hierarquia: qual política vale para uma fatura") A resolução é em cascata, e o primeiro nível que indica uma política ganha: ``` Fatura → Assinatura → Conta de cobrança → Política padrão da organização ``` Um nível em branco significa **herdar**, nunca "sem cobrança". Não cobrar nada é uma política explícita, com os dois tipos em `Sem cobrança`. ### Faturas já emitidas não mudam[​](#faturas-já-emitidas-não-mudam "Link direto para Faturas já emitidas não mudam") Ao ser finalizada, a fatura **congela** a política vigente naquele momento. Se você renegociar a política em março, as faturas emitidas em janeiro continuam cobrando as regras de janeiro. Isso vale tanto para o cálculo quanto para a instrução registrada no banco. ## Como o encargo é cobrado[​](#como-o-encargo-é-cobrado "Link direto para Como o encargo é cobrado") | Meio | Como funciona | | ---------- | ----------------------------------------------------------------------------------------------------------------- | | **Boleto** | A instrução de multa e juros é registrada no banco. O próprio banco calcula e recolhe o valor extra na liquidação | | **Pix** | Registrado como Pix Cobrança, com a mesma lógica. Um Pix instantâneo não aceita encargo | | **Cartão** | Não existe instrução bancária: o valor cobrado é recalculado no momento da tentativa | Ao reemitir uma 2ª via de boleto vencido, o **vencimento original é preservado**. Redatar o boleto para hoje zeraria o atraso e perdoaria o encargo que o cliente já deve. :::caution Dias úteis dependem do cadastro de feriados Com a contagem em dias úteis e a lista de feriados vazia, o cálculo desconta apenas os fins de semana — o banco desconta os feriados também e vai recolher menos do que apuramos. Importe os feriados nacionais em `Sistema` → [Feriados](https://docs.billing.kobana.com.br/pt/pt/configuracoes/feriados.md) antes de ligar essa opção. ::: :::note Bancos e percentual mensal O tipo "percentual por mês" no boleto é suportado por Bradesco, BB, BTG, Caixa, Inter, Itaú, Safra, Santander, Sicoob e Sicredi. Em outros bancos, prefira o percentual diário. ::: ## O que acontece quando o cliente paga[​](#o-que-acontece-quando-o-cliente-paga "Link direto para O que acontece quando o cliente paga") O valor liquidado é decomposto em três partes: 1. **Principal** — abate o saldo da fatura 2. **Multa e juros** — registrados à parte, como receita financeira 3. **Excedente inexplicado** — o que a política não justifica vira crédito na conta do cliente, como antes Essa separação importa em três lugares: * **Nota fiscal**: o valor da NF-e é o valor do serviço, sem os encargos. Multa e juros são receita financeira e estão fora da base de cálculo do ISS e das retenções. * **Relatórios de receita**: a receita por cliente conta só o principal. Contar os encargos infla o LTV com dinheiro que não veio da venda. * **Extrato do cliente**: os encargos aparecem em linha própria, "Juros e multa — fatura X". Quando o valor recebido passa do que a política explica, o sistema registra o evento `invoice.late_charges_unexplained`. Isso normalmente significa que nosso cálculo e o do banco divergiram além do arredondamento, e vale conferir. ## Onde acompanhar[​](#onde-acompanhar "Link direto para Onde acompanhar") * **Detalhe da fatura**: card "Encargos por atraso", com dias de atraso, multa, juros, total atualizado e o que já foi recebido. Aparece só em fatura vencida ou que já recebeu encargo. * **Inadimplência**: o total vencido segue sendo apenas o principal — é a métrica comparável entre períodos. Os encargos acumulados aparecem em coluna separada. ## Pela API[​](#pela-api "Link direto para Pela API") O recurso é `/v1/late_fee_policies`. Os percentuais são float (`2.0` para 2%) e os valores em reais. ``` curl -X POST https://api.kobana.com.br/billing/v1/late_fee_policies \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Padrão", "is_default": true, "fine_mode": "percentage", "fine_percent": 2.0, "interest_mode": "monthly_percentage", "interest_percent": 1.0 }' ``` Para conferir o cálculo antes de uma fatura vencer de verdade: ``` 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": "..." }' ``` A resposta traz `days_past_due`, `fine`, `interest`, `total` e `total_due`. ## Perguntas frequentes[​](#perguntas-frequentes "Link direto para Perguntas frequentes") **Os encargos entram no valor da nota fiscal?** Não. A NF-e usa o valor do serviço. Multa e juros são receita financeira, fora da base do ISS e das retenções. Se a sua operação precisar de nota complementar sobre os encargos, ela é emitida manualmente. **O que acontece com faturas antigas ao ligar a cobrança?** Faturas ainda em `draft` passam a herdar a política nova ao serem finalizadas. Faturas já finalizadas mantêm o que carregam — inclusive as que ainda não tinham política nenhuma. **E se o cliente pagar mais do que multa e juros justificam?** A diferença vira crédito na conta dele, e o evento `invoice.late_charges_unexplained` é emitido para você conferir. **Posso cobrar juros sem multa, ou multa sem juros?** Sim. Os dois tipos são independentes; basta deixar um em `Sem cobrança`. --- # Recuperação de Receita O sistema rastreia toda receita recuperada via dunning para análise de eficiência. ## Registro de Recuperação[​](#registro-de-recuperação "Link direto para Registro de Recuperação") Cada pagamento bem-sucedido via retry cria um `RecoveryRecord`: | Campo | Descrição | | ------------------------------- | ------------------------------------------------ | | **Conta de cobrança** | Conta que pagou | | **Fatura** | Fatura recuperada | | **Pagamento** | Pagamento que efetivou | | **Valor** | Montante recuperado | | **Dias em atraso** | Quantos dias de atraso no momento da recuperação | | **Tentativas** | Quantas tentativas até o sucesso | | **Método de recuperação** | Ex: `auto_retry_pix`, `manual_retry_card` | | **Data original de vencimento** | Quando a fatura deveria ter sido paga | | **Recuperado em** | Data do pagamento | ## Métricas Disponíveis[​](#métricas-disponíveis "Link direto para Métricas Disponíveis") ### Visão Geral[​](#visão-geral "Link direto para Visão Geral") | Métrica | Descrição | | ------------------------------ | --------------------------------------- | | **Total recuperado** | Soma de todos os pagamentos recuperados | | **Total perdido** | Faturas marcadas como incobráveis | | **Taxa de recuperação** | Percentual do potencial recuperado | | **Dias médios para recuperar** | Média de dias em atraso até pagamento | | **Tentativas médias** | Média de tentativas até o sucesso | ### Por Método de Pagamento[​](#por-método-de-pagamento "Link direto para Por Método de Pagamento") Distribuição de recuperações por método: * PIX * Cartão de crédito * Boleto bancário * Transferência bancária ### Por Faixa de Atraso (Aging Buckets)[​](#por-faixa-de-atraso-aging-buckets "Link direto para Por Faixa de Atraso (Aging Buckets)") | Faixa | Taxa estimada de recuperação | | ---------- | ---------------------------- | | 1-7 dias | 85% | | 8-15 dias | 70% | | 16-30 dias | 50% | | 30+ dias | 25% | ### Tendências[​](#tendências "Link direto para Tendências") Acompanhe a evolução mensal: * Valores recuperados e perdidos por mês * Taxa de recuperação mensal * Quantidade de faturas processadas ### Potencial de Recuperação[​](#potencial-de-recuperação "Link direto para Potencial de Recuperação") Estimativa do quanto pode ser recuperado das faturas atualmente em atraso, baseada nas taxas históricas por faixa de atraso. --- # Suspensão de Contas Contas inadimplentes são automaticamente suspensas quando o período de carência é excedido. ## Worker de Suspensão[​](#worker-de-suspensão "Link direto para Worker de Suspensão") Executa **diariamente às 02:00 UTC** e: 1. Sincroniza o status das contas inadimplentes 2. Obtém o `gracePeriodDays` da configuração de dunning (padrão: 3 dias) 3. Busca contas inadimplentes com: * Estágio `warning` ou `final` * Data do atraso mais antigo > período de carência * Ainda não suspensas * Não recuperadas 4. Para cada conta: * Altera status da conta de cobrança para `suspended` * Atualiza o estágio de inadimplência para `suspended` * **Pausa todas as assinaturas ativas** * Envia notificação de suspensão ## Efeitos da Suspensão[​](#efeitos-da-suspensão "Link direto para Efeitos da Suspensão") * Status da conta de cobrança: `suspended` * Todas as assinaturas ativas são pausadas automaticamente * O motivo da suspensão é registrado (ex: "Inadimplência por X+ dias") * Notificação enviada ao titular da conta ## Notificação de Suspensão[​](#notificação-de-suspensão "Link direto para Notificação de Suspensão") Tipo: `account_suspended` Variáveis disponíveis: * Nome da organização * Total em atraso * Data da suspensão ## Reativação[​](#reativação "Link direto para Reativação") A reativação é feita manualmente após o pagamento ser regularizado: 1. Operador acessa a conta de cobrança 2. Clica em "Reativar" 3. Status volta para `active` 4. Campos de suspensão são limpos 5. Assinaturas pausadas podem ser retomadas individualmente --- # Tentativas de Pagamento (Payment Retry) O sistema de retry processa automaticamente tentativas de cobrança para faturas em atraso. ## Estados da Tentativa[​](#estados-da-tentativa "Link direto para Estados da Tentativa") | Status | Descrição | | ------------ | ----------------------------------------------- | | `pending` | Aguardando processamento | | `processing` | Sendo processada (reivindicada pelo worker) | | `succeeded` | Pagamento bem-sucedido | | `failed` | Pagamento recusado, mais tentativas disponíveis | | `exhausted` | Máximo de tentativas atingido | ## Campos da Tentativa[​](#campos-da-tentativa "Link direto para Campos da Tentativa") | Campo | Descrição | | ----------------------- | ------------------------------------- | | **Fatura** | Fatura associada | | **Pagamento** | Registro de pagamento criado | | **Número da tentativa** | Sequencial (1, 2, 3...) | | **Método de pagamento** | Método utilizado na tentativa | | **Valor** | Valor a ser cobrado | | **Código de falha** | Motivo da recusa | | **Mensagem de falha** | Descrição detalhada do erro | | **Agendado para** | Data/hora da tentativa | | **Processado em** | Data/hora do processamento | | **Próximo retry em** | Quando a próxima tentativa será feita | ## Worker de Retry[​](#worker-de-retry "Link direto para Worker de Retry") O worker executa **a cada 6 horas** e: 1. Busca tentativas com `status=pending` e `scheduledFor ≤ agora` 2. Reivindica atomicamente cada tentativa (`pending → processing`) para evitar duplicação 3. Para cada tentativa: * Verifica se a fatura já foi paga (pula) * Cria registro de pagamento * Processa o pagamento via gateway 4. Em caso de **sucesso**: * Marca a fatura como paga * Cria registro de recuperação * Remove a conta da lista de inadimplentes 5. Em caso de **falha**: * Se há tentativas restantes: agenda a próxima * Se esgotou tentativas: marca como `exhausted` e suspende a conta (se configurado) ## Prevenção de Condições de Corrida[​](#prevenção-de-condições-de-corrida "Link direto para Prevenção de Condições de Corrida") O sistema usa `updateMany` atômico com verificação de status para garantir que apenas um worker processe cada tentativa: ``` WHERE id = X AND status = 'pending' SET status = 'processing' ``` Se `count = 0`, outro worker já reivindicou a tentativa. ## Retry para Parcelas[​](#retry-para-parcelas "Link direto para Retry para Parcelas") Tentativas também podem ser direcionadas a parcelas específicas: * O `metadata.installmentId` identifica a parcela * O valor da tentativa é o da parcela, não o da fatura inteira --- # Primeiros Passos A página **Getting Started** (`/dashboard/getting-started`) é o ponto de partida para novas organizações. Ela apresenta uma sequência guiada das tarefas necessárias para começar a cobrar de forma recorrente: cadastrar a empresa, configurar gateways e NF-e, criar planos e produtos, importar clientes e ativar a primeira assinatura. Cada cartão da página representa um marco do onboarding e mostra o estado da organização em tempo real (concluído, pendente ou bloqueado). O dashboard usa essas mesmas verificações para decidir quando esconder as instruções iniciais e exibir as métricas operacionais. ## Etapas sugeridas[​](#etapas-sugeridas "Link direto para Etapas sugeridas") 1. **Configurar empresa e dados fiscais** — informar CNPJ, regime tributário e endereços em `Contas > Empresas`. 2. **Conectar um gateway de pagamento** — escolher provedor (Kobana, Asaas, Iugu, Pagar.me) em `Gateways de Pagamento` e definir o gateway padrão por método (cartão, boleto, PIX). 3. **Cadastrar planos e produtos** — definir o catálogo em `Planos e Produtos`, com ciclos, valores em reais e regras de proration. 4. **Habilitar emissão de NF-e** (opcional) — selecionar provedor em `Nota Fiscal > Configurações`, anexar certificado digital e mapear códigos de serviço. 5. **Importar clientes** — usar importação CSV em `Exportação e Importação > Importações` ou cadastrar manualmente. 6. **Criar a primeira assinatura** — vincular cliente a um plano em `Assinaturas` e confirmar o início do ciclo. 7. **Configurar dunning e notificações** — em `Gestão de Inadimplência` e `Configurações > Notificações`. 8. **Conectar webhooks e API** — cadastrar endpoints em `Webhooks`. A API pública usa o access token da Conta Kobana (`Authorization: Bearer`), não uma chave gerada aqui. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Painel de onboarding com checklist de configuração inicial](/pt/assets/images/primeiros-passos-9664956115b2bce50ceef894779a8604.png) --- ## [📄️Impostos](https://docs.billing.kobana.com.br/pt/pt/impostos.md) [O Faturamento Automático possui um motor de cálculo fiscal completo para o mercado brasileiro, com suporte a múltiplos regimes tributários, retenções e o novo sistema CBS/IBS.](https://docs.billing.kobana.com.br/pt/pt/impostos.md) --- ## [📄️Impostos](https://docs.billing.kobana.com.br/pt/pt/impostos.md) [O Faturamento Automático possui um motor de cálculo fiscal completo para o mercado brasileiro, com suporte a múltiplos regimes tributários, retenções e o novo sistema CBS/IBS.](https://docs.billing.kobana.com.br/pt/pt/impostos.md) --- # Motor de Cálculo de Impostos O motor de cálculo determina todos os impostos aplicáveis com base nas regras fiscais, perfil da empresa e tipo fiscal do cliente. ## Impostos Suportados[​](#impostos-suportados "Link direto para Impostos Suportados") | Imposto | Descrição | Jurisdição | | ---------- | ---------------------------------------------------- | ---------------- | | **ISS** | Imposto sobre Serviços | Municipal | | **PIS** | Programa de Integração Social | Federal | | **COFINS** | Contribuição para Financiamento da Seguridade Social | Federal | | **CSLL** | Contribuição Social sobre o Lucro Líquido | Federal | | **IRPJ** | Imposto de Renda Pessoa Jurídica | Federal | | **IRRF** | Imposto de Renda Retido na Fonte | Federal | | **CSRF** | PIS + COFINS + CSLL retidos em conjunto | Federal | | **INSS** | Contribuição à Previdência Social | Federal | | **CBS** | Contribuição sobre Bens e Serviços (2026+) | Federal | | **IBS** | Imposto sobre Bens e Serviços (2026+) | Federal/Estadual | ## Fluxo de Cálculo[​](#fluxo-de-cálculo "Link direto para Fluxo de Cálculo") ### 1. Obter Regras Aplicáveis[​](#1-obter-regras-aplicáveis "Link direto para 1. Obter Regras Aplicáveis") Consulta o `TaxRuleService` com o contexto da operação. As regras são filtradas por escopo e prioridade. ### 2. Resolver Alíquotas[​](#2-resolver-alíquotas "Link direto para 2. Resolver Alíquotas") * Extrai alíquotas das regras aplicáveis * Faz fallback para o Perfil Fiscal da empresa * Aplica sobrescritas de retenção da conta de cobrança ### 3. Calcular Cada Imposto[​](#3-calcular-cada-imposto "Link direto para 3. Calcular Cada Imposto") ``` ISS = valor_serviço × (alíquota_iss / 100) PIS = valor_serviço × (alíquota_pis / 100) COFINS = valor_serviço × (alíquota_cofins / 100) CSLL = valor_serviço × (alíquota_csll / 100) IRRF = valor_serviço × (alíquota_irrf / 100) [sempre retido] CSRF = valor_serviço × (4,65 / 100) [sempre retido] INSS = valor_serviço × (alíquota_inss / 100) [sempre retido] ``` ### 4. Arredondamento[​](#4-arredondamento "Link direto para 4. Arredondamento") Cada imposto é arredondado independentemente com `Math.round()`. Compensação de arredondamento aplicada ao imposto com maior contribuição. ### 5. Resultado[​](#5-resultado "Link direto para 5. Resultado") ``` Total de impostos = soma de todos os impostos Total retido = soma dos impostos com flag isWithheld Valor líquido = valor do serviço - total de impostos ``` ## CBS/IBS (Reforma Tributária 2026+)[​](#cbsibs-reforma-tributária-2026 "Link direto para CBS/IBS (Reforma Tributária 2026+)") O sistema já suporta os novos impostos da reforma tributária: | Modo | Descrição | | ------------- | ------------------------------------------ | | `informative` | Calculado mas não incluído no total (2026) | | `compositive` | Incluído no total (2027+) | As alíquotas de CBS e IBS são configuráveis no Perfil Fiscal da empresa. --- # Perfil Fiscal O perfil fiscal define a configuração tributária de cada empresa (entidade jurídica) da organização. ## Campos Principais[​](#campos-principais "Link direto para Campos Principais") ### Regime Tributário[​](#regime-tributário "Link direto para Regime Tributário") | Regime | Descrição | | ----------------- | ---------------------------- | | `simple_national` | Simples Nacional | | `presumed_profit` | Lucro Presumido | | `real_profit` | Lucro Real | | `mei` | Microempreendedor Individual | ### Simples Nacional[​](#simples-nacional "Link direto para Simples Nacional") | Campo | Descrição | | --------------------- | ----------------------------------------------- | | **Anexo** | `annex_iii`, `annex_iv` ou `annex_v` | | **RBT12** | Receita Bruta Tributária dos últimos 12 meses | | **Fator R** | Relação folha de pagamento / receita | | **CPP dentro do DAS** | Se a Contribuição Patronal está incluída no DAS | ### Lucro Presumido[​](#lucro-presumido "Link direto para Lucro Presumido") | Campo | Descrição | | --------------------- | -------------------------- | | **Taxa de presunção** | Padrão: 32% do faturamento | ### ISS[​](#iss "Link direto para ISS") | Campo | Descrição | | -------------------- | ------------------------ | | **Município (IBGE)** | Código IBGE do município | | **Alíquota ISS** | Percentual de ISS | ### Impostos Federais[​](#impostos-federais "Link direto para Impostos Federais") | Campo | Descrição | | ------------------- | -------------------- | | **Alíquota PIS** | Percentual do PIS | | **Alíquota COFINS** | Percentual da COFINS | | **Alíquota CSLL** | Percentual da CSLL | | **Alíquota IRPJ** | Percentual do IRPJ | ### CBS/IBS (2026+)[​](#cbsibs-2026 "Link direto para CBS/IBS (2026+)") | Campo | Descrição | | ---------------- | --------------------------------------------- | | **Habilitado** | Se o novo sistema está ativo | | **Alíquota CBS** | Percentual da CBS | | **Alíquota IBS** | Percentual do IBS | | **Modo** | `informative` (2026) ou `compositive` (2027+) | ## Versionamento[​](#versionamento "Link direto para Versionamento") Perfis fiscais são versionados: * `effective_from` e `effective_to` definem a vigência * `version` é incrementado automaticamente a cada alteração * O histórico permite rastrear mudanças ao longo do tempo ## RBT12 Histórico[​](#rbt12-histórico "Link direto para RBT12 Histórico") O sistema mantém o histórico da Receita Bruta Tributária mensal para cálculo preciso do Simples Nacional. Cada registro contém mês, ano e valor da receita. --- # Períodos Fiscais Períodos fiscais agregam as faturas para apuração mensal ou trimestral de impostos. ## Tipos de Período[​](#tipos-de-período "Link direto para Tipos de Período") | Tipo | Descrição | | ----------- | ----------------------------------- | | `monthly` | Apuração mensal (mês 1-12) | | `quarterly` | Apuração trimestral (trimestre 1-4) | ## Campos do Período[​](#campos-do-período "Link direto para Campos do Período") ### Receita[​](#receita "Link direto para Receita") | Campo | Descrição | | ---------------------- | ---------------------------- | | **Receita bruta** | Total faturado no período | | **Receita tributável** | Base de cálculo dos impostos | ### Impostos Devidos[​](#impostos-devidos "Link direto para Impostos Devidos") | Campo | Descrição | | ----------------- | -------------- | | **ISS devido** | ISS a pagar | | **PIS devido** | PIS a pagar | | **COFINS devido** | COFINS a pagar | | **IRPJ devido** | IRPJ a pagar | | **CSLL devido** | CSLL a pagar | ### Compensação de Retenções[​](#compensação-de-retenções "Link direto para Compensação de Retenções") | Campo | Descrição | | -------------------- | ------------------------------------------ | | **IRRF a compensar** | IRRF retido para abater do IRPJ | | **CSRF a compensar** | CSRF retido para abater do PIS/COFINS/CSLL | | **ISS a compensar** | ISS retido para abater | ### Simples Nacional[​](#simples-nacional "Link direto para Simples Nacional") | Campo | Descrição | | -------------------- | ------------------------------- | | **DAS estimado** | Valor estimado do DAS | | **Alíquota efetiva** | Alíquota calculada | | **Anexo** | Anexo do Simples (III, IV ou V) | ### CBS/IBS[​](#cbsibs "Link direto para CBS/IBS") | Campo | Descrição | | -------------- | ----------- | | **CBS devido** | CBS a pagar | | **IBS devido** | IBS a pagar | ## Status[​](#status "Link direto para Status") | Status | Descrição | | ------------ | ------------------------------------ | | `open` | Período em aberto, recebendo faturas | | `calculated` | Impostos calculados | | `closed` | Período encerrado | ## Cálculos[​](#cálculos "Link direto para Cálculos") ### Para Simples Nacional[​](#para-simples-nacional "Link direto para Para Simples Nacional") 1. Obtém RBT12 (Receita Bruta Tributária dos últimos 12 meses) 2. Localiza a faixa aplicável 3. Calcula a alíquota efetiva 4. Aplica à receita mensal 5. Distribui entre ISS, PIS, COFINS, CPP 6. Rastreia retenções para compensação ### Para Lucro Presumido[​](#para-lucro-presumido "Link direto para Para Lucro Presumido") 1. Obtém receita bruta 2. Aplica taxa de presunção (padrão: 32%) 3. Calcula IRPJ sobre o lucro presumido 4. Calcula CSLL sobre o lucro presumido 5. Calcula PIS/COFINS sobre a receita bruta 6. Calcula ISS conforme regras municipais 7. Rastreia retenções para compensação ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") A tela `/dashboard/tax-periods` lista cada período fiscal (mensal, trimestral ou anual), com receita bruta, receita tributável, tributos devidos (ISS, PIS, COFINS, IRPJ, CSLL, CBS, IBS), retenções a compensar, DAS estimado e alíquota efetiva. Períodos podem ser fechados (`closed`) — operação irreversível que congela os valores apurados. ![Períodos fiscais com receita, tributos e status de fechamento](/pt/assets/images/periodos-fiscais-0e650a9ad807b8682be0f0140933257e.png) --- # Regras Fiscais Regras fiscais permitem configurar alíquotas de impostos com diferentes níveis de especificidade. ## Campos da Regra[​](#campos-da-regra "Link direto para Campos da Regra") | Campo | Descrição | | -------------- | ------------------------------------------------ | | **Nome** | Nome descritivo da regra | | **Escopo** | Nível de aplicação (ver tabela) | | **Prioridade** | Maior número = maior prioridade dentro do escopo | | **Ativa** | Se a regra está ativa | | **Vigência** | Período de validade (de/até) | | **Itens** | Lista de impostos e alíquotas | ### Critérios de Correspondência (opcionais)[​](#critérios-de-correspondência-opcionais "Link direto para Critérios de Correspondência (opcionais)") | Campo | Descrição | | -------------------------- | --------------------------- | | **Empresa** | Empresa emissora específica | | **Item de serviço** | Serviço específico | | **Conta de cobrança** | Cliente específico | | **Tipo fiscal do cliente** | Classificação do cliente | | **Município** | Código IBGE do município | | **Tipo de operação** | `interno` ou `externo` | ## Escopo e Prioridade[​](#escopo-e-prioridade "Link direto para Escopo e Prioridade") As regras são avaliadas do mais específico para o mais genérico: | Escopo | Prioridade | Descrição | | -------------- | ---------- | ------------------------------------- | | `customer` | 100 | Regra para cliente específico | | `service` | 80 | Regra para item de serviço específico | | `company` | 60 | Regra para empresa emissora | | `municipality` | 40 | Regra por município | | `organization` | 20 | Regra geral da organização | | `global` | 0 | Padrão do sistema | **Regra com prioridade maior prevalece.** Múltiplas regras da mesma prioridade são combinadas. ## Itens da Regra[​](#itens-da-regra "Link direto para Itens da Regra") Cada regra contém itens que definem alíquotas: | Campo | Descrição | | --------------------- | ------------------------------------------------------------- | | **Tipo de imposto** | ISS, PIS, COFINS, CSLL, IRPJ, IRRF, CSRF, INSS | | **Alíquota** | Percentual (ex: 5,00 para 5%) | | **Retido** | Se é retido na fonte | | **Base de cálculo** | `service_value`, `service_value_minus_iss` ou `presumed_base` | | **Isento** | Se o imposto é isento | | **Motivo da isenção** | Justificativa da isenção | ## Exemplos[​](#exemplos "Link direto para Exemplos") ### ISS padrão da organização[​](#iss-padrão-da-organização "Link direto para ISS padrão da organização") ``` Escopo: organization (prioridade 20) Item: ISS = 5,00%, retido na fonte, base = valor do serviço ``` ### Regra específica para serviço[​](#regra-específica-para-serviço "Link direto para Regra específica para serviço") ``` Escopo: service (prioridade 80) Item de serviço: "Desenvolvimento de Software" Itens: - ISS = 3,50%, não retido - IRRF = 15,00%, retido na fonte ``` A regra de serviço prevalece sobre a regra da organização para o ISS. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") A tela `/dashboard/tax-rules` permite criar, editar e priorizar regras tributárias. Os filtros principais incluem empresa, cliente, item de serviço, tipo de imposto e indicação de retenção. Cada regra carrega uma lista de tributos com alíquota, flag de retenção e isenção. ![Lista de regras tributárias com escopo, prioridade e alíquotas](/pt/assets/images/regras-fiscais-1ddc1b10a06ca4c0327f2d7c996a7cd5.png) --- # Relatórios Fiscais A área de relatórios fiscais (`/dashboard/fiscal/reports`) consolida as informações necessárias para fechamento contábil e geração de obrigações acessórias. Os dados são gerados a partir das faturas pagas, NF-e emitidas, retenções e períodos fiscais já fechados pela organização. ## Tipos de relatório[​](#tipos-de-relatório "Link direto para Tipos de relatório") * **Resumo por competência** — receita bruta, tributável, ISS, PIS, COFINS, IR, CSLL, INSS e DAS estimado por mês, trimestre ou ano. * **Retenções sofridas** — todas as retenções aplicadas pelos tomadores (IR, INSS, CSRF, ISS), com base de cálculo, alíquota, valor retido e status (`open`, `partially_compensated`, `fully_compensated`). * **NF-e emitidas no período** — lista paginada com número, série, valor, status, código do município, alíquotas aplicadas e tributos calculados. * **DAS / Simples Nacional** — para empresas no regime simplificado, o relatório mostra a RBT12, a faixa atual e o valor estimado da guia. ## Filtros disponíveis[​](#filtros-disponíveis "Link direto para Filtros disponíveis") * **Empresa** — limita a uma das empresas cadastradas. * **Período** — mês, trimestre, ano ou intervalo customizado. * **Regime tributário** — quando a organização tem empresas em regimes diferentes. ## Como os valores são apurados[​](#como-os-valores-são-apurados "Link direto para Como os valores são apurados") Os relatórios consultam diretamente as tabelas de `tax_periods`, `tax_computations`, `withholdings` e `nfes`, sempre filtradas por `organization_id`. Períodos `closed` são imutáveis; períodos `open` podem mudar conforme novas faturas são pagas ou NF-e emitidas. Para fechar a competência, use [Períodos Fiscais](https://docs.billing.kobana.com.br/pt/pt/impostos/periodos-fiscais/.md). ## Exportação[​](#exportação "Link direto para Exportação") Os relatórios podem ser exportados em CSV para envio ao contador ou importação em sistemas de escrituração. As exportações ficam disponíveis em [Exportação e Importação](https://docs.billing.kobana.com.br/pt/pt/exportacao-e-importacao.md). ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Relatórios fiscais com tributos por competência e retenções](/pt/assets/images/relatorios-fiscais-01c31ce31b389d3194e3cd2a3aab7b93.png) --- # Retenções na Fonte Retenções são impostos retidos pelo pagador (cliente) que devem ser rastreados, reportados e compensados. ## Tipos de Retenção[​](#tipos-de-retenção "Link direto para Tipos de Retenção") | Imposto | Descrição | | -------- | -------------------------------------- | | **ISS** | Retido pelo tomador do serviço | | **IRRF** | Imposto de renda retido na fonte | | **CSRF** | PIS + COFINS + CSLL combinados (4,65%) | | **INSS** | Contribuição previdenciária | ## Campos da Retenção[​](#campos-da-retenção "Link direto para Campos da Retenção") | Campo | Descrição | | -------------------------- | ---------------------------------------------------- | | **Fatura** | Fatura de origem | | **NF-e** | Nota fiscal relacionada | | **Tipo de imposto** | Qual imposto foi retido | | **Base** | Base de cálculo | | **Alíquota** | Percentual retido | | **Valor** | Montante retido | | **Retentor** | Entidade que reteve (geralmente a conta de cobrança) | | **Mês/Ano de competência** | Período contábil | | **Status** | Estado da retenção | | **Compensado** | Valor já utilizado para abater impostos | ## Status da Retenção[​](#status-da-retenção "Link direto para Status da Retenção") | Status | Descrição | | ----------------------- | -------------------------------- | | `retained` | Registrada, ainda não compensada | | `compensated` | Totalmente compensada | | `partially_compensated` | Parcialmente compensada | ## Fluxo[​](#fluxo "Link direto para Fluxo") 1. **Criação**: Gerada automaticamente a partir do cálculo de impostos de cada fatura 2. **Retenção**: O valor é retido pelo cliente no momento do pagamento 3. **Rastreamento**: Armazenada por mês/ano de competência 4. **Compensação**: Aplicada para reduzir a obrigação tributária nos períodos seguintes 5. **Reconciliação**: Reportada nas declarações fiscais ## Configuração por Cliente[​](#configuração-por-cliente "Link direto para Configuração por Cliente") Cada conta de cobrança pode ter flags individuais de retenção: * `withholdIss` — Reter ISS * `withholdIrrf` — Reter IRRF * `withholdCsrf` — Reter CSRF (PIS/COFINS/CSLL) * `withholdInss` — Reter INSS Essas flags sobrescrevem o comportamento padrão das regras fiscais. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") A tela `/dashboard/withholdings` lista todas as retenções da organização, com filtros por tipo de imposto, status, mês/ano de competência, empresa retentora e busca por fatura ou NF-e. Cada linha mostra base, alíquota, valor retido, valor já compensado e ações para abrir a fatura/NF-e de origem. ![Lista de retenções com tipo, base, alíquota e compensação](/pt/assets/images/retencoes-f307e667e1de9cd1f3b631c2fe9c9cd5.png) --- # Simples Nacional O sistema calcula automaticamente o DAS (Documento de Arrecadação do Simples Nacional) com base na receita e no anexo correto. ## Anexos Suportados[​](#anexos-suportados "Link direto para Anexos Suportados") ### Anexo III — Serviços em Geral[​](#anexo-iii--serviços-em-geral "Link direto para Anexo III — Serviços em Geral") | Faixa | RBT12 (R$ mil) | Alíquota Nominal | | ----- | -------------- | ---------------- | | 1ª | Até 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 — Construção, Vigilância, Limpeza[​](#anexo-iv--construção-vigilância-limpeza "Link direto para Anexo IV — Construção, Vigilância, Limpeza") | Faixa | RBT12 (R$ mil) | Alíquota Nominal | | ----- | -------------- | ---------------- | | 1ª | Até 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 — Serviços Intelectuais[​](#anexo-v--serviços-intelectuais "Link direto para Anexo V — Serviços Intelectuais") | Faixa | RBT12 (R$ mil) | Alíquota Nominal | | ----- | -------------- | ---------------- | | 1ª | Até 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% | ## Fator R[​](#fator-r "Link direto para Fator R") O Fator R determina se empresas originalmente no Anexo V podem usar o Anexo III (alíquotas menores): ``` Fator R = Folha de Pagamento (12 meses) / Receita Bruta (12 meses) ``` * **Fator R ≥ 28%**: Pode usar o Anexo III * **Fator R < 28%**: Permanece no Anexo V ## Cálculo da Alíquota Efetiva[​](#cálculo-da-alíquota-efetiva "Link direto para Cálculo da Alíquota Efetiva") ``` Alíquota Efetiva = (RBT12 × Alíquota Nominal - Dedução) / RBT12 × 100 ``` ## Cálculo do DAS[​](#cálculo-do-das "Link direto para Cálculo do DAS") ``` DAS = Receita Mensal × Alíquota Efetiva ``` ## Distribuição do DAS[​](#distribuição-do-das "Link direto para Distribuição do DAS") O valor do DAS é distribuído entre os impostos: * 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% As proporções variam conforme o anexo e a faixa. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") A tela `/dashboard/simples` apresenta a apuração do Simples Nacional por empresa: anexo atual, RBT12 (receita bruta dos últimos 12 meses), faixa em que a empresa está, alíquota nominal, parcela a deduzir, fator R quando aplicável e estimativa do DAS para o mês corrente. Inclui alertas de proximidade do teto e de mudança de faixa. ![Apuração Simples Nacional com anexo, faixa e DAS estimado](/pt/assets/images/simples-nacional-f9e1b8e843e4bd1046168589d83b5591.png) --- # Autenticação O servidor MCP aceita um **Bearer token** no cabeçalho `Authorization`, e nada além disso — sem cookie, sem certificado de cliente. :::warning Nunca na URL Token na query string (`?access_token=…`, ou parâmetros como `token` e `api_key`) **não autentica**, mesmo acompanhado de um cabeçalho válido: a requisição responde `401` com `error="invalid_request"` no `WWW-Authenticate`. Um token na URL vaza em logs de proxy e CDN, no `Referer` e no histórico — a especificação de autorização do MCP e a RFC 6750 proíbem esse uso. ::: Esse token é um **access token OAuth 2.1 emitido pelo authorization server da Kobana** (`https://account.kobana.com.br`), um JWT assinado em RS256 e emitido **para este recurso**: o `aud` dele é `https://mcp.billing.kobana.com.br`. Ele chega por um de dois caminhos — o fluxo OAuth, feito pelo próprio cliente, ou um **token pessoal** que você cria na sua conta Kobana — e é verificado do mesmo jeito nos dois casos. ``` Authorization: Bearer eyJhbGciOiJSUzI1NiIs… ``` :::info Cada superfície tem a sua audience Um token emitido para o MCP **não vale** na API REST (`api.billing.*`), e um token da API não vale aqui. É o que impede que o token entregue a um assistente seja reaproveitado contra a API — e o contrário. ::: ## Dois jeitos de conectar[​](#dois-jeitos-de-conectar "Link direto para Dois jeitos de conectar") | | Fluxo OAuth | Token pessoal | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Como você obtém | Cola a URL no cliente; ele abre o login da Kobana e você autoriza | Cria em **Conta Kobana → Tokens e Acesso → Novo Token Pessoal**: app **Faturamento Automático**, uso **MCP**, recursos e acessos, validade | | Como o cliente usa | Sozinho, depois da autorização | Você cola no cliente como `Authorization: Bearer ` | | Validade | 30 minutos, renovado pelo cliente | De 7 dias a 1 ano, escolhida por você | | Escopo | Os recursos e os níveis de acesso que você manteve marcados na tela de consentimento (`read`, `write`, `delete`, `import`, `export`, `all`) | Os recursos e acessos que você marcou | | Bom para | Claude, ChatGPT, IDEs e qualquer cliente com OAuth | Clientes sem suporte a OAuth, scripts e automações | O token pessoal tem que ser criado com o uso **MCP**. Um token criado para **API REST** tem a audience da API e é recusado aqui com `401` — e o contrário também vale. ## O fluxo OAuth[​](#o-fluxo-oauth "Link direto para O fluxo OAuth") Você não executa nenhum destes passos: o cliente MCP (Claude, ChatGPT, uma IDE) faz tudo sozinho a partir da URL. Eles estão aqui para quando algo falhar no meio. 1. **Desafio.** Uma requisição sem token recebe `401` com o desafio que todo resource server OAuth 2.1 deve mandar ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)): ``` WWW-Authenticate: Bearer realm="kobana-billing-mcp", error="invalid_token", resource_metadata="https://mcp.billing.kobana.com.br/.well-known/oauth-protected-resource" ``` 2. **Metadata do recurso.** O cliente lê o documento apontado. Ele é público e não carrega segredo nenhum — só ponteiros: ``` curl https://mcp.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 do authorization server** ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)), em `https://account.kobana.com.br/.well-known/oauth-authorization-server`. 4. **Registro dinâmico do cliente** ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)). O cliente se registra sozinho; a tela de consentimento avisa que ele não é um app verificado. 5. **Autorização com PKCE e `resource`** ([RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707)). Você faz login na Kobana, escolhe a organização (se tiver mais de uma) e autoriza. 6. **Token.** O cliente troca o código por um access token de vida curta e passa a mandá-lo em toda requisição, renovando quando expira. O token carrega quem você é (`sub`) e a organização que você autorizou (`org`). É o `org` que escopa os dados — nenhuma tool aceita organização como argumento. Um token cuja organização não existe no Faturamento recebe `403 unknown_organization`. ## Autorização: as permissões de quem autorizou[​](#autorização-as-permissões-de-quem-autorizou "Link direto para Autorização: as permissões de quem autorizou") O que um chamador vê é **mais estreito** que o catálogo: as tools são filtradas pelas **permissões de dashboard da pessoa que autorizou o cliente**, naquela organização, resolvidas a cada requisição. O teto é sempre o que essa pessoa pode fazer na interface. | Situação | Resultado | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | A pessoa não é membro da organização | **Nega todas as tools** (`key_owner_not_member`). Autorize de novo com uma conta que pertença à organização. | | Vínculo ativo | As permissões e papéis da pessoa, aplicados tool a tool. `owner` e o curinga `*` liberam tudo; `invoices.*` libera a família. | | Vínculo suspenso, removido, ou sem nenhum papel | **Nega todas as tools** (`membership_inactive`). | | A consulta de permissões falha | **Nega todas as tools.** Falha fechada. | As permissões são lidas a cada chamada, então revogar um papel no dashboard vale já na tool seguinte, sem esperar o token expirar. Uma tool que o chamador não pode rodar **não é listada** em `tools/list`. Quando `tools/call` recusa, o código diz **quem resolve**: | Código | Quem resolve | | ------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `insufficient_scope` | Usar um token que alcance o recurso com o acesso pedido — por exemplo, um token pessoal com escrita nesse recurso. | | `insufficient_permission` | Um admin da organização, concedendo a permissão (o erro nomeia qual). | | `membership_inactive` | Reativar a pessoa — nenhuma permissão conserta um vínculo morto. | | `key_owner_not_member` | Autorizar de novo com uma conta que seja membro da organização. | :::tip Postura recomendada para agentes Autorize o cliente com uma conta que só tenha as permissões que o agente precisa. Um cliente autorizado por um analista somente-leitura expõe só as tools de leitura, faça o que fizer o modelo do outro lado. ::: ## Escopo do token[​](#escopo-do-token "Link direto para Escopo do token") Além das permissões, o MCP aplica o escopo que o token carrega, no claim `scope`. As duas checagens se somam: uma tool só aparece se as duas deixarem. Leitura é tool de leitura, resource, prompt de leitura e completion. As tools de exclusão (`*_delete`, inclusive as em lote) exigem `delete`; a importação de NFS-e de Barueri (`billing_nfes_import_barueri`) exige `import`; todo o resto que altera dados exige `write`. Um nível não substitui outro: `write` não exclui nem importa. Cada tool exige exatamente o nível que o endpoint REST por trás dela exige — toda tool de exclusão chama um `DELETE`, e o endpoint confere o token de novo com esse nível. **Token com recursos** — o caso do token pessoal e do fluxo OAuth. Os recursos definem até onde o token chega, e os verbos valem só dentro deles: | Escopo do token | Resultado | | ----------------------------------------------- | --------------------------------------------- | | `billing/invoices billing/customers read write` | Lê e escreve faturas e clientes — e nada mais | | `billing/invoices read` | Só lê faturas | | `billing/all read` | Lê tudo, não escreve nada | Contas bancárias, bancos e chaves Pix só são alcançáveis com `billing/all`. `delete`, `import` e `export` sozinhos não contam como escrita, e `write` sozinho não exclui. Para excluir, o token precisa do recurso e de `delete`: `billing/products read write delete` lê, altera e exclui produtos. **Token sem recursos** — um token que não traz nenhum escopo `billing/…`. Vale só o nível de acesso: leitura com `read`, `write` ou `all`; escrita com `write` ou `all`; exclusão com `delete` ou `all`; importação com `import` ou `all`; exportação com `export` ou `all`. Um token sem nenhum desses níveis e sem `billing/…` não alcança tool nenhuma além de `billing_me`. :::info Clientes conectados pelo fluxo OAuth pedem todos os níveis — você escolhe quais conceder O documento `/.well-known/oauth-protected-resource` anuncia os recursos do billing e os seis níveis de acesso — `read`, `write`, `delete`, `import`, `export` e `all` —, e é isso que o cliente (Claude, ChatGPT, o MCP Inspector, IDEs) pede na tela de consentimento. Lá você desmarca o que não quer conceder, nível a nível: o token emitido traz só os recursos e os níveis que ficaram marcados, e o MCP lista só as tools que eles alcançam. Uma tool fora dele volta `insufficient_scope`, e a saída é autorizar de novo concedendo o acesso que faltou — por exemplo, `delete` para as tools de exclusão. ::: A mesma regra vale na API REST, com o recurso tirado do caminho e um nível por requisição: `GET` exige `read`, `DELETE` exige `delete`, a importação exige `import` e o resto exige `write` — sem o nível, a resposta é `403 insufficient_scope`. Veja [Autenticação da API](https://docs.billing.kobana.com.br/pt/pt/api/overview/authentication.md). ### Revogação do token pessoal[​](#revogação-do-token-pessoal "Link direto para Revogação do token pessoal") Revogar um token pessoal na sua conta Kobana **não corta o acesso na hora**: o Faturamento verifica o token sozinho, sem consultar a Kobana a cada chamada, e ele continua aceito até a validade dele. Por isso: * escolha a **validade mais curta** que o uso permite; * marque só os **recursos e acessos** de que o agente precisa; * para cortar um agente imediatamente, suspenda ou remova o vínculo da pessoa na organização — as permissões são lidas a cada chamada e valem na hora. ## Modos de falha[​](#modos-de-falha "Link direto para Modos de falha") | HTTP | `code` | Causa | | ---- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `-32022` (JSON-RPC) | Versão do protocolo não suportada, no cabeçalho `MCP-Protocol-Version` ou no `_meta`; `data.supported` lista as que são. Veja [Transporte](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/transport.md#vers%C3%B5es-do-protocolo). | | 401 | `invalid_token` | Token ausente, malformado, inválido, emitido para outro recurso (por exemplo, para a API REST) ou com mais de uma audience no `aud`. | | 401 | `token_expired` | O token expirou. O cliente renova e tenta de novo. | | 401 | `invalid_request` | Token na query string — veja o aviso no topo da página. | | 403 | `unknown_organization` | O token é válido, mas a organização que ele nomeia não existe no Faturamento. | | 403 | `FORBIDDEN` | `Origin` fora da allowlist (`origin_not_allowed`). | | 404 | `NOT_FOUND` | A requisição chegou por um host que não serve MCP. | | 429 | `TOO_MANY_REQUESTS` | Limite de requisições atingido, com `Retry-After` e `X-RateLimit-*` — veja [Limite de requisições](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/rate-limit.md). | | 503 | `SERVICE_UNAVAILABLE` | Não conseguimos falar com o authorization server para verificar o token. É do nosso lado: tente de novo depois do `Retry-After`. | Todo `401` carrega o desafio `WWW-Authenticate` acima, que manda o cliente de volta ao fluxo OAuth. O desafio diz sempre `error="invalid_token"` (ou `invalid_request`, para token na URL), como manda a RFC 6750; é o `code` do corpo que separa um token expirado (`token_expired`) dos demais. Nenhuma resposta de `/mcp` é cacheável: todas, inclusive as recusas, vêm com `Cache-Control: no-store` e `Content-Security-Policy: default-src 'none'`. A exceção é o documento `/.well-known/oauth-protected-resource`, público, com `Cache-Control: public, max-age=300`. Negativas de permissão **não** são erros HTTP: elas voltam como resultado de tool marcado `isError`, para que o modelo leia e reaja — veja [Erros](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/errors.md). ## Host e borda[​](#host-e-borda "Link direto para Host e borda") `/mcp` tem que ser alcançável **só** por `mcp.billing.*` — nunca pelo host do app, nunca pelo host da API, cujas distributions apontam para a mesma origin. Qualquer outro caminho responde `404`: o endpoint não anuncia que existe em outro lugar. O identificador de recurso OAuth — e, portanto, a audience que o token precisa ter — é derivado da **configuração do servidor**, nunca do `Host` da requisição, para que um `Host` forjado não consiga apontar um cliente para outro identificador. --- # Clientes Qualquer cliente que fale **Streamable HTTP** MCP e saiba fazer o fluxo **OAuth 2.1** do MCP consegue conectar. Você só informa a URL; o cliente descobre sozinho onde autenticar, abre o login da Kobana no navegador e guarda o token — veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). Cliente sem suporte a OAuth também conecta, com um **token pessoal**: crie em **Conta Kobana → Tokens e Acesso → Novo Token Pessoal**, com o app **Faturamento Automático** e o uso **MCP**, e configure o cliente para mandá-lo no cabeçalho `Authorization: Bearer `. ## Claude Code[​](#claude-code "Link direto para Claude Code") ``` claude mcp add --transport http kobana-billing https://mcp.billing.kobana.com.br ``` Depois, rode `/mcp` numa sessão e escolha **Authenticate** para fazer login na Kobana. Com um token pessoal, sem fluxo OAuth: ``` claude mcp add --transport http kobana-billing https://mcp.billing.kobana.com.br \ --header "Authorization: Bearer " ``` ## Clientes configurados por arquivo[​](#clientes-configurados-por-arquivo "Link direto para Clientes configurados por arquivo") Clientes que leem um arquivo JSON de configuração pedem a URL e o transporte. Pelo fluxo OAuth, não há cabeçalho de autenticação: ``` { "mcpServers": { "kobana-billing": { "type": "http", "url": "https://mcp.billing.kobana.com.br" } } } ``` Na primeira conexão o cliente abre o navegador para você autorizar. Não há cabeçalho de seleção de organização: você escolhe a organização na tela de consentimento, e ela fica gravada no token. Com um token pessoal, acrescente o cabeçalho — a organização é a da conta em que você criou o token: ``` { "mcpServers": { "kobana-billing": { "type": "http", "url": "https://mcp.billing.kobana.com.br", "headers": { "Authorization": "Bearer " } } } } ``` Trate o arquivo como segredo: quem o lê usa o token. ## Clientes que conectam por URL[​](#clientes-que-conectam-por-url "Link direto para Clientes que conectam por URL") Claude e ChatGPT conectam um servidor remoto colando a URL `https://mcp.billing.kobana.com.br` nas configurações de conectores. O fluxo OAuth roda dentro do próprio app. ## Postura recomendada para agentes[​](#postura-recomendada-para-agentes "Link direto para Postura recomendada para agentes") * **Autorize com a conta certa.** As tools são estreitadas para as permissões de dashboard de quem autorizou o cliente. Um cliente autorizado por um analista somente-leitura expõe só as tools de leitura, faça o que fizer o modelo do outro lado. É a forma mais forte de restringir um agente. * **Um token por cliente.** Cada cliente faz o próprio fluxo e recebe o próprio token, que só vale no MCP — ele não serve para chamar a API REST. Para desligar um agente, remova a autorização dele na Kobana sem afetar as suas integrações. * **Token pessoal: validade curta e escopo mínimo.** Marque só os recursos e acessos de que o agente precisa, e a validade mais curta que o uso permite: revogar o token na Kobana não corta o acesso antes da validade — veja [Revogação do token pessoal](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md#revoga%C3%A7%C3%A3o-do-token-pessoal). * **Comece no sandbox.** As tools destrutivas cancelam assinaturas e invalidam faturas de verdade; o servidor pede confirmação antes de cada uma (e as recusa a um cliente que não consegue confirmar), mas a primeira exploração não deve ser em produção. ## Verificando a conexão[​](#verificando-a-conexão "Link direto para Verificando a conexão") O jeito mais simples é pedir ao assistente: "qual organização eu estou usando no Faturamento?" — ele chama `billing_organization_get`. Com um token emitido para o MCP — um token pessoal com uso **MCP**, por exemplo —, dá para conferir por `curl`: ``` # 1. Qual organização este token alcança? 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. Quantas tools este token alcança? 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' ``` Se o número for menor do que você esperava, são as permissões de quem autorizou ou o escopo do token — veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). Não é um erro. --- # Endpoints ## Servidor MCP[​](#servidor-mcp "Link direto para Servidor MCP") | Ambiente | URL | | -------- | ------------------------------------------- | | Produção | `https://mcp.billing.kobana.com.br` | | Sandbox | `https://mcp.billing.sandbox.kobana.com.br` | A URL do servidor é a **raiz do host** — é esse endereço inteiro que você cola num cliente MCP. Ela é também o *resource identifier* OAuth, e é por isso que não carrega caminho nenhum. ## Rotas servidas[​](#rotas-servidas "Link direto para Rotas servidas") | Método | Caminho | Para quê | | -------- | --------------------------------------- | --------------------------------------------------------------------- | | `POST` | `/` | Uma mensagem JSON-RPC por requisição. Toda a superfície de tools. | | `GET` | `/.well-known/oauth-protected-resource` | Metadata do recurso protegido (RFC 9728). Pública, sem autenticação. | | `GET` | `/` | `405` — este servidor é stateless e não abre stream servidor→cliente. | | `DELETE` | `/` | `204` — não há sessão para encerrar. | ## Documentação e API[​](#documentação-e-api "Link direto para Documentação e API") | | URL | | ------------------- | ------------------------------------------- | | Documentação | | | API REST (produção) | | | API REST (sandbox) | | dica Cada ambiente tem banco e authorization server próprios. Um token emitido em sandbox não vale em produção — comece pelo sandbox. :::info Host separado, de propósito O servidor MCP tem host próprio em vez de um caminho no host da API ou do app. São três razões: o documento de descoberta OAuth precisa morar na raiz do host; nenhum cookie de dashboard é enviado para esta origin, o que elimina por construção uma classe inteira de problemas de *confused deputy*; e o host da API tem uma política de borda desenhada para integrações servidor-a-servidor, não para um app de consumo. ::: ## Desenvolvimento local[​](#desenvolvimento-local "Link direto para Desenvolvimento local") Em desenvolvimento o endpoint responde em `/mcp` no host do app (`http://localhost:3001/mcp`), e o documento de descoberta em `/.well-known/oauth-protected-resource`. Fora do desenvolvimento a allowlist de host esconde o endpoint (`404`) fora de `mcp.billing.*`. No host MCP, qualquer caminho que não seja o endpoint nem o documento de descoberta responde `404` em JSON, com qualquer método: ``` { "error": { "code": "NOT_FOUND", "message": "Not found." } } ``` --- # Erros As falhas chegam por **dois canais diferentes**, e a distinção importa: um é requisição quebrada, o outro é algo que o modelo deve ler e reagir. ## Erros de tool[​](#erros-de-tool "Link direto para Erros de tool") Tudo sobre o que o chamador pode agir — validação, não encontrado, escopo insuficiente, permissão insuficiente, um erro do endpoint — volta como uma **resposta JSON-RPC bem-sucedida** cujo resultado está marcado `isError`, carregando o envelope de erro da própria API como texto: ``` { "jsonrpc": "2.0", "id": 2, "result": { "isError": true, "content": [{ "type": "text", "text": "{ \"error\": { \"code\": \"NOT_FOUND\", \"message\": \"Invoice not found\" } }" }] } } ``` O vocabulário de `code` é o da API REST, sem mudança. Os que você mais vai encontrar: | `code` | Quando | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `VALIDATION_ERROR` | Os argumentos falharam na validação do endpoint; os detalhes nomeiam os campos. | | `NOT_FOUND` | Não existe esse registro, ou ele pertence a outra organização. | | `CONFLICT` / `DUPLICATE_ERROR` | `external_id` já em uso, ou uma chave de negócio duplicada. | | `BAD_REQUEST` | Regra de negócio violada — cancelar uma assinatura já cancelada, finalizar uma fatura que não está em rascunho. | | `FORBIDDEN` | A operação não é permitida para este recurso no estado em que ele está. | | `GATEWAY_ERROR` / `EXTERNAL_SERVICE_ERROR` | O gateway de pagamento ou o provedor de NF-e recusou ou não respondeu. | | `USER_DECLINED` | Na era `2026-07-28`, o usuário recusou ou cancelou a confirmação de uma tool destrutiva. Nada foi alterado. | | `confirmation_required` | A tool é destrutiva, o cliente não consegue confirmar no chat e o token não tem uma pessoa que possa abrir um link de aprovação. Use um cliente na revisão `2026-07-28` com elicitation. Nada foi executado. | | `confirmation_replayed` | A confirmação enviada já tinha sido usada — cada uma roda uma chamada uma vez. Chame a tool de novo para ser perguntado outra vez. Nada foi executado. | | `confirmation_unavailable` | O servidor não conseguiu registrar a confirmação (ou a aprovação por link) agora, então recusou a tool. Nada foi executado; tente de novo depois. | E os quatro que o próprio MCP acrescenta, porque são sobre *autorização*, não sobre o recurso: | `code` | Quem resolve | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `insufficient_scope` | O escopo do token não alcança a tool: o recurso não está no token, ou falta o verbo que a tool exige (`write`, `delete` ou `import`). Autorize de novo concedendo o acesso que faltou (no fluxo OAuth, leitura, escrita e importação sobre os recursos aprovados), ou use um token pessoal que alcance o recurso com o verbo pedido — exclusão (`delete`) só por token pessoal. | | `insufficient_permission` | Um admin da organização, concedendo a permissão que o erro nomeia. | | `membership_inactive` | Reativar a pessoa que autorizou o cliente — nenhuma permissão conserta um vínculo morto. | | `key_owner_not_member` | Autorizar o cliente de novo com uma conta que seja membro da organização. | Esses quatro são separados **de propósito**: são conversas diferentes, com pessoas diferentes. Um erro único diria "você não pode" sem dizer a quem pedir. Veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). ### `input_required` não é erro[​](#input_required-não-é-erro "Link direto para input_required-não-é-erro") Na era `2026-07-28`, o primeiro `tools/call` de uma tool destrutiva pode voltar `resultType: "input_required"` com um pedido de confirmação ao usuário. É o fluxo normal, não uma falha: o cliente mostra a pergunta e reenvia a mesma chamada com a resposta. Veja [Confirmação de tools destrutivas](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md#confirma%C3%A7%C3%A3o-de-tools-destrutivas). ## Erros de protocolo[​](#erros-de-protocolo "Link direto para Erros de protocolo") Uma mensagem malformada recebe um objeto de erro JSON-RPC, não um resultado: | Código | Significado | | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `-32700` | Parse error — o corpo não é JSON válido | | `-32600` | Invalid request — não é um objeto JSON-RPC, ou é um array (batching não é suportado) | | `-32601` | Method not found | | `-32602` | Invalid params — tool, prompt ou argumento inexistente, `name` ausente; na era `2026-07-28`, também resource não encontrado | | `-32002` | Resource não encontrado — só na era 2025 (a `2026-07-28` usa `-32602`) | | `-32603` | Internal error — falha inesperada ao rodar a tool | ``` { "jsonrpc": "2.0", "id": 3, "error": { "code": -32601, "message": "Method not found: tools/describe" } } ``` ## Erros de transporte[​](#erros-de-transporte "Link direto para Erros de transporte") Recusas que acontecem **antes** da mensagem JSON-RPC ser lida são respostas HTTP comuns, com o envelope de erro da API: token ausente ou inválido, versão de protocolo não suportada, `Origin` fora da allowlist, limite de requisições, corpo acima de **1 MB** (`413`, com o erro JSON-RPC `-32600` `Request body too large`). Estão listadas em [Autenticação → Modos de falha](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md#modos-de-falha). ## Por que `isError` e não erro JSON-RPC[​](#por-que-iserror-e-não-erro-json-rpc "Link direto para por-que-iserror-e-não-erro-json-rpc") Um `404` numa fatura não é um defeito do cliente MCP — é informação sobre o mundo, e o modelo do outro lado precisa dela para corrigir a si mesmo. Enterrá-la num erro de protocolo faria o cliente tratá-la como falha de transporte, esconder o texto e, no melhor caso, tentar de novo idêntico. Por isso a regra é: **se o chamador pode agir, é resultado; se a requisição está quebrada, é erro.** ## Observabilidade[​](#observabilidade "Link direto para Observabilidade") Cada `tools/call` escreve uma linha estruturada com a tool, a organização, o token, o status e a duração. As **escritas** também aparecem na trilha de auditoria da organização, gravada pelo próprio endpoint despachado e atribuída à pessoa que autorizou o cliente — o que um agente fez aparece ao lado do que uma pessoa fez, na mesma tela. --- # Idempotência As tools que **criam um recurso ou movem dinheiro** aceitam um argumento opcional `idempotency_key`. Ele é enviado ao endpoint como o cabeçalho `X-Idempotency-Key` que a API REST já honra. ``` { "name": "billing_invoices_create", "arguments": { "billing_account_id": "…", "total": 1250.00, "idempotency_key": "7c4a8d09-ca37-4f21-b1f0-3d2f2b8c9a11" } } ``` | | | | --------------------------------- | ------------------------------------------------------------ | | **Formato** | String opaca, 1 a 255 caracteres. Um UUID é a escolha usual. | | **Repetição com o mesmo corpo** | Devolve a resposta original, sem rodar a operação de novo. | | **Repetição com corpo diferente** | Conflito. | ## Por que um agente precisa disto mais que o seu backend[​](#por-que-um-agente-precisa-disto-mais-que-o-seu-backend "Link direto para Por que um agente precisa disto mais que o seu backend") Um cliente MCP que dá timeout e tenta de novo, ou um modelo que decide "não tenho certeza se aquilo funcionou, vou refazer", é exatamente o padrão que cria a segunda fatura, a segunda cobrança e o segundo cliente. Seu backend tem um laço de retry que você escreveu; o agente tem um julgamento. **Mande uma chave sempre que a operação cobre, emita ou crie.** Leituras e atualizações são naturalmente idempotentes e não pedem chave. ## Tools que aceitam[​](#tools-que-aceitam "Link direto para Tools que aceitam") | Família | 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 As que cobram `billing_invoices_pay`, `billing_payments_create`, `billing_payments_retry` e `billing_nfes_issue` produzem um efeito no mundo — uma cobrança no gateway, uma nota fiscal na SEFAZ — que nenhum `_delete` desfaz. Mande `idempotency_key` nessas mesmo quando você acha que não vai repetir. ::: ## Upsert não é idempotência[​](#upsert-não-é-idempotência "Link direto para Upsert não é idempotência") `*_upsert` casa um registro existente por `id`, depois `external_id`, depois pela chave de negócio do recurso, e cria só se não achar. Isso resolve "não sei se já existe", que é um problema diferente de "não sei se minha chamada chegou". As duas coisas se combinam bem: um `upsert` com `idempotency_key` é seguro nas duas dimensões. --- # Introdução O **servidor MCP do Faturamento Automático** é um servidor [Model Context Protocol](https://modelcontextprotocol.io) remoto que expõe as operações da API pública — clientes, assinaturas, faturas, pagamentos, notas fiscais, propostas e consumo — como **tools** que um cliente de IA pode chamar. Você o conecta por URL; não há nada para instalar. Ele é servido em host próprio, `mcp.billing.kobana.com.br`, com transporte **Streamable HTTP** em modo stateless e autenticação por **Bearer token**. Nenhum certificado de cliente está envolvido. :::info Disponibilidade O servidor e suas **293 tools** estão implementados, e a autenticação é pelo authorization server da Kobana: pelo fluxo **OAuth 2.1**, em que o cliente recebe só a URL e faz o login sozinho, ou por um **token pessoal** criado na sua conta Kobana. A borda dedicada (distribution `mcp.billing.*`, WAF e DNS) ainda está sendo provisionada. ::: ## Quando usar[​](#quando-usar "Link direto para Quando usar") | | API REST (`/v1`) | Servidor MCP (este) | | ------------ | ------------------------------- | ----------------------------------------------------- | | Consumidor | seu backend | um cliente de IA (Claude, ChatGPT, uma IDE) | | Configuração | token, fora de banda | uma URL | | Transporte | HTTPS/REST | Streamable HTTP (JSON-RPC 2.0) | | Autenticação | Bearer token emitido para a API | OAuth 2.1 ou token pessoal, sempre emitido para o MCP | | Superfície | 178 rotas | 293 tools sobre os mesmos endpoints | O servidor MCP **não substitui** a API REST. Cada tool despacha in-process para o endpoint que implementa a operação, então filtros, regras de upsert, validação, proração e isolamento por organização são exatamente os mesmos. Se você está escrevendo código, use a [API REST](https://docs.billing.kobana.com.br/pt/pt/api/overview/introduction.md). Se está conectando um assistente, use isto. ## O princípio[​](#o-princípio "Link direto para O princípio") **Uma capability só existe no MCP se existir na API pública.** Não há uma segunda implementação de nada. A tool chama o handler do endpoint com a identidade que o token do chamador já provou — a mesma pessoa, a mesma organização —, então ele roda como rodaria para qualquer requisição HTTP, e a auditoria que grava é atribuída a quem autorizou o cliente. Uma tool faz o que o endpoint faz por REST — nunca mais. A consequência prática: o que hoje só existe no dashboard não vira tool antes de virar endpoint. ## O que você vê é mais estreito que o catálogo[​](#o-que-você-vê-é-mais-estreito-que-o-catálogo "Link direto para O que você vê é mais estreito que o catálogo") `tools/list` devolve apenas as tools que **este chamador pode rodar**, filtradas pelas permissões de dashboard de quem autorizou o cliente. Um agente não é informado de capacidades que só levariam negativa. As regras estão em [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). ## Primeiros passos[​](#primeiros-passos "Link direto para Primeiros passos") 1. **Aponte seu cliente para a URL do servidor** — veja [Endpoints](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/endpoints.md) e [Clientes](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/clients.md). 2. **Autorize.** O cliente abre o login da Kobana; entre com uma conta da organização e autorize o acesso. Veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). 3. **Liste as tools** para confirmar o que o seu acesso alcança — peça ao assistente, ou, com um token emitido para o MCP em mãos: ``` curl https://mcp.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. **Explore a documentação** — o catálogo completo está em [Tools](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/overview.md). ## Próximos passos[​](#próximos-passos "Link direto para Próximos passos") * [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md) — o fluxo OAuth, o token pessoal, o escopo e as permissões aplicados, e os modos de falha. * [Endpoints](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/endpoints.md) — URLs por ambiente e rotas servidas. * [Transporte](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/transport.md) — JSON-RPC, cabeçalhos e métodos. * [Resources e prompts](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md) — documentos por URI, roteiros prontos, autocomplete e a confirmação de tools destrutivas. * [Clientes](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/clients.md) — como conectar Claude Code e clientes por arquivo. * [Listagem, ordenação e campos](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/pagination.md) — `page`, `sort_by`, `fields`. * [Erros](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/errors.md) — os dois canais de falha, e por que a distinção importa. * [Tools](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/overview.md) — o catálogo das 293 tools. --- # Listagem, Ordenação e Campos As tools `*_list` usam a mesma paginação da API REST: **por número de página**. | Argumento | Padrão | Máximo | | ---------- | ------ | ------ | | `page` | `1` | — | | `per_page` | `20` | `100` | ``` { "name": "billing_invoices_list", "arguments": { "status": "open", "page": 2, "per_page": 50 } } ``` O resultado traz o envelope de sempre: ``` { "data": [ /* ... */ ], "meta": { "total": 142, "page": 2, "per_page": 50, "total_pages": 3 } } ``` Quando `page > total_pages`, `data` volta vazio — não é erro. :::note Coleções que não paginam Algumas coleções são **conjuntos-filhos limitados por construção** (os itens de um plano, as tentativas de uma NF-e) ou listas de configuração pequenas. Essas respondem o conjunto inteiro e **não aceitam `page`** — e a tool correspondente também não oferece o argumento. Isso é intencional: uma tool que anunciasse `page` numa rota que o ignora faria o modelo paginar para sempre uma lista que não anda. ::: ## Ordenação[​](#ordenação "Link direto para Ordenação") | Argumento | Valores | Padrão | | ------------ | ------------------------------------------------------------ | ----------------- | | `sort_by` | Nome de coluna em **snake\_case** (`due_date`, `created_at`) | varia por recurso | | `sort_order` | `asc` ou `desc`, em qualquer caixa | varia por recurso | ``` { "name": "billing_invoices_list", "arguments": { "sort_by": "due_date", "sort_order": "asc" } } ``` Duas regras que valem conhecer, porque são diferentes entre si de propósito: * **Uma coluna que o recurso não ordena cai no padrão.** Ordenar por um campo inexistente é um pedido que o servidor não consegue atender, mas também não é motivo para derrubar a chamada inteira; `billing_schemas_get` lista os aceitos em `sortable_fields`. * **Uma direção que não é direção é `400`.** `sort_order: "descending"` é erro, não um `desc` silencioso — devolver a ordem certa por acidente esconderia o bug até o dia em que o acidente mudasse de lado. ## Campos (`fields`)[​](#campos-fields "Link direto para campos-fields") Toda tool de leitura aceita `fields`, um array de nomes de coluna. Omitido, volta o recurso inteiro; informado, volta só aquilo: ``` { "name": "billing_invoices_list", "arguments": { "status": "open", "fields": ["number", "total", "due_date"] } } ``` | Regra | Por quê | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **`id` sempre volta** | Uma projeção que você não consegue seguir não serve para nada, e derrubar o `id` em silêncio quebraria a chamada seguinte, não esta. | | **Só o nível de cima** | `fields: ["billing_account"]` devolve o objeto aninhado inteiro; não há sintaxe `billing_account.name`. | | **Só em leitura** | Um create responde com um envelope que o chamador não escolheu; projetá-lo esconderia metade do recibo de uma operação que já aconteceu. | | **Nome desconhecido é `400`** | Com a lista do que existe. Ignorar devolveria menos campos do que o pedido, parecendo que o recurso não os tem — resposta errada com cara de certa. | `fields` é a forma mais barata de reduzir o contexto que um agente gasta: a lista de 300 faturas com três colunas cabe onde a mesma lista completa não caberia. ## `billing_schemas_get` — o catálogo de campos[​](#billing_schemas_get--o-catálogo-de-campos "Link direto para billing_schemas_get--o-catálogo-de-campos") `fields` só serve se você souber o que pedir, e um modelo que precisa adivinhar vai tentar `invoice.amount` quando o contrato diz `total`. `billing_schemas_get` responde isso direto: ``` { "name": "billing_schemas_get", "arguments": {} } { "name": "billing_schemas_get", "arguments": { "resource": "invoice" } } ``` Sem argumento, devolve o catálogo dos recursos. Com `resource`, devolve todos os campos daquele recurso — nome, tipo, enum, se aceita nulo, descrição — e, separadamente, os `sortable_fields`. Ela vem dos mesmos schemas que geram o OpenAPI publicado, então a lista que a tool reporta e a que esta documentação publica não têm como divergir. ## Contrato de dados[​](#contrato-de-dados "Link direto para Contrato de dados") O que vale para a API v1 vale aqui, porque é o mesmo código: * **snake\_case em tudo**, argumentos e respostas. * **Dinheiro é float em BRL**, nos dois sentidos, sem sufixo de unidade. `amount: 100` é R$ 100,00; campos de precificação aceitam até 4 casas decimais. * **Datas em ISO 8601**, processadas em UTC. * **Escritas aceitam `idempotency_key`** — veja [Idempotência](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/idempotency.md). --- # Limite de Requisições O servidor MCP compartilha os **mesmos limites da API REST**, contados **por pessoa e organização** — o `sub` e o `org` do token, não o token em si. Trocar de token não zera o orçamento: um token novo, seja de uma nova autorização OAuth ou um novo token pessoal, da mesma pessoa na mesma organização cai no mesmo bucket. A mesma pessoa em outra organização tem orçamento próprio. Uma chamada de tool **nunca é mais barata que o endpoint que ela espelha**: a requisição é contada uma vez no bucket do próprio MCP e, quando é um `tools/call`, de novo pelo bucket do endpoint para onde ela despacha. Isso é deliberado — um agente que varre listagens em laço não deve conseguir contornar o limite que a mesma varredura pagaria por REST. Tentativas com token inválido são estranguladas **por IP**, não por token, do mesmo jeito que na borda REST: um token que não verifica não pode ter bucket próprio. Uma requisição sem token nenhum — o primeiro passo de todo cliente, antes do OAuth — não conta como tentativa. ## Quando o limite é atingido[​](#quando-o-limite-é-atingido "Link direto para Quando o limite é atingido") O servidor responde `429` — **a mensagem JSON-RPC não chega a ser processada**: ``` 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 } ``` Espere os segundos de `Retry-After` antes da próxima requisição. `X-RateLimit-Limit` e `X-RateLimit-Remaining` dizem o tamanho do bucket e o que sobrou; `X-RateLimit-Reset` é quando ele renova, em segundos desde a época Unix. Os limites por conta e por tipo de requisição estão na [página de limites da API](https://docs.billing.kobana.com.br/pt/pt/api/overview/rate-limit.md) — são os mesmos. ## Gastando menos[​](#gastando-menos "Link direto para Gastando menos") Um agente consome o mesmo orçamento que o seu backend, e ainda paga contexto por linha que traz. Dois hábitos resolvem quase tudo: * **Filtre antes de paginar.** `billing_invoices_list { status: "open", due_date_lte: "2026-09-30" }` custa uma requisição; varrer todas as faturas para filtrar no modelo custa dezenas. * **Peça só as colunas que interessam.** `fields: ["number", "total", "due_date"]` não reduz o número de requisições, mas reduz muito o contexto gasto — veja [Listagem, ordenação e campos](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/pagination.md). --- # Resources e prompts Além das tools, o servidor oferece três coisas que o **cliente** usa por conta própria: **resources** (documentos que o usuário anexa à conversa), **prompts** (roteiros prontos que o usuário escolhe) e **completions** (autocomplete dos argumentos dos dois). Na era `2026-07-28`, ele também pede **confirmação** antes de rodar uma tool destrutiva. Nada disso abre um caminho novo até os seus dados: tudo passa pelas mesmas tools, sob as mesmas permissões e o mesmo [escopo do token](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md#escopo-do-token). Com um token só de leitura, resources e completions continuam disponíveis, mas um prompt que escreve — como `collect_overdue_invoices`, que manda lembretes — não aparece. ## Resources[​](#resources "Link direto para Resources") Um resource é um documento identificado por uma URI. O usuário escolhe, por exemplo, uma fatura, e o cliente lê o documento e o põe no contexto, sem que o modelo precise chamar uma tool. | URI | O que volta | | ------------------------------------- | ---------------------------------------------------------------------- | | `kobana://billing/organization` | A organização do token (JSON) | | `kobana://billing/schemas` | O catálogo de recursos da API (JSON) | | `kobana://billing/schemas/{resource}` | Os campos de um recurso: tipo, enum, significado, quais ordenam (JSON) | | `kobana://billing/customers/{id}` | Um cliente (JSON) | | `kobana://billing/subscriptions/{id}` | Uma assinatura (JSON) | | `kobana://billing/invoices/{id}` | Uma fatura (JSON) | | `kobana://billing/invoices/{id}/pdf` | O PDF da fatura | | `kobana://billing/nfes/{id}` | Uma NF-e (JSON) | | `kobana://billing/nfes/{id}/pdf` | O DANFE da NF-e | | `kobana://billing/nfes/{id}/xml` | O XML autorizado da NF-e (texto) | `resources/list` traz as URIs fixas e `resources/templates/list` os templates com `{id}`. * **Permissões.** Cada resource é lido pela tool correspondente (`kobana://billing/invoices/{id}` é `billing_invoices_get`). Ele só aparece, e só é lido, se você pode rodar essa tool. * **Binários.** PDFs voltam em base64 (`blob`), até **10 MB**. Diferente das tools, que só descrevem o arquivo, aqui o documento é a resposta: foi o cliente que pediu por ele. * **Não encontrado.** URI desconhecida, ou registro que não existe nesta organização, é `-32002` na era 2025 e `-32602` na `2026-07-28` — veja [Erros](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/errors.md). * **Sem assinatura de mudanças.** O servidor é stateless: não há `resources/subscribe` nem aviso de lista alterada. ## Prompts[​](#prompts "Link direto para Prompts") Um prompt é uma instrução pronta que você escolhe no cliente e que vira a primeira mensagem da conversa. Ele só aparece se você pode rodar **todas** as tools em que se apoia. | Prompt | Argumentos | O que faz | | -------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `collect_overdue_invoices` | `customer_id` (opcional) | Lista as faturas em aberto vencidas, mostra uma tabela e **pergunta** quais devem receber lembrete antes de enviar. | | `review_pending_nfes` | — | Junta as faturas que ainda não têm NF-e e as NF-e rejeitadas, resume e sugere o próximo passo, sem emitir nada. | | `customer_overview` | `customer_id` | O retrato de um cliente: dados, assinaturas, o que está em aberto e o que está vencido. | | `monthly_billing_summary` | `month` (opcional, `YYYY-MM`) | O que foi faturado, recebido e ficou em aberto no mês. | Argumento obrigatório ausente, ou `month` fora do formato, é `-32602`. ## Completions[​](#completions "Link direto para Completions") `completion/complete` sugere valores enquanto você digita um argumento: * **Ids** (`customer_id`, o `{id}` de clientes, faturas e assinaturas): busca na listagem correspondente, sob a mesma permissão dela. Se você não pode listar, não há sugestão. * **`{resource}` de `kobana://billing/schemas/{resource}`**: os nomes do catálogo, pelo prefixo. * **`month`**: os últimos doze meses. Sem fonte de sugestão, a resposta é uma lista vazia, e você continua digitando. ## Confirmação de tools destrutivas[​](#confirmação-de-tools-destrutivas "Link direto para Confirmação de tools destrutivas") Tools destrutivas — as que apagam, anulam, cancelam ou arquivam em massa; cobram, pagam, estornam, marcam como pago ou aplicam crédito; emitem ou cancelam nota fiscal; enviam e-mail, convite, lembrete ou proposta, ou publicam um link público; ou mudam a conta e a chave Pix de recebimento — são marcadas com `destructiveHint`. O **servidor** não confia só no cliente: na era `2026-07-28` ele mesmo pede a confirmação: 1. O primeiro `tools/call` não roda nada. Ele volta `resultType: "input_required"` com um formulário de uma pergunta: rodar esta ação, com estes argumentos? 2. O cliente mostra a pergunta e reenvia a mesma chamada com a sua resposta. 3. Só um **sim** explícito executa. Recusar ou cancelar volta um resultado `isError` com `USER_DECLINED`, e nada muda. A confirmação vale **só para aquela chamada**: a mesma tool, os mesmos argumentos, a mesma pessoa e organização, por **5 minutos**. Uma resposta não pode ser reaproveitada para outra fatura ou outra ação; se algo não bater, o servidor simplesmente pergunta de novo. E ela é de **uso único**: reenviar uma chamada já confirmada volta `isError` com `confirmation_replayed`, sem executar nada — para repetir a ação, chame a tool de novo e confirme outra vez. ### Cliente sem formulário de confirmação: aprovação por link[​](#cliente-sem-formulário-de-confirmação-aprovação-por-link "Link direto para Cliente sem formulário de confirmação: aprovação por link") Um cliente que **não consegue confirmar no chat** — na era 2025, ou na `2026-07-28` sem declarar suporte a formulários de elicitation (o app do Claude no celular, por exemplo) — também usa as tools destrutivas, mas por um **link de aprovação**. A chamada **não executa nada**: o servidor guarda a operação como pendente e responde com sucesso, num ú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. O assistente mostra a URL. Não chame a tool de novo: isso criaria outra aprovação. 2. Você abre o link **logado no Faturamento Automático** (sem sessão, ele passa pelo login e volta ao link). A tela mostra o que vai acontecer ("Pagar a fatura", "Excluir o cliente"), quem pediu, quando, a organização, os dados atuais do registro e **todos** os argumentos — os itens de um lote, um a um. Os argumentos crus ficam em "Detalhes técnicos". 3. **Continuar** executa a operação na hora, com as permissões que você tem **agora**: se perdeu a permissão desde o pedido, a execução falha e nada muda. **Cancelar** encerra sem executar nada. O link vale **15 minutos** e decide **uma vez só**: dois cliques em Continuar executam uma vez, e um link vencido ou cancelado não executa. Só **você** — a pessoa por trás do token que fez a chamada — abre o link: para qualquer outra pessoa, mesmo da sua organização, ele não existe. Suas aprovações ficam em **Sistema → Aprovações** no painel, com abas por situação; clicar numa linha abre a aprovação só para leitura (uma pendente se decide pelo link que o assistente mostrou). #### Depois da decisão: o resultado no próprio chat[​](#depois-da-decisão-o-resultado-no-próprio-chat "Link direto para Depois da decisão: o resultado no próprio chat") A mesma sessão que pediu a operação consulta o que aconteceu, sem você copiar nada da tela. Depois que você disser ao assistente que decidiu, ele chama **uma vez** `billing_operation_approvals_get` com o `approval.id` da resposta — sem ficar consultando em loop enquanto você não decide: ``` { "data": { "id": "6f0c2d1e-…", "status": "executed", "action": "billing_invoices_pay", "title": "Pagar a fatura", "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` | O que significa | | ---------- | ----------------------------------------------------------------------------------------------------------------------- | | `pending` | Ainda não decidida. | | `approved` | Você escolheu Continuar e a execução está em andamento. | | `executed` | Executada: `result` traz o que a tool devolveu, com segredos mascarados (o valor em claro aparece uma vez só, na tela). | | `failed` | Não executou; `error.code` diz por quê (`subject_changed`, falta de permissão…). Nada foi alterado por ela. | | `declined` | Você cancelou. Nada foi executado. | | `expired` | O link venceu sem decisão. Nada foi executado. | `billing_operation_approvals_list` lista as suas aprovações, da mais recente para a mais antiga, com filtro por `status` e por `created_after`/`created_before`. As duas tools são só leitura — nenhuma aprova, cancela ou reabre uma aprovação — e não pedem escopo nem permissão: qualquer token com pessoa lê as **próprias** aprovações naquela organização. A de outra pessoa, de outra organização ou um id que não existe respondem o mesmo `NOT_FOUND`. O retorno da operação (`result`, `error` e um `amount` lido do registro) só vem quando o token também lê o recurso daquela aprovação e você ainda tem permissão de leitura dele: um token restrito a produtos vê a sua aprovação sobre uma fatura — situação, título, datas —, mas com esses campos `null` e `result_hidden: true`. O `title` sai no idioma do pedido (`Accept-Language`), e a resposta nunca traz o link nem os argumentos. Na API REST, o mesmo está em `GET /v1/operation_approvals` e `GET /v1/operation_approvals/{id}`. Se a fatura, o pagamento, a conta ou a chave de destino mudar entre a abertura da tela e o Continuar, nada executa (`subject_changed`): peça a operação de novo e revise o novo link. Dados de cartão em claro (número ou CVV) nunca ficam guardados esperando aprovação: a chamada volta `confirmation_required` — use um `card_token` ou um cliente com formulário de confirmação. Um token sem pessoa que possa abrir o link volta `isError` com `confirmation_required`. Se o servidor não consegue registrar a aprovação naquele momento, a tool é recusada com `confirmation_unavailable`; tente de novo depois. As demais tools seguem funcionando normalmente. --- # Transporte **Streamable HTTP, stateless.** Uma mensagem JSON-RPC 2.0 por `POST`, uma resposta JSON. Não há `Mcp-Session-Id`, não há resumabilidade e não há stream servidor→cliente: a aplicação roda várias réplicas, e toda operação longa já responde de imediato e termina num worker em segundo plano, não no canal MCP. ## Versões do protocolo[​](#versões-do-protocolo "Link direto para Versões do protocolo") O servidor fala duas eras do protocolo no mesmo endpoint: | Versão | Era | Status | | ------------ | ------------------------------------------------------------------------------ | --------- | | `2026-07-28` | Stateless, sem handshake — descoberta por `server/discover` | Suportada | | `2025-06-18` | Handshake por `initialize` — é a versão em que o `initialize` fecha por padrão | Suportada | | `2025-03-26` | Handshake por `initialize` | Suportada | A era é decidida **pelo corpo** da requisição, com os cabeçalhos como conferência: * **`params._meta` traz `io.modelcontextprotocol/protocolVersion`** → era `2026-07-28` (veja abaixo). * **Sem esse envelope**, com `MCP-Protocol-Version` de 2025 ou sem o cabeçalho → era 2025, com `initialize`. * **`MCP-Protocol-Version: 2026-07-28` sem o envelope** → `400` com `-32602`. O servidor não cai para a era antiga em silêncio: você pediu a semântica stateless e receberia a outra. Uma versão que o servidor não fala — no cabeçalho ou no envelope, em qualquer era — é respondida com `400` e o erro JSON-RPC `-32022`, listando as suportadas: ``` { "jsonrpc": "2.0", "id": 1, "error": { "code": -32022, "message": "Unsupported protocol version", "data": { "supported": ["2026-07-28", "2025-06-18", "2025-03-26"], "requested": "1999-01-01" } } } ``` A versão em uso volta no cabeçalho `MCP-Protocol-Version` da resposta. ### Era `2026-07-28`[​](#era-2026-07-28 "Link direto para era-2026-07-28") Não há handshake: **toda** requisição carrega a própria versão e as capacidades do cliente em `params._meta`, e o servidor não lembra nada entre uma requisição e outra. | Chave de `params._meta` | Obrigatória | Significado | | -------------------------------------------- | ----------- | ---------------------------------------------- | | `io.modelcontextprotocol/protocolVersion` | sim | `2026-07-28` | | `io.modelcontextprotocol/clientCapabilities` | sim | Capacidades do cliente (um objeto; `{}` serve) | | `io.modelcontextprotocol/clientInfo` | recomendada | `name` e `version` do cliente | Os cabeçalhos repetem o que está no corpo, para que intermediários possam rotear sem lê-lo — e por isso têm que concordar com ele: | Cabeçalho | Tem que ser igual a | | ---------------------- | --------------------------------------------------------------- | | `MCP-Protocol-Version` | A versão do envelope | | `Mcp-Method` | O `method` da mensagem | | `Mcp-Name` | Só no `tools/call`: o `params.name`, cru ou como `=?base64?…?=` | Qualquer divergência é `400` com `-32020` (`Header mismatch: …`). Faltar `clientCapabilities` é `400` com `-32602`. Os resultados dessa era sempre trazem `resultType: "complete"` e o servidor em `_meta["io.modelcontextprotocol/serverInfo"]`. `server/discover`, `tools/list`, `resources/list`, `resources/templates/list`, `resources/read` e `prompts/list` trazem também `ttlMs: 0` e `cacheScope: "private"`: o que volta é filtrado pelas permissões de quem chama, então não deve ser reaproveitado nem compartilhado. Um `tools/call` de tool destrutiva pode voltar `resultType: "input_required"` — veja [Confirmação de tools destrutivas](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md#confirma%C3%A7%C3%A3o-de-tools-destrutivas). ## Cabeçalhos da requisição[​](#cabeçalhos-da-requisição "Link direto para Cabeçalhos da requisição") | Cabeçalho | Obrigatório | Significado | | ---------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | sim | `Bearer ` emitido para o MCP — veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md) | | `Content-Type` | sim | `application/json` | | `Accept` | recomendado | `application/json` | | `MCP-Protocol-Version` | sim na era `2026-07-28`; recomendado na de 2025 | Revisão do protocolo | | `Mcp-Method` | sim na era `2026-07-28` | O método da mensagem | | `Mcp-Name` | sim no `tools/call` da era `2026-07-28` | O nome da tool | | `Origin` | condicional | Mandado por clientes de navegador; validado contra uma allowlist | Não há cabeçalho de seleção de tenant: a organização vem do próprio token, e nenhuma tool aceita um argumento de organização. O corpo da requisição tem limite de **1 MB**. Acima disso — pelo `Content-Length` declarado ou pelo que de fato chega — a resposta é `413` com `{ "jsonrpc": "2.0", "id": null, "error": { "code": -32600, "message": "Request body too large (limit 1048576 bytes)" } }`. Nenhuma tool recebe arquivo, então uma chamada legítima fica muito abaixo disso. ## Cabeçalhos da resposta[​](#cabeçalhos-da-resposta "Link direto para Cabeçalhos da resposta") | Cabeçalho | Significado | | ---------------------- | --------------------------------------------------------------------------------------------------------------- | | `MCP-Protocol-Version` | Revisão em uso | | `Cache-Control` | Sempre `no-store` | | `Retry-After` | Só em `429` — veja [Limite de requisições](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/rate-limit.md) | ## Métodos[​](#métodos "Link direto para Métodos") | Método | Era `2026-07-28` | Era 2025 | Para quê | | -------------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------ | | `server/discover` | sim | — | Versões suportadas, capacidades do servidor e instruções | | `initialize` | — | sim | Negociação de versão, capacidades do servidor e instruções | | `ping` | — | sim | Teste de vida; responde um resultado vazio | | `tools/list` | sim | sim | As tools que este chamador pode rodar, com JSON Schema e anotações | | `tools/call` | sim | sim | Roda uma tool | | `resources/list` | sim | sim | Os documentos de URI fixa que este chamador pode ler | | `resources/templates/list` | sim | sim | Os templates de URI (`kobana://billing/invoices/{id}`, …) que este chamador pode ler | | `resources/read` | sim | sim | Lê um documento pela URI | | `prompts/list` | sim | sim | Os roteiros prontos que este chamador pode usar | | `prompts/get` | sim | sim | Monta um roteiro com os argumentos dados | | `completion/complete` | sim | sim | Sugestões para um argumento de prompt ou de template | Resources, prompts e completions estão em [Resources e prompts](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md). Qualquer outro método é `-32601 Method not found` — na era `2026-07-28`, com HTTP `404`; na de 2025, no corpo de um `200`. **Batching JSON-RPC não é suportado** — foi removido na revisão `2025-06-18`, e um corpo em array é respondido com `400`. Uma **notificação** (mensagem sem `id`, como `notifications/initialized`) é aceita com `202` e corpo vazio, nas duas eras. A autenticação vem **antes** de qualquer método, inclusive do `server/discover`: sem token, a resposta é o `401` com o desafio que leva o cliente ao login OAuth — veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). ### `server/discover` (era `2026-07-28`)[​](#serverdiscover-era-2026-07-28 "Link direto para serverdiscover-era-2026-07-28") ``` POST / HTTP/1.1 Authorization: Bearer Content-Type: application/json MCP-Protocol-Version: 2026-07-28 Mcp-Method: server/discover ``` ``` { "jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {}, "io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0.0" } } } } ``` ``` { "jsonrpc": "2.0", "id": 1, "result": { "resultType": "complete", "supportedVersions": ["2026-07-28", "2025-06-18", "2025-03-26"], "capabilities": { "tools": {}, "resources": {}, "prompts": {}, "completions": {} }, "instructions": "Tools for Kobana Billing: ...", "ttlMs": 0, "cacheScope": "private", "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "kobana-billing", "title": "Kobana Billing", "version": "1.0.0" } } } } ``` ### `initialize` (handshake da era 2025)[​](#initialize-handshake-da-era-2025 "Link direto para initialize-handshake-da-era-2025") ``` { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18" } } ``` ``` { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-06-18", "capabilities": { "tools": { "listChanged": false }, "resources": { "subscribe": false, "listChanged": false }, "prompts": { "listChanged": false }, "completions": {} }, "serverInfo": { "name": "kobana-billing", "title": "Kobana Billing", "version": "1.0.0" }, "instructions": "Tools for Kobana Billing: ..." } } ``` ### `tools/list`[​](#toolslist "Link direto para toolslist") Devolve **apenas** as tools que o chamador pode rodar, filtradas pelas permissões de dashboard de quem autorizou o cliente. Cada tool carrega `annotations`, que é o que faz o cliente pedir confirmação ao usuário: | Anotação | Significado | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `readOnlyHint` | A tool só lê | | `destructiveHint` | A tool apaga, cancela, cobra, estorna, emite nota fiscal ou envia algo a terceiros. O servidor pede confirmação no chat na era `2026-07-28` com elicitation; a qualquer outro cliente responde um link de aprovação, e nada roda até você escolher Continuar | | `idempotentHint` | Repetir a chamada tem o mesmo efeito | | `openWorldHint` | Sempre `false` — a tool não alcança nada fora do Faturamento Automático | ### `tools/call`[​](#toolscall "Link direto para 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"] } } } ``` O resultado traz a resposta JSON do endpoint como conteúdo de texto: ``` { "jsonrpc": "2.0", "id": 2, "result": { "content": [{ "type": "text", "text": "{ \"data\": [ ... ], \"meta\": { \"total\": 42, ... } }" }] } } ``` Erros sobre os quais o chamador pode agir voltam com `isError: true` **dentro** do resultado, não como erro JSON-RPC — veja [Erros](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/errors.md). ## Despacho in-process[​](#despacho-in-process "Link direto para Despacho in-process") Cada tool despacha **in-process** para o handler de `/api/v1` que implementa a operação. Não há segunda viagem HTTP nem segunda implementação: filtros de listagem, regras de upsert, validação, soft-delete, cálculo de proração e isolamento por organização são o mesmo código que a API REST roda. Uma tool não tem como divergir do endpoint que espelha. ## Binários[​](#binários "Link direto para Binários") `billing_invoices_pdf`, `billing_nfes_pdf` e `billing_nfes_xml` **não** devolvem os bytes: um PDF em base64 no contexto de um modelo é caro e inútil. O resultado traz o `content_type`, o tamanho e o caminho para buscar o arquivo no host da API, com um token emitido para a API. --- # Catálogo O que a organização vende: produtos e seus grupos, planos, preços e itens de serviço avulsos. ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | ------------------------------------------ | ----- | ---- | ----- | ----------- | | `products` — Produtos e grupos de produtos | 24 | 4 | 16 | 4 | | `plans` — Planos, preços e grupos | 21 | 5 | 12 | 4 | | `services` — Itens de serviço | 6 | 2 | 3 | 1 | ## `products`[​](#products "Link direto para products") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | -------------------------------------- | ----------- | -------- | ----------------- | --------------------------------------- | -------------------------------------------------------------------------------------- | | `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 "Link direto para plans") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ------------------------------- | ----------- | -------- | -------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `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 "Link direto para services") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ------------------------------ | ----------- | -------- | ----------------- | ------------------------------ | -------------------------------------------------------------------------------------------- | | `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. | *** Os campos de cada recurso estão na [Referência da API](https://docs.billing.kobana.com.br/pt/pt/api/v1) e em `billing_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Clientes e acessos Clientes, suas contas de cobrança, os usuários que entram no portal e o time que usa o dashboard da organização. ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | ------------------------------------------- | ----- | ---- | ----- | ----------- | | `customers` — Clientes e contas de cobrança | 19 | 6 | 9 | 4 | | `portal-users` — Usuários do portal | 9 | 4 | 2 | 3 | | `users` — Usuários do dashboard | 6 | 2 | 1 | 3 | | `roles` — Papéis do time | 6 | 2 | 3 | 1 | ## `customers`[​](#customers "Link direto para customers") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | --------------------------------------- | ----------- | -------- | ---------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Link direto para portal-users") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | -------------------------------------- | ----------- | -------- | --------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `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 "Link direto para users") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | -------------------------------- | ----------- | -------- | -------------- | -------------------------------- | ---------------------------------------------------------------------------- | | `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 "Link direto para roles") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | --------------------------- | ----------- | -------- | -------------- | --------------------------- | --------------------------------------------------------------------- | | `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. | *** Os campos de cada recurso estão na [Referência da API](https://docs.billing.kobana.com.br/pt/pt/api/v1) e em `billing_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Fiscal Emissão de NF-e, as empresas emissoras e seus certificados digitais, regras e períodos de apuração de impostos e as retenções na fonte. ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | -------------------------------------- | ----- | ---- | ----- | ----------- | | `nfes` — Notas fiscais (NF-e) | 24 | 8 | 10 | 6 | | `companies` — Empresas emissoras | 12 | 4 | 6 | 2 | | `certificates` — Certificados digitais | 3 | 2 | 0 | 1 | | `tax-rules` — Regras fiscais | 6 | 2 | 3 | 1 | | `tax-periods` — Períodos de apuração | 5 | 2 | 2 | 1 | | `withholdings` — Retenções | 8 | 2 | 3 | 3 | ## `nfes`[​](#nfes "Link direto para nfes") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | -------------------------------- | ----------- | -------- | ------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `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 "Link direto para companies") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ----------------------------------------- | ----------- | -------- | ------------------ | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `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 "Link direto para certificates") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ----------------------------- | ----------- | -------- | --------------------- | ----------------------------- | ------------------------------------------------------------------ | | `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 "Link direto para tax-rules") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | -------------------------- | ----------- | -------- | ------------------ | -------------------------- | ------------------------------------------------------------ | | `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 "Link direto para tax-periods") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ----------------------------------- | ----------- | -------- | -------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------- | | `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 "Link direto para withholdings") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ----------------------------------------- | ----------- | -------- | --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `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. | *** Os campos de cada recurso estão na [Referência da API](https://docs.billing.kobana.com.br/pt/pt/api/v1) e em `billing_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Faturas e recebimentos Faturas e seus itens, pagamentos e métodos de pagamento, as contas bancárias e chaves Pix que recebem cobranças por transferência, créditos aplicados na conta e cupons de desconto. ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | ------------------------------------------------------- | ----- | ---- | ----- | ----------- | | `invoices` — Faturas | 23 | 8 | 5 | 10 | | `payments` — Pagamentos e métodos de pagamento | 19 | 4 | 6 | 9 | | `transfer-destinations` — Contas bancárias e chaves Pix | 11 | 5 | 0 | 6 | | `credits` — Créditos | 7 | 3 | 1 | 3 | | `coupons` — Cupons e códigos de desconto | 8 | 3 | 4 | 1 | ## `invoices`[​](#invoices "Link direto para invoices") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ----------------------------------------- | ----------- | -------- | ----------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Link direto para payments") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | -------------------------------------- | ----------- | -------- | ----------------- | ------------------------------------------ | ------------------------------------------------------------------- | | `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 "Link direto para transfer-destinations") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ------------------------------ | ----------- | ------------------------ | ----------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- | | `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 "Link direto para credits") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ---------------------------------- | ----------- | -------- | ---------------- | -------------------------------------- | ---------------------------------------------------------- | | `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 "Link direto para coupons") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ----------------------------- | ----------- | -------- | ---------------- | --------------------------------- | ----------------------------------------------------------------------- | | `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. | *** Os campos de cada recurso estão na [Referência da API](https://docs.billing.kobana.com.br/pt/pt/api/v1) e em `billing_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Organização e schemas O perfil da própria organização, `billing_schemas_get` — o catálogo de campos que diz o que pedir em `fields` e em `sort_by` — e as suas aprovações por link: `billing_operation_approvals_get` diz o que aconteceu com uma operação destrutiva depois que você decidiu na tela de aprovação. ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | ------------------------------------------- | ----- | ---- | ----- | ----------- | | `settings` — Organização e schemas | 4 | 3 | 1 | 0 | | `operation-approvals` — Aprovações por link | 2 | 2 | 0 | 0 | ## `settings`[​](#settings "Link direto para settings") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ----------------------------- | ----- | ---------- | -------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `billing_me` | read | — (nenhum) | — (só vínculo ativo) | `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 "Link direto para operation-approvals") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ---------------------------------- | ---- | ---------- | -------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `billing_operation_approvals_get` | read | — (nenhum) | — (só vínculo ativo) | `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 | — (nenhum) | — (só vínculo ativo) | `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`). | *** Os campos de cada recurso estão na [Referência da API](https://docs.billing.kobana.com.br/pt/pt/api/v1) e em `billing_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Tools O servidor expõe **296 tools** sobre **26 famílias de recurso**. Cada uma despacha in-process para o endpoint de `/v1` que já implementa a operação, então filtros, validação, regras de upsert e isolamento por organização são exatamente os da API REST — a tool *é* o endpoint. A única exceção, `billing_schemas_get`, responde localmente e está marcada como tal. ## Como ler estas páginas[​](#como-ler-estas-páginas "Link direto para Como ler estas páginas") Cada tool aparece com cinco fatos, nesta ordem: > `billing_invoices_void` · **destructive** · escopo `write` · recurso `invoices` · permissão `invoices.void` · `POST /v1/invoices/:id/void` | Campo | Significado | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **read** / **write** / **destructive** | A anotação que o cliente MCP lê. Uma `destructive` (exclui, anula, cancela, cobra, paga, estorna, aplica crédito, emite ou cancela nota fiscal, envia e-mail, convite ou link público) só roda depois de o usuário confirmar: no formulário que o servidor envia, na revisão 2026-07-28 com elicitation, ou por um link de aprovação que ele abre logado no painel, nos demais clientes ([Confirmação de tools destrutivas](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/resources-and-prompts.md#confirma%C3%A7%C3%A3o-de-tools-destrutivas)). | | **escopo** | O verbo de escopo que o token precisa carregar para a tool: `read`, `write`, `delete` (as tools `*_delete`) ou `import` (`billing_nfes_import_barueri`). Um não substitui o outro — veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). Marcada `billing/all`, a tool chama um endpoint fora do catálogo de recursos (contas bancárias, bancos, chaves Pix) e só um token com `billing/all` a alcança. Como o AS não concede `billing/all` a cliente OAuth e recusa verbo junto de `billing/all` no token pessoal, essas tools são, pelo MCP, só leitura e só por token pessoal: as que escrevem ou excluem não rodam hoje. | | **recurso** | A família de recurso da tool — o que agrupa as tools nesta documentação. | | **permissão** | A permissão de dashboard que a pessoa que autorizou o cliente precisa ter na organização. `billing_me` e as tools `billing_operation_approvals_*` (que leem as aprovações da própria pessoa) não exigem nenhuma — só um vínculo ativo. | | **`MÉTODO /caminho`** | O endpoint de `/v1` para onde a tool despacha, para cruzar com a [Referência da API](https://docs.billing.kobana.com.br/pt/pt/api/v1). | ## Argumentos comuns[​](#argumentos-comuns "Link direto para Argumentos comuns") Estes aparecem em muitas tools e significam sempre a mesma coisa. | Argumento | Tipo | Descrição | | ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | inteiro | Página, a partir de 1. Padrão `1`. | | `per_page` | inteiro | Itens por página. Padrão `20`, máximo `100`. | | `sort_by` | string | Coluna de ordenação, em snake\_case. Os aceitos estão em `billing_schemas_get`. | | `sort_order` | `asc` \| `desc` | Direção. Um valor que não é direção é erro, não um `desc` silencioso. | | `fields` | string\[] | Colunas a devolver. Omitido, volta o recurso inteiro; `id` sempre volta. | | `filters` | object | Filtros adicionais, repassados ao endpoint. Não aceita paginação, ordenação (`page`, `per_page`, `sort_by`, `sort_order`, `limit`, `cursor`, `sort`) nem um filtro que a tool já nomeia — esses vão como argumento nomeado; dentro de `filters` são recusados com `VALIDATION_ERROR`. | | `idempotency_key` | string | Proteção contra replay, enviada como `X-Idempotency-Key`. | | `custom_metadata` | object | JSON livre seu, devolvido em toda leitura e em todo webhook. | ## O catálogo[​](#o-catálogo "Link direto para O catálogo") | Família | Tools | read | write | destructive | | ------------------------------------------------------------------------------------------------------------------------- | ----- | ---- | ----- | ----------- | | [`certificates` — Certificados digitais](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/fiscal.md) | 3 | 2 | 0 | 1 | | [`companies` — Empresas emissoras](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/fiscal.md) | 12 | 4 | 6 | 2 | | [`coupons` — Cupons e códigos de desconto](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/invoices.md) | 8 | 3 | 4 | 1 | | [`credits` — Créditos](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/invoices.md) | 7 | 3 | 1 | 3 | | [`customers` — Clientes e contas de cobrança](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/customers.md) | 19 | 6 | 9 | 4 | | [`invoices` — Faturas](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/invoices.md) | 23 | 8 | 5 | 10 | | [`nfes` — Notas fiscais (NF-e)](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/fiscal.md) | 24 | 8 | 10 | 6 | | [`operation-approvals` — Aprovações por link](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/organization.md) | 2 | 2 | 0 | 0 | | [`payments` — Pagamentos e métodos de pagamento](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/invoices.md) | 19 | 4 | 6 | 9 | | [`plan-changes` — Mudanças de plano](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/subscriptions.md) | 11 | 6 | 3 | 2 | | [`plans` — Planos, preços e grupos](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/catalog.md) | 21 | 5 | 12 | 4 | | [`portal-users` — Usuários do portal](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/customers.md) | 9 | 4 | 2 | 3 | | [`products` — Produtos e grupos de produtos](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/catalog.md) | 24 | 4 | 16 | 4 | | [`proposals` — Propostas](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/proposals.md) | 25 | 7 | 7 | 11 | | [`roles` — Papéis do time](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/customers.md) | 6 | 2 | 3 | 1 | | [`services` — Itens de serviço](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/catalog.md) | 6 | 2 | 3 | 1 | | [`settings` — Organização e schemas](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/organization.md) | 4 | 3 | 1 | 0 | | [`subscription-changes` — Mudanças de assinatura](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/subscriptions.md) | 5 | 3 | 1 | 1 | | [`subscriptions` — Assinaturas](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/subscriptions.md) | 16 | 4 | 6 | 6 | | [`tax-periods` — Períodos de apuração](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/fiscal.md) | 5 | 2 | 2 | 1 | | [`tax-rules` — Regras fiscais](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/fiscal.md) | 6 | 2 | 3 | 1 | | [`templates` — Templates de proposta](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/proposals.md) | 9 | 2 | 6 | 1 | | [`transfer-destinations` — Contas bancárias e chaves Pix](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/invoices.md) | 11 | 5 | 0 | 6 | | [`usage` — Consumo medido](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/usage.md) | 7 | 4 | 3 | 0 | | [`users` — Usuários do dashboard](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/customers.md) | 6 | 2 | 1 | 3 | | [`withholdings` — Retenções](https://docs.billing.kobana.com.br/pt/pt/mcp/tools/fiscal.md) | 8 | 2 | 3 | 3 | Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Propostas Propostas comerciais — do rascunho ao aceite, com a assinatura que vira assinatura — e os templates a partir dos quais elas são renderizadas. ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | ----------------------------------- | ----- | ---- | ----- | ----------- | | `proposals` — Propostas | 25 | 7 | 7 | 11 | | `templates` — Templates de proposta | 9 | 2 | 6 | 1 | ## `proposals`[​](#proposals "Link direto para proposals") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | -------------------------------- | ----------- | -------- | ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Link direto para templates") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | --------------------------------------- | ----------- | -------- | ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------ | | `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. | *** Os campos de cada recurso estão na [Referência da API](https://docs.billing.kobana.com.br/pt/pt/api/v1) e em `billing_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Assinaturas O ciclo de vida da assinatura — trial, ativação, pausa, cancelamento — e as mudanças de plano, com a proração que cada uma gera. ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | ----------------------------------------------- | ----- | ---- | ----- | ----------- | | `subscriptions` — Assinaturas | 16 | 4 | 6 | 6 | | `plan-changes` — Mudanças de plano | 11 | 6 | 3 | 2 | | `subscription-changes` — Mudanças de assinatura | 5 | 3 | 1 | 1 | ## `subscriptions`[​](#subscriptions "Link direto para subscriptions") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ------------------------------------------- | ----------- | -------- | ---------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `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 "Link direto para plan-changes") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ------------------------------------ | ----------- | -------- | ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `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 "Link direto para subscription-changes") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | -------------------------------------------- | ----------- | ------- | ----------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | *** Os campos de cada recurso estão na [Referência da API](https://docs.billing.kobana.com.br/pt/pt/api/v1) e em `billing_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- # Consumo Consumo medido para cobrança por uso: registros crus, o resumo agregado por item de assinatura e os snapshots diários e mensais. ## Famílias nesta página[​](#famílias-nesta-página "Link direto para Famílias nesta página") | Família | Tools | read | write | destructive | | ------------------------ | ----- | ---- | ----- | ----------- | | `usage` — Consumo medido | 7 | 4 | 3 | 0 | ## `usage`[​](#usage "Link direto para usage") | Tool | Tipo | Escopo | Permissão | Endpoint | O que faz | | ---------------------------------------- | ----- | ------- | ------------ | ---------------------------------- | -------------------------------------------------------------------------------------------- | | `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`. | *** Os campos de cada recurso estão na [Referência da API](https://docs.billing.kobana.com.br/pt/pt/api/v1) e em `billing_schemas_get`. Uma tool que você não pode rodar não aparece em `tools/list`. Se uma daqui não está lá, veja [Autenticação](https://docs.billing.kobana.com.br/pt/pt/mcp/overview/authentication.md). --- ## [📄️Certificados Digitais](https://docs.billing.kobana.com.br/pt/pt/nota-fiscal/certificados.md) [A página /dashboard/certificates gerencia os certificados digitais A1 usados para assinar NF-e e se autenticar nos webservices das prefeituras. Cada certificado é vinculado a uma empresa cadastrada e fica armazenado de forma criptografada em repouso.](https://docs.billing.kobana.com.br/pt/pt/nota-fiscal/certificados.md) --- ## [📄️Certificados Digitais](https://docs.billing.kobana.com.br/pt/pt/nota-fiscal/certificados.md) [A página /dashboard/certificates gerencia os certificados digitais A1 usados para assinar NF-e e se autenticar nos webservices das prefeituras. Cada certificado é vinculado a uma empresa cadastrada e fica armazenado de forma criptografada em repouso.](https://docs.billing.kobana.com.br/pt/pt/nota-fiscal/certificados.md) --- # Certificados Digitais A página `/dashboard/certificates` gerencia os **certificados digitais A1** usados para assinar NF-e e se autenticar nos webservices das prefeituras. Cada certificado é vinculado a uma empresa cadastrada e fica armazenado de forma criptografada em repouso. ## Como funciona[​](#como-funciona "Link direto para Como funciona") 1. **Upload do arquivo `.pfx`** — o operador envia o certificado e informa a senha. 2. **Validação automática** — o sistema verifica CNPJ, validade e cadeia de certificação. 3. **Armazenamento criptografado** — o conteúdo do `.pfx` e a senha são cifrados com AES-256-GCM antes de ir para o banco. 4. **Vinculação à empresa** — uma empresa pode ter apenas um certificado ativo por vez. ## Informações exibidas[​](#informações-exibidas "Link direto para Informações exibidas") * **Empresa associada** e **CNPJ** * **Validade** — data de expiração e aviso quando faltam menos de 30 dias * **Emissor** — Autoridade Certificadora que emitiu (Serasa, Certisign, Soluti, etc.) * **Status** — `active`, `expired` ou `revoked` * **Última utilização** — data da última NF-e assinada ## Alertas e renovação[​](#alertas-e-renovação "Link direto para Alertas e renovação") O sistema notifica administradores quando um certificado se aproxima da expiração. Após expirar, o provedor de NF-e deixa de aceitar a assinatura e novas emissões falham até que um certificado novo seja enviado. A renovação substitui o arquivo sem perder o histórico de NF-e emitidas com o certificado anterior. ## Segurança[​](#segurança "Link direto para Segurança") * Senhas e bytes do `.pfx` são cifrados em repouso (ver `lib/crypto.ts`). * O acesso à página é restrito a membros com a permissão fiscal apropriada. * Toda criação, substituição ou remoção gera entrada em [Auditoria](https://docs.billing.kobana.com.br/pt/pt/configuracoes/auditoria.md). ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Lista de certificados digitais com empresa, validade e status](/pt/assets/images/certificados-3cf5519adb195dae24055cc52cbb32e6.png) --- # Configuração de NF-e Cada organização pode habilitar e configurar a emissão automática de notas fiscais. ## Campos de Configuração[​](#campos-de-configuração "Link direto para Campos de Configuração") | Campo | Descrição | | ---------------------------------------- | ----------------------------------------- | | **Provedor** | `mock`, `nfe_io` ou `kobana` | | **Ambiente** | `sandbox` ou `production` | | **Habilitado** | Se a emissão de NF-e está ativa | | **Política de emissão** | Quando a NF-e é emitida automaticamente | | **Chave da API NFe.io** | Chave de autenticação (criptografada) | | **Empresas NFe.io** | Cache de empresas cadastradas no provedor | | **Descrição do serviço** | Descrição padrão adicionada às notas | | **Máximo de tentativas de emissão** | Padrão: 5 | | **Máximo de tentativas de cancelamento** | Padrão: 5 | | **Intervalos de retry (minutos)** | Padrão: \[0, 30, 60, 180, 360] | ## Políticas de Emissão[​](#políticas-de-emissão "Link direto para Políticas de Emissão") | Política | Descrição | | ----------------- | ------------------------------------------------- | | `disabled` | Emissão de NF-e desabilitada | | `on_finalization` | Emitir quando a fatura é finalizada | | `on_full_payment` | Emitir quando a fatura é totalmente paga (padrão) | | `per_installment` | Emitir uma NF-e para cada parcela paga | ### Exemplos[​](#exemplos "Link direto para Exemplos") **`on_full_payment`**: Uma fatura de R$ 1.000 gera **uma** NF-e de R$ 1.000 quando totalmente paga. **`per_installment`**: Uma fatura de R$ 1.000 parcelada em 3× gera **três** NF-e de R$ 333,33 conforme cada parcela é paga. **`on_finalization`**: A NF-e é emitida no momento da finalização da fatura, independente do pagamento. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") A tela `/dashboard/nfe-settings` reúne a configuração de NF-e por empresa: provedor (NFe.io, Kobana), ambiente (sandbox/produção), chave de API criptografada em repouso, mapeamento de código de serviço, política de emissão (`per_payment`, `per_installment`, `on_finalization`), webhooks de retorno e flags de envio de e-mail. ![Configuração de NF-e por empresa com provedor e políticas](/pt/assets/images/configuracao-nfe-8bc079afd6c175bd2817ccf71260af08.png) --- # Emissão de NF-e ## Estados da NF-e[​](#estados-da-nf-e "Link direto para Estados da NF-e") ``` draft → pending → processing → issued ↓ (erro) → error issued → pending_cancel → canceling → canceled ↓ (erro) → error ``` | Status | Descrição | | ------------------- | ----------------------------------------------------- | | **draft** | Rascunho, ainda não enviada | | **pending** | Na fila para emissão | | **processing** | Sendo processada pelo provedor (async) | | **issued** | Emitida com sucesso | | **pending\_cancel** | Marcada para cancelamento | | **canceling** | Cancelamento em processamento | | **canceled** | Cancelada com sucesso | | **error** | Falha na emissão/cancelamento após esgotar tentativas | ## Campos da NF-e[​](#campos-da-nf-e "Link direto para Campos da NF-e") ### Identificação[​](#identificação "Link direto para Identificação") | Campo | Descrição | | --------------------- | ---------------- | | **Fatura** | Fatura associada | | **Conta de cobrança** | Cliente | | **Empresa** | Empresa emissora | ### Números e Chaves[​](#números-e-chaves "Link direto para Números e Chaves") | Campo | Descrição | | ------------------------- | ----------------------------- | | **Número da NF-e** | Número sequencial | | **Série** | Série da NF-e | | **Chave** | Chave de 44 dígitos | | **Código de verificação** | Para consulta | | **Número RPS** | Recibo Provisório de Serviços | ### Serviço[​](#serviço "Link direto para Serviço") | Campo | Descrição | | --------------------- | ----------------------------------- | | **Valor** | Valor do serviço | | **Código do serviço** | Código LC 116/2003 | | **Descrição** | Descrição do serviço prestado | | **Código CNAE** | Classificação de atividade | | **Código NBS** | Nomenclatura Brasileira de Serviços | ### Impostos[​](#impostos "Link direto para Impostos") A NF-e armazena o detalhamento dos impostos calculados: * ISS (taxa e valor) * PIS, COFINS, CSLL * IRRF * INSS ### URLs[​](#urls "Link direto para URLs") | Campo | Descrição | | -------------- | ------------------------ | | **URL do XML** | Download do XML da nota | | **URL do PDF** | Download do DANFE em PDF | ## Snapshot do Cliente[​](#snapshot-do-cliente "Link direto para Snapshot do Cliente") A NF-e armazena uma **foto** dos dados do cliente no momento da emissão: * Nome, documento, e-mail, telefone * Endereço completo com código IBGE da cidade Isso garante que a nota reflita os dados corretos mesmo se o cliente alterar seu cadastro posteriormente. ## Trilha de Auditoria[​](#trilha-de-auditoria "Link direto para Trilha de Auditoria") Cada requisição HTTP feita ao provedor é registrada em `NfeRequestTry`: * Ação (emitir, cancelar, consultar) * Endpoint chamado * Request e response completos * Status HTTP * Duração em milissegundos * Resultado (sucesso/falha) ## Capturas de tela[​](#capturas-de-tela "Link direto para Capturas de tela") ### Lista de NF-e[​](#lista-de-nf-e "Link direto para Lista de NF-e") A tela `/dashboard/nfes` lista todas as notas fiscais emitidas, com filtros por status (`pending`, `processing`, `issued`, `error`, `canceled`), empresa, cliente, intervalo e número. Cada linha mostra número, valor, impostos calculados, fatura/origem e ações (baixar XML, PDF, reenviar, cancelar). ![Lista de NF-e com status, valor e impostos](/pt/assets/images/notas-fiscais-c1d9818f4ff23dc6c672c9a64c2557af.png) ### Detalhe da NF-e[​](#detalhe-da-nf-e "Link direto para Detalhe da NF-e") A página `/dashboard/nfes/[id]` reúne dados fiscais completos: emissora, destinatário, itens (com códigos LC 116/municipal), impostos calculados, retenções, XML retornado pela prefeitura, PDF e histórico de tentativas no provedor. ![Detalhe de uma NF-e com tributos, XML e tentativas no provedor](/pt/assets/images/nota-fiscal-detalhe-79a51301a2acb805d659871c7a2b5e48.png) --- # Provedores de NF-e O sistema abstrai a comunicação com provedores de NF-e através de uma interface comum. ## Provedores Disponíveis[​](#provedores-disponíveis "Link direto para Provedores Disponíveis") ### NFe.io (`nfe_io`)[​](#nfeio-nfe_io "Link direto para nfeio-nfe_io") Integração com a plataforma NFe.io para emissão de NFS-e. * **API**: * **Documentação**: * **Suporte**: NFS-e (serviços) **Mapeamento de Status:** | Status NFe.io | Status interno | | --------------------------------------------------------------------------- | -------------- | | Created, WaitingCalculateTaxes, WaitingSend, WaitingReturn, WaitingDownload | `processing` | | Issued | `issued` | | Cancelled | `canceled` | | Error | `error` | ### Kobana NF-e (`kobana`)[​](#kobana-nf-e-kobana "Link direto para kobana-nf-e-kobana") Integração com o serviço interno de NF-e da Kobana. * **API**: (configurável) * **Versão**: /api/v1 * **Suporte**: Emissão e cancelamento ### Mock (`mock`)[​](#mock-mock "Link direto para mock-mock") Provedor de desenvolvimento que simula emissões com dados fictícios. * Sem chamadas externas * Armazenamento em memória * Gera chaves e códigos de verificação realistas ## Interface Comum[​](#interface-comum "Link direto para Interface Comum") Todos os provedores implementam: | Operação | Descrição | | ------------- | ---------------------------- | | `issue` | Emitir uma NF-e | | `cancel` | Cancelar uma NF-e emitida | | `query` | Consultar status de uma NF-e | | `downloadXml` | Baixar XML da nota | | `downloadPdf` | Baixar PDF (DANFE) | --- # Tentativas e Retry de NF-e O sistema implementa retry automático para emissões que falham. ## Worker Automático[​](#worker-automático "Link direto para Worker Automático") Executa **a cada 30 minutos** e realiza: 1. **Processar retries**: NF-e pendentes ou com erro que ainda têm tentativas 2. **Atualizar status**: Consultar o provedor para NF-e em `processing` (últimos 7 dias) 3. **Auto-emissão por pagamento**: Emitir NF-e para faturas pagas (política `on_full_payment`) 4. **Auto-emissão por finalização**: Emitir para faturas finalizadas (política `on_finalization`) 5. **Auto-emissão por parcela**: Emitir para parcelas pagas (política `per_installment`) ## Lógica de Retry[​](#lógica-de-retry "Link direto para Lógica de Retry") ### Intervalos Padrão[​](#intervalos-padrão "Link direto para Intervalos Padrão") | Tentativa | Intervalo | Tempo acumulado | | --------- | --------- | --------------- | | 1ª | Imediata | 0 min | | 2ª | +30 min | 30 min | | 3ª | +60 min | 1h30 | | 4ª | +180 min | 4h30 | | 5ª | +360 min | \~10h30 | Os intervalos são configuráveis por organização via `retryDelaysMinutes`. ### Máximo de Tentativas[​](#máximo-de-tentativas "Link direto para Máximo de Tentativas") * Emissão: 5 tentativas (configurável via `maxIssueAttempts`) * Cancelamento: 5 tentativas (configurável via `maxCancelAttempts`) Após esgotar as tentativas, o status muda para `error`. ## Tratamento de Erros[​](#tratamento-de-erros "Link direto para Tratamento de Erros") * Erros na auto-emissão são **não-bloqueantes** (esperados quando NF-e não está habilitada) * Logs detalhados para cada tentativa * Contadores de processos e erros por execução do worker --- ## [📄️Grupos de Planos](https://docs.billing.kobana.com.br/pt/pt/planos-e-produtos/grupos-de-planos/.md) [Grupos de planos permitem organizar planos relacionados para facilitar a gestão e visualização no dashboard.](https://docs.billing.kobana.com.br/pt/pt/planos-e-produtos/grupos-de-planos/.md) --- ## [📄️Grupos de Planos](https://docs.billing.kobana.com.br/pt/pt/planos-e-produtos/grupos-de-planos/.md) [Grupos de planos permitem organizar planos relacionados para facilitar a gestão e visualização no dashboard.](https://docs.billing.kobana.com.br/pt/pt/planos-e-produtos/grupos-de-planos/.md) --- # Grupos de Planos Grupos de planos permitem organizar planos relacionados para facilitar a gestão e visualização no dashboard. ## Campos[​](#campos "Link direto para Campos") | Campo | Descrição | | --------------------- | ------------------------------------------------------- | | **Nome** | Nome do grupo (único por organização) | | **Slug** | Identificador amigável para URL (único por organização) | | **Ordem de exibição** | Controla a posição do grupo na interface | ## Funcionalidades[​](#funcionalidades "Link direto para Funcionalidades") * Auto-gera o slug a partir do nome se não fornecido * Impede o arquivamento se ainda houver planos vinculados ao grupo * A ordem de exibição controla a organização dos grupos na interface ## Operações[​](#operações "Link direto para Operações") * **Criar**: Informar nome e organização * **Atualizar**: Nome e slug editáveis * **Arquivar**: Desativa o grupo (soft delete) * **Desarquivar**: Reativa o grupo * **Mover planos**: É possível mover planos entre grupos ou remover de um grupo (definir como `null`) --- # Grupos de Produtos Grupos de produtos permitem categorizar produtos para facilitar a organização, filtros no dashboard e vinculação com templates de propostas. ## Campos[​](#campos "Link direto para Campos") | Campo | Descrição | | ------------------------ | ------------------------------------------ | | **Nome** | Nome do grupo (único por organização) | | **Slug** | Identificador amigável para URL | | **Empresa** | Empresa específica (opcional) | | **Template de proposta** | Template padrão para propostas deste grupo | | **Item de serviço** | Item de serviço fiscal padrão para o grupo | | **Ordem de exibição** | Posição na interface | ## Operações[​](#operações "Link direto para Operações") * **Criar**: Informar nome, organização e opcionalmente empresa/template/item de serviço * **Atualizar**: Todos os campos editáveis * **Arquivar/Desarquivar**: Ativa e desativa grupos * **Reordenar**: Controlar a ordem de exibição dos grupos ## Capturas de tela[​](#capturas-de-tela "Link direto para Capturas de tela") ### Lista de grupos[​](#lista-de-grupos "Link direto para Lista de grupos") A tela `/dashboard/product-groups` lista os grupos do catálogo com nome, número de produtos vinculados, status e ordem de exibição. Os grupos definem como o catálogo aparece no portal do cliente. ![Lista de grupos de produtos com nome e quantidade de itens](/pt/assets/images/grupos-de-produtos-54117976fbd0fc6291ba3caf761e1d75.png) ### Detalhe do grupo[​](#detalhe-do-grupo "Link direto para Detalhe do grupo") A página `/dashboard/product-groups/[id]` permite organizar produtos do grupo, definir descrição apresentada no portal, escolher template fiscal/item de serviço padrão e arquivar. ![Detalhe de um grupo de produtos com lista de itens](/pt/assets/images/grupo-de-produtos-detalhe-296f506935f46b3ffdd3bdf07d1150d4.png) --- # Itens de Serviço Itens de serviço (`/dashboard/service-items`) são o catálogo de **descrições fiscais** usadas em faturas e NF-e de serviço. Cada item carrega informações que a prefeitura exige na hora da emissão: código municipal de serviço, código LC 116, código tributário nacional, alíquotas padrão de ISS, PIS, COFINS, IR, INSS, CSLL. Diferente de um produto comercial, um item de serviço não tem preço próprio — ele é vinculado a um produto, plano ou linha de fatura para fornecer os metadados fiscais corretos. Quando uma NF-e é gerada, o motor fiscal consulta o item vinculado para preencher os campos obrigatórios e calcular os tributos. ## O que cada item armazena[​](#o-que-cada-item-armazena "Link direto para O que cada item armazena") * **Nome e descrição** — usados no corpo da nota fiscal. * **Código municipal** — código de serviço da prefeitura emitente (varia por município). * **Código LC 116** — código nacional definido pela Lei Complementar 116/2003. * **NBS / NCM** — quando aplicável a serviços que envolvem produtos. * **Alíquotas padrão** — usadas como base de cálculo quando não há regra tributária específica. * **Empresa associada** (opcional) — limita o item a uma das empresas cadastradas, útil para grupos com filiais em municípios diferentes. ## Quando usar[​](#quando-usar "Link direto para Quando usar") * Catálogo SaaS com poucos serviços distintos: cadastre um único item ("Licença de software") e reutilize em todos os produtos. * Operação multi-empresa com municípios diferentes: cadastre o mesmo serviço uma vez por empresa, com o código municipal correto de cada uma. * Vendas pontuais de consultoria, treinamento ou setup: crie itens dedicados para que a NF-e saia com a descrição e o código corretos. ## Relação com regras tributárias[​](#relação-com-regras-tributárias "Link direto para Relação com regras tributárias") Quando uma [regra tributária](https://docs.billing.kobana.com.br/pt/pt/impostos/regras-fiscais/.md) é avaliada, ela pode filtrar por item de serviço para aplicar alíquotas específicas — por exemplo, uma retenção de IR só sobre serviços de consultoria. Isso permite manter alíquotas padrão no item e exceções na regra. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Lista de itens de serviço com código municipal e alíquotas](/pt/assets/images/itens-de-servico-a039eaf946c4c6103463f908ee3aa63c.png) --- # Planos Planos são os modelos que definem como seus clientes serão cobrados. Cada plano agrupa produtos com preços específicos e configura ciclo de cobrança, período de trial e funcionalidades incluídas. ## Campos do Plano[​](#campos-do-plano "Link direto para Campos do Plano") | Campo | Descrição | | ---------------------------- | ---------------------------------------------------------------------------------------------------- | | **Nome** | Nome de exibição do plano (1-255 caracteres) | | **Slug** | Identificador único amigável para URL (1-100 caracteres, apenas letras minúsculas, números e hífens) | | **Descrição** | Texto descritivo sobre o que o plano inclui | | **Tipo** | `standard` (padrão), `custom` (negociado) ou `promotional` (promocional) | | **Visibilidade** | `public` (visível em listagens) ou `private` (apenas via link direto) | | **Ciclo de cobrança padrão** | `monthly`, `quarterly`, `semiannual` ou `annual` | | **Ciclos disponíveis** | Quais ciclos o cliente pode escolher ao assinar | | **Período de trial** | 0 a 90 dias de teste gratuito | | **Features** | Lista de funcionalidades incluídas no plano | | **Limites** | Quotas e restrições (ex: usuários, subcontas, API requests/dia) | ## Status e Ciclo de Vida[​](#status-e-ciclo-de-vida "Link direto para Status e Ciclo de Vida") ``` draft (rascunho) → active (ativo) → archived (arquivado) ↓ ↓ DELETE RESTORE (apenas draft) (volta a active) ``` | Status | Descrição | | ------------ | ----------------------------------------------------------------------- | | **draft** | Em construção. Pode ser publicado ou deletado | | **active** | Disponível para novas assinaturas | | **archived** | Desativado para novas assinaturas, mas existentes continuam funcionando | ### Regras de Transição[​](#regras-de-transição "Link direto para Regras de Transição") * **Arquivar**: Não é possível se existirem assinaturas ativas ou em trial * **Restaurar**: Disponível apenas para planos arquivados; volta ao status `active` * **Deletar**: Disponível apenas para planos em `draft` sem nenhuma assinatura associada ## Itens do Plano[​](#itens-do-plano "Link direto para Itens do Plano") Cada plano contém **itens** que vinculam um produto a um preço específico: | Campo | Descrição | | -------------- | --------------------------------------------------------- | | **Produto** | O produto incluído (apenas produtos raiz, sem filhos) | | **Preço** | A variante de preço selecionada para o produto | | **Quantidade** | Quantidade incluída (mínimo 1) | | **Incluído** | Se o item faz parte do preço base ou é um add-on opcional | ### Regras dos Itens[​](#regras-dos-itens "Link direto para Regras dos Itens") * Apenas **produtos raiz** podem ser adicionados (produtos filhos são herdados automaticamente) * Não é permitido duplicar o mesmo produto em um plano * Todos os produtos devem pertencer à mesma organização e empresa do plano ## Criando um Plano[​](#criando-um-plano "Link direto para Criando um Plano") 1. Acesse **Planos** no dashboard 2. Clique em **Novo Plano** 3. Preencha os campos obrigatórios (nome, slug) 4. Adicione produtos e seus preços como itens do plano 5. Configure os ciclos de cobrança disponíveis 6. Opcionalmente defina um período de trial 7. Salve como rascunho ou publique diretamente ## Duplicar Plano[​](#duplicar-plano "Link direto para Duplicar Plano") Utilize a função de duplicação para copiar todos os detalhes de um plano. O sistema adiciona automaticamente "(Cópia)" ao nome e "-copy" ao slug. O plano duplicado é criado no status `draft`. ## Operações em Lote[​](#operações-em-lote "Link direto para Operações em Lote") * **Arquivar em lote**: Arquiva múltiplos planos de uma vez (pula planos em uso) * **Deletar em lote**: Remove múltiplos planos em draft (pula planos com assinaturas) * **Mover para grupo**: Move múltiplos planos para um grupo específico ## Empresa e Organização[​](#empresa-e-organização "Link direto para Empresa e Organização") * Todo plano pertence a uma **organização** (obrigatório) * Opcionalmente pode estar vinculado a uma **empresa** específica (para faturamento por entidade jurídica) * Todos os produtos do plano devem pertencer à mesma empresa/organização ## Capturas de tela[​](#capturas-de-tela "Link direto para Capturas de tela") ### Lista de planos[​](#lista-de-planos "Link direto para Lista de planos") A tela `/dashboard/plans` lista os planos do catálogo com nome, ciclo, valor recorrente, número de assinaturas ativas, status (`active`/`archived`) e ações (editar, duplicar, arquivar). ![Lista de planos com ciclo, valor e assinaturas ativas](/pt/assets/images/planos-4649f694857ba2bd2d91757483c1a8fd.png) ### Detalhe do plano[​](#detalhe-do-plano "Link direto para Detalhe do plano") A página `/dashboard/plans/[id]` mostra itens do plano (produtos, preços, quantidades), regras de proration, política de cancelamento, lista de assinaturas vinculadas e auditoria. ![Detalhe de um plano com itens, regras e assinaturas](/pt/assets/images/plano-detalhe-b3a3e48085be143786993da2a18d3e4d.png) --- # Preços e Modelos de Precificação Cada produto pode ter múltiplos preços, permitindo variantes por moeda, intervalo de cobrança ou modelo de precificação. Os preços são **em grande parte imutáveis** após criação — apenas nome e metadados podem ser alterados. Para mudar valores, desative o preço antigo e crie um novo. ## Campos do Preço[​](#campos-do-preço "Link direto para Campos do Preço") | Campo | Descrição | | ---------------------------- | -------------------------------------------------- | | **Nome** | Nome da variante (ex: "Standard", "Pro") | | **Moeda** | Código ISO 4217 (padrão: BRL) | | **Ativo** | Se o preço está disponível para uso | | **Billing Scheme** | Modelo de precificação | | **Valor unitário** | Preço por unidade, em reais (até 4 casas decimais) | | **Intervalo de recorrência** | `month` ou `year` | | **Contagem de intervalos** | Repetições (ex: 3 meses) | | **Tipo de uso** | `licensed` (fixa) ou `metered` (medida) | ## Valores Monetários[​](#valores-monetários "Link direto para Valores Monetários") Preços são números decimais em reais (BRL) e aceitam até **4 casas decimais**, o que permite preços unitários fracionados: | Valor | Significado | | ------- | ----------- | | `100` | R$ 100,00 | | `50.5` | R$ 50,50 | | `0.999` | R$ 0,999 | > **Importante**: preços são o único lugar onde as 4 casas decimais são preservadas. Os demais valores monetários (fatura, pagamento, crédito) são arredondados para 2 casas. ## Modelos de Precificação[​](#modelos-de-precificação "Link direto para Modelos de Precificação") ### 1. Por Unidade (`per_unit`)[​](#1-por-unidade-per_unit "Link direto para 1-por-unidade-per_unit") O modelo mais simples: preço fixo por unidade. ``` Preço: R$ 5,00/usuário/mês 10 usuários = R$ 50,00/mês ``` ### 2. Escalonado — Graduated (`tiered` + `graduated`)[​](#2-escalonado--graduated-tiered--graduated "Link direto para 2-escalonado--graduated-tiered--graduated") Cada faixa tem um preço diferente, e **apenas as unidades dentro de cada faixa** são cobradas naquele valor. ``` Faixa 1: 1-10 unidades → R$ 10,00/un Faixa 2: 11-50 unidades → R$ 8,00/un Faixa 3: 51+ unidades → R$ 5,00/un Para 25 unidades: (10 × R$ 10,00) + (15 × R$ 8,00) = R$ 220,00 ``` ### 3. Volume (`tiered` + `volume`)[​](#3-volume-tiered--volume "Link direto para 3-volume-tiered--volume") Quando o cliente atinge uma faixa, **todas as unidades** são cobradas pelo valor daquela faixa. ``` Faixa 1: 1-10 unidades → R$ 10,00/un Faixa 2: 11-50 unidades → R$ 8,00/un Faixa 3: 51+ unidades → R$ 5,00/un Para 25 unidades: 25 × R$ 8,00 = R$ 200,00 (todas na faixa 2) ``` ### 4. Pacote (`package`)[​](#4-pacote-package "Link direto para 4-pacote-package") Preço fixo para um pacote de itens definido. ### Configuração de Faixas (Tiers)[​](#configuração-de-faixas-tiers "Link direto para Configuração de Faixas (Tiers)") Cada faixa define: | Campo | Descrição | | ------------- | ---------------------------------------------------------- | | `up_to` | Limite superior da faixa (`null` = ilimitado, faixa final) | | `unit_amount` | Preço por unidade nesta faixa | | `flat_amount` | Valor fixo adicional por faixa (padrão: 0) | ## Tipo de Uso[​](#tipo-de-uso "Link direto para Tipo de Uso") | Tipo | Descrição | | ---------- | ----------------------------------------------- | | `licensed` | Quantidade fixa definida na assinatura | | `metered` | Quantidade medida e reportada ao longo do ciclo | --- # Produtos Produtos representam os serviços ou recursos cobráveis da sua organização. Cada produto pode ter múltiplos preços e suporta hierarquia de um nível (produto raiz com filhos/add-ons). ## Campos do Produto[​](#campos-do-produto "Link direto para Campos do Produto") | Campo | Descrição | | -------------------- | --------------------------------------------------------------- | | **Nome** | Nome de exibição (1-255 caracteres) | | **Slug** | Identificador único amigável para URL | | **Descrição** | Detalhes sobre o produto | | **Tipo** | Determina o modelo de uso (ver tabela abaixo) | | **Visibilidade** | `public` ou `private` | | **Label da unidade** | Nome da unidade (ex: "usuários", "GB") | | **Incremento** | Passo mínimo de quantidade (ex: 10 = quantidades 10, 20, 30...) | | **Obrigatório** | Se é necessário para assinar | | **URL do site** | Link para documentação/página do produto | ## Tipos de Produto[​](#tipos-de-produto "Link direto para Tipos de Produto") | Tipo | Descrição | Recorrência | | ------------------- | ------------------------------- | ----------------------- | | `base` | Produto padrão recorrente | Recorrente | | `addon_quantity` | Add-on com preço por quantidade | Recorrente | | `addon_fixed` | Add-on com preço fixo | Recorrente | | `metered` | Cobrança baseada em uso medido | Recorrente (em arrears) | | `one_time_fixed` | Taxa única fixa | Uma vez | | `one_time_quantity` | Taxa única por unidade | Uma vez | ## Hierarquia de Produtos[​](#hierarquia-de-produtos "Link direto para Hierarquia de Produtos") Produtos suportam **um nível** de hierarquia: ``` Produto Raiz (parentProductId = null) ├── Produto filho 1 (add-on) ├── Produto filho 2 (taxa de setup) └── Produto filho 3 (módulo opcional) ``` ### Regras de Hierarquia[​](#regras-de-hierarquia "Link direto para Regras de Hierarquia") * Não é possível aninhar mais de 1 nível (filhos não podem ter filhos) * Produtos filhos herdam a organização/empresa do pai * Apenas produtos raiz podem ser adicionados a planos * Produtos filhos aparecem como add-ons/opções do produto pai ## Status e Ciclo de Vida[​](#status-e-ciclo-de-vida "Link direto para Status e Ciclo de Vida") ``` draft (rascunho) → active (ativo) → archived (arquivado) ↓ ↑ ↓ DELETE PUBLISH RESTORE ``` | Status | Descrição | | ------------ | --------------------------------------------------- | | **draft** | Em desenvolvimento, não visível para planos | | **active** | Disponível para planos e assinaturas | | **archived** | Desativado; não pode ser usado em novas assinaturas | ### Regras[​](#regras "Link direto para Regras") * **Arquivar**: Não é possível se usado por assinaturas ativas, em trial ou past\_due. Desativa todos os preços automaticamente * **Restaurar**: Volta ao status `active` * **Publicar**: Move de `draft` para `active` ## Operações em Lote[​](#operações-em-lote "Link direto para Operações em Lote") * **Arquivar em lote**: Arquiva múltiplos produtos * **Deletar em lote**: Remove produtos não utilizados em assinaturas * **Mover para grupo**: Move produtos para um grupo de produtos * **Alterar visibilidade**: Muda a visibilidade de múltiplos produtos * **Alterar empresa**: Move produtos para outra empresa ## Reordenação[​](#reordenação "Link direto para Reordenação") Produtos possuem um campo `display_order` para controlar a ordem de exibição no dashboard e portal. É possível reordenar via drag-and-drop ou API. ## Capturas de tela[​](#capturas-de-tela "Link direto para Capturas de tela") ### Lista de produtos[​](#lista-de-produtos "Link direto para Lista de produtos") A tela `/dashboard/products` lista o catálogo com nome, tipo (recorrente, único, metered), preço base, status e visibilidade no portal. Suporta reordenação por drag-and-drop e ações em massa. ![Lista de produtos com tipo, preço e visibilidade](/pt/assets/images/produtos-77edf887ff68e78fa1fdd14c8facb4b4.png) ### Detalhe do produto[​](#detalhe-do-produto "Link direto para Detalhe do produto") A página `/dashboard/products/[id]` reúne preços vinculados (com moeda e ciclo), itens de serviço fiscal, planos que incluem o produto, eventos de uso e auditoria. ![Detalhe de um produto com preços e planos vinculados](/pt/assets/images/produto-detalhe-97fc65103fe6c528e87664fcfced007a.png) --- ## [📄️Portal do Cliente](https://docs.billing.kobana.com.br/pt/pt/portal.md) [O Portal do Cliente é a área self-service que os clientes finais (assinantes) acessam para gerenciar a relação com a empresa que usa o Faturamento Automático. Cada portal opera em https:///portal (ou no domínio padrão da plataforma) e mostra apenas os dados da conta de cobrança autenticada.](https://docs.billing.kobana.com.br/pt/pt/portal.md) --- ## [📄️Portal do Cliente](https://docs.billing.kobana.com.br/pt/pt/portal.md) [O Portal do Cliente é a área self-service que os clientes finais (assinantes) acessam para gerenciar a relação com a empresa que usa o Faturamento Automático. Cada portal opera em https:///portal (ou no domínio padrão da plataforma) e mostra apenas os dados da conta de cobrança autenticada.](https://docs.billing.kobana.com.br/pt/pt/portal.md) --- # Assinaturas A página `/portal/subscriptions` lista as assinaturas vinculadas à conta de cobrança autenticada. Cada linha mostra o plano, status, valor recorrente, próximo ciclo e ações disponíveis. ## Informações exibidas[​](#informações-exibidas "Link direto para Informações exibidas") * **Plano e itens** — produto principal e add-ons. * **Status** — `trialing`, `active`, `past_due`, `paused` ou `canceled`. * **Ciclo** — mensal, trimestral, semestral ou anual. * **Valor recorrente** — em reais com formatação `R$ 1.234,56`. * **Início do período atual** e **próximo ciclo**. * **Método de pagamento** — cartão final, boleto ou PIX. ## Ações disponíveis[​](#ações-disponíveis "Link direto para Ações disponíveis") Dependendo da configuração da organização, o cliente pode: * **Mudar de plano** — fluxo guiado com preview de proration antes de confirmar. * **Cancelar** — agendar cancelamento no fim do ciclo ou cancelar imediatamente (se permitido). * **Pausar** — interromper temporariamente a cobrança. * **Atualizar método** — trocar o cartão sem afetar a assinatura. ## Detalhe da assinatura[​](#detalhe-da-assinatura "Link direto para Detalhe da assinatura") Ao clicar em uma assinatura, o cliente vê a página de detalhe (`/portal/subscriptions/[id]`) com: * Histórico de faturas geradas pela assinatura * Histórico de mudanças (plano, itens, pausas) * Linha do tempo de eventos * Documentos relacionados (contrato, proposta original) ## Capturas de tela[​](#capturas-de-tela "Link direto para Capturas de tela") ### Lista de assinaturas[​](#lista-de-assinaturas "Link direto para Lista de assinaturas") ![Lista de assinaturas no portal do cliente](/pt/assets/images/portal-assinaturas-03afc225044f7d5fe19d84e52aaaaf03.png) ### Detalhe da assinatura[​](#detalhe-da-assinatura-1 "Link direto para Detalhe da assinatura") ![Detalhe de uma assinatura com histórico de faturas e mudanças](/pt/assets/images/portal-assinatura-detalhe-03afc225044f7d5fe19d84e52aaaaf03.png) --- # Configurações A página `/portal/settings` agrupa preferências da conta de cobrança que afetam **como o cliente recebe cobranças e comunicações**. ## Preferências de cobrança[​](#preferências-de-cobrança "Link direto para Preferências de cobrança") * **Método de pagamento padrão** — usado em cobranças automáticas. * **Dia de vencimento preferido** (quando o plano permite). * **E-mail para receber faturas** — pode ser diferente do e-mail de login. * **Idioma das comunicações** — `pt-BR` ou `en-US`. ## Notificações[​](#notificações "Link direto para Notificações") Toggles para habilitar/desabilitar: * Lembrete antes do vencimento da fatura * Confirmação de pagamento * Aviso de pagamento falho * Fim de trial * Mudança de plano * Cartão prestes a expirar * Receber NF-e por e-mail Cada toggle controla um canal (e-mail) específico. Webhooks para integrações são configurados no dashboard administrativo da organização. ## Dados da empresa[​](#dados-da-empresa "Link direto para Dados da empresa") Atalhos para [Conta](https://docs.billing.kobana.com.br/pt/pt/portal/conta.md) (dados fiscais) e [Métodos de Pagamento](https://docs.billing.kobana.com.br/pt/pt/portal/metodos-de-pagamento.md). ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Configurações do portal com preferências de cobrança e notificações](/pt/assets/images/portal-configuracoes-1ceeec4c789037c429c38f2e4d189a49.png) --- # Conta Em `/portal/account` o cliente gerencia os **dados da conta de cobrança** (`BillingAccount`) — razão social, CNPJ/CPF, inscrição estadual e municipal, endereço, contato financeiro e e-mails para envio de fatura. ## Dados editáveis[​](#dados-editáveis "Link direto para Dados editáveis") * **Razão social** e **nome fantasia** * **Documento** (CNPJ ou CPF) * **Inscrição estadual** e **inscrição municipal** (quando aplicáveis) * **Endereço completo** — usado para emissão de NF-e e cobrança * **E-mails para receber faturas e cobranças** * **Telefone de contato** ## Validações[​](#validações "Link direto para Validações") * CNPJ e CPF são validados via dígitos verificadores. * CEP busca endereço automaticamente quando possível. * Alterações em CNPJ exigem reemissão de faturas em aberto (a organização pode bloquear esse campo). ## NF-e[​](#nf-e "Link direto para NF-e") Quando a NF-e está habilitada, os dados desta página são copiados para o documento fiscal emitido. Manter o cadastro atualizado evita rejeições por divergência no SEFAZ ou na prefeitura. ## Atualizações restritas[​](#atualizações-restritas "Link direto para Atualizações restritas") Alguns campos (documento, endereço fiscal) podem estar bloqueados para edição direta dependendo da política da organização — nesses casos, o cliente vê instruções para abrir um chamado com o suporte. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Edição dos dados de conta de cobrança no portal](/pt/assets/images/portal-conta-679b6b5484a772d9080e373daa466a21.png) --- # Créditos A página `/portal/credits` exibe o **saldo de créditos** da conta de cobrança e o histórico de aplicações. Créditos surgem por diversos motivos — proration de downgrade, estorno de fatura, ajuste manual da organização, promoção — e são automaticamente aplicados nas próximas faturas. ## Saldo[​](#saldo "Link direto para Saldo") O topo da página mostra o saldo total disponível em reais. Quando há créditos com data de expiração, a página alerta sobre os que estão próximos do vencimento. ## Histórico[​](#histórico "Link direto para Histórico") Cada registro de crédito mostra: * **Data** de geração * **Origem** — `downgrade_proration`, `refund`, `manual_adjustment`, `promotion`, etc. * **Valor** * **Status** — `available`, `partially_applied`, `fully_applied`, `expired` * **Aplicações** — faturas em que o crédito foi consumido (parcial ou total) ## Como o crédito é aplicado[​](#como-o-crédito-é-aplicado "Link direto para Como o crédito é aplicado") Quando uma fatura é finalizada (`open`), o motor de cobrança consome créditos disponíveis em ordem FIFO (mais antigo primeiro), até zerar o crédito ou cobrir a fatura. O valor consumido aparece como linha negativa na fatura e o saldo restante segue disponível. ## Quando o crédito **não** é aplicado[​](#quando-o-crédito-não-é-aplicado "Link direto para quando-o-crédito-não-é-aplicado") * Faturas em status `void` ou já `paid` * Quando a configuração do plano desabilita uso de crédito * Créditos expirados ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Saldo e histórico de créditos no portal](/pt/assets/images/portal-creditos-ecdf2d5e03d70b0981f648813cb6fd7c.png) --- # Faturas A página `/portal/invoices` lista todas as faturas da conta de cobrança, com filtros por status e período. O cliente pode visualizar, baixar PDF, copiar linha digitável ou QR Code PIX, pagar online e consultar NF-e relacionada. ## Status visíveis no portal[​](#status-visíveis-no-portal "Link direto para Status visíveis no portal") * **Aberta** — gerada, aguardando pagamento. * **Paga** — quitada (parcial ou totalmente). * **Vencida** — passou da data de vencimento sem pagamento. * **Cancelada** — invalidada pela organização. * **Em processamento** — pagamento submetido, aguardando confirmação do gateway. ## Ações por fatura[​](#ações-por-fatura "Link direto para Ações por fatura") * **Pagar** — abre o fluxo de pagamento com os métodos habilitados. * **Baixar PDF** — gera o documento da fatura. * **Copiar linha digitável** (boleto) — código de barras pronto para pagar. * **Copiar PIX** — copia-e-cola ou QR Code. * **Ver NF-e** — link para a nota fiscal vinculada, quando emitida. * **Histórico de pagamentos** — todas as tentativas e estornos. ## Detalhe da fatura[​](#detalhe-da-fatura "Link direto para Detalhe da fatura") A página de detalhe (`/portal/invoices/[id]`) mostra: * **Linha-a-linha** dos itens (descrição, quantidade, valor unitário, total) * **Total bruto, descontos, créditos aplicados, impostos retidos, valor a pagar** * **Histórico de tentativas de pagamento** (gateway, método, status, erro) * **NF-e** quando houver, com link para download do XML e do PDF ## Captura de tela — lista[​](#captura-de-tela--lista "Link direto para Captura de tela — lista") ![Lista de faturas no portal com status e ações](/pt/assets/images/portal-faturas-7c445110a6f940c0d2247bb6f277efe3.png) ## Captura de tela — detalhe[​](#captura-de-tela--detalhe "Link direto para Captura de tela — detalhe") ![Detalhe de uma fatura com itens, totais e histórico de pagamento](/pt/assets/images/portal-fatura-detalhe-6dcf935d6a555b315f4de53ce8e056bd.png) --- # Métodos de Pagamento Em `/portal/payment-methods` o cliente gerencia os meios de pagamento associados à conta de cobrança. A página suporta múltiplos métodos simultaneamente e define qual é o padrão para cobranças automáticas. ## Métodos suportados[​](#métodos-suportados "Link direto para Métodos suportados") * **Cartão de crédito** — bandeiras Visa, Mastercard, Elo, Amex e Hipercard, conforme o gateway. Salva token, marca, últimos 4 dígitos e expiração. * **Boleto bancário** — gerado a cada fatura quando o cliente escolhe boleto como padrão. * **PIX** — pagamento via QR Code ou copia-e-cola, gerado fatura a fatura. * **Transferência bancária** — quando habilitada pela organização, com dados de conta para depósito. ## Ações[​](#ações "Link direto para Ações") * **Adicionar cartão** — formulário tokenizado pelo gateway; dados sensíveis nunca passam pelos servidores da plataforma. * **Definir como padrão** — método usado em cobranças automáticas (charge\_automatically). * **Remover** — exclui o token; cobranças futuras dependem de outro método. ## Cartão expirando[​](#cartão-expirando "Link direto para Cartão expirando") O worker `card-expiring` (semanal) detecta cartões prestes a expirar e dispara notificação para o cliente atualizar antes que a próxima cobrança falhe. ## Segurança[​](#segurança "Link direto para Segurança") * Tokens de cartão são armazenados no gateway, não na plataforma. * O cliente nunca vê o número completo do cartão após o cadastro. * Adição e remoção são registradas em [Auditoria](https://docs.billing.kobana.com.br/pt/pt/configuracoes/auditoria.md). ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Tela de métodos de pagamento com cartões cadastrados](/pt/assets/images/portal-metodos-de-pagamento-e0d96dc0bc2708430fa6495ea46e1093.png) --- # Pagamentos A página `/portal/payments` traz o **histórico de pagamentos** já processados na conta de cobrança — independente do método ou da fatura de origem. É a visão do extrato, útil para conferência contábil e dúvidas de cobrança. ## Informações por pagamento[​](#informações-por-pagamento "Link direto para Informações por pagamento") * **Data** do processamento * **Valor** * **Método** — cartão, boleto, PIX, transferência * **Status** — `succeeded`, `pending`, `failed`, `refunded`, `chargeback` * **Fatura relacionada** — link para a fatura de origem * **Gateway** — quando relevante (apenas para suporte) ## Filtros[​](#filtros "Link direto para Filtros") * **Status** * **Método** * **Intervalo de datas** ## Detalhe do pagamento[​](#detalhe-do-pagamento "Link direto para Detalhe do pagamento") Em `/portal/payments/[id]` o cliente vê o **recibo**: * Identificador do pagamento * Cliente pagador, conta de cobrança * Fatura quitada e seus itens * Método utilizado (últimos 4 dígitos do cartão, banco do boleto, chave PIX) * Status detalhado e mensagem do gateway * Botão para baixar comprovante em PDF ## Estornos e reembolsos[​](#estornos-e-reembolsos "Link direto para Estornos e reembolsos") Quando um pagamento é estornado pela organização, o status fica `refunded` e um link aponta para o registro do estorno. O crédito correspondente (se gerado) aparece em [Créditos](https://docs.billing.kobana.com.br/pt/pt/portal/creditos.md). ## Captura de tela — lista[​](#captura-de-tela--lista "Link direto para Captura de tela — lista") ![Histórico de pagamentos no portal](/pt/assets/images/portal-pagamentos-c3a4ff1f30a3af7e42a3743656886211.png) ## Captura de tela — detalhe[​](#captura-de-tela--detalhe "Link direto para Captura de tela — detalhe") ![Detalhe de um pagamento com recibo e fatura relacionada](/pt/assets/images/portal-pagamento-detalhe-267baee469cc531973e249b8b80bb631.png) --- # Perfil A página `/portal/profile` reúne as **preferências pessoais do usuário** logado no portal. Diferente de [Conta](https://docs.billing.kobana.com.br/pt/pt/portal/conta.md), que cuida da pessoa jurídica/física pagadora, o perfil é por pessoa que usa o portal. ## O que o usuário pode ajustar[​](#o-que-o-usuário-pode-ajustar "Link direto para O que o usuário pode ajustar") * **Nome de exibição** * **E-mail** — usado para login mágico e notificações * **Tema** — claro, escuro ou automático * **Idioma** — `pt-BR` ou `en-US` * **Preferências de notificação** — quais e-mails receber (lembrete de fatura, recibo de pagamento, fim de trial, etc.) ## Múltiplos usuários por conta[​](#múltiplos-usuários-por-conta "Link direto para Múltiplos usuários por conta") Uma mesma conta de cobrança pode ter vários usuários do portal (sócios, financeiro, contador). Cada um tem o próprio perfil e a própria preferência de e-mail, mas todos veem os mesmos dados de cobrança. ## Segurança[​](#segurança "Link direto para Segurança") * Trocar o e-mail dispara confirmação no e-mail antigo e no novo. * O token de confirmação fica armazenado criptografado (`lib/crypto.ts`). * Toda alteração é registrada em [Auditoria](https://docs.billing.kobana.com.br/pt/pt/configuracoes/auditoria.md). ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Configuração de perfil do usuário do portal](/pt/assets/images/portal-perfil-be57322c8f34cdceda34a917507b5dc5.png) --- # Produtos A página `/portal/products` é a **vitrine self-service** dos produtos e planos que a organização publicou para venda direta no portal. O cliente pode contratar novos produtos sem passar pelo time comercial, com checkout integrado aos métodos de pagamento já cadastrados. ## O que aparece[​](#o-que-aparece "Link direto para O que aparece") Apenas produtos marcados como **publicados** (`is_published = true`) e com pelo menos um preço ativo. A apresentação segue o agrupamento configurado em [Grupos de Produtos](https://docs.billing.kobana.com.br/pt/pt/planos-e-produtos/grupos-de-produtos/.md), com cards, descrições e tabela de preços. ## Fluxo de contratação[​](#fluxo-de-contratação "Link direto para Fluxo de contratação") 1. Cliente seleciona o produto/plano. 2. Confirma quantidade e add-ons. 3. Escolhe ou cadastra método de pagamento. 4. Confirma — uma assinatura é criada (ou um pedido avulso, conforme o produto). 5. Primeira fatura é gerada e cobrada conforme o método. Todo o fluxo respeita as configurações de ciclo, trial e proration definidas pela organização. Quando o cliente já tem assinatura ativa, o sistema oferece a opção de adicionar o item à assinatura existente. ## Catálogo customizado[​](#catálogo-customizado "Link direto para Catálogo customizado") A organização pode esconder produtos do portal mantendo-os disponíveis via API ou propostas comerciais. Isso permite usar o portal apenas para upsell controlado, ou disponibilizar tudo em self-service. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Vitrine de produtos no portal do cliente](/pt/assets/images/portal-produtos-19ca81eed49b7cd3a52dcfed03d664df.png) --- # Propostas Em `/portal/proposals` o cliente vê as **propostas comerciais** enviadas pelo time da organização. Cada proposta detalha planos, itens, descontos, prazo e condições — e pode ser aceita diretamente no portal, transformando-se em assinatura ativa. ## Estados da proposta[​](#estados-da-proposta "Link direto para Estados da proposta") * **draft** — em edição interna; não visível no portal. * **sent** — enviada ao cliente, aguardando ação. * **viewed** — cliente abriu a proposta no portal (registrado com timestamp). * **accepted** — cliente aceitou; gera assinatura, primeira fatura e auditoria. * **declined** — cliente recusou; motivo opcional registrado. * **expired** — passou da validade. ## Conteúdo da proposta[​](#conteúdo-da-proposta "Link direto para Conteúdo da proposta") * Cliente e dados de cobrança * Itens (planos, produtos, add-ons) com quantidade e valor * Descontos aplicados, valor total e impostos * Condições comerciais (prazo, ciclo, trial) * PDF gerado automaticamente para impressão e arquivo ## Aceitar uma proposta[​](#aceitar-uma-proposta "Link direto para Aceitar uma proposta") 1. Cliente clica em **Aceitar**. 2. Confirma método de pagamento (cadastrado ou novo). 3. Sistema cria a assinatura, emite a primeira fatura e dispara webhook `proposal.accepted`. 4. Cliente é redirecionado para a assinatura recém-criada. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Lista de propostas comerciais no portal do cliente](/pt/assets/images/portal-propostas-639a503415356ff706771ef1dfddf161.png) --- # Uso A página `/portal/usage` mostra ao cliente o **consumo medido** acumulado no ciclo atual — quantas chamadas de API, mensagens enviadas, eventos processados ou GBs armazenados, conforme as métricas definidas pela organização. ## O que é exibido[​](#o-que-é-exibido "Link direto para O que é exibido") * **Lista de produtos metered** ativos na conta * **Consumo do período** com unidade de medida correta * **Comparativo** com período anterior (quando disponível) * **Estimativa de cobrança** para a próxima fatura, com base no consumo até o momento * **Limites e alertas** quando o produto tem teto ou faixas configuradas ## Filtros[​](#filtros "Link direto para Filtros") * **Intervalo de datas** — padrão do início do ciclo atual até hoje * **Produto** — quando há várias métricas ## Atualização[​](#atualização "Link direto para Atualização") Os dados refletem o mesmo backend usado pelo dashboard administrativo. Eventos chegam via API de Usage Records, integrações ou worker `usage-sync` (horário). O atraso é tipicamente de minutos. ## Para que serve[​](#para-que-serve "Link direto para Para que serve") * **Previsibilidade** — cliente sabe o que vai pagar antes da virada do ciclo. * **Detecção de anomalia** — picos suspeitos ficam evidentes. * **Suporte** — discussões sobre cobrança começam com os mesmos números que o dashboard mostra. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Métricas de uso/consumo do ciclo atual no portal](/pt/assets/images/portal-uso-e9c37cd826d89fc096b6efbdd21cde94.png) --- # Visão Geral A página inicial do portal (`/portal`) traz um **resumo da relação financeira** do cliente com a organização: assinatura ativa, próxima fatura, último pagamento, créditos disponíveis e atalhos para as ações mais comuns. ## Cartões principais[​](#cartões-principais "Link direto para Cartões principais") * **Próxima cobrança** — data, valor e método (cartão, boleto, PIX). * **Assinatura ativa** — plano, ciclo e status. * **Último pagamento** — data, valor e status (sucedido, em processamento, falhou). * **Crédito disponível** — saldo total e link para o histórico. * **Faturas em aberto** — alerta quando há boletos vencidos ou próximos do vencimento. ## Atalhos[​](#atalhos "Link direto para Atalhos") A página oferece atalhos para: * Pagar a próxima fatura * Trocar o método de pagamento padrão * Atualizar dados de cobrança * Falar com o suporte ## Personalização[​](#personalização "Link direto para Personalização") A logo, cores e textos seguem a configuração definida pela organização em [Portal do Cliente](https://docs.billing.kobana.com.br/pt/pt/contas/portal-do-cliente/.md). O cliente pode alternar entre tema claro e escuro. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") ![Visão geral do portal do cliente com próxima cobrança e assinatura ativa](/pt/assets/images/portal-visao-geral-679b6b5484a772d9080e373daa466a21.png) --- ## [📄️Geração de PDF](https://docs.billing.kobana.com.br/pt/pt/propostas/geracao-de-pdf/.md) [O sistema gera PDFs de propostas integrando com Google Docs/Slides via Google Apps Script.](https://docs.billing.kobana.com.br/pt/pt/propostas/geracao-de-pdf/.md) --- ## [📄️Geração de PDF](https://docs.billing.kobana.com.br/pt/pt/propostas/geracao-de-pdf/.md) [O sistema gera PDFs de propostas integrando com Google Docs/Slides via Google Apps Script.](https://docs.billing.kobana.com.br/pt/pt/propostas/geracao-de-pdf/.md) --- # Geração de PDF O sistema gera PDFs de propostas integrando com Google Docs/Slides via Google Apps Script. ## Fluxo de Geração[​](#fluxo-de-geração "Link direto para Fluxo de Geração") 1. Serviço cria um **token de dados temporário** (validade: 10 minutos) 2. Constrói a URL segura com os dados da proposta 3. Chama o **Google Apps Script** com os dados 4. O Apps Script popula o template no Google Drive 5. Retorna o ID do documento e URLs ## Dados Enviados ao Template[​](#dados-enviados-ao-template "Link direto para Dados Enviados ao Template") ### Informações Básicas[​](#informações-básicas "Link direto para Informações Básicas") * Data de geração e expiração * Código, título e descrição da proposta ### Dados do Cliente[​](#dados-do-cliente "Link direto para Dados do Cliente") * Nome, documento, razão social * Contato (e-mail, telefone) * Responsável (usuário do portal) ### Produtos[​](#produtos "Link direto para Produtos") Para cada item: * Nome, descrição, quantidade * Preço unitário e total * Setup por unidade e total * Recorrente por unidade e total * Se é produto one-time ### Preços por Ciclo[​](#preços-por-ciclo "Link direto para Preços por Ciclo") Para cada ciclo (mensal, trimestral, semestral, anual): * Total do ciclo * Desconto e percentual * Primeiro pagamento * Valor mensal equivalente ### Cupom[​](#cupom "Link direto para Cupom") * Código, tipo e valor do desconto ### Setup[​](#setup "Link direto para Setup") * Se há setup, total e primeiro pagamento ### Organização[​](#organização "Link direto para Organização") * Nome e documento da organização ## URLs Geradas[​](#urls-geradas "Link direto para URLs Geradas") | 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` | ## Segurança[​](#segurança "Link direto para Segurança") Os dados da proposta são acessados via token temporário de 10 minutos. Após o uso ou expiração, o token é invalidado. --- # Propostas Propostas são documentos comerciais enviados a clientes ou prospects com itens, preços e condições de pagamento. ## Ciclo de Vida[​](#ciclo-de-vida "Link direto para Ciclo de Vida") ``` draft → sent → viewed → accepted ↓ rejected ``` | Status | Descrição | | ------------ | ---------------------------------------------------- | | **draft** | Rascunho, editável | | **sent** | Enviada ao cliente | | **viewed** | Visualizada pelo cliente | | **accepted** | Aceita — assinatura e fatura criadas automaticamente | | **rejected** | Rejeitada pelo cliente (motivo armazenado) | | **expired** | Expirou sem resposta | | **canceled** | Cancelada pela organização | ## Campos da Proposta[​](#campos-da-proposta "Link direto para Campos da Proposta") | Campo | Descrição | | --------------------- | ------------------------------------------------- | | **Código** | Identificador único gerado automaticamente | | **Título** | Título da proposta (padrão: "Proposta Comercial") | | **Descrição** | Detalhes da proposta | | **Conta de cobrança** | Para clientes existentes | | **Prospect** | Para novos clientes (Person tipo customer) | | **Cupom** | Cupom de desconto aplicado | | **Template** | Template de documento para geração de PDF | | **Data de expiração** | Configurável (padrão: conforme billing settings) | | **Notas** | Observações internas | ## Itens da Proposta[​](#itens-da-proposta "Link direto para Itens da Proposta") Cada proposta contém itens com produtos e preços: | Campo | Descrição | | ------------------ | ----------------------------- | | **Produto** | Produto cotado | | **Preço** | Variante de preço selecionada | | **Quantidade** | Quantidade (padrão: 1) | | **Valor unitário** | Preço por unidade | Restrição: Não é permitido duplicar o mesmo produto em uma proposta. ## Cálculo de Preços[​](#cálculo-de-preços "Link direto para Cálculo de Preços") O sistema calcula automaticamente os preços por ciclo de cobrança: | Ciclo | Desconto Padrão | | ---------- | --------------- | | Mensal | 0% | | Trimestral | 5% | | Semestral | 10% | | Anual | 15% | Os descontos por ciclo são configuráveis nas configurações de cobrança da organização. Para cada ciclo, o sistema calcula: * Subtotal (soma dos itens recorrentes × meses) * Desconto do ciclo * Desconto do cupom * Total com descontos * Preço por mês * Primeiro pagamento (incluindo taxas únicas/setup) ## Operações[​](#operações "Link direto para Operações") ### Enviar (`draft` → `sent`)[​](#enviar-draft--sent "Link direto para enviar-draft--sent") Requer pelo menos 1 item. Registra `sent_at`. ### Despublicar (`sent`/`viewed` → `draft`)[​](#despublicar-sentviewed--draft "Link direto para despublicar-sentviewed--draft") Permite reeditar uma proposta já enviada. ### Aceitar[​](#aceitar "Link direto para Aceitar") Quando o cliente aceita: 1. Status muda para `accepted` 2. **Assinatura é criada** automaticamente com os itens da proposta 3. **Fatura é criada e finalizada** 4. O ciclo de cobrança é escolhido pelo cliente no momento da aceitação ### Rejeitar[​](#rejeitar "Link direto para Rejeitar") O cliente pode rejeitar informando um motivo opcional. ### Desfazer Aceitação[​](#desfazer-aceitação "Link direto para Desfazer Aceitação") Reverte a proposta de `accepted` para `sent` e deleta a assinatura vinculada. ### Cancelar[​](#cancelar "Link direto para Cancelar") Disponível em qualquer estado exceto `accepted` e `canceled`. ## PDF e Documento[​](#pdf-e-documento "Link direto para PDF e Documento") ### Invalidação Automática[​](#invalidação-automática "Link direto para Invalidação Automática") Quando itens são alterados após a geração do PDF, o campo `pdf_outdated_at` é definido, sinalizando que o PDF precisa ser regenerado. ## Propostas no Portal[​](#propostas-no-portal "Link direto para Propostas no Portal") Clientes acessam propostas pelo portal usando o código único. Podem visualizar, aceitar ou rejeitar. ## Capturas de tela[​](#capturas-de-tela "Link direto para Capturas de tela") ### Lista de propostas[​](#lista-de-propostas "Link direto para Lista de propostas") A tela `/dashboard/proposals` lista todas as propostas comerciais com filtros por status (`draft`, `sent`, `viewed`, `accepted`, `declined`, `expired`), cliente, prazo de validade e valor. Cada linha mostra cliente, valor, dias para expirar e ações (enviar, duplicar, cancelar, baixar PDF). ![Lista de propostas comerciais com status e validade](/pt/assets/images/propostas-ffd0820aeb88302401151332d63c9bfa.png) ### Detalhe da proposta[​](#detalhe-da-proposta "Link direto para Detalhe da proposta") A página `/dashboard/proposals/[id]` reúne itens (planos e produtos com quantidade e valor), descontos, totais, condições, prazo de validade, timeline de eventos (enviada, visualizada, aceita) e ações para reenviar, duplicar ou converter manualmente em assinatura. ![Detalhe de uma proposta com itens, totais e timeline](/pt/assets/images/proposta-detalhe-1ba04b8455682a752db03a599424f52f.png) --- # Templates de Proposta Templates definem o modelo de documento usado para gerar PDFs das propostas. ## Campos do Template[​](#campos-do-template "Link direto para Campos do Template") | Campo | Descrição | | ---------------------- | ---------------------------------------------------- | | **Nome** | Nome do template (único por organização) | | **Descrição** | Detalhes sobre o template | | **Google Doc ID** | ID do documento template no Google Drive | | **Tipo de documento** | `google_doc` ou `google_slides` | | **URL do Apps Script** | URL do deployment do Google Apps Script para geração | | **Pasta do Drive** | ID da pasta onde os documentos gerados são salvos | | **Padrão** | Se é o template padrão da organização | | **Ativo** | Se está disponível para uso | ## Operações[​](#operações "Link direto para Operações") * **Criar**: Informar nome, Google Doc ID e opcionalmente Apps Script URL * **Atualizar**: Todos os campos editáveis * **Definir como padrão**: Desmarca o padrão anterior automaticamente * **Ativar/Desativar**: Controla disponibilidade (não pode desativar o único template ativo) * **Deletar**: Apenas se não utilizado por nenhuma proposta ## Integração com Google[​](#integração-com-google "Link direto para Integração com Google") O template é um documento do Google Docs ou Google Slides que contém placeholders para dados da proposta. O Google Apps Script processa os dados e gera o documento final. ## Captura de tela[​](#captura-de-tela "Link direto para Captura de tela") A tela `/dashboard/proposal-templates` lista os templates de proposta da organização, com nome, tipo (Google Docs, Google Slides), última atualização e número de propostas que usam cada template. Inclui preview da estrutura de placeholders e ações para duplicar ou arquivar. ![Lista de templates de proposta com placeholders](/pt/assets/images/templates-de-proposta-3d6f51f634207ad183ea351611c31245.png) --- ## [📄️Endpoints de Webhook](https://docs.billing.kobana.com.br/pt/pt/webhooks/endpoints/.md) [Cada organização pode configurar múltiplos endpoints para receber notificações de eventos.](https://docs.billing.kobana.com.br/pt/pt/webhooks/endpoints/.md) --- ## [📄️Endpoints de Webhook](https://docs.billing.kobana.com.br/pt/pt/webhooks/endpoints/.md) [Cada organização pode configurar múltiplos endpoints para receber notificações de eventos.](https://docs.billing.kobana.com.br/pt/pt/webhooks/endpoints/.md) --- # Endpoints de Webhook Cada organização pode configurar múltiplos endpoints para receber notificações de eventos. ## Campos do Endpoint[​](#campos-do-endpoint "Link direto para Campos do Endpoint") | Campo | Descrição | | ------------- | ---------------------------------------------- | | **URL** | Endereço HTTPS que receberá as notificações | | **Descrição** | Descrição do endpoint (máx 255 caracteres) | | **Eventos** | Lista de tipos de eventos inscritos | | **Segredo** | Chave HMAC-SHA256 para validação de assinatura | | **Ativo** | Se o endpoint está habilitado | ## Criando um Endpoint[​](#criando-um-endpoint "Link direto para Criando um Endpoint") Ao criar, o sistema gera automaticamente um **segredo** (`whsec_...`) que é mostrado **apenas na criação**. Armazene-o com segurança — ele é necessário para validar as assinaturas dos webhooks. ## Assinatura dos Webhooks[​](#assinatura-dos-webhooks "Link direto para Assinatura dos Webhooks") Cada entrega leva os headers padrão 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`) e o trio `webhook-id` / `webhook-timestamp` / `webhook-signature` no layout Standard Webhooks: ``` X-Kobana-Signature: v1, ``` ### Verificação[​](#verificação "Link direto para Verificação") 1. Leia `webhook-id`, `webhook-timestamp` e `webhook-signature` 2. Rejeite se o timestamp estiver a mais de 5 minutos do relógio atual 3. Reconstrua `delivery_id.timestamp.body_cru` e calcule o HMAC-SHA256 com a chave (base64 decodificado do secret sem o prefixo `whsec_`) 4. Compare com cada token `v1,` do header em tempo constante O algoritmo completo, com exemplos em Node.js e Python, está em [Referência da API — Webhooks](https://docs.billing.kobana.com.br/pt/pt/api/overview/webhooks.md#headers-e-assinatura-padr%C3%A3o-kobana). O header legado `X-Signature` (`t=,v1=`) continua sendo enviado, deprecado. ## Rotação de Segredo[​](#rotação-de-segredo "Link direto para Rotação de Segredo") Quando suspeitar que o segredo foi comprometido, use a rotação de segredo. Um novo segredo é gerado e o anterior é invalidado imediatamente. ## Teste de Webhook[​](#teste-de-webhook "Link direto para Teste de Webhook") Envie um payload de teste para verificar se o endpoint está configurado corretamente. O resultado inclui o status HTTP e a resposta recebida. ## Desativação Automática[​](#desativação-automática "Link direto para Desativação Automática") Após **10 falhas consecutivas** de entrega, o endpoint é **desativado automaticamente**. Para reativar, corrija o problema e atualize o endpoint para ativo. ## Proteção contra SSRF[​](#proteção-contra-ssrf "Link direto para Proteção contra SSRF") URLs são validadas para rejeitar IPs privados e localhost, prevenindo ataques de Server-Side Request Forgery. --- # Entregas de Webhook Cada notificação enviada a um endpoint é registrada como uma entrega, permitindo monitoramento e retry. ## Status da Entrega[​](#status-da-entrega "Link direto para Status da Entrega") | Status | Descrição | | ----------- | ------------------------------- | | `pending` | Aguardando envio | | `delivered` | Entregue com sucesso (HTTP 2xx) | | `failed` | Falha na entrega | | `retrying` | Aguardando nova tentativa | ## Campos da Entrega[​](#campos-da-entrega "Link direto para Campos da Entrega") | Campo | Descrição | | ------------------------- | --------------------------------------- | | **Endpoint** | Webhook de destino | | **Evento** | Evento que gerou a entrega | | **Status HTTP** | Código de resposta do destino | | **Headers da requisição** | Headers enviados | | **Body da requisição** | Payload enviado (JSON) | | **Headers da resposta** | Headers recebidos | | **Body da resposta** | Corpo da resposta (máx 2000 caracteres) | | **Erro** | Mensagem de erro (se falhou) | | **Tentativas** | Número de tentativas | | **Próximo retry** | Data/hora da próxima tentativa | | **Entregue em** | Timestamp de sucesso | ## Pipeline de Processamento[​](#pipeline-de-processamento "Link direto para Pipeline de Processamento") ### Etapa 1: Criação do Evento[​](#etapa-1-criação-do-evento "Link direto para Etapa 1: Criação do Evento") ``` Operação no recurso (ex: pagamento criado) → Evento criado no banco de dados → Job enfileirado: EVENT_DISPATCH ``` ### Etapa 2: Despacho do Evento[​](#etapa-2-despacho-do-evento "Link direto para Etapa 2: Despacho do Evento") ``` Worker processa EVENT_DISPATCH → Busca webhooks ativos da organização → Filtra por eventos inscritos → Para cada webhook correspondente: → Cria registro de WebhookDelivery → Enfileira job: WEBHOOK_DELIVERY ``` ### Etapa 3: Entrega[​](#etapa-3-entrega "Link direto para Etapa 3: Entrega") ``` Worker processa WEBHOOK_DELIVERY → Gera payload + assinatura → POST para URL do webhook (timeout: 30s) → Sucesso (2xx): marca como delivered, reseta contador de falhas → Falha: atualiza stats, agenda retry → Após 10 falhas consecutivas: desativa endpoint ``` ## Retry Automático[​](#retry-automático "Link direto para Retry Automático") * Entregas falhas são retentadas automaticamente * Backoff exponencial (1s, 2s, 4s, 8s...) * Máximo de tentativas configurável por job ## Retry Manual[​](#retry-manual "Link direto para Retry Manual") Entregas individuais podem ser retentadas manualmente pelo dashboard. ## Monitoramento[​](#monitoramento "Link direto para Monitoramento") Para cada organização: * Total de webhooks ativos/inativos * Total de entregas * Entregas com falha * Contadores de falhas consecutivas --- # Eventos de Webhook O sistema emite eventos para todas as operações significativas. Cada organização pode se inscrever nos tipos relevantes. ## Formato do Payload[​](#formato-do-payload "Link direto para Formato do 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` é o UUID do evento e `created_at` é ISO 8601 (UTC). Todos os campos do envelope usam `snake_case`. * `data` traz o recurso serializado no mesmo formato da API v1, também em `snake_case`. * `changes` é opcional: aparece nos eventos que carregam mudanças de campos (`.db.updated` e `*.status_changed`), no formato `{"campo": {"from": valorAntigo, "to": valorNovo}}`. ## Tipos de Eventos[​](#tipos-de-eventos "Link direto para Tipos de Eventos") ### Assinaturas (11 tipos)[​](#assinaturas-11-tipos "Link direto para Assinaturas (11 tipos)") | Evento | Descrição | | ----------------------------- | ----------------------- | | `subscription.db.created` | Assinatura criada | | `subscription.db.updated` | Assinatura atualizada | | `subscription.db.deleted` | Assinatura deletada | | `subscription.status_changed` | Status alterado | | `subscription.canceled` | Cancelada | | `subscription.paused` | Pausada | | `subscription.resumed` | Retomada | | `subscription.renewed` | Renovada | | `subscription.trial_ending` | Trial prestes a expirar | | `subscription.past_due` | Em atraso | ### Faturas (10 tipos)[​](#faturas-10-tipos "Link direto para Faturas (10 tipos)") | Evento | Descrição | | ------------------------ | ----------------------- | | `invoice.db.created` | Fatura criada | | `invoice.db.updated` | Fatura atualizada | | `invoice.db.deleted` | Fatura deletada | | `invoice.status_changed` | Status alterado | | `invoice.finalized` | Finalizada | | `invoice.paid` | Paga | | `invoice.payment_failed` | Pagamento falhou | | `invoice.voided` | Anulada | | `invoice.uncollectible` | Marcada como incobrável | | `invoice.overdue` | Vencida | ### Pagamentos (8 tipos)[​](#pagamentos-8-tipos "Link direto para Pagamentos (8 tipos)") | Evento | Descrição | | ------------------------ | -------------------- | | `payment.db.created` | Pagamento criado | | `payment.db.updated` | Pagamento atualizado | | `payment.db.deleted` | Pagamento deletado | | `payment.status_changed` | Status alterado | | `payment.processing` | Em processamento | | `payment.succeeded` | Bem-sucedido | | `payment.failed` | Falhou | | `payment.refunded` | Reembolsado | ### Métodos de Pagamento (5 tipos)[​](#métodos-de-pagamento-5-tipos "Link direto para Métodos de Pagamento (5 tipos)") | Evento | Descrição | | ------------------------------- | ----------------- | | `payment_method.db.created` | Método criado | | `payment_method.db.updated` | Método atualizado | | `payment_method.db.deleted` | Método removido | | `payment_method.status_changed` | Status alterado | | `payment_method.expired` | Expirado | ### Planos (4 tipos)[​](#planos-4-tipos "Link direto para Planos (4 tipos)") | Evento | Descrição | | ----------------- | ---------------- | | `plan.db.created` | Plano criado | | `plan.db.updated` | Plano atualizado | | `plan.db.deleted` | Plano deletado | | `plan.archived` | Plano arquivado | ### Produtos (6 tipos)[​](#produtos-6-tipos "Link direto para Produtos (6 tipos)") | Evento | Descrição | | ------------------------ | ------------------ | | `product.db.created` | Produto criado | | `product.db.updated` | Produto atualizado | | `product.db.deleted` | Produto deletado | | `product.status_changed` | Status alterado | | `product.archived` | Arquivado | | `product.restored` | Restaurado | ### Contas de Cobrança (5 tipos)[​](#contas-de-cobrança-5-tipos "Link direto para Contas de Cobrança (5 tipos)") | Evento | Descrição | | -------------------------------- | ---------------- | | `billing_account.db.created` | Conta criada | | `billing_account.db.updated` | Conta atualizada | | `billing_account.db.deleted` | Conta deletada | | `billing_account.status_changed` | Status alterado | | `billing_account.suspended` | Conta suspensa | ### Empresa, Clientes e Outros[​](#empresa-clientes-e-outros "Link direto para Empresa, Clientes e Outros") * `company.db.created` / `db.updated` / `db.deleted` / `status_changed` * `customer.db.created` / `db.updated` / `db.deleted` **Total: 56 tipos de eventos** --- # Faturamento Automático — Documentação ![Painel de Primeiros Passos do Faturamento Automático](/img/screenshots/pt-BR/primeiros-passos.png) Bem-vindo à documentação do Faturamento Automático, a plataforma B2B2C de faturamento, assinaturas e cobrança recorrente para o mercado brasileiro. ## Primeiros Passos[​](#primeiros-passos "Link direto para Primeiros Passos") O Faturamento Automático permite que organizações gerenciem assinaturas, faturas, pagamentos e conformidade fiscal (NF-e) de seus clientes através de uma plataforma completa com dashboard, portal do cliente e backoffice administrativo. ## Navegação[​](#navegação "Link direto para Navegação") ### Catálogo[​](#catálogo "Link direto para Catálogo") * [Planos e Produtos](https://docs.billing.kobana.com.br/pt/pt/planos-e-produtos.md) — Gerencie planos de assinatura, produtos, preços e grupos ### Assinaturas[​](#assinaturas "Link direto para Assinaturas") * [Assinaturas](https://docs.billing.kobana.com.br/pt/pt/assinaturas.md) — Ciclo de vida, mudança de plano, pausar, termos de cobrança ### Financeiro[​](#financeiro "Link direto para Financeiro") * [Faturas e Pagamentos](https://docs.billing.kobana.com.br/pt/pt/faturas-e-pagamentos.md) — Faturas, pagamentos, métodos de pagamento, créditos e parcelamento * [Cupons e Descontos](https://docs.billing.kobana.com.br/pt/pt/cupons-e-descontos.md) — Cupons promocionais e códigos de desconto * [Gestão de Inadimplência](https://docs.billing.kobana.com.br/pt/pt/gestao-de-inadimplencia.md) — Dunning, tentativas de pagamento, suspensão e recuperação ### Integrações[​](#integrações "Link direto para Integrações") * [Gateways de Pagamento](https://docs.billing.kobana.com.br/pt/pt/gateways-de-pagamento.md) — Provedores, configuração e callbacks * [Webhooks](https://docs.billing.kobana.com.br/pt/pt/webhooks.md) — Endpoints, eventos e entregas ### Fiscal[​](#fiscal "Link direto para Fiscal") * [Nota Fiscal Eletrônica](https://docs.billing.kobana.com.br/pt/pt/nota-fiscal.md) — Configuração, emissão automática e provedores de NF-e * [Impostos](https://docs.billing.kobana.com.br/pt/pt/impostos.md) — Motor de cálculo, regras fiscais, retenções e Simples Nacional ### Comercial[​](#comercial "Link direto para Comercial") * [Propostas Comerciais](https://docs.billing.kobana.com.br/pt/pt/propostas.md) — Criação, envio e aceitação de propostas ### Administração[​](#administração "Link direto para Administração") * [Contas](https://docs.billing.kobana.com.br/pt/pt/contas.md) — Organizações, contas de cobrança, clientes e portal * [Exportação e Importação](https://docs.billing.kobana.com.br/pt/pt/exportacao-e-importacao.md) — Exportar e importar dados em massa * [Configurações](https://docs.billing.kobana.com.br/pt/pt/configuracoes.md) — Empresa, cobrança, rate limiting, notificações e e-mails ---