Customer → BillingAccount → PortalUser. Native multi-account.
A customer can have multiple billing accounts (branch, department, project). Each account with its own payment method, tax cycle and portal users.
Feature
∞
customers per organization
N
billing accounts per customer
CNPJ/CPF
automatically validated
LGPD
native export and delete
3-tier hierarchy
Customer
Registration entity. Individual (CPF) or company (CNPJ). Stores name, company name, document, addresses (JSON), emails (JSON), phones (JSON).
- DocumentType: cpf | cnpj
- PersonKind: natural | juridical
- Free custom data + metadata
BillingAccount
Billing account. Each customer can have several (Main Branch, RJ Branch, finance department). Consolidated MRR in mrrAmountCents.
- 3 statuses: active, suspended, closed
- paymentTermsDays (default 10 days)
- autoCollection toggle per account
- Own tax configuration
PortalUser
User who accesses the portal. Linked to a BillingAccount. SSO or password. Optional 2FA.
- Magic link, password, SSO
- 5 statuses (active, pending_verification, pending_invitation, suspended)
- Failed login attempts tracked
- Multiple users per billing account
What you can do
Complete Registration
Individual or company with full address (postal code, IBGE), multiple contacts (emails/phones), free tags.
- CPF/CNPJ digit validation
- Optional Revenue Bureau query (MinhaReceita)
- Tags + JSON customData for integration
Multi-Billing Account
A corporate customer can have independent accounts for branches or departments. Separate invoices, payment methods and portal.
- Individual invoices per account
- Report consolidation at Customer level
- Different permissions in portal
Bulk Import (CSV)
ImportService processes CSV with pre-import validation. Import worker runs in background, generating error report.
- Standard template provided
- Row-by-row validation
- Legacy system migration
Communication Schedule
Automatic notifications per event (invoice_created, payment_failed, trial_ending). Customizable templates per organization.
- Email (AWS SES)
- In-app (Notification)
- Webhook for integration
Payment History
All financial movements stored in StatementItem (credit/debit). Statement view in portal and dashboard.
- balanceCents balance per billing account
- Negative balance allowed with limit (allowedNegativeBalanceCents)
- Export in CSV/Excel
Suspension and Reactivation
BillingAccount with suspended status blocks new invoices and actions. suspendedAt + reason recorded. Reactivation via API or dashboard.
- Manual or automatic (dunning)
- Complete audit log
- Webhook billing_account.suspended
LGPD: Export and Deletion
DataPurgeService implements the right to be forgotten. Data-purge worker executes scheduled deletion with confirmation.
- Complete export in ZIP (data + invoices + payments)
- Soft delete on customers (deletedAt)
- Optional anonymization preserving accounting history
Tags and Segmentation
Free tags on Person + customMetadata. Advanced filters in listing for segmentation (high value, expiring, delinquent, by region).
- Tags as JSON array
- Combined filters (AND/OR)
- Save custom views
Create customer + 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": "finance@acme.com.br" }],
"addresses": [{
"street": "Av. Paulista",
"number": "1000",
"city": "São Paulo",
"state": "SP",
"zip_code": "01310100"
}],
"billing_accounts": [{
"billing_email": "finance@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 }
]
}