Accounting Integration & Sync

NexusRMS provides two-way synchronisation with leading accounting platforms, ensuring your invoices, payments, and client records stay consistent across systems. The integration also supports ZUGFeRD e-invoicing for EU compliance, allowing you to generate machine-readable invoices for clients in supported countries.

Supported platforms

NexusRMS connects to three accounting platforms via their official APIs:

• Xero — Full invoice, payment, and client synchronisation
• QuickBooks Online — Full invoice, payment, and client synchronisation
• Sage Business Cloud — Invoice and payment synchronisation

The AccountingSyncService automatically determines which platform is active for the current tenant by checking the TenantAccountingIntegration record with a connection_status of "connected".

Sync configuration

Navigate to Configuration > Financial Settings > Accounting Sync to manage your integration.

Account Mappings

Map each item_type (equipment, labour, service, delivery, custom) to the corresponding ledger account and tax_type in your accounting software. This ensures line items are posted to the correct accounts when invoices are synced.

Sync Modes

Choose when synchronisation occurs:

• manual — Sync only when you click the Sync button on an individual invoice or use the bulk export action
• on_create — Automatically sync when a new invoice is created
• on_send — Automatically sync when an invoice is sent to the client
• scheduled — Sync at a set time each day via the scheduled sync feature

Auto-Sync Options

Three independent toggle switches control which entities are synchronised automatically:

• Invoices — Push invoice data to the accounting platform
• Payments — Push payment records when received
• Clients — Create or update customer records in the accounting platform

Scheduled Sync

When the scheduled sync toggle is enabled, a time picker allows you to set the daily sync time. All pending invoices, payments, and clients are synchronised at the configured time.

Sync Statistics

The integration status panel displays key health metrics:

• total_syncs — Total number of sync operations performed
• successful — Number of successful syncs
• failed — Number of failed syncs
• health_score — A percentage representing successful syncs divided by total syncs

Invoice accounting fields

Each invoice tracks its accounting sync state through five dedicated fields:

• accounting_synced_at — Timestamp of the last successful sync
• accounting_external_id — The invoice ID in the external accounting system (e.g., Xero invoice ID)
• accounting_platform — Which platform the invoice is synced to (xero, quickbooks, or sage)
• accounting_sync_status — The current sync state (e.g., synced, pending, failed)
• accounting_sync_error — The error message from the last failed sync attempt

Sync status indicators on invoice list

The invoice list page displays a small icon next to each invoice to indicate its sync state:

• Cloud check icon — Invoice has been successfully synced
• Spinner icon — Sync is currently in progress
• Alert icon — Sync failed. Hover for the error message.

Payment accounting fields

The Payment model stores external IDs for each supported platform:

• xero_payment_id — Payment ID in Xero
• quickbooks_payment_id — Payment ID in QuickBooks
• sage_payment_id — Payment ID in Sage
• synced_from_accounting — Boolean indicating whether this payment was imported from an accounting platform rather than recorded in NexusRMS
• synced_at — Timestamp of the last sync

Payment methods for synced payments

When payments are imported from an accounting platform, they are assigned a platform-specific payment method:

• xero_sync — "Synced from Xero"
• quickbooks_sync — "Synced from QuickBooks"
• sage_sync — "Synced from Sage"

Tax rate external mapping

The TaxRate model includes fields for mapping to external accounting systems:

• external_id — The tax code ID in the connected accounting platform
• external_mapping — A JSON object containing platform-specific field mappings (e.g., account codes, tax group references)

When invoices are synced, the system uses external_id to map each line item's tax rate to the correct tax code in the accounting platform.

Bulk export

On the invoice list page, select multiple invoices using the checkboxes and click the Export to Accounting bulk action button. This queues all selected invoices for synchronisation with the connected platform.

ZUGFeRD e-invoicing

For EU compliance, NexusRMS generates ZUGFeRD/Factur-X compliant e-invoices that embed machine-readable XML data within a PDF/A-3 document.

How it works

• ZugferdService — Orchestrates the generation of ZUGFeRD-compliant PDFs and standalone XML
• ZugferdDataMapper — Maps Invoice model data to the ZUGFeRD XML schema (EN16931 compliant)
• shouldGenerateZugferd(Invoice) — Checks whether the client's billing country is in the list of ZUGFeRD-enabled countries
• getClientCountryCode() — Resolves the client's ISO 3166-1 alpha-2 country code from billing_country_code, country_code, or country name fields
• validateInvoice(Invoice) — Checks that all required fields are present (invoice_number, issue_date, client name, line items, total greater than zero, and seller company name)
• generateFromPdf(Invoice, sourcePdfPath) — Takes an existing branded PDF and embeds the ZUGFeRD XML to create a compliant document
• generateXml(Invoice) — Returns the raw XML content for inspection or standalone use

Supported countries

ZUGFeRD generation is triggered automatically for clients with a billing address in: Germany, France, Italy, Austria, Switzerland, Belgium, Netherlands, Luxembourg, Spain, Portugal, and Poland.

Tips

• Map accounts before syncing — Ensure all item types have a corresponding ledger account in the Account Mappings section before enabling auto-sync. Unmapped items will cause sync failures.
• Start with manual sync mode — Use manual sync for the first few weeks to verify that invoices and payments appear correctly in your accounting software before switching to on_send or scheduled mode.
• Check health_score regularly — A health_score below 90% indicates frequent sync failures. Review accounting_sync_error on failed invoices to identify the root cause.
• Map tax rates to external IDs — Set the external_id on each TaxRate to match the corresponding tax code in your accounting platform. This prevents "tax code not found" errors during sync.
• Validate before ZUGFeRD export — Use validateInvoice() to check that all required fields are present before generating a ZUGFeRD PDF. Missing fields will produce an invalid e-invoice.
• Test the connection periodically — The testConnection() method verifies that API credentials are still valid. OAuth tokens can expire, so re-authenticate if the connection test fails.