Overview

This guide describes how BUSY — the on-premise Windows accounting + ERP by BUSY Infotech — connects to TrustBill, a UAE FTA-accredited service provider (ASP), so BUSY users in the UAE can issue PINT-AE compliant e-invoices without switching software.

BUSY is a desktop-first product widely used by retail, wholesale, distribution and trading SMEs across the Middle East and South Asia. Modern BUSY versions (18+) ship UAE VAT localization, including 15-digit TRN, UAE VAT tax types, and Arabic-friendly invoice layouts. But BUSY does not ship a native PINT-AE XML generator or a UAE ASP transmission channel.

TrustBill fills that gap through a small Windows service — the TrustBill Desktop Agent for BUSY — installed on the same PC (or LAN server) as BUSY. The agent reads posted vouchers via BUSY's XML export / ODBC surface, ships them to TrustBill over TLS 1.3, and TrustBill generates PINT-AE XML, validates it, and delivers it via a certified UAE ASP (Tron-Stride or Storecove). The FTA acknowledgement reference is written back into the invoice's Narration field on the next agent cycle.

What this integration delivers

Read-only Windows agent — cannot create, edit, delete or post vouchers in BUSY
Works with BUSY 14 through BUSY 22, Basic / Standard / Enterprise editions, and BUSY on Cloud
Sales, Sales Return, Purchase and Purchase Return vouchers mapped to PINT-AE document types
BUSY UAE VAT tax types (5% Standard, Zero-Rated, Exempt, Reverse Charge, Out of Scope) auto-mapped to FTA tax categories
Arabic + English legal names preserved end to end (PINT-AE requires Arabic seller name)
FTA acknowledgement stamped back into the voucher Narration on the next agent cycle
Bulk migration path for historical BUSY vouchers via XML export or CSV
Multi-company + multi-financial-year BUSY databases supported

What is BUSY?

BUSY Accounting Software is a Windows-based accounting + inventory + ERP product developed by BUSY Infotech Pvt. Ltd. It is one of the most widely-installed accounting products across South Asia and the GCC, especially for retail, wholesale, distribution and light manufacturing SMEs.

Ships as a Windows installer; data stored locally in the BUSY folder (default C:\BUSY{version}\Data\{company}) or on a LAN file server / SQL backend on Enterprise
Modules: Accounting, Inventory, VAT/GST, POS, MRP, TDS, Payroll, Fixed Assets
Editions: Basic (single-user, single-company), Standard (multi-user LAN), Enterprise (multi-user LAN + advanced modules + SQL backend)
Additional products: BUSY on Cloud (RDP-hosted desktop BUSY), BUSY Mobile (companion iOS/Android app), BizNext (newer web-native product line)
Import / Export via a documented XML dialect and CSV; ODBC access on Enterprise
UAE VAT localization has shipped since BUSY 18 (rolled out with the 2018 UAE VAT introduction) — TRN, VAT tax types, VAT 201 return format

Why BUSY needs an ASP bridge: BUSY posts VAT correctly on its own — including 15-digit TRN handling — but the invoice output is a PDF (Print / Email) or a BUSY-XML that is not PINT-AE compliant. UAE FTA e-invoicing requires structured PINT-AE XML transmitted over Peppol via an accredited ASP. TrustBill is that ASP.

Supported BUSY Versions & Editions

The TrustBill Desktop Agent works with every BUSY release from BUSY 14 onwards. The optimal starting point for UAE FTA e-invoicing is BUSY 18 or newer because that is when UAE VAT localization landed.

BUSY release	UAE VAT localization	XML export	ODBC	Support level
BUSY 22 (current)	Yes	Yes	Enterprise	Full — recommended
BUSY 21	Yes	Yes	Enterprise	Full
BUSY 20 / 19	Yes	Yes	Enterprise	Full
BUSY 18	Yes (initial UAE VAT rollout)	Yes	Enterprise	Full — recommend upgrading to BUSY 21+ for latest patches
BUSY 17 / 16 / 15 / 14	Legacy — no UAE VAT prior to BUSY 18	Yes	Enterprise only	Best-effort — customer must have manually configured VAT and TRN fields; upgrade strongly recommended
BUSY versions older than 14	No	Limited	No	Not supported — upgrade required

