Overview

This guide describes how QuickBooks Desktop (QBD) — Intuit's on-premise, Windows-first accounting product — connects to TrustBill, a UAE FTA-accredited service provider (ASP), so QBD users in the UAE can issue PINT-AE compliant e-invoices without leaving QuickBooks.

Unlike QuickBooks Online, QBD has no cloud API. Integrations go through Intuit's free QuickBooks Web Connector (QBWC) — a tiny Windows program installed next to QuickBooks that polls a SOAP endpoint we host, executes qbXML requests locally against the company file, and posts the results back.

TrustBill's QBWC endpoint (POST /v1/qbwc) is the actual, shipped integration surface. Once the customer completes the 3-step connect wizard in the TrustBill dashboard, QBWC begins polling on its schedule — invoices flow into TrustBill's staging table, run through the same PINT-AE pipeline that Zoho / QBO invoices use, and the FTA acknowledgement reference is written back into the QuickBooks invoice Memo field on the next poll cycle.

What this integration delivers

Certified, permit-listed QBWC integration — no direct cloud connection, no ODBC, no exported files sitting on a shared drive
Works with Pro / Premier / Enterprise / Accountant editions on any VAT-capable region (UK edition strongly recommended for UAE)
Sales invoices and credit memos mapped to PINT-AE document types
Read-only VAT mapping for the customer's existing Sales Tax Items (5% VAT, Zero-Rated, Exempt, RCM)
FTA acknowledgement reference stamped back into the Memo field of each QuickBooks invoice on the next QBWC cycle
End-to-end audit trail: every qbXML request is stored, every session is logged, the shared secret is argon2id-hashed
Password rotation without re-installing QBWC — the .qwc file's identity (OwnerID + FileID) is stable across rotations

How QBD Differs from Cloud ERPs

The mental model for QBD is inverted compared to QBO / Zoho. Understanding this up-front avoids a lot of confusion during setup.

