284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
43 lines
2.5 KiB
Markdown
43 lines
2.5 KiB
Markdown
# QuickBooks Integrations – Technical Overview
|
||
|
||
This document describes the current QuickBooks integration architecture in Alga PSA.
|
||
|
||
## Current State (UI)
|
||
- **QuickBooks CSV (`quickbooks_csv`)**: enabled and selectable in **Settings → Integrations → Accounting**.
|
||
- **QuickBooks Online OAuth (`quickbooks_online`)**: shown as **Coming soon** (disabled in UI).
|
||
|
||
## Shared Accounting Export Architecture
|
||
QuickBooks integrations use the shared accounting export pipeline:
|
||
- **Accounting Export Service** (`server/src/lib/services/accountingExportService.ts`) orchestrates batch creation, validation, execution, and audit tracking.
|
||
- **Validation** (`server/src/lib/validation/accountingExportValidation.ts`) ensures required mappings exist and updates batch status to `ready` or `needs_attention`.
|
||
- **Audit trail** is stored in `accounting_export_batches`, `accounting_export_lines`, and `accounting_export_errors`.
|
||
|
||
## CSV Flow (QuickBooks CSV)
|
||
### UI + API
|
||
- **Settings page**: QuickBooks CSV panels live under `server/src/components/settings/integrations/CSVIntegrationSettings.tsx`.
|
||
- **Export API**: `POST /api/accounting/csv/export` via `server/src/lib/api/controllers/ApiCSVAccountingController.ts`.
|
||
- **Tax import APIs**: `/api/accounting/csv/import/tax/*` via the same controller.
|
||
|
||
### Mappings
|
||
- Stored in `tenant_external_entity_mappings` with `integration_type = 'quickbooks_csv'`.
|
||
- Mapping tabs are rendered by the generic mapping UI:
|
||
- `server/src/components/integrations/csv/CSVMappingManager.tsx`
|
||
- `server/src/components/integrations/csv/csvMappingModules.ts`
|
||
- Canonical Alga entity types used for QuickBooks CSV mappings:
|
||
- `client` (QuickBooks “Customer”)
|
||
- `service` (QuickBooks “Item”)
|
||
- `tax_code` (QuickBooks “TaxCode”)
|
||
- `payment_term` (QuickBooks “Term”)
|
||
|
||
### Export semantics
|
||
- **Immutability**: once an invoice is successfully exported, we create an invoice mapping for `quickbooks_csv` and exclude it from future CSV exports.
|
||
- **Retry behavior**: when users re-export with the same filter set, the request reuses the existing batch and re-validates after mappings are updated.
|
||
|
||
## OAuth Flow (QuickBooks Online – Coming Soon)
|
||
The `quickbooks_online` adapter and supporting services exist in code, but the UI entry point is disabled until OAuth rollout is complete.
|
||
|
||
When enabled, OAuth will add:
|
||
- Realm-scoped catalog lookups (items/tax codes/terms/customers) to improve mapping UX.
|
||
- API-based delivery via the `quickbooks_online` adapter (instead of file delivery).
|
||
|