Integration APIs #

This document provides basic information about the available integrations in Tofu and the APIs required to activate them.

Overview #

Tofu supports two main types of integrations:

1. Accounting Integrations - Connect to accounting software for invoice synchronization
2. Trigger Integrations - Connect to document storage systems for automated document processing

At a minimum integrations of any type require two steps to fully integrate.

1. OAuth Integration Flow
2. Integration Setup

Tofu AccountClass Types #

Tofu uses a unified AccountClass enum to categorize all accounting accounts across different providers:

• Asset: Assets (current, fixed, inventory, etc.)
• Liability: Liabilities (current, non-current, payables, etc.)
• Equity: Equity accounts (share capital, retained earnings, etc.)
• Revenue: Revenue/Income accounts (sales, other income, etc.)
• Expense: Expense accounts (costs, overheads, depreciation, etc.)
• Bank: Bank accounts
• CreditCard: Credit card accounts

Available Integrations #

Xero (Accounting Integration) #

Xero is a cloud-based accounting software that allows you to sync invoice data and manage your financial records.

Provider Code: XERO

APIs Required for Activation #

1. Get OAuth Authorization URL

   POST /api/v1/integrations/oauth/authorize
   

   • Parameters:
     • entity_id (required): UUID of the entity
     • provider: XERO
     • redirect_url (required): URL to redirect after OAuth flow
   • Response: Returns authorization URL for Xero OAuth flow

2. Fetch Available Organizations

   GET /api/v1/integrations/{integrationId}/accounting-organizations
   

   • Parameters:
     • integrationId (required): UUID of the integration
     • entity_id (required): UUID of the entity
   • Response: List of available Xero organizations/tenants

3. Setup Integration

   PUT /api/v1/integrations/{integrationId}
   

   • Parameters:

     • integrationId (required): UUID of the integration
     • entity_id (required): UUID of the entity

   • Request Body:

     {
       "status": "PENDING",
       "public_metadata": {
         "provider": "XERO",
         "organization_id": "your-xero-org-id",
         "pays_tax": true
       }
     }
     

Additional Xero APIs #

• Chart of Accounts: GET /api/v1/integrations/{integrationId}/accounting-accounts
• Contacts/Vendors: GET /api/v1/integrations/{integrationId}/accounting-contacts
• Tax Rates: GET /api/v1/integrations/{integrationId}/accounting-tax-rates
• Currencies: GET /api/v1/integrations/{integrationId}/accounting-currencies

Xero Account Type Mapping #

The following table shows how Xero account types are mapped to Tofu’s internal AccountClass:

Note:

• Tofu’s AccountClass also includes CreditCard, but Xero doesn’t have a specific credit card account type
• Unknown account types default to Expense with a warning logged

Account Type Filtering #

The chart of accounts API supports filtering by account type:

GET /api/v1/integrations/{integrationId}/accounting-accounts?account_types=BANK,EXPENSE

• Parameters:
  • account_types: Comma-separated list of AccountClass values to filter
  • Valid values: ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE, BANK, CREDIT_CARD
  • If not provided, returns all account types

QuickBooks Online (Accounting Integration) #

QuickBooks Online is a cloud-based accounting software that allows you to sync invoice data and manage your financial records.

Provider Code: QBO

QuickBooks Account Type Mapping #

QuickBooks Online uses the AccountTypeEnum to categorize accounts:

Note:

• QBO doesn’t support the “Non-Posting” Account type for API operations
• The API returns the original AccountType value in the class field
• Filtering uses SQL-like syntax: AccountType = 'Bank'

Bukku (Accounting Integration) #

Bukku is a Malaysian cloud accounting platform. Unlike OAuth-based accounting connectors, Bukku uses an API Access Token and company subdomain.

Provider Code: BUKKU

Authentication: API key (no OAuth flow)

APIs Required for Activation #

1. Create API-Key Integration

   POST /api/v1/integrations/api-key
   

   • Parameters:

     • entity_id (required): UUID of the entity

   • Request Body:

     {
       "provider": "BUKKU",
       "credentials": {
         "access_token": "your-bukku-access-token",
         "subdomain": "your-company-subdomain"
       }
     }
     

   • Response: Returns the created EntityIntegration in PENDING status after credential validation

   • Credential source: Bukku Control Panel → Integrations → API Access

   • Subdomain: URL prefix from https://{subdomain}.bukku.my

2. Setup Integration (Activate)

   PUT /api/v1/integrations/{integrationId}
   

   • Parameters:

     • integrationId (required): UUID of the integration
     • entity_id (required): UUID of the entity

   • Request Body:

     {
       "status": "PENDING",
       "public_metadata": {
         "provider": "BUKKU",
         "subdomain": "your-company-subdomain"
       }
     }
     