Aspect	Cloud ERPs (Zoho / QBO)	QuickBooks Desktop (this guide)
Data flow direction	TrustBill polls / receives webhooks from the vendor cloud	QBWC (on the customer's PC) polls TrustBill's SOAP endpoint
Authentication	OAuth 2.0 with refresh tokens	Shared secret (argon2id-hashed) + short-lived session ticket per SOAP cycle
Transport	REST + JSON	SOAP 1.1 + qbXML (an XML dialect Intuit designed for QBD)
Trigger	Webhook on invoice change → near real-time	QBWC poll interval — customer-configurable, default every 15 min
Where connectivity fails	Our servers must reach the vendor cloud	The customer's Windows PC must reach us — corporate firewalls and inconsistent internet at the customer site are the top-two setup blockers
Write-back to the ERP	Real-time API call from TrustBill	Queued qbXML request executed on the next QBWC poll — up to one poll interval of latency

Supported QuickBooks Desktop Versions & Editions

QBWC has been shipping since QuickBooks Desktop 2005. The integration works with any QBD build that supports qbXML 8.0 or later — that is every mainstream QBD release since 2008. Older builds work too, but their qbXML dialects are missing fields we now depend on.

Product	Release	qbXML support	Support level
QuickBooks Desktop Pro	2019 – 2024, Pro Plus subscription	qbXML 13.0+	Full
QuickBooks Desktop Premier	2019 – 2024, Premier Plus subscription	qbXML 13.0+	Full
QuickBooks Desktop Enterprise	19.0 – 24.0	qbXML 13.0+	Full — recommended for > 30 concurrent users
QuickBooks Desktop Enterprise Solutions (industry editions)	Contractor / Manufacturing & Wholesale / Non-Profit / Professional Services / Retail / Accountant	qbXML 13.0+	Full — custom line-item fields flow through the standard mapping
QuickBooks Accountant Desktop	2019 – 2024	qbXML 13.0+	Full — one QBWC per client company file
QuickBooks for Mac	2019 – 2024	qbXML via Mac Connector	Supported via QBWC-for-Mac (Intuit ships a Mac-native bridge; slower cadence than Windows)
QuickBooks Desktop Point of Sale	v18 / v19	Discontinued by Intuit in 2023	Read-only — POS invoices only reach TrustBill after they sync into QBD Pro/Premier via Financial Exchange
QuickBooks Desktop Middle East (ME) edition	Legacy — Intuit discontinued sales 2014, still deployed in UAE	qbXML 10.0+	Supported — VAT was retrofitted onto the sales-tax engine; treat every ME "tax rate" as a VAT rate
QuickBooks Desktop 2015 – 2018	Legacy on-premise	qbXML 11.0 – 12.0	Supported — recommend upgrading before UAE FTA go-live because Intuit has ended security patches
QuickBooks Online Hosted (Right Networks etc.)	QBD running in a hosted Windows VM	Same as underlying QBD	Full — QBWC runs inside the hosted VM; outbound HTTPS to TrustBill required

Which QBD edition should I buy for new UAE deployments? Pro Plus or Premier Plus (subscription) UK edition — VAT engine + Intuit's active security updates. If you already run US or ME edition, you don't need to migrate to add e-invoicing; TrustBill maps whatever tax items already exist.

Regional Edition Notes (UAE fits UK)

QuickBooks Desktop ships different tax engines per country. The engine is set at company-file creation and cannot be swapped. For UAE FTA e-invoicing, the goal is a company file whose tax engine can carry rate + TRN in a shape our qbXML mapper can read.

QBD region	Tax engine	qbXMLCountry code	UAE recommendation
QBD UK	VAT (multi-rate, EC codes)	`UK`	Recommended
QBD Middle East (legacy)	VAT (retrofitted onto Sales Tax)	`UK` (ME reports as UK)	Supported — no need to migrate
QBD Australia	GST	`AU`	Supported — GST codes mapped to VAT categories at connector setup
QBD Canada	GST/HST/PST	`CA`	Supported — multi-jurisdiction tax lines collapsed into a single VAT figure
QBD US	Sales Tax (no VAT engine)	`US`	Not recommended — spin up a fresh UK-edition company file and use the built-in Copy List Data tool to migrate customers/vendors/items before installing TrustBill

TrustBill's QBWC service reads the qbXMLCountry field returned by HostQueryRq on first connect and stores it on the session so every subsequent qbXML request uses a dialect the customer's QuickBooks understands.

Prerequisites

On the QuickBooks Desktop side

Windows 10 / 11 (or Windows Server 2019+) running QuickBooks Desktop Pro / Premier / Enterprise / Accountant, 2018 or later — or QuickBooks for Mac 2019+ with Mac Connector installed
Intuit's free QuickBooks Web Connector installed (see step 1 of the wizard for the download link)
A company file that's already tracking VAT — Edit → Preferences → Sales Tax → Company Preferences → Do you charge sales tax? = Yes
Company Information carries the 15-digit UAE TRN (Company → My Company → Company Information → Federal Tax ID / VAT Registration Number)
Customers have their TRN populated in the Additional Info → Resale Number field (used by our mapper regardless of region — see below)
Sales Tax Items created for each VAT scheme (5% VAT, Zero-Rated Sales, Exempt Sales, Reverse Charge, Out of Scope)
QuickBooks running in Single-user mode during the first QBWC poll — Intuit's own limitation on Read/Write access
The Windows account that runs QBWC needs read + write permission on the company file

On the TrustBill side

A TrustBill SME account (one account = one TRN = one QuickBooks company file)
Completed KYB (business verification) — trade licence + TRN certificate uploaded
Submission mode set to test or sandbox during onboarding, live for production
No manual API credentials — the wizard mints a fresh shared secret and generates the .qwc file for you

Integration Architecture (QBWC)

The customer's PC runs the client (QBWC); TrustBill runs the server (the SOAP endpoint). Every QBWC cycle is a short conversation over that link:

A single QBWC poll cycle

QBWC's scheduler fires (default: every 15 minutes) and reads the .qwc file's AppURL.
QBWC POSTs a SOAP authenticate(username, password) to TrustBill.
TrustBill's QbwcService.authenticate looks up the source connection by username, verifies the argon2id-hashed password, mints a short-lived session ticket, and either returns a work-pending marker or a "nothing to do this cycle" marker.
QBWC calls sendHostQueryRq once per session — TrustBill records the QuickBooks major/minor version and country code onto the session row.
QBWC calls sendRequestXML. TrustBill dequeues the next pending qbXML request from qbwc_request_queue and returns it.
QBWC executes the qbXML against QuickBooks locally and posts the response back via receiveResponseXML.
TrustBill's qbxml-parser reads the response and lands the parsed invoices in source_staging_invoices.
Steps 5–7 repeat until TrustBill returns an empty request, then QBWC calls closeConnection.
Staged invoices are picked up by the standard pipeline: queued → transformed → validated → delivered.
ASP forwards the PINT-AE XML to the FTA over Peppol; on ack, TrustBill enqueues an InvoiceModRq memo write-back for the next QBWC cycle.

QBWC is not an always-on service. It runs as a background app on the customer's PC. If the PC is off, the cycle is skipped. First-time customers commonly miss this — set QBWC's Run Every N Minutes to 15 (or lower) and leave the QBWC window minimised, not closed.

Connection Methods

QBWC is the primary and only real-time path. Two fallbacks exist for edge cases:

1. QuickBooks Web Connector (recommended)

Intuit's own free Windows program. Installed once per Windows PC that runs QuickBooks. All the details on this page assume QBWC unless stated otherwise.

Real-time-ish (within one poll interval)
Signed by Intuit, allow-listed by most enterprise firewalls
Free — no per-user licence
Works with all QBD editions and both Windows and Mac
Handles read + write-back in the same cycle

2. IIF (Intuit Interchange Format) file drop

Fallback when QBWC cannot run — e.g. QuickBooks on a segmented network with no outbound HTTPS. The bookkeeper exports invoices from File → Utilities → Export → Lists to IIF Files → Transactions, drops the file to a monitored folder, and TrustBill picks it up.

No real-time; runs on the customer's export cadence
No write-back — status is visible only in the TrustBill dashboard, not stamped back into QBD
Best for very-low-volume single-user QBD deployments

3. CSV Export for one-off migrations

Historical invoices from QBD can be bulk-loaded via Reports → Sales → Sales by Customer Detail → Excel. See Bulk Migration for the schema.

Which method should I use?

For 99% of QBD UAE customers, use QBWC. Use IIF drop only when the PC can't make outbound HTTPS calls to https://api.trustbill.ae. Use CSV export only for one-off historical migrations before go-live.

The 3-Step Connect Wizard

Sign into the TrustBill dashboard, open Sources → Connect QuickBooks Desktop, and follow three steps. End-to-end setup runs about three minutes.

Step 1 — Install QuickBooks Web Connector

The wizard shows a link to Intuit's own QBWC installer. Install it on the same Windows PC that runs QuickBooks (or on the machine hosting the multi-user Enterprise database), then give the connection a display name (default: "QuickBooks Desktop").

Step 2 — Reveal the shared secret + download .qwc

Clicking Continue calls POST /v1/sources/quickbooks-desktop. TrustBill generates a fresh 32-byte random password, argon2id-hashes it, and returns the plaintext + a signed URL for the .qwc config file.

The plaintext password is shown once — copy it before dismissing the dialog
If you lose it, use Sources → this connection → Rotate password to mint a fresh one — you do not need to reinstall QBWC or import a new .qwc
Download the .qwc file — it's a small XML config, safe to email (see Security Notes)

Step 3 — Import into QBWC + paste the password

Open the .qwc file — QBWC launches and asks whether to trust the new application. Click Yes, always allow access even if QuickBooks isn't running so the sync survives a QuickBooks restart. Paste the password from step 2 into QBWC's Password column. Tick Auto-Run, set Every_Min = 15.

Within one poll cycle, the connection status in the TrustBill Sources page flips from Awaiting first sync to Connected. First sync typically pulls 30–90 days of history; incremental syncs run in seconds.

.qwc File & Shared Secret

The .qwc file is a plain-text XML config that QBWC reads once, on import. It carries no secret — it tells QBWC where to send SOAP calls and how to identify itself, nothing more.

.qwc field	Value TrustBill sets	Purpose
`AppName`	"TrustBill E-Invoicing"	Shown in QBWC's app list
`AppURL`	https://api.trustbill.ae/v1/qbwc	SOAP endpoint QBWC polls
`UserName`	Random per-connection ID	Sent in every `authenticate` call
`OwnerID` + `FileID`	Derived from the connection UUID (stable across rotations)	Binds the config to the specific QuickBooks company file after first run
`QBType`	QBFS	Financial Software (QuickBooks proper, not POS)
`Scheduler.RunEveryNMinutes`	15	Default poll interval — customer can override in QBWC's UI
`IsReadOnly`	false	We need Read/Write to stamp the FTA memo back — Read-Only mode blocks the memo write-back

The shared secret lives outside the .qwc file. QBWC keeps it in its own local password store (Windows DPAPI). TrustBill stores only the argon2id hash on source_connections.qbwc_password_hash. If a customer loses their password, we cannot recover it — we rotate. Rotation preserves OwnerID / FileID, so QBWC treats the new password as an update, not a fresh app.

Authentication (SOAP + Session Ticket)

Every QBWC cycle begins with SOAP authenticate(username, password). TrustBill's response is a two-string array per Intuit's spec:

TrustBill returns	Meaning
`[ticket, ""]`	Auth OK, work pending; QBWC continues with the currently-open company file
`[ticket, "none"]`	Auth OK, no work this cycle — QBWC closes cleanly (green tick)
`["", "nvu"]`	Invalid username / password — QBWC shows a red X and re-prompts
`[ticket, "path"]`	Auth OK, force QBWC to open a specific company file (used when the customer has multiple company files on one PC)

The ticket is short-lived (~30 min) and only accepted for the SOAP methods that follow (sendRequestXML, receiveResponseXML, connectionError, closeConnection). The password is never sent again after authenticate.

Permit-Listed qbXML Requests

TrustBill maintains an allow-list of qbXML request types the QBWC handler may ever ask a customer's QuickBooks to run. If the enqueue service is asked for a type not on the list, it throws before the row hits the queue — so a permit-list violation cannot escape into a customer's QuickBooks file even if a bug reaches production.

qbXML request type	Direction	Purpose
`HostQueryRq`	Read	QuickBooks version, edition, country — once per session, drives qbXML dialect selection
`CompanyQueryRq`	Read	Company file identity — guards against pointing QBWC at the wrong file after a laptop swap
`InvoiceQueryRq`	Read	Pull invoices — initial full sync + incremental sync via `ModifiedDateRangeFilter`
`CreditMemoQueryRq`	Read	Pull credit memos — same incremental pattern as invoices
`CustomerQueryRq`	Read	Customer catalogue — resolves buyer TRN, address and tax scheme
`ItemInventoryQueryRq` / `ItemServiceQueryRq` / `ItemNonInventoryQueryRq`	Read	Item catalogue — needed for line-item VAT mapping and UOM resolution
`SalesTaxCodeQueryRq`	Read	Sales-tax codes + rates — mapped to TrustBill `taxCategory` once per customer
`InvoiceModRq`	Write	Stamp the invoice Memo with the FTA acknowledgement reference. Response elements narrowed to `[Memo, TxnID, EditSequence]` so nothing else on the invoice can be accidentally overwritten.

Extending this list is a security-review touchpoint. Adding a new qbXML request type (e.g. to write back a custom-field value instead of the Memo, or to create a Credit Memo automatically on FTA rejection) requires an internal design review — not a config change.

QBD Invoice → PINT-AE Field Mapping

The qbxml-parser reads InvoiceQueryRs / CreditMemoQueryRs responses and lands the data in the same InvoiceCreateInput shape used across all TrustBill sources.

Header-level mapping

QBD field (qbXML)	TrustBill field	Notes
`RefNumber`	`number`	Human-readable invoice number ("INV-1042"); 1–64 chars
`TxnID`	Stored on staging + used for Idempotency-Key	QBD-internal ID; stable across QBD renumbering
`TxnDate`	`issueDate`	ISO YYYY-MM-DD
`DueDate`	`dueDate`	Optional
`CurrencyRef.FullName`	`currency`	Must be `AED`; multi-currency invoices converted at `ExchangeRate`
`ExchangeRate`	used to convert non-AED lines	Applied to `InvoiceLineRet.Rate`
`Company.CompanyName` (via `CompanyQueryRq`)	`seller.name`	—
`Company.CompanyID` or Federal Tax ID	`seller.trn`	15-digit UAE TRN
`CustomerRef.FullName` → `CustomerRet`	`buyer.name`	Resolved via `CustomerQueryRq`
`CustomerRet.ResaleNumber`	`buyer.trn`	QBD's Additional Info → Resale Number field carries the buyer TRN in UAE deployments; leave empty for B2C
`CustomerRet.BillAddress`	`buyer.address`	`Addr1`–`Addr5` → `line1/line2/city/state/country`
`IsTaxIncluded`	controls inclusive/exclusive handling	If true, connector strips VAT from line prices before mapping
`Memo`	`notes`	Preserved verbatim; also the target of write-back — do not use the Memo field for internal notes once TrustBill is connected
`PONumber`	`sellerInvoiceReference`	Preserved for reconciliation

Line-level mapping (`InvoiceLineRet`)

QBD field	TrustBill field	Notes
`Desc`	`lines[].description`	Non-empty; supports Arabic if the company file is Unicode
`Quantity`	`lines[].quantity`	Must be > 0
`Rate`	`lines[].unitPrice`	VAT-exclusive after inclusive-tax normalisation
`ItemRef.FullName`	`lines[].sellerItemId`	Preserved for traceability
`UnitOfMeasure`	`lines[].unit`	QBD UOM mapped to UN/ECE Rec 20 (each → C62, hour → HUR, kg → KGM, litre → LTR)
`SalesTaxCodeRef.FullName`	`lines[].vatRate` + `lines[].taxCategory`	Mapped via the QBD Sales Tax Code table below
`ItemDiscountLineRet` (subsequent line)	`lines[].discountAmount`	QBD posts discounts as a separate discount line; parser rolls it into the preceding item line

Totals are computed server-side

Do not rely on QBD's Subtotal / SalesTaxTotal matching TrustBill's computed totals. QBD's rounding is per-line, TrustBill's is per-invoice. If they differ by more than ±0.01 AED, the connector logs a variance and blocks submission until you resave the invoice in QBD (which forces a fresh rounding pass).

How Invoices Reach TrustBill

Unlike cloud ERPs, there's no "push an invoice to TrustBill" button. QBWC's next poll cycle finds the new invoice via the incremental InvoiceQueryRq and hands it back to TrustBill.

Bookkeeper saves an invoice in QuickBooks as usual (Ctrl+Alt+N → Save).
Within the QBWC poll interval (default 15 min), QBWC connects, TrustBill enqueues an InvoiceQueryRq filtered by ModifiedDateRangeFilter = last-seen timestamp.
QBWC executes it locally and posts back an InvoiceQueryRs with the new invoice(s).
TrustBill's qbxml-parser parses the response and inserts rows into source_staging_invoices.
The staging pipeline picks them up and calls POST /v1/invoices internally — invoice is stored as draft.
If auto-submit is enabled on the TrustBill tenant, POST /v1/invoices/submit fires immediately.

Delete = tombstone. If the bookkeeper deletes a QBD invoice before it's submitted, the connector detects the deletion on the next InvoiceQueryRq (the TxnID no longer appears) and marks the TrustBill draft as tombstoned. Already-submitted invoices are never deleted — reverse them via a Credit Memo instead.

Credit Memos

QBD's Refunds & Credits screen (Ctrl+I → Credit Memo) posts to the CreditMemo entity, pulled by CreditMemoQueryRq on the same schedule as invoices.

QBD object	`invoiceType`	Required extra fields
Credit Memo with `LinkedTxn.TxnType = Invoice`	`credit_note`	`referencedInvoiceNumber` = original invoice's `RefNumber`, `reasonCode`
Standalone Credit Memo (no `LinkedTxn`)	`credit_note`	`reasonCode` = `OtherAdjustment`

Vendor Credit (purchase-side) support is planned for a later slice — file a request through TrustBill support if you need debit_note handling from QBD's Enter Bills → Credit screen.

Submit Invoice

Once the invoice is in TrustBill as draft, submission is a normal POST /v1/invoices/submit against the shared invoice API — the same flow as every other source.

Auto-submit on ingest (recommended for QBD): TrustBill submits every draft as soon as it lands from QBWC. The bookkeeper's Save-in-QuickBooks is effectively the "Send to FTA" action.
Manual review: leave auto-submit off and click Submit from the TrustBill dashboard for each invoice. The QuickBooks-side workflow doesn't change.

There's no equivalent of a "Send to FTA" button inside QBD itself — QBD has no plug-in surface for a third-party button. Bookkeepers who want per-invoice review use the dashboard for that step.

Status Tracking & Memo Write-back

Because QBD has no cloud API, TrustBill's status write-back rides the same QBWC channel as the outbound flow. A separate 10-minute cron scans for cleared invoices and enqueues a memo write-back for each; the next QBWC cycle picks them up.

Memo stamp format

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

Short by design — QuickBooks's Memo field is 4,095 chars, but bookkeepers often add their own notes. The stamp is prefixed with TrustBill: so it's easy to strip if the invoice needs to be re-exported.

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

The write-back service (QbwcWriteBackService) runs on a 10-minute cron across the pod, guarded by a Postgres advisory lock so only one instance drives write-backs at a time. Write-back latency is therefore at most one poll interval + 10 minutes after FTA acknowledgement.

Bulk Migration from QBD

QBWC pulls history from the first poll cycle onwards — by default the last 12 months. For older invoices, or when you don't want QBWC to slow-scan your file, use CSV export:

In QBD: Reports → Sales → Sales by Customer Detail, set the date range, click Excel → Create New Worksheet
Save as CSV
Run the TrustBill qbd-csv-normaliser script to remap QBD's column headers to the TrustBill schema below
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,buyerTrn,buyerName,buyerCountry,buyerAddressLine1,buyerCity,lineDescription,lineQty,lineUnit,lineUnitPrice,lineVatRate,lineTaxCategory,referencedInvoiceNumber,notes

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

Test / Sandbox / Live Modes

One TrustBill tenant has one active submission mode. Invoices are hard-partitioned per mode — a live invoice cannot be viewed from sandbox, and vice-versa.

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

QBD-specific tip: because QBWC syncs your real QuickBooks data, there's no "QBD sandbox company file" to fake. Use a copy of your production company file (File → Copy Company File for QuickBooks Statement Writer / third-party tool) as your sandbox for the first VAT return period.

QBD Tax Item Mapping (UAE)

QBD tracks VAT via Sales Tax Items (Lists → Item List → Sales Tax Item). Configure the following items in QBD, and the connector maps them automatically. If your company file already has custom-named tax items, map them once in Sources → this connection → Tax Mapping in the TrustBill dashboard.

QBD Sales Tax Item name	Rate	TrustBill `vatRate`	TrustBill `taxCategory`
Standard 5% VAT	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`
Reverse Charge (Designated Zone)	0%	0	`reverse_charge_designated_zone`
Out of Scope	Non-taxable	0	`out_of_scope`

QBD ME (Middle East) legacy edition uses the sales-tax engine to track VAT — treat every ME sales-tax item as a VAT rate and map accordingly. The connector recognises common ME item names ("VAT 5%", "VAT@5"), but custom names still need manual mapping.

UAE-Specific Scenarios

Free Zone / Designated Zone sellers

QBD has no built-in designated-zone flag. Set it at the TrustBill-tenant level (Settings → Company → Zone Type = Designated). This flows through as seller.designatedZone: true so PINT-AE emits the free-zone declaration.

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

Add a QBD Item Custom Field called "Margin Scheme" and tick it on qualifying items. The connector reads the field via ItemInventoryQueryRs → DataExt and sends lines[].marginScheme: true. The line's Cost is used as the margin base.

Reverse charge on imports

Purchase Bills from non-UAE vendors — pull these into TrustBill via a Bill-side counterpart of InvoiceQueryRq once BillQueryRq is added to the permit-list (roadmap). For now, run reverse-charge purchases through the CSV migration path.

B2C simplified tax invoices

Customers with no Resale Number in QBD are treated as B2C. Invoices under 10,000 AED are simplified tax invoices under FTA rules; TrustBill emits the correct PINT-AE profile automatically.

Multi-company (accountants)

One QBWC install can serve multiple .qwc files, each pointing at a different TrustBill tenant. Accountants run one .qwc per client company file. TrustBill's Accounting Firm account type surfaces every client tenant on a single dashboard.

Error Handling

There are three distinct failure surfaces: (1) SOAP-layer errors QBWC shows the customer directly, (2) qbXML-layer errors QuickBooks returns to QBWC and QBWC reports to us via connectionError, (3) TrustBill pipeline errors visible in the dashboard.

Layer	Symptom	Root cause	Action
SOAP	QBWC shows "Invalid username / password" (`nvu`)	Password mismatch or rotated on the TrustBill side	Reveal the current password in TrustBill or rotate, then re-enter in QBWC
SOAP	QBWC shows "Connection error, will retry"	Outbound HTTPS blocked by customer firewall	Whitelist `api.trustbill.ae:443` egress
qbXML	QuickBooks says "The current user does not have permission..."	First-run integrated-app dialog was dismissed as "No"	In QBD: Edit → Preferences → Integrated Applications → Company Preferences → grant TrustBill access
qbXML	QuickBooks returns "Company file is in multi-user mode"	Write-back tried while file is open in multi-user mode	Switch to single-user mode for the first sync; multi-user works after that on Enterprise
Pipeline	`invalid_body` — missing buyer TRN	Customer's Resale Number field empty	Fill it in QBD; connector re-emits on the next cycle
Pipeline	`totals_mismatch`	QBD per-line rounding vs TrustBill per-invoice	Re-save the invoice in QBD (Ctrl+S); QBD refreshes its rounding
Pipeline	`unknown_tax_code`	Custom-named Sales Tax Item not mapped	Map it in Sources → connection → Tax Mapping
Pipeline	`region_not_supported`	`HostQueryRq` returned `qbXMLCountry = US` and there's no VAT engine	Create a new UK-edition company file and migrate; see Regional Edition Notes
Write-back	Memo stamp doesn't appear on invoice	QBD is set to Read-Only integration, or the invoice is locked (in a closed accounting period)	Grant Read/Write in Integrated Applications; unlock the period or wait for the next open period

Setup Checklist

Confirm QBD edition — Pro / Premier / Enterprise / Accountant 2018+ on Windows, or QuickBooks for Mac 2019+
Confirm region — UK / ME / AU / CA edition (US not compatible without migration)
Enable VAT in QBD (Edit → Preferences → Sales Tax)
Create the eight standard Sales Tax Items (Standard 5%, Zero-Rated Export/Healthcare/Education, Exempt Financial/Rent, Reverse Charge, Out of Scope)
Fill the TRN under Company → My Company → Company Information
Populate customer TRNs in the Resale Number field for B2B customers
Install QuickBooks Web Connector on the same PC that runs QuickBooks (Intuit's own installer, free)
Create your TrustBill SME account and complete KYB (trade licence + TRN certificate)
Open the Connect QuickBooks Desktop wizard in the TrustBill dashboard (Sources → Add Source → QuickBooks Desktop)
Copy the one-time password shown in step 2 of the wizard
Download and open the .qwc file — QBWC launches
Grant access when QuickBooks asks (choose "always allow, even if QuickBooks isn't running")
Paste the password into QBWC, tick Auto-Run, set Every_Min = 15
Enable sandbox mode in TrustBill
Save a test invoice in QuickBooks — confirm it reaches acknowledged within ~20 minutes
Reconcile QBD's VAT 100 Report against TrustBill's Delivered Invoices
Switch to live when FTA registration is complete

Suggested test cases before go-live

B2B invoice, single line, 5% VAT — expect acknowledged within one poll cycle after submit
B2C invoice under 10,000 AED (customer with no Resale Number) — expect PINT-AE "simplified" profile
Credit Memo linked to an earlier invoice — expect matching pair
Zero-rated export sale — expect zero_rated_export
Multi-line invoice with mixed VAT (5% + 0%) — expect two taxCategory values
Modify an invoice in QBD after it was submitted — expect connector to detect the alter and (if enabled) auto-raise a Credit Memo + new invoice pair
Delete a draft (not-yet-submitted) invoice in QBD — expect TrustBill draft to be tombstoned on next cycle
Password rotation while QBWC is running — expect QBWC's next poll to fail once, then succeed after the customer pastes the new password

Troubleshooting

Symptom	Likely cause	Fix
QBWC never fires — no log entries	Auto-Run unticked in QBWC, or the Windows PC sleeps overnight	Tick Auto-Run + set the PC to never sleep during business hours
First invoice never reaches TrustBill	Integrated Applications dialog was dismissed as "No"	In QBD: Edit → Preferences → Integrated Applications → Company Preferences → Properties → TrustBill → check "Allow this application to read and modify this company file"
Memo stamp appears once then never updates	Invoice was later locked (accounting period closed)	Reopen the period, or accept that the stamp reflects the state at first write
QBWC hangs on "Contacting server..."	Outbound HTTPS blocked, or SSL inspection MITM'ing the connection	Whitelist `api.trustbill.ae` egress; disable SSL inspection for that host
"Company file has changed" on every cycle	Customer restored a backup or moved the company file — OwnerID/FileID mismatch	Re-import the .qwc; QBWC re-binds the config to the new file location
Arabic descriptions arrive as `???`	Company file is on a non-Unicode QBD build (pre-2019)	Upgrade to QBD 2019+ Unicode; older files can be migrated via File → Utilities → Verify Data
Password rotation broke QBWC	User forgot to paste the new password into QBWC after rotating	In QBWC: click the connection → Password column → paste — no .qwc re-import needed
Duplicate invoices in TrustBill	Same QBD file connected to two different TrustBill tenants	Only one .qwc per company file; delete the extra source connection
Sync is very slow (30+ min)	Company file has ~100k+ historical invoices, or QBD is on a network drive over VPN	Move the company file locally; reduce first-sync window via Sources → Advanced → Sync From Date

Security Notes

Argon2id-hashed shared secret. The plaintext password is shown once at wizard step 2 and never re-shown. TrustBill stores only the hash.
Password rotation is a first-class flow (POST /v1/sources/:id/rotate-qbwc-password). Rotation preserves the .qwc's OwnerID + FileID, so QBWC treats the new password as an update, not a fresh application.
.qwc files carry no secret, only endpoint URL + username. Safe to email or check into a config repo.
Permit-list of qbXML request types. The enqueue service refuses to queue any request type not on ALLOWED_QBXML_REQUEST_TYPES. A bug that tries to run a broader request can't ship to a customer's file.
Response elements narrowed on writes. The Memo write-back's InvoiceModRq returns only [Memo, TxnID, EditSequence] so nothing else on the invoice can accidentally round-trip through our parser.
TLS 1.3 in transit + AES-256-GCM at rest. Company file data never leaves your PC in cleartext.
UAE data residency. All staging + PINT-AE XML + audit logs live in AWS me-central-1.
Every SOAP call is logged with a redacted body — support can retrace a failed sync without seeing the invoice detail.

Support & Contact

Technical Support

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

Escalation

For QBD go-live escalations, please include: your TrustBill tenant ID, the QBD version (Help → About QuickBooks), the QBWC version, the .qwc filename, and the QBWC log timestamp of the failing cycle (QBWC → View Log). We can retrace the exact SOAP conversation from those five details.

QuickBooks Desktop Integration with UAE FTA E-Invoicing via TrustBill