Editions and deployment models

Product	Deployment	Data backend	Support level
BUSY Basic	Single-PC on-premise	Local file store	Full via XML export path
BUSY Standard	LAN multi-user (up to ~10 concurrent)	Shared file store on server	Full — recommended
BUSY Enterprise	LAN multi-user + advanced modules	SQL backend (SQL Server Express / full)	Full — ODBC also available
BUSY on Cloud	RDP-hosted BUSY on a BUSY Infotech Windows VM	SQL backend on the hosted VM	Full — Desktop Agent installed inside the hosted VM (outbound HTTPS to TrustBill required)
BUSY BizNext	Web-native successor to desktop BUSY	Cloud SQL	Supported via BizNext REST API (see connection methods)

Prerequisites

On the BUSY side

BUSY 18 or newer with UAE VAT localization enabled (Administration → Configuration → Features / Options → VAT Applicable → United Arab Emirates)
Windows 10 / 11 / Server 2019+ running BUSY (or a BUSY on Cloud VM)
Company Info populated with the 15-digit UAE TRN under Company → TRN No. and legal names in both English and Arabic
Party (customer / vendor) master records populated with 15-digit TRN for B2B and country
VAT Tax Categories configured for UAE — Standard 5%, Zero-Rated, Exempt, Reverse Charge, Out of Scope (BUSY ships these as defaults on UAE-VAT-enabled companies)
A Windows account with read permission on the BUSY data folder (for XML export path) or an ODBC-enabled BUSY Enterprise installation
BUSY set to Enable XML Import / Export under Administration → Configuration → Import/Export (required for the XML export path)

On the TrustBill side

A TrustBill SME account (one account = one TRN = one BUSY company)
Completed KYB (business verification) — trade licence + TRN certificate uploaded
Submission mode set to test or sandbox during onboarding, live for production
The Desktop Agent is downloaded from Sources → Add BUSY — no manual credential setup, the wizard mints a fresh shared secret

Integration Architecture

BUSY has no cloud API surface of its own, so the data-flow model mirrors what we use for QuickBooks Desktop: the customer's Windows agent pushes to TrustBill rather than TrustBill polling BUSY.

Outbound flow (BUSY → TrustBill → FTA)

A user posts a Sales voucher in BUSY (Transactions → Sales → Add).
The TrustBill Desktop Agent's scheduler wakes on its poll interval (default: every 5 minutes) and asks BUSY for vouchers modified since the last sync via the XML export (or ODBC / BizNext REST — depending on your configured path).
The agent serialises the vouchers into TrustBill's InvoiceCreateInput shape and POSTs them to https://api.trustbill.ae/v1/invoices over TLS 1.3 with the agent's Bearer JWT.
TrustBill stores the invoice as draft.
If auto-submit is enabled, POST /v1/invoices/submit fires immediately; otherwise the invoice waits for a manual Submit-to-FTA in the TrustBill dashboard.
Pipeline: queued → transformed → validated → delivered. ASP forwards to FTA over Peppol.

Inbound flow (FTA → TrustBill → BUSY)

The ASP posts an inbound webhook to TrustBill when the FTA acknowledges or rejects the invoice.
TrustBill's BUSY worker enqueues a Narration write-back keyed on the BUSY voucher's UUID.
On the agent's next cycle, it dequeues pending write-backs and updates the invoice's Narration field via a BUSY XML import (or ODBC UPDATE on Enterprise).
The Narration stamp format is TrustBill: {status} · {peppol-uuid} · {ISO date} — short by design so it doesn't push out the user's own narration.
Latency: up to one poll interval (default 5 min) after FTA ack.

Connection Methods

Four ways to bridge BUSY to TrustBill. All except CSV run through the Desktop Agent.

1. Desktop Agent + BUSY XML Import/Export (recommended)

The agent uses BUSY's own documented XML dialect — the same feature customers use for bank statement import, master transfer, etc. This works on every BUSY edition including Basic and BUSY on Cloud.