Bukku Notes #

• Read-only integration: can_publish and can_import are false; reference-data sync is implemented incrementally.
• Feature flag: Requires bukku_integration enabled on the organization before the provider appears in the UI.
• One accounting integration per entity: Creating Bukku fails if another accounting integration is already connected.
• Credential validation: Backend calls GET /contacts?page=1&page_size=1 with Authorization: Bearer <access_token> and Company-Subdomain: <subdomain>.

For end-user setup steps, see the Bukku Integration guide.

FreeAgent (Accounting Integration) #

FreeAgent is a UK-first cloud accounting product (NatWest-owned) for freelancers, contractors, and micro-businesses. API v2.

• Provider Code: FREE_AGENT
• Authentication: OAuth2 (authorization-code); no granular scopes (access follows the connecting user’s role).

Auth / Connection Model #

• Authorize: …/v2/approve_app (the authorize URL carries only response_type, client_id, redirect_uri, state — no scope string).
• Token exchange: POST …/v2/token_endpoint using HTTP Basic auth (client_id = username, client_secret = password); form body grant_type=…&code=…&redirect_uri=….
• Rotating refresh tokens: the refresh grant returns a new access token AND a new refresh token — always persist the latest. There is no documented revoke endpoint; disconnect just drops the stored token.
• API version header: every request pins X-Api-Version: 2024-10-01; unversioned requests silently follow “today’s” behavior.
• User-Agent: FreeAgent rejects any request without a User-Agent header ("User agent http header not set"), so the HTTP client pins one.
• Sandbox vs production host: selected by ENVIRONMENT_NAME (mirrors QBO) — production → https://api.freeagent.com, everything else (dev/preview/dev_local) → https://api.sandbox.freeagent.com. Overridable per-URL via FREEAGENT_API_BASE_URL / FREEAGENT_AUTH_URL / FREEAGENT_TOKEN_URL or the task-local runtime config (.config.yaml).
• Credentials: FREEAGENT_CLIENT_ID / FREEAGENT_CLIENT_SECRET, redirect via OAUTH_REDIRECT_URL. One dev-dashboard app works for both sandbox and prod (the account you authorize picks the environment).
• Multi-org: one authorization = one company (repeat authorization for more, like Xero/QBO).

APIs Required for Activation #

1. Get OAuth Authorization URL — POST /api/v1/integrations/oauth/authorize (entity_id, provider: FREE_AGENT, redirect_url).

2. Setup / Activate — PUT /api/v1/integrations/{integrationId}. FreeAgent scopes one token to one company, so the activate probe is GET /v2/company (no org-picker step); the connected company URL is the tenant id. Example body:

   {
     "status": "PENDING",
     "public_metadata": { "provider": "FREE_AGENT" }
   }
   

Per-Object Read Support #

Calculation Config #

TaxCalculationMode = LineByLine, RoundingMethod = Nearest (UK VAT round-half-away), per-doc-type basis (AR exclusive, AP/expense inclusive), currency precision from the document currency (GBP 2dp). Registered as AccountingTarget::FreeAgent (YAML freeagent + codegen) and served by EntityIntegrationAccountingConfigService.

FreeAgent Notes #

