Customer → BillingAccount → PortalUser. Multi-cuenta nativo.
Un cliente puede tener varias cuentas de facturación (filial, departamento, proyecto). Cada cuenta con método de pago, ciclo fiscal y usuarios del portal propios.
Funcionalidad
∞
clientes por organización
N
billing accounts por cliente
CNPJ/CPF
validados automáticamente
LGPD
export y delete nativos
Jerarquía en 3 capas
Customer
Entidad catastral. Persona física (CPF) o jurídica (CNPJ). Almacena nombre, razón social, documento, direcciones (JSON), emails (JSON), teléfonos (JSON).
- DocumentType: cpf | cnpj
- PersonKind: natural | juridical
- Custom data + metadata libres
BillingAccount
Cuenta de facturación. Cada cliente puede tener varias (filial Matriz, filial RJ, departamento financiero). MRR consolidado en mrrAmountCents.
- 3 estados: active, suspended, closed
- paymentTermsDays (default 10 días)
- autoCollection toggle por cuenta
- Configuración fiscal propia
PortalUser
Usuario que accede al portal. Vinculado a un BillingAccount. SSO o contraseña. 2FA opcional.
- Magic link, contraseña, SSO
- 5 estados (active, pending_verification, pending_invitation, suspended)
- Failed login attempts registrados
- Múltiples usuarios por billing account
Qué puedes hacer
Registro Completo
Persona física o jurídica con dirección completa (CEP, IBGE), múltiples contactos (emails/teléfonos), etiquetas libres.
- Validación de dígitos CPF/CNPJ
- Consulta Receita opcional (MinhaReceita)
- Tags + customData JSON para integración
Multi-Cuenta de Facturación
Un cliente corporativo puede tener cuentas independientes para filiales o departamentos. Facturas, métodos de pago y portal separados.
- Facturas individuales por cuenta
- Consolidación de informes en el Customer
- Permisos diferentes en el portal
Importación en Masa (CSV)
ImportService procesa CSV con validación pre-import. Worker import ejecuta en background, generando informe de errores.
- Template estándar disponible
- Validación row-by-row
- Migración de sistemas legacy
Régua de Comunicación
Notificaciones automáticas por evento (invoice_created, payment_failed, trial_ending). Templates personalizables por organización.
- Email (AWS SES)
- In-app (Notification)
- Webhook para integración
Historial de Pagos
Toda movimentación financiera queda en StatementItem (credit/debit). Vista extracto en portal y dashboard.
- Saldo balanceCents por billing account
- Saldo negativo permitido con límite (allowedNegativeBalanceCents)
- Export en CSV/Excel
Suspensión y Reactivación
BillingAccount con estado suspended bloquea nuevas facturas y acciones. suspendedAt + razón registrados. Reactivación vía API o dashboard.
- Manual o automática (dunning)
- Audit log completo
- Webhook billing_account.suspended
LGPD: Exportación y Exclusión
DataPurgeService implementa derecho al olvido. Worker data-purge ejecuta exclusión programada con confirmación.
- Export completo en ZIP (datos + facturas + pagos)
- Soft delete en customers (deletedAt)
- Anonimización opcional preservando historial contable
Etiquetas y Segmentación
Tags libres en Person + customMetadata. Filtros avanzados en el listado para segmentar (alto valor, venciendo, moroso, por región).
- Tags como array JSON
- Filtros combinados (AND/OR)
- Guardado de vistas personalizadas
Crear cliente + billing account vía 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 Tecnología Ltda",
"document_type": "cnpj",
"document_number": "12.345.678/0001-90",
"kind": "juridical",
"emails": [{ "kind": "work", "address": "finanzas@acme.com.br" }],
"addresses": [{
"street": "Av. Paulista",
"number": "1000",
"city": "São Paulo",
"state": "SP",
"zip_code": "01310100"
}],
"billing_accounts": [{
"billing_email": "finanzas@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 }
]
}