Works on Basic / Standard / Enterprise / BUSY on Cloud
No SQL access required — reads from the BUSY data folder
Delta-only sync via BUSY's Last Modified filter
Write-back done via XML import — BUSY's own transaction log preserves auditability

2. Desktop Agent + ODBC (Enterprise only)

BUSY Enterprise exposes the SQL backend over ODBC. Faster than XML export for large volumes and lets the agent write back with a simple UPDATE.

BUSY Enterprise only
Faster on very high-volume companies (~500+ vouchers / day)
Read-only queries on the invoice tables; single UPDATE on Narration for write-back
Requires a Windows ODBC DSN pointed at the BUSY SQL instance

3. BUSY BizNext REST API

For customers on BUSY BizNext (the newer cloud-native product line), TrustBill uses the BizNext REST API directly — no agent needed, same pattern as Zoho / QBO.

BizNext only — desktop BUSY still needs the agent
Real-time push via BizNext webhooks + REST fetch-back
API key + workspace ID authentication

4. CSV Export (one-off migrations)

For historical vouchers, export via Display → Voucher Register → Print / Export → CSV. Use TrustBill's busy-csv-normaliser script to remap columns, then upload via POST /v1/invoices/bulk.

Which method should I use?

For 90% of desktop BUSY customers, use the Desktop Agent + XML path — no SQL setup, works on all editions. Switch to ODBC only if you're on Enterprise with high voucher volume. Use BizNext REST only if you actually run BUSY BizNext (not desktop BUSY). Use CSV only for historical migrations before go-live.

TrustBill Desktop Agent for BUSY

A signed Windows service (~15 MB) installed on the same machine as BUSY (or on any LAN host that can reach the BUSY data folder). Once installed, it runs headless — no UI to keep open.

Install steps

Sign into TrustBill → Sources → Add BUSY. Enter a display name and click Continue.
TrustBill mints a fresh 32-byte shared secret and returns a signed installer URL. Copy the plaintext secret — shown once.
Download the installer, run it as Administrator. The wizard asks for: BUSY data folder path (or ODBC DSN), the shared secret, and the TrustBill API endpoint (pre-filled).
The installer registers a Windows service TrustBill BUSY Agent (auto-start, "Local System" or a dedicated service account).
Within one poll cycle, the connection status in the TrustBill Sources page flips from Awaiting first sync to Connected.

Configuration file

The agent's C:\ProgramData\TrustBill\busy-agent\config.yaml holds the runtime settings:

api_endpoint: https://api.trustbill.ae
tenant_id: <redacted>
shared_secret: <argon2id-hash-only>
busy:
  method: xml            # xml | odbc | biznext
  data_path: C:\BUSY22\Data\MyCompany
  odbc_dsn: null         # required if method: odbc
  company_code: MYC
  financial_year: 2026-27
poll_interval_seconds: 300
prices_include_vat: false
seller_arabic_name: "شركة تجارية ذ.م.م"

Where to run the agent: the agent must reach BUSY's data folder AND make outbound HTTPS to api.trustbill.ae. On single-PC BUSY installs, run it on the same PC. On LAN multi-user Standard/Enterprise, run it on the BUSY database server, not on every workstation. For BUSY on Cloud, run it inside the hosted VM.

Authentication (Shared Secret)

The Desktop Agent authenticates to TrustBill with a per-connection shared secret — same argon2id-hash pattern used for the QuickBooks Desktop QBWC integration.

Aspect	Detail
Secret length	32 bytes, base64-encoded
Storage on TrustBill	Argon2id hash only — never re-shown after generation
Storage on the agent	Windows DPAPI-encrypted at rest in `config.yaml`
Session model	Agent exchanges secret for a short-lived JWT (60 min), refreshed automatically
Rotation	TrustBill Sources → BUSY → Rotate Secret. Rotation preserves connection identity; only the agent needs the new secret pasted in

Idempotency-Key derivation for BUSY

Every TrustBill write endpoint requires an Idempotency-Key. Derive it from BUSY's stable UUID for the voucher:

Idempotency-Key: busy::{company_code}::{financial_year}::voucher::{voucher_uuid}