• Read-only + contact write-back: read_only_access().with_create_contacts().with_direct_expense_self_prompt() — can_publish / can_import are false; contact create/update (tax-id) is the only write.
• Feature flag: requires freeagent_integration enabled on the organization.
• Resource ids are bare, not URLs. FreeAgent identifies resources by full URI, but the id must survive single-segment internal paths (/accounting-invoices/{id}, /contact-knowledge/{id}), so invoice/bill/expense/contact external ids are stored as the bare last URL segment (e.g. 743559) and the fetch/write layer rebuilds the full API URL.
• Decode-hardening: all decoders are open-world (#[serde(default)], tolerate unknown fields, no panic on unknown enum). Note contact_name_on_invoices is a boolean toggle (not a name).
• Known gaps: attachment download-by-id path is not yet path-safe (the attachment id still embeds a URL); JPY zero-decimal + calculator reconciliation fixtures pending a sandbox probe; no invoice-history endpoint; production app / high-volume sign-off is a dev-portal chore.

Microsoft Dynamics 365 Business Central (Accounting Integration) #

Microsoft Dynamics 365 Business Central (BC) is Microsoft’s cloud ERP for small and mid-sized businesses. Only the online SaaS product is supported, via BC REST API v2.0; on-premises Business Central is out of scope.

⚠️ Dynamics 365 is a suite, not one product. This connector targets Business Central only. Dynamics 365 Finance & Operations (F&O) is a different product with a different API and is NOT supported — check which product the customer actually runs before triaging a “Dynamics” ticket.

• Provider Code: DYNAMICS_BC
• Authentication: OAuth2 (authorization-code) via Microsoft Entra ID, delegated — the connecting user must hold a Business Central license.

Auth / Connection Model #

• Authorize/token endpoints: https://login.microsoftonline.com/common/oauth2/v2.0/authorize / .../token (the multi-tenant common endpoint, so any BC tenant can consent).
• Scope: https://api.businesscentral.dynamics.com/.default offline_access — offline_access is mandatory; without it Entra issues no refresh token.
• Token lifecycle (support-relevant): access token ~1 h; the refresh token is 90-day rolling and rotates on every use. It is revoked when the connecting user is disabled, resets their password, or an admin revokes consent — the heartbeat then flips the integration to unauthorized and the customer must reconnect. This is the #1 expected support scenario for this connector.
• Composite “organization”: unlike Xero’s single org-picker, BC addresses data by Entra tenant × environment × company, so activation has two picker levels (environment, then company). The selector is stored as {tenantId}:{environmentName}:{companyId}.
• Company-scoped URLs: every data call hits {host}/v2.0/{tenant}/{environment}/api/v2.0/companies({companyId})/<entity>. Environment discovery is GET {host}/environments/v1.2 (bare host, NOT under the API base).
• Read-replica reads: all sync GETs (including attachment downloads) send Data-Access-Intent: ReadOnly.
• Rate limits: 6,000 requests / 5 min, 5 concurrent. 429 responses carry no Retry-After header, so the client applies a conservative 30 s fallback backoff via IntegrationRetryAfterCache.
• Credentials: DYNAMICS_BC_CLIENT_ID / DYNAMICS_BC_CLIENT_SECRET, redirect via OAUTH_REDIRECT_URL. Host/auth/token URLs are overridable via DYNAMICS_BC_API_BASE_URL / DYNAMICS_BC_AUTH_URL / DYNAMICS_BC_TOKEN_URL or the task-local runtime config (.config.yaml).

APIs Required for Activation #

1. Get OAuth Authorization URL

   POST /api/v1/integrations/oauth/authorize
   

   • Parameters:
     • entity_id (required): UUID of the entity
     • provider: DYNAMICS_BC
     • redirect_url (required): URL to redirect after OAuth flow
   • Response: Returns the Microsoft Entra ID authorization URL

2. Fetch Available Organizations

   GET /api/v1/integrations/{integrationId}/accounting-organizations
   

   • Parameters:
     • integrationId (required): UUID of the integration
     • entity_id (required): UUID of the entity
   • Response: List of environment × company pairs. The backend enumerates environments (GET /environments/v1.2), then companies per environment; each organization id is the composite selector {tenantId}:{environmentName}:{companyId}.

3. Setup Integration

   PUT /api/v1/integrations/{integrationId}
   

   • Parameters:

     • integrationId (required): UUID of the integration
     • entity_id (required): UUID of the entity

   • Request Body:

     {
       "status": "PENDING",
       "public_metadata": {
         "provider": "DYNAMICS_BC",
         "tenant_id": "f1e2d3c4-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
         "environment_name": "production",
         "company_id": "6b1c31d8-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
       }
     }
     

   • The activate request carries only the selector; company_name, base_currency, and multi_currency_enabled are resolved from Business Central server-side.

   • Activation also seeds the company’s tax codes as internal, editable Tofu tax rates (see Tax rates below).

Per-Object Support #

Attachments: an invoice/bill’s documents are read from two collections (attachments and documentAttachments) plus the BC-rendered pdfDocument. The stored attachment id is prefixed (att: / docatt: / pdf:) and download routes by prefix to attachments({id})/attachmentContent, documentAttachments({id})/attachmentContent, or pdfDocument/pdfDocumentContent. Attachment upload/delete is not supported (read-only connector).

Business Central Account Category Mapping #

BC’s category field (“G/L Account Category”) maps onto Tofu’s AccountClass:

Note:

• Blank/unknown categories default to Expense with a warning logged.
• Only accountType == "Posting" rows are ingested; Heading/Total/Begin Total/End Total rows are dropped.
• The BC chart of accounts never yields Bank/CreditCard classes — bank accounts live in the separate bankAccounts entity, which is not ingested.

Business Central Notes #

• Read-only + contact write-back: read_only_access().with_create_contacts().with_direct_expense_self_prompt().with_have_header_level_tags() — can_publish / can_sync / can_import are false. Self-prompt is ON for AP bills, AR invoices, AND direct expenses; header-level tags are ON. Contact create/update (TIN) is the only write to BC.
• Feature flag: requires dynamics_bc_integration enabled on the organization before the provider appears in the UI.
• Known gaps / runtime notes:
  • Sales/purchase invoices are aggregate entities with a shared status enum (" ", Draft, In Review, Open, Paid, Canceled, Corrective); a posted document’s id differs from its systemId.
  • VAT is computed per document per VAT-Identifier with a manual tolerance, so server net* totals are trusted rather than recomputed; opt-in invoice rounding can add an extra G/L line; pricesIncludeTax is per-document.
  • Enum/format quirks: blocked is a string enum (with a blank member) on customers/vendors but a boolean on items/accounts; amountDecimalPlaces is a string; Comment lines carry no amounts.
  • All decoders are open-world (live payloads exceed the documented schema; vNext adds enum members such as Allocation Account).
  • Localization drift: US (Sales Tax) vs EU/UK (VAT) tenants populate fields differently; taxType follows the tenant’s GeneralLedgerSetup.UseVat().
  • Pagination follows the server’s absolute @odata.nextLink, validated against the API host before following (SSRF guard), with a defensive 50-page cap per call.
  • Tag auto-assign: BC dimensions expose no scope/level, so per the ENG-5093 pattern AI tag auto-assign should be OFF, but the capabilities arm currently leaves it at the read-only default (ON) — pending reconciliation.
  • Sandbox-dependent, still unconfirmed: Retry-After presence on 429; lastModifiedDateTime $filter behavior; whether LCY ever appears in currencies; G/L Setup rounding defaults / VAT Rounding Type.

SharePoint (Trigger Integration) #

SharePoint integration allows you to monitor specific SharePoint sites and document libraries for new documents.

Provider Code: SHAREPOINT

APIs Required for Activation #

1. Get OAuth Authorization URL

   POST /api/v1/integrations/oauth/authorize
   

   • Parameters:
     • entity_id (required): UUID of the entity
     • provider: SHAREPOINT
     • redirect_url (required): URL to redirect after OAuth flow
   • Response: Returns authorization URL for SharePoint OAuth flow

2. Fetch Available Sources

   GET /api/v1/integrations/{integrationId}/trigger-sources
   

   • Parameters:
     • integrationId (required): UUID of the integration
     • entity_id (required): UUID of the entity
   • Response: List of available SharePoint sites

3. Fetch Sub-sources (Document Libraries)

   GET /api/v1/integrations/{integrationId}/trigger-sources/{sourceId}/sub-sources
   

   • Parameters:
     • integrationId (required): UUID of the integration
     • sourceId (required): SharePoint site ID
     • entity_id (required): UUID of the entity
   • Response: List of document libraries in the specified site

4. Setup Integration

   PUT /api/v1/integrations/{integrationId}
   

   • Parameters:

     • integrationId (required): UUID of the integration
     • entity_id (required): UUID of the entity

   • Request Body:

     {
       "status": "PENDING",
       "public_metadata": {
         "provider": "SHAREPOINT",
         "source_id": "sharepoint-site-id",
         "sub_source_id": "document-library-id",
         "directories": ["path/to/watch", "another/path"]
       }
     }
     

Google Drive (Trigger Integration) #

Google Drive integration allows you to monitor specific Google Drive folders for new documents.

Provider Code: GOOGLE_DRIVE

APIs Required for Activation #

1. Get OAuth Authorization URL

   POST /api/v1/integrations/oauth/authorize
   

   • Parameters:
     • entity_id (required): UUID of the entity
     • provider: GOOGLE_DRIVE
     • redirect_url (required): URL to redirect after OAuth flow
   • Response: Returns authorization URL for Google Drive OAuth flow

2. Fetch Available Sources

   GET /api/v1/integrations/{integrationId}/trigger-sources
   

   • Parameters:
     • integrationId (required): UUID of the integration
     • entity_id (required): UUID of the entity
   • Response: List of available Google Drive folders

3. Fetch Sub-sources (Sub-folders)

   GET /api/v1/integrations/{integrationId}/trigger-sources/{sourceId}/sub-sources
   

   • Parameters:
     • integrationId (required): UUID of the integration
     • sourceId (required): Google Drive folder ID
     • entity_id (required): UUID of the entity
   • Response: List of sub-folders in the specified folder

4. Setup Integration

   PUT /api/v1/integrations/{integrationId}
   

   • Parameters:

     • integrationId (required): UUID of the integration
     • entity_id (required): UUID of the entity

   • Request Body:

     {
       "status": "PENDING",
       "public_metadata": {
         "provider": "GOOGLE_DRIVE",
         "source_id": "google-drive-folder-id",
         "sub_source_id": "sub-folder-id",
         "directories": ["path/to/watch", "another/path"]
       }
     }
     

Complete API Documentation #

For detailed API specifications, request/response schemas, and additional endpoints, refer to the OpenAPI documentation.