Customer → BillingAccount → PortalUser. Multi-conta nativo.
Um cliente pode ter várias contas de faturamento (filial, departamento, projeto). Cada conta com método de pagamento, ciclo fiscal e usuários do portal próprios.
Funcionalidade
∞
clientes por organização
N
billing accounts por cliente
CNPJ/CPF
validados automaticamente
LGPD
export e delete nativos
Hierarquia em 3 camadas
Customer
Entidade cadastral. Pessoa física (CPF) ou jurídica (CNPJ). Armazena nome, razão social, documento, endereços (JSON), e-mails (JSON), telefones (JSON).
- DocumentType: cpf | cnpj
- PersonKind: natural | juridical
- Custom data + metadata livres
BillingAccount
Conta de faturamento. Cada cliente pode ter várias (filial Matriz, filial RJ, departamento financeiro). MRR consolidado em mrrAmountCents.
- 3 status: active, suspended, closed
- paymentTermsDays (default 10 dias)
- autoCollection toggle por conta
- Configuração fiscal própria
PortalUser
Usuário que acessa o portal. Vinculado a um BillingAccount. SSO ou senha. 2FA opcional.
- Magic link, senha, SSO
- 5 status (active, pending_verification, pending_invitation, suspended)
- Failed login attempts trackados
- Múltiplos usuários por billing account
O que você pode fazer
Cadastro Completo
Pessoa física ou jurídica com endereço completo (CEP, IBGE), múltiplos contatos (e-mails/telefones), tags livres.
- Validação de dígitos CPF/CNPJ
- Consulta Receita opcional (MinhaReceita)
- Tags + customData JSON para integração
Multi-Conta de Faturamento
Um cliente corporativo pode ter contas independentes para filiais ou departamentos. Faturas, métodos de pagamento e portal separados.
- Faturas individuais por conta
- Consolidação de relatórios no Customer
- Permissões diferentes no portal
Importação em Massa (CSV)
ImportService processa CSV com validação pré-import. Worker import executa em background, gerando relatório de erros.
- Template padrão disponível
- Validação row-by-row
- Migração de sistemas legados
Régua de Comunicação
Notificações automáticas por evento (invoice_created, payment_failed, trial_ending). Templates personalizáveis por organização.
- Email (AWS SES)
- In-app (Notification)
- Webhook para integração
Histórico de Pagamentos
Toda movimentação financeira fica em StatementItem (credit/debit). Visão extrato no portal e dashboard.
- Saldo balanceCents por billing account
- Saldo negativo permitido com limite (allowedNegativeBalanceCents)
- Export em CSV/Excel
Suspensão e Reativação
BillingAccount com status suspended bloqueia novas faturas e ações. suspendedAt + razão registrados. Reativação via API ou dashboard.
- Manual ou automática (dunning)
- Audit log completo
- Webhook billing_account.suspended
LGPD: Exportação e Exclusão
DataPurgeService implementa direito ao esquecimento. Worker data-purge executa exclusão programada com confirmação.
- Export completo em ZIP (dados + faturas + pagamentos)
- Soft delete em customers (deletedAt)
- Anonimização opcional preservando histórico contábil
Tags e Segmentação
Tags livres em Person + customMetadata. Filtros avançados na listagem para segmentar (alto valor, vencendo, inadimplente, por região).
- Tags como array JSON
- Filtros combinados (AND/OR)
- Salvamento de visões customizadas
Criar cliente + billing account via API
bash
curl -X POST https://api.billing.kobana.com.br/v1/customers \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "ACME Tecnologia Ltda",
"document_type": "cnpj",
"document_number": "12.345.678/0001-90",
"kind": "juridical",
"emails": [{ "kind": "work", "address": "financeiro@acme.com.br" }],
"addresses": [{
"street": "Av. Paulista",
"number": "1000",
"city": "São Paulo",
"state": "SP",
"zip_code": "01310100"
}],
"billing_accounts": [{
"billing_email": "financeiro@acme.com.br",
"payment_terms_days": 15,
"customer_tax_type": "simples_optante",
"withhold_iss": false
}]
}'response
{
"id": "cust_xyz789",
"billing_accounts": [
{ "id": "ba_abc123", "status": "active", "mrr_amount_cents": 0 }
]
}