Agent retries after a network blip reuse the same key — TrustBill returns the cached response, so duplicates never reach the FTA.

BUSY → PINT-AE Field Mapping

The agent translates BUSY's XML voucher shape (Sales / Sales Return / Purchase / Purchase Return) into TrustBill's InvoiceCreateInput. Below is the mapping. BUSY field names follow BUSY's own XML dialect.

Header-level mapping

BUSY field	TrustBill field	Notes
`Voucher.VchNo`	`number`	Human-readable ("SI/2026-27/00042"); 1–64 chars
`Voucher.VchUUID`	Idempotency-Key + `sellerInvoiceReference`	BUSY-internal UUID; stable across renumbering
`Voucher.Date`	`issueDate`	DD-MM-YYYY converted to ISO YYYY-MM-DD
`Voucher.DueDate`	`dueDate`	Optional
`Voucher.Type`	`invoiceType`	Sales → `sale`, Purchase → `purchase`, Sales Return → `credit_note`, Purchase Return → `debit_note`
`Voucher.Currency`	`currency`	Must be `AED`; multi-currency vouchers converted at `ExchangeRate`
`Company.LegalNameEnglish`	`seller.name`	From BUSY Company Info
`Company.LegalNameArabic` (or agent config `seller_arabic_name`)	`seller.legalNameArabic`	Required by PINT-AE; fallback to agent config if the BUSY field is blank
`Company.TRN`	`seller.trn`	15-digit UAE TRN
`Party.Name`	`buyer.name`	Party ledger name
`Party.NameArabic`	`buyer.legalNameArabic`	Preserved when populated
`Party.TRN`	`buyer.trn`	15-digit TRN; leave empty for B2C
`Party.Country`	`buyer.country`	Normalised to ISO 3166-1 alpha-2
`Party.Address1..3`, `City`, `State`	`buyer.address.{line1,line2,city,state}`	—
`Voucher.RefVchNo`	`referencedInvoiceNumber`	Required for Sales Return / Purchase Return — original voucher number
`Voucher.Narration`	`notes`	Preserved verbatim + used as the write-back target — see write-back

Line-level mapping (`ItemDetails/Item`)

BUSY field	TrustBill field	Notes
`Item.Name` / `ItemDesc`	`lines[].description`	Supports Arabic when Company code page is Unicode
`Item.Qty`	`lines[].quantity`	Must be > 0 (positive on returns too; the invoiceType handles the sign)
`Item.Rate`	`lines[].unitPrice`	VAT-exclusive; connector strips VAT if `prices_include_vat: true` in agent config
`Item.DiscAmt` / `Item.DiscPercent`	`lines[].discountAmount`	Per-line discount, applied before VAT
`Item.Alias` / `Item.Code`	`lines[].sellerItemId`	Preserved for traceability
`Item.UOM`	`lines[].unit`	BUSY UOM mapped to UN/ECE Rec 20 (Nos → C62, Kg → KGM, Ltr → LTR, Hrs → HUR)
`Item.TaxCategory` / `Item.VATType`	`lines[].vatRate` + `lines[].taxCategory`	Mapped via the BUSY VAT Type Mapping table
`Voucher.VoucherClass`	tax category hint	e.g. "Sales — Zero Rated Export" overrides individual line VAT type

Totals are computed server-side

Do not send BUSY's Voucher.NetAmt / TaxAmt / GrossAmt. TrustBill re-computes totals from lines[] and returns them. If BUSY's total differs from TrustBill's by more than ±0.01 AED, the connector logs a variance — usually because BUSY's Rounding-Off ledger adjusts a rounding penny that TrustBill doesn't yet see. Add the Rounding-Off ledger to your BUSY VAT mapping as out_of_scope and it will pass on the next cycle.

Create Invoice (draft)

Endpoint: POST /v1/invoices

A real BUSY Sales voucher mapped to the TrustBill payload. BUSY voucher: SI/2026-27/00042 — Sale of 20 GPS trackers to a Dubai reseller at 5% VAT.

Request body

