# Accounting Integrations

## Scope
FieldOps Cloud now has a provider registry and settings surface for:

- Xero
- Intuit QuickBooks Online
- Sage Accounting
- Zoho Books
- MYOB
- FreeAgent
- Reckon
- SMEPlus
- FreshBooks
- Wave Accounting

This implementation adds the safe integration foundation: provider metadata, app UI, tenant-scoped connection tables, sync job tables, sync log tables, and validation rules. It does not collect live OAuth credentials yet.

There are two integration scopes:

- Tenant accounting: each trade company can connect its own accounting system for operational customers, quotes, invoices, payments, items, and taxes.
- Platform accounting: the FieldOps platform owner/site admin can connect the platform billing entity for tenant subscription invoices, payments, and revenue reconciliation.

## Supported Data Flows
- Clients/customers/contacts from FieldOps to accounting providers.
- Quotes/estimates from FieldOps to accounting providers.
- Invoices from FieldOps to accounting providers.
- Payments from accounting providers back to FieldOps.
- Items/products/services and tax codes from accounting providers into FieldOps mapping screens.
- Sync logs and retryable sync jobs for auditability.
- Platform tenant-invoice sync from the platform billing ledger to the site admin's accounting system.

## Provider Notes
- Xero: official Accounting API docs are at `https://developer.xero.com/documentation/api/accounting/overview`.
- Intuit QuickBooks Online: official getting-started docs describe the QuickBooks Online Accounting API as REST-based at `https://developer.intuit.com/app/developer/qbo/docs/get-started`.
- Sage Accounting: official developer quick start is at `https://developer.sage.com/accounting/quick-start`.
- Zoho Books: official API docs include OAuth, multiple data centers, contacts, estimates, invoices, payments, and other accounting resources at `https://www.zoho.com/books/api/v3/introduction/`.
- MYOB: official MYOB Business API docs describe OAuth 2.0, JSON, contacts, sales, quotes, invoices, inventory, purchases, and reports at `https://developer.myob.com/api/myob-business-api/`.
- FreeAgent: official docs describe OAuth 2.0, REST, JSON/XML responses, contacts, estimates, invoices, bills, expenses, projects, and reports at `https://dev.freeagent.com/docs`.
- Reckon: official developer portal and API product entrypoint is `https://developer.reckon.com/`.
- SMEPlus: official API documentation was not found in current project research. Treat as "requires owner confirmation" before live setup.
- FreshBooks: official docs describe JSON API access, OAuth2, clients, invoices, expenses, estimates, projects, reports, and webhooks at `https://www.freshbooks.com/api/start`.
- Wave Accounting: official developer portal is at `https://developer.waveapps.com/hc/en-us`.

## Security Requirements
- Store only encrypted OAuth access and refresh tokens in `accounting_connections.token_ciphertext` and `refresh_token_ciphertext`.
- Never log access tokens, refresh tokens, authorization codes, raw provider payloads containing personal data, or provider secrets.
- Use tenant-scoped lookups for every connection, sync job, and sync log query.
- Require `view_accounting_integrations` for the read-only integration status page.
- Require `manage_settings` for future connection setup and revocation actions.
- Require `manage_platform_billing` for platform accounting connection changes.
- Use OAuth `state` values tied to tenant/user/session and validate them before token exchange.
- Use provider-specific scopes with least privilege; do not request payroll, banking, or payments scopes unless a feature explicitly needs them.
- Make outbound sync idempotent with `accounting_sync_jobs.idempotency_key`.
- Record non-sensitive audit events for connect, disconnect, sync started, sync completed, and sync failed.

## Next Build Steps
1. Add encrypted secret storage using an app key from environment.
2. Add OAuth authorization and callback controllers per provider.
3. Add mapping tables for tax codes, products/services, accounts, and payment methods.
4. Add invoice export and payment import jobs behind explicit user action.
5. Add webhook signature validation for providers that support webhooks.
6. Add live sandbox tests only after test credentials are available.