Technical Documentation & Runbooks

Heirview Integration Documentation

Complete implementation specifications, OAuth 2.0 lifecycles, installation walkthroughs, and backend deployment guides for QuickBooks Online integrations.

01.System Overview & Architecture

Heirview operates two commercial enterprise integration layers with Intuit QuickBooks Online:

Power BI Custom Connector

An Open Packaging Convention (.mez) bundle executed by the Power Query M mashup engine. Communicates directly with Intuit REST APIs and translates M AST expressions into folded SQL queries.

Zendesk Support App

A Zendesk App Framework (ZAF v2) sidebar iframe with an edge-native Cloudflare Worker backend. Communicates via secure settings and responds in under 100ms with requester response caching.

02.Power BI Connector Installation

Follow these three steps to deploy the connector on Power BI Desktop:

Download the Package: Download QuickBooksOnline.mez from the Heirview download center.
Copy to Custom Connectors Folder: Place the file in:
C:\Users\<YourUsername>\Documents\Power BI Desktop\Custom Connectors
Configure Power BI Security Settings: In Power BI Desktop, navigate to File > Options and settings > Options > Security > Data Extensions. Select "Allow any extension to load without validation or warning".
Restart Power BI Desktop: Open Get Data > Online Services > QuickBooks Online (Heirview). Enter your QuickBooks Realm ID and your Heirview License Key.

03.On-Premises Data Gateway Deployment

For automated scheduled dataset refreshes in the Power BI Service (cloud), deploy the connector to your Microsoft On-Premises Data Gateway (Standard Mode):

1. Copy QuickBooksOnline.mez to your gateway custom connectors folder (e.g. C:\GatewayConnectors).

2. In the On-Premises Data Gateway application, go to Connectors, set the directory to C:\GatewayConnectors, and verify that QuickBooksOnline appears with a green checkmark.

3. The connector exposes SupportsGateway = true and satisfies all gateway test-connection contracts.

04.Zendesk Support App Setup

The sidebar app connects ticket requesters to customer balances using Zendesk App Framework (ZAF v2):

Backend Deployment (Cloudflare Workers):

Deploy the backend worker with a single command:

wrangler deploy

Provision the D1 database using wrangler d1 create qb_zendesk_db and execute migrations.

Zendesk Marketplace App Configuration:

In Zendesk Admin Center under Apps and Integrations > Zendesk Support Apps, install the package and enter:

Backend Base URL: https://api.heirviewhq.com
Backend API Key: The 256-bit API key generated during onboarding.

05.OAuth 2.0 Token Lifecycle Governance

QuickBooks Online enforces non-standard OAuth 2.0 constraints that Heirview manages automatically:

Parameter	Intuit Value	Heirview Production Rule
Access Token TTL	3,600s (1 hour)	Proactive refresh at 50 minutes (no reactive 401s).
Refresh Token TTL	100 days rolling	Monitored with alerts at 60, 30, and 7 days.
Token Rotation	Single-use mandatory	Persisted atomically to encrypted storage immediately on refresh.
Encryption at Rest	Required	AES-256-GCM with unique 12-byte IVs and 16-byte auth tags.

06.Billing, Licensing & Webhooks

Heirview handles subscription lifecycle and license verification through automated webhooks:

License Validation API:

POST https://api.heirviewhq.com/api/v1/license/validate

{ "key": "HV-PBI-LIVE-...", "realm_id": "9341452..." }

Dodo Payments Webhook Endpoint:

POST https://api.heirviewhq.com/api/v1/webhooks/dodo