{
  "number": "SI/2026-27/00042",
  "issueDate": "2026-09-08",
  "dueDate": "2026-10-08",
  "currency": "AED",
  "invoiceType": "sale",
  "buyer": {
    "name": "Al Manara Electronics LLC",
    "legalNameArabic": "المنارة للإلكترونيات ذ.م.م",
    "trn": "100756432100011",
    "country": "AE",
    "email": "purchase@almanara.example",
    "address": {
      "line1": "Deira Electronics Souk, Shop 42",
      "city": "Dubai",
      "country": "AE"
    }
  },
  "seller": {
    "name": "BUSY Trading LLC",
    "legalNameArabic": "بيزي التجارية ذ.م.م",
    "trn": "100100100100017",
    "country": "AE"
  },
  "lines": [
    {
      "description": "GPS Vehicle Tracker — 4G LTE",
      "sellerItemId": "GPS-4G-V2",
      "quantity": 20,
      "unit": "C62",
      "unitPrice": 275.00,
      "vatRate": 0.05,
      "taxCategory": "standard_5"
    }
  ],
  "sellerInvoiceReference": "BUSY VchUUID f3c8b2a1-....",
  "notes": "Payment on delivery"
}

Response (201 Created) — abbreviated:

{
  "id": "b8e2a1c4-....-uuid",
  "number": "SI/2026-27/00042",
  "status": "draft",
  "invoiceType": "sale",
  "totals": { "subtotal": 5500, "tax": 275, "total": 5775, "currency": "AED" },
  "pipeline": [],
  "errors": [],
  "submissionMode": "sandbox",
  "source": "busy-desktop-agent"
}

Sales Return & Purchase Return

BUSY records Sales Returns (Credit Notes) and Purchase Returns (Debit Notes) as separate voucher types. The agent maps them directly.

BUSY voucher	`invoiceType`	Required extra fields
Sales Return / Credit Note (Sales Type: Return)	`credit_note`	`referencedInvoiceNumber` = `Voucher.RefVchNo`, `reasonCode`
Purchase Return / Debit Note	`debit_note`	`referencedInvoiceNumber` = original Purchase voucher, `reasonCode`

Sign convention: BUSY posts returns with positive quantities and positive rates — send them the same way to TrustBill. The invoiceType tells the FTA that the document reverses the reference voucher; PINT-AE handles the sign in the XML.

Submit Invoice(s) for Delivery

Creating a draft in TrustBill does not deliver the invoice to the FTA. Submission is an explicit second call.

Endpoint: POST /v1/invoices/submit

{ "ids": ["b8e2a1c4-....-uuid"] }

BUSY-specific UX: BUSY has no in-app plug-in surface for a third-party "Send to FTA" button, so auto-submit on ingest is the recommended pattern. The bookkeeper's Save in BUSY is effectively the send-to-FTA moment; the agent auto-submits within one poll interval.

Status Tracking & Narration Write-back

Because BUSY has no custom-field infrastructure like Zoho or QBO, write-back rides on the invoice's Narration field. Only stable statuses are stamped so the field doesn't flap during pipeline transitions.

Narration stamp format

TrustBill: {status} · {peppol-uuid} · {ISO date}

Short by design — BUSY's Narration field is typically 500 chars and bookkeepers often add their own notes. The stamp is prefixed with TrustBill: so it can be regex-stripped for re-exports.

TrustBill status	Written back to BUSY Narration?
draft / queued / transformed / validated	No — not stable enough to stamp
delivered	Yes — stamped on next agent cycle
acknowledged	Yes — stamp refreshed with the FTA ack ref
rejected	Yes — Narration shows `TrustBill: rejected · <reject code>`

The agent's write-back cron (every 10 minutes across pods, guarded by a Postgres advisory lock) picks up pending stamps and issues one BUSY XML import (or one ODBC UPDATE) per invoice. Latency is at most one poll interval + 10 minutes after FTA ack.

Bulk Migration from BUSY

The Desktop Agent pulls the last 12 months by default on first sync. For older history, use CSV export:

In BUSY: Display → Voucher Register → filter by date range → Print / Export → CSV
Run the TrustBill busy-csv-normaliser script to remap BUSY column headers
Upload in test mode via POST /v1/invoices/bulk
Review the summary; repeat in sandbox and live

