Zum Hauptinhalt springen

Vodia Billing

Vodia Billing is standalone billing middleware for Vodia PBX fleets. It sits beside your PBX systems, receives their CDRs, and turns raw call records into invoices, accounting entries and fraud alerts.

It is a companion product to Vodia Analytics: the same architecture and the same interface conventions, but a separate server and a separate database. Analytics answers "what happened on the phones". Billing answers "what does this cost, who owes it, and has it been paid".

Version 1.0.0-beta

This is a beta release. See the Release Notes before billing a live customer, and run in parallel with your existing system for one to two full cycles.

What it does​

  • Ingests CDRs from one or more Vodia PBX systems over the PBX's own webcdr webhook, and recovers missed days from archive CSV files.
  • Rates outbound calls against your rate sheets, with per-destination charge types, connect fees, billing increments, minimum durations and included-minute allowances.
  • Counts recurring items from daily PBX snapshots: extensions, hunt groups, auto attendants, queues, DIDs, concurrent-call peaks.
  • Computes tax in per-bucket components, or hands tax computation to QuickBooks Online.
  • Produces invoices with gapless fleet-wide numbering, frozen detail, twelve languages, per-tenant branding and revocable share links.
  • Delivers by email with a call-detail CSV attached, and by CSV over SFTP, HTTP or email to a payment system.
  • Hands off to accounting — Xero or QuickBooks Online, with customer mapping, payment sync back, and per-invoice push state.
  • Chases payment with configurable reminder schedules and overdue alerts.
  • Watches for fraud with twenty detectors, optional automatic extension disable on the PBX, and per-tenant threshold overrides.
  • Reports margin per tenant per month, split by charge basis, with loss-makers flagged. Partner-only, never customer-visible.

Architecture​

Three containers behind a reverse proxy:

ContainerRole
caddyTLS termination via Let's Encrypt, reverse proxy to the API
apiNode.js / Fastify: HTTP API, web interface, scheduler, rating engine
mongoMongoDB 7: all billing data

The web interface is served directly by the API as static files. There is no build step and no separate frontend container.

The scheduler runs inside the API container. It takes daily PBX snapshots, runs fraud detectors, fires scheduled bill runs, sends payment reminders and syncs payments from the accounting package. Nothing depends on an external job queue.

The two shapes​

Almost every configuration question comes down to which of two shapes a tenant is in, and the difference is who computes the tax and who sends the invoice. These are deliberately separate concepts.

Shape 1 — Vodia Billing owns the invoice. You build a tax profile here, Vodia Billing computes tax per bucket, renders the invoice, emails it to the customer with the call detail attached, and chases it. Xero tenants are in this shape: Xero records the tax figures Vodia Billing supplies, because Xero's automated sales tax cannot run on invoices created through its API.

Shape 2 — the accounting package owns the invoice. QuickBooks Online computes its own tax as an external tax authority and emails the invoice itself. Vodia Billing supplies the lines; QuickBooks decides the tax and therefore owns the total. A difference between the QuickBooks total and the Vodia Billing total on such a tenant is expected and harmless.

Tenants with no accounting connection are self-billed: Vodia Billing computes tax and sends the invoice. These are also the only tenants where credits can be issued from within Vodia Billing, because on an external-tax tenant a credit has to be raised in the accounting package that owns the numbers.

The interface​

The sidebar groups every screen into four sections.

Setup — Systems, Tenants, Trunks, Plans, Catalogue, Tax. Configuration you do once, then revisit occasionally.

Operations — Spend, Rate Test, Alerts, Detection, Import. The day-to-day view of traffic, cost and anomalies.

Billing — Bill Runs, Schedules, Invoices, Terms & Reminders, Accounting, Export, Margin, Delivery. This month's money.

Account — Settings, Audit log, Security, Users. Your business identity, your own 2FA, and team access.

Money and precision​

All money is held in integer micro-units: 1,000,000 units is 1.00 in the tenant's currency. Nothing in the system uses floating-point currency arithmetic.

Invoice subtotals are rounded to cents before tax is computed, so the lines printed on an invoice and the invoice total can never disagree by a rounding remainder.

Discounts apply before tax, so they reduce the tax base. Credits apply after tax, because a credit is money already owed. Credits are recorded as adjustment links rather than balance decrements, so voiding an invoice restores the credit rather than destroying it.

Where to go next​

New here? Start with the Quick Start. It goes from a bare server to a first draft invoice in about an hour, with a worked example throughout, and it flags the one step everybody forgets: every trunk starts non-billable.