TrustBill CSV column headers

number,issueDate,dueDate,invoiceType,currency,sellerTrn,sellerName,sellerLegalNameArabic,buyerTrn,buyerName,buyerLegalNameArabic,buyerCountry,buyerAddressLine1,buyerCity,lineDescription,lineQty,lineUnit,lineUnitPrice,lineVatRate,lineTaxCategory,referencedInvoiceNumber,notes

Limit	Value
Max rows per file	1,000 vouchers
Max file size	5 MB
Partial success	Yes — bad rows reported without rolling back the batch

Test / Sandbox / Live Modes

BUSY does not have a separate sandbox instance. Use TrustBill's mode switch + a spare BUSY financial year (or a copied company) to isolate testing.

TrustBill mode	Purpose	Reaches FTA?
`test`	Local integration testing — no ASP call	No
`sandbox`	End-to-end dry run against the ASP sandbox	FTA sandbox only
`live`	Real, legally binding e-invoicing	Yes — the FTA production network

BUSY-specific tip: use BUSY's Copy Company Data feature to create a sandbox copy of your production company for the first VAT-return period. Point the agent at the copy in sandbox mode, verify totals match BUSY's VAT Computation report, then re-point at production in live mode.

BUSY VAT Type Mapping (UAE)

BUSY UAE localization ships a preset of VAT tax types. The agent auto-maps them by name and rate. Custom-named types (common in older BUSY companies migrated from pre-VAT setups) need a one-time mapping in the agent config.

Typical BUSY VAT Type name	Rate	TrustBill `vatRate`	TrustBill `taxCategory`
VAT @ 5% Sales / Standard Rated	5%	0.05	`standard_5`
Zero Rated Sales — Export	0%	0	`zero_rated_export`
Zero Rated Sales — Healthcare	0%	0	`zero_rated_healthcare`
Zero Rated Sales — Education	0%	0	`zero_rated_education`
Exempt Sales — Financial	Exempt	0	`exempt_financial`
Exempt Sales — Residential Rent	Exempt	0	`exempt_residential_rent`
RCM Sales / Designated Zone	0%	0	`reverse_charge_designated_zone`
Out of Scope Sales	Non-taxable	0	`out_of_scope`

The agent reads Item.TaxCategory and Item.VATType and matches by name-plus-rate. Names differ slightly across BUSY versions and Arabised builds — add each variant to the agent config's tax_mapping: section for a one-time fix.

UAE-Specific Scenarios

Free Zone / Designated Zone sellers

Set the flag on your TrustBill tenant (Settings → Company → Zone Type = Designated) — BUSY has no company-level designated-zone flag. The flag flows through as seller.designatedZone: true so PINT-AE emits the free-zone declaration correctly.

Margin scheme (used cars, antiques, second-hand goods)

Use BUSY's Item Category field on the item master and add the category name (e.g. "Margin Scheme — Used Cars") to the agent's margin_scheme_categories list. The agent sends lines[].marginScheme: true and uses the item's Cost as the margin base.

Reverse charge on imports

Purchase vouchers from non-UAE vendors using the RCM tax type are mapped to invoiceType: purchase + taxCategory: reverse_charge_designated_zone. PINT-AE emits the ReverseCharge markers.

B2C simplified tax invoices (POS)

BUSY POS receipts land in the same voucher table with Voucher.Type = POSSale. Vouchers where the Party has no TRN and total < 10,000 AED emit the PINT-AE simplified profile automatically.

Bilingual (Arabic + English) legal names

PINT-AE requires the seller's Arabic legal name. BUSY 20+ has a dedicated Arabic-name field on Company Info; on older versions, the agent's seller_arabic_name config is used as a fallback. Buyer Arabic names are read from Party.NameArabic when present.

Multi-Company & Multi-Financial-Year

Multi-company BUSY

One BUSY installation typically holds many companies (one folder per legal entity under C:\BUSY\Data). Each company = one TRN = one TrustBill tenant. Configure the agent with a companies: list — one entry per company code, each with its own tenant credential.

Multi-financial-year

BUSY partitions vouchers by financial year (e.g. 2025-26, 2026-27). The agent tracks the "current" and "previous" financial years so late-posted vouchers in a closed year still sync. Set the current year in config.yaml → busy.financial_year; the agent adjusts the XML export filter accordingly.

Error Handling

Three failure surfaces: BUSY-side XML export errors (agent log), TrustBill pipeline errors (dashboard), and Narration write-back errors (agent log + dashboard).

Layer	Symptom	Root cause	Action
Agent	Agent log: "cannot open BUSY data folder"	Service account lacks NTFS read permission	Grant the service account read access to the BUSY data folder
Agent	Agent log: "BUSY XML import feature not enabled"	Import/Export unticked in BUSY Configuration	In BUSY: Administration → Configuration → Features/Options → Enable XML Import/Export
Pipeline	`invalid_body` — missing buyer TRN	Party's TRN field empty	Fill it in BUSY Party master; agent auto-retries on next cycle
Pipeline	`arabic_seller_name_required`	Company Arabic legal name empty (common on English-first setups)	Fill BUSY Company → Legal Name (Arabic), or set `seller_arabic_name` in agent config
Pipeline	`totals_mismatch`	BUSY Rounding-Off ledger not mapped	Add BUSY's Rounding-Off ledger to agent config `tax_mapping` as `out_of_scope`
Pipeline	`unknown_tax_type`	Custom-named BUSY VAT type not mapped	Add the name → category to agent config `tax_mapping`
Pipeline	`uae_vat_not_enabled`	Company was set up before BUSY 18 with pre-VAT config	In BUSY: Administration → Configuration → Features/Options → VAT Applicable → UAE
Pipeline	409 `invoice_number_duplicate`	Same VchNo posted in two BUSY companies	Use per-company voucher number prefix in Administration → Voucher Series
Write-back	Narration stamp doesn't appear	Voucher is in a locked financial year, or user lacks Modify permission	Unlock the FY (Administration → Configuration → Financial Year → Lock Period) or grant Voucher-Modify to the agent's user
Agent	Duplicate FTA submissions after service restart	Agent lost its "already sent" marker	Confirm Idempotency-Key formula uses `VchUUID` — duplicates are safely deduped on TrustBill side

Setup Checklist

Confirm BUSY version (18+) and enable UAE VAT localization
Enable XML Import/Export in BUSY Configuration (required for the XML path)
Fill the TRN on Company Info
Fill the Arabic legal name on Company Info (or set seller_arabic_name in agent config later)
Populate Party TRNs for B2B customers
Confirm the eight UAE VAT tax types exist (Standard 5%, Zero-Rated Export/Healthcare/Education, Exempt Financial/Rent, RCM Designated Zone, Out of Scope)
Create your TrustBill SME account and complete KYB (trade licence + TRN certificate)
Open the Connect BUSY wizard in the TrustBill dashboard (Sources → Add Source → BUSY)
Copy the one-time shared secret shown in step 2 of the wizard
Download and run the Desktop Agent installer as Administrator on the BUSY PC / server
Point the wizard at the BUSY data folder (or configure ODBC on Enterprise)
Enable sandbox mode in TrustBill
Post a test Sales voucher in BUSY — confirm it reaches acknowledged in TrustBill within one poll interval + 3 min
Reconcile BUSY's Display → Statutory Reports → VAT → VAT Computation against TrustBill's Delivered Invoices
Switch to live mode when FTA registration is complete

Suggested test cases before go-live

B2B Sales voucher, single line, 5% VAT — expect acknowledged
POS Sales < 10,000 AED with no Party TRN — expect PINT-AE "simplified" profile
Sales Return referencing an earlier Sales voucher — expect matching pair
Export sale (Party country = SA, USA, etc.) — expect zero_rated_export
Designated-zone customer — expect reverse-charge markers
Multi-line voucher with mixed VAT (5% + 0%) — expect two taxCategory values
Voucher with a Rounding-Off ledger row — expect totals to match
Multi-currency voucher (USD → AED via ExchangeRate) — expect conversion, matching totals
Multi-company BUSY database — expect vouchers routed to the correct TrustBill tenant per company code
Late-posted voucher in the previous financial year — expect it still to sync
Bulk upload of 500 historical vouchers via CSV — expect partial success reported per row

Troubleshooting

Symptom	Likely cause	Fix
Agent installed but no invoices reach TrustBill	Windows Service stopped, or agent points to wrong company folder	Check services.msc → TrustBill BUSY Agent = Running; check `config.yaml → busy.data_path`
Agent log shows "auth: nvu"	Shared secret pasted incorrectly, or rotated on TrustBill side	Rotate the secret in TrustBill Sources; paste the new value into agent config; restart the service
Agent hangs on "Contacting TrustBill…"	Outbound HTTPS blocked, or SSL inspection MITM'ing	Whitelist `api.trustbill.ae:443`; disable SSL inspection for that host
Arabic party names arrive as `???`	BUSY company created with a non-Unicode code page	Recreate the company with Unicode enabled (BUSY 20+ default); migrate masters via XML export
Multi-currency voucher totals mismatch	BUSY's exchange rate rounded to 2 decimals; TrustBill uses 6	Set BUSY Administration → Configuration → Currency → Rate Precision = 6
Narration stamp appears but is truncated	Bookkeeper's existing narration + stamp exceeds BUSY's 500-char Narration limit	Shorten the base narration; TrustBill's stamp is ~75 chars — reserve 100 chars for it
Financial year rollover breaks the agent	`config.yaml → busy.financial_year` not updated	Update the FY setting; the agent picks up the new year on next start
Sync very slow after a big BUSY reindex	Every voucher's LastModified timestamp bumped, so agent thinks everything is new	Reset the agent's high-water mark to today's date; historical vouchers already delivered are safely deduped via Idempotency-Key
Duplicate FTA submissions after a BUSY laptop swap	Agent reinstalled without the previous sync-cursor file	Copy `C:\ProgramData\TrustBill\busy-agent\cursor.json` from the old laptop before uninstalling; if lost, TrustBill dedupes on Idempotency-Key anyway

Security Notes

Argon2id-hashed shared secret. The plaintext secret is shown once at wizard step 2 and never re-shown. TrustBill stores only the hash; the agent stores it Windows-DPAPI-encrypted.
Secret rotation is a first-class flow (Sources → BUSY → Rotate Secret). Rotation preserves connection identity — only the agent needs the new secret.
Read-only integration. The agent cannot create, edit, delete or post vouchers in BUSY. The only write path is a targeted UPDATE / import on the Narration field of already-posted vouchers.
Signed installer. The Desktop Agent installer is signed with a TrustBill EV code-signing certificate. Windows SmartScreen recognises it without prompts on modern Windows.
TLS 1.3 in transit + AES-256-GCM at rest. BUSY invoice data never leaves your PC / server in cleartext.
UAE data residency. All staging + PINT-AE XML + audit logs live in AWS me-central-1.
Agent audit log. Every poll cycle, every voucher pull, every Narration write-back is logged locally in C:\ProgramData\TrustBill\busy-agent\logs\ and mirrored to TrustBill's cloud logs.

Support & Contact

Technical Support

WhatsApp: +971 52 260 9313
Email: info@trustbill.ae
Documentation hub: trustbill.ae/en/documentation
BUSY integration marketing page: trustbill.ae/en/integrations/busy
Tally integration: /documentation/tally
Focus RT integration: /documentation/focus-rt
QuickBooks Desktop integration: /documentation/quickbooks-desktop
Daftra integration: /documentation/daftra
Odoo integration: /documentation/odoo
Zoho integration: /documentation/zoho
QuickBooks Online integration: /documentation/quickbooks-online
ERP Partner API guide: /documentation/erp-partner-api

Escalation

For BUSY go-live escalations, please include: your TrustBill tenant ID, the BUSY version + edition, the company code + financial year, the failing voucher's VchNo + VchUUID, and the agent log line from the failing cycle (C:\ProgramData\TrustBill\busy-agent\logs\agent.log). We can retrace the exact XML exchange from those details.

BUSY ERP Integration with UAE FTA E-Invoicing via TrustBill