# Henda — Multi-Tenant Headless General Ledger, Subledger & Graph API (v2.0.0)

> Multi-Book Headless General Ledger, Accounts Receivable Subledger, Oracle Cash Management Bank Reconciliation, Henda Excel Add-in Engine, Graph API, and Model Context Protocol (MCP) Server.

## Standard Machine-Readable Discovery Files
- **Interactive Developer & API Documentation Portal**: https://www.henda.ai/docs
- **OpenAPI 3.1.0 Specification (JSON)**: https://www.henda.ai/openapi.json
- **GraphQL Schema Definition Language (SDL)**: https://www.henda.ai/graphql/schema.graphql
- **Full JSON API & Module Discovery Catalog**: https://www.henda.ai/v1/discovery
- **GraphQL Endpoint**: `POST https://www.henda.ai/graphql`
- **Native Graph Batch Endpoint**: `POST https://www.henda.ai/v1/batch`
- **TwentyCRM-Compatible REST Batch Endpoint**: `POST https://www.henda.ai/rest/batch/:objectName`
- **MCP Streamable HTTP Endpoint**: `POST https://www.henda.ai/mcp` (63 tools)

## Strict General Ledger & Chart of Accounts Invariants
- Chart of Accounts segment structure (1..10 segments, segment_num, segment_name, qualifier, exact_length, numeric_only) is defined explicitly via typed segments at Set of Books creation time (create_set_of_books / createGlLedgers).
- Account and segment-value operations (create_account, upsert_accounts, upsert_segment_values, createGlAccounts, createGlSegmentValues) strictly enforce exact_length and numeric_only rules and support parent/child hierarchies (is_summary=true for parent rollup headers, parent_code for child accounts/segment values).
- Double-entry equilibrium (Total Debits == Total Credits), Balancing Segment equilibrium, period status controls (OPEN vs CLOSED), and budget journal enforcement (require_budget_journals) are strictly enforced.

## Modules & Endpoints
### Multi-Tenant Onboarding, API Keys & Set of Books RBAC
Tenant workspace registration and onboarding (provisioning tenant_id UUID, primary ORG_ADMIN user, initial Set of Books with 1..10 CoA segments, and initial API Key), Bearer API Key generation/revocation, Set of Books access matrix, and OAuth 2.0 MCP discovery.
- `GET /v1/tenants` — List registered tenant workspaces, their associated Sets of Books (sob_id), and active API key count
- `POST /v1/tenants/register` — Register & provision a new tenant workspace, primary admin user, optional initial Set of Books (1..10 segments), and scoped Bearer API Key
- `GET /v1/auth/api-keys` — List active & revoked Private API Keys (masked prefix, scopes, allowed_sob_ids)
- `POST /v1/auth/api-keys` — Generate a new Private API Key scoped to a tenant_id and allowed Sets of Books
- `DELETE /v1/auth/api-keys/:keyId` — Revoke a Private API Key immediately
- `GET /v1/auth/users` — List organization users and their Set of Books (SOB) query/post access matrix
- `POST /v1/auth/users` — Invite or update an organization user and assign accessible Sets of Books (sob_ids)
- `PATCH /v1/auth/users/:userId/sob-access` — Grant or revoke a user access to a specific Set of Books (sob_id)
- `POST /v1/auth/login` — Authenticate a user and cache selected Sets of Books for session / Henda Excel Add-in queries
- **GraphQL Queries**: `glLedgers`
- **GraphQL Mutations**: `createGlLedgers(ledgers)`

### General Ledger & Chart of Accounts (1..10 Segments)
Multi-Book Sets of Books (SOB 1, 2, 3...), 1..10 Segment Key Flexfield Chart of Accounts (BALANCING, NATURAL_ACCOUNT, COST_CENTER, INTERCOMPANY, CUSTOM), and Parent/Child Accounts & Segment Values (is_summary, parent_code, account_sub_type, default_tax_rate_code, hidden_description).
- `GET /v1/accounts` — List CoA segment definitions (1..10) and Parent/Child Accounts & Segment Values for a Set of Books (sob_id, segment_num, account_category, account_sub_type, search)
- `POST /v1/accounts` — Create a single Account/Segment Value or batch-upsert an array of Accounts/Segment Values across segments 1..10
- `GET /v1/segment-values` — List CoA segment definitions (1..10) and Segment Values (alias for /v1/accounts)
- `POST /v1/segment-values` — Create or batch-upsert Segment Values across segments 1..10 (supports parent summary is_summary=true and child parent_code)
- `PATCH /v1/segment-values/:valueId` — Update/rename an Account or Segment Value (account_name, description, hidden_description, account_sub_type, default_tax_rate_code, parent_code, is_summary, allow_posting, is_active)
- `DELETE /v1/segment-values/:valueId` — Delete an unused Account or Segment Value (verifies zero posted journal lines)
- `POST /v1/calendars` — Create an Accounting Fiscal Calendar & Periods
- `POST /v1/coa-structures` — Create a Chart of Accounts Key Flexfield Structure (1..10 segments)
- `POST /v1/ledgers` — Create a Set of Books (General Ledger)
- `POST /v1/coa-structures/:coaStructureId/segment-values` — Create a Segment Value in a specific CoA Structure UUID
- `POST /v1/coa-structures/:coaStructureId/code-combinations` — Resolve or dynamically create a Code Combination (CCID)
- **GraphQL Queries**: `glLedgers`, `glCoaSegments(sobId)`, `coaStructure(sobId)`, `glAccounts(sobId, segmentNum, accountCategory, accountSubType, search)`, `glSegmentValues(sobId, segmentNum, accountCategory, accountSubType, search)`
- **GraphQL Mutations**: `createGlLedgers(ledgers)`, `createGlAccounts(sobId, accounts)`, `updateGlAccounts(sobId, accounts)`, `createGlSegmentValues(sobId, segmentValues)`, `updateGlSegmentValues(sobId, segmentValues)`, `deleteGlAccounts(sobId, deleteCodes, segmentNum)`

### Double-Entry Journals, Fiscal Periods & Financial Statements
Atomic double-entry journal posting (single or vectorized batch), journal reversal, fiscal period OPEN/CLOSED control with automatic balance roll-forward, Year-End Close rollover, Trial Balance, P&L, Balance Sheet, and Account Activity Drilldown.
- `POST /v1/journals` — Post a balanced Double-Entry Journal Entry (or vectorized batch of journals)
- `POST /v1/journals/batch` — Vectorized high-speed batch journal posting engine
- `POST /v1/journals/:jeHeaderId/reverse` — Reverse a posted Journal Entry
- `GET /v1/ledgers/:ledgerId/periods` — List fiscal periods and statuses for a Set of Books
- `PATCH /v1/ledgers/:ledgerId/periods` — Open or Close a fiscal period (rolls forward Asset/Liability/Equity balances)
- `POST /v1/ledgers/:ledgerId/year-end-close` — Run Year-End Close rollover into Retained Earnings
- `GET /v1/ledgers/:ledgerId/trial-balance` — Get Trial Balance rollup (supports Actuals, Budgets, and Variance comparison)
- `GET /v1/ledgers/:ledgerId/financial-statements` — Get Financial Statement (PNL or BALANCE_SHEET)
- `GET /v1/ledgers/:ledgerId/drilldown` — Drill down into posted journal lines for an account or segment filter
- **GraphQL Queries**: `glPeriods(sobId)`, `trialBalance(sobId, periodName, actualFlag, budgetName, compareBudgetName)`, `pnl(sobId, periodName)`, `balanceSheet(sobId, periodName)`
- **GraphQL Mutations**: `createGlJournals(sobId, actualFlag, budgetName, journals)`, `manageGlPeriods(sobId, periods)`

### Oracle GL Budgets & Forecasts
Multi-version Budgets and Rolling Forecasts per Set of Books with configurable require_budget_journals control (direct balance injection vs formal budget journals) and Actual vs Budget variance reporting.
- `GET /v1/budgets` — List Budgets and Forecasts for a Set of Books (sob_id)
- `POST /v1/budgets` — Create a Budget or Forecast version (supports copy_from_budget_name)
- `PATCH /v1/budgets/:budgetId` — Update Budget status (OPEN, CURRENT, FROZEN) or require_budget_journals flag
- `POST /v1/budgets/inject` — Inject budget balances across periods or annual spread rules (when require_budget_journals=false)
- `POST /v1/budgets/journals` — Post balanced double-entry Budget Journals (actual_flag="B")
- **GraphQL Queries**: `glBudgets(sobId)`
- **GraphQL Mutations**: `createGlBudgets(sobId, budgets)`, `injectGlBudgetBalances(sobId, budgetName, mode, budgetEntries)`

### Accounts Receivable (AR) & AI Invoice Branding Studio
Accounts Receivable subledger: AR GL Control Account onboarding setup, Tax Rates, Contacts (Customers & Suppliers), non-inventory Products & Services, multi-line Sales Invoices (Draft -> Approved -> Posted to GL -> Paid), Customer Payments, and AI-customizable HTML/PDF Invoice Layouts.
- `GET /v1/ar/setup` — Get AR subledger onboarding status and GL control account mapping
- `POST /v1/ar/setup` — Configure AR subledger GL control accounts (AR Control, Tax Liability, Default Sales Revenue)
- `GET /v1/ar/tax-rates` — List Tax Rates (GST on Income, GST Free, BAS Excluded, etc.)
- `POST /v1/ar/tax-rates` — Create or update an AR Tax Rate
- `DELETE /v1/ar/tax-rates/:taxRateId` — Delete or deactivate a custom Tax Rate
- `GET /v1/ar/contacts` — List Customer & Supplier Contacts with outstanding & overdue AR balances
- `POST /v1/ar/contacts` — Create or update a Customer or Supplier Contact
- `GET /v1/ar/products` — List non-inventory Products & Services
- `POST /v1/ar/products` — Create or update a non-inventory Product or Service
- `DELETE /v1/ar/products/:productId` — Deactivate, reactivate, or delete an unused Product/Service
- `GET /v1/ar/invoices` — List Sales Invoices with status, due amounts, and GL posting status
- `POST /v1/ar/invoices` — Create or update a Sales Invoice (supports auto_approve and auto_post_to_gl)
- `POST /v1/ar/invoices/approve` — Approve a Draft Sales Invoice and optionally post to GL
- `POST /v1/ar/invoices/post-to-gl` — Post approved Sales Invoice(s) to the General Ledger (respects OPEN/CLOSED period policies)
- `POST /v1/ar/invoices/payments` — Record a Customer Payment against an Invoice and post Cash Receipt journal to GL
- `POST /v1/ar/invoices/void` — Void an Invoice and automatically reverse its GL journal if posted
- `GET /v1/ar/invoice-layouts` — List AI-customizable Invoice Layouts & Branding Themes
- `POST /v1/ar/invoice-layouts` — Create or update an Invoice Layout (THEME_TOKENS or CUSTOM_HTML)
- `POST /v1/ar/invoice-layouts/render` — Render an Invoice into a standalone print-ready HTML document
- `GET /invoices/:sobId/:invoiceNumber` — Browser-accessible standalone HTML Invoice document view
- **GraphQL Queries**: `arSetup(sobId)`, `arTaxRates(sobId)`, `arContacts(sobId, contactType, search)`, `arProducts(sobId, search)`, `arInvoices(sobId, status, glPostingStatus, search)`, `arInvoiceLayouts(sobId)`
- **GraphQL Mutations**: `configureArSetup(sobId, setup)`, `upsertArTaxRates(sobId, taxRates)`, `upsertArContacts(sobId, contacts)`, `upsertArProducts(sobId, products)`, `createArInvoices(sobId, invoices)`, `approveArInvoices(sobId, invoices)`, `postArInvoicesToGl(sobId, options)`, `recordArPayments(sobId, payments)`, `upsertArInvoiceLayouts(sobId, layouts)`

### Oracle Cash Management (CE) & AI Bank Reconciliation
Bank, Credit Card, and Clearing account designation, multi-format Bank Statement Import Wizard (CSV, TSV, OFX/QFX, CAMT.053, JSON) with SHA-256 duplicate protection, and 4-tier AI reconciliation engine (Existing GL Journal Match -> Deterministic Rules -> MY_ACCOUNTANT.MD + hidden_description AI -> User Resolution).
- `GET /v1/bank-accounts` — List designated Bank, Credit Card, and Clearing accounts
- `POST /v1/bank-accounts` — Designate or update a Bank Account linked to a GL Cash/Card account
- `PATCH /v1/sob-bank-settings` — Update Set of Books bank reconciliation posting mode (AUTO_POST_HIGH_CONFIDENCE, REVIEW_ALL, AUTO_POST_ALL)
- `POST /v1/bank-reconciliation-rules` — Create or update a deterministic Bank Reconciliation Rule
- `POST /v1/bank-statements/preview` — Preview & auto-detect format/columns of a raw Bank Statement export
- `POST /v1/bank-statements/import` — Import Bank Statement lines and run 4-tier reconciliation
- `POST /v1/bank-statements/process` — Run or re-run the 4-tier Bank Reconciliation engine
- `POST /v1/bank-statements/resolve` — Approve AI suggestions, assign GL accounts, or ignore statement lines (can save learned rules)
- `GET /v1/bank-reconciliation` — Get Bank-to-GL Reconciliation Report and line-by-line status
- **GraphQL Queries**: `bankAccounts(sobId)`, `bankReconciliation(sobId, periodName, bankAccountId)`
- **GraphQL Mutations**: `upsertBankAccounts(sobId, bankAccounts)`, `importBankStatement(sobId, statement)`, `processBankStatement(sobId, options)`, `resolveBankStatementLines(sobId, resolutions)`

### Henda Excel Add-in, AI Accountant Brain & Multi-Book Security
Live Henda Excel Add-in formula endpoints (=Get_Balance, =Segment_Description, Expand, Drilldown), server-side .xlsx report generator, per-Set-of-Books AI Accountant Brain (MY_ACCOUNTANT.MD), and Multi-User Set of Books RBAC.
- `GET /v1/accountant-brain` — Get compiled MY_ACCOUNTANT.MD AI Accountant Brain & CoA intended usage rules
- `PATCH /v1/accountant-brain` — Update MY_ACCOUNTANT.MD policies, append learned rules, or update account hidden_description rules
- `POST /v1/reports/excel` — Generate a multi-sheet .xlsx Financial Workbook (Trial Balance, P&L, Balance Sheet, Henda Excel Add-in Formulas)
- `GET /v1/reports/download/:filename` — Download a generated .xlsx report workbook
- `GET /gl-wand` — Open the Interactive Henda Excel Add-in Web Workbench
- `POST /v1/gl-wand/get-balance` — Evaluate Henda Excel Add-in Get_Balance() formula with ranges, wildcards, and parent rollups across 1..10 segments
- `POST /v1/gl-wand/drilldown` — Drill down from a Henda Excel Add-in balance cell into underlying journal lines & source invoice links
- `GET /v1/auth/users` — List users and their Set of Books (SOB) access matrix
- **GraphQL Queries**: `accountantBrain(sobId)`, `glWandBatchBalances(balanceQueries)`, `glWandBatchDescriptions(descriptionQueries)`
- **GraphQL Mutations**: `executeGraphBatch(batch)`

## MCP Tools (63 Registered Tools)
- `get_sets_of_books_status` (`POST /v1/gpt/get_sets_of_books_status`): Get comprehensive status of all Sets of Books (SOB 1, SOB 2, SOB 3...), including functional currency, company description, MY_ACCOUNTANT.MD rules, open/closed accounting periods, posted journal counts, Trial Balance equilibrium status, and active user session access.
- `get_accountant_brain` (`POST /v1/gpt/get_accountant_brain`): Get the complete AI Accountant Brain (`MY_ACCOUNTANT.MD`) for a Set of Books (`sob_id`), including what the company/Set of Books is about (`description`), standing accounting policies & learned user preferences (`my_accountant_md`), open periods, every Chart of Accounts segment & account with its intended usage (`hidden_description`), and the full compiled `MY_ACCOUNTANT.MD` context document.
- `update_accountant_brain` (`POST /v1/gpt/update_accountant_brain`): Update the AI Accountant Brain (`MY_ACCOUNTANT.MD`) for a Set of Books (`sob_id`): update the Set of Books company `description` (what the company is about), replace `my_accountant_md`, append a new learned user preference/feedback rule (`append_learned_rule`), or update intended account usage descriptions (`account_rules`).
- `create_set_of_books` (`POST /v1/gpt/create_set_of_books`): Create a new Set of Books (General Ledger) with its own SOB_ID, Functional Currency (e.g. AUD, USD, EUR, SGD), company description, MY_ACCOUNTANT.MD rules, and its own isolated Chart of Accounts (coa_structure_id) supporting 1 to 10 segments (e.g. 3 segments: Company-Account-Cost Center, or 6 segments: Company-Natural Account-Cost Centre-Product-Channel-Intercompany, up to 10 segments). Pass `segments` to define 1..10 custom segments and their default values, and optionally pass `accounts` to seed right away.
- `list_accounts` (`POST /v1/gpt/list_accounts`): List Chart of Accounts segment definitions (1..10) and Natural Accounts / Flexfield Segment Values for a Set of Books (sob_id), including code, account_name, description, and hidden_description (AI/AR automatic journal allocation rules).
- `batch_execute` (`POST /v1/gpt/batch_execute`): High-Speed Graph & Bulk Operations Engine (TwentyCRM-style batch mutations + compound queries in a single sub-10ms transaction). PREFERRED whenever creating a multi-segment Set of Books (1 to 10 segments), creating/renaming/deleting multiple accounts or segment values (across segments 1..10), opening/closing multiple periods, or posting multiple journals at once. Can also return requested reports (status, accounts, trial_balance, pnl, balance_sheet, periods) in the same round-trip.
- `create_account` (`POST /v1/gpt/create_account`): Create a single Natural Account or Segment Value (across any segment_num 1..10) OR pass `accounts` (array) to batch-create/upsert many accounts/segment values at once in a single fast SQL transaction for a Set of Books (`sob_id`).
- `rename_account` (`POST /v1/gpt/rename_account`): Rename/update a single Account or Segment Value (`code`) OR pass `accounts` (array) to batch-rename/update multiple accounts/segment values (across segments 1..10) in a single fast SQL transaction for a Set of Books (`sob_id`).
- `delete_account` (`POST /v1/gpt/delete_account`): Delete a single Account (`code`) OR pass `codes` (array of strings) to batch-delete multiple accounts/segment values from a Set of Books (`sob_id`) in one call. Safely prevents deletion if posted journal entries reference an account.
- `manage_period_status` (`POST /v1/gpt/manage_period_status`): Open or Close one period (`period_name`) OR a batch of periods (`period_names` or `periods`) for a Set of Books (`sob_id`). Automatically rolls forward ending balances when opening a period.
- `get_ledger_periods` (`POST /v1/gpt/get_ledger_periods`): List all fiscal periods (JUL-26 through ADJ-27) and their OPEN / CLOSED / NEVER_OPENED statuses for a Set of Books.
- `post_journal_entry` (`POST /v1/gpt/post_journal_entry`): Post a single balanced double-entry journal (`name` + `lines`) OR pass `journals` (array) to batch-post multiple journals in one call for any Set of Books (`sob_id`). Supports both Actual journals (`actual_flag: "A"`) and Budget journals (`actual_flag: "B"` + `budget_name`). Lines specify major currency amounts (debit: 1500.00, credit: 1500.00).
- `reverse_journal_entry` (`POST /v1/gpt/reverse_journal_entry`): Reverse a posted journal entry by its je_header_id, creating an immutable contra-journal that swaps debits and credits.
- `get_trial_balance` (`POST /v1/gpt/get_trial_balance`): Query the pre-aggregated Trial Balance for a Set of Books (sob_id 1, 2, 3...) and period (e.g. "OCT-26"). Supports Actuals (`actual_flag: "A"`), Budget/Forecast versions (`actual_flag: "B"`, `budget_name`), and Actual vs. Budget variance (`compare_budget_name`).
- `get_financial_statement` (`POST /v1/gpt/get_financial_statement`): Generate a Profit & Loss (PNL) or Balance Sheet (BALANCE_SHEET) statement for a Set of Books (sob_id 1, 2, 3...) and period. Supports Actuals (`actual_flag: "A"`), Budget/Forecast versions (`actual_flag: "B"`, `budget_name`), and Actual vs. Budget variance (`compare_budget_name`).
- `get_balance` (`POST /v1/gpt/get_balance`): Evaluate a Henda Excel Add-in =Get_Balance(SOB_ID, Period, Balance_Type, Currency, Currency_Type, Actual_Flag, Budget_Name, Seg1..Seg10) formula with support for up to 10 segments (segment1..segment10), wildcards (%), ranges (4000-6999 or 1-3), comma lists (1010,1200), exclusions (~3), Actuals (`actual_flag: "A"`), and named Budget/Forecast versions (`actual_flag: "B"`, `budget_name: "FY27_BUDGET"` or `"FY27_FORECAST"`).
- `drilldown_account_activity` (`POST /v1/gpt/drilldown_account_activity`): Drill down into posted journal lines and full `source_journals` for a Set of Books (sob_id 1, 2, 3... or "%"), period, optional account combination (`01-1200-000` or natural account `1200`), optional `je_source` filter (`"MANUAL"` or `"ACCOUNTS_RECEIVABLE"`), and Actuals (`actual_flag: "A"`) or Budget version (`actual_flag: "B"`, `budget_name`). When a journal originates from Accounts Receivable (`je_source = "ACCOUNTS_RECEIVABLE"`), returns the full `source_journal` (all sibling debit/credit lines), the `source_invoice` detail (customer, dates, line items, quantities, prices, tax), and a clickable `invoice_url` (`/invoices/:sobId/:invoiceNumber`) where the actual invoice document can be opened in a browser.
- `suggest_ai_transaction_allocation` (`POST /v1/gpt/suggest_ai_transaction_allocation`): Phase 2 AI/AR Brain: Analyze an inbound transaction description, counterparty, and amount against every account's account_name, description, and hidden_description (AI allocation rules) to recommend or auto-post the Debit & Credit journal entry.
- `run_year_end_close` (`POST /v1/gpt/run_year_end_close`): Run the Year-End Close process for a Set of Books: close all YTD Revenue & Expense balances into Retained Earnings (3200) and close the fiscal period.
- `manage_users_and_sob_access` (`POST /v1/gpt/manage_users_and_sob_access`): List organization users, invite a new user with Set of Books permissions and send an invitation email via Resend (`invite`), accept an invitation token to activate the user and issue a Personal Access Token (`accept_invitation`), generate a user-level Personal Access Token (`create_token`), toggle SOB access (`toggle_access`), preview accessible Sets of Books (`preview_books`), or switch the active cached Sets of Books session (`login`).
- `create_budget` (`POST /v1/gpt/create_budget`): Create a new Oracle GL Budget or Forecast version linked to a Set of Books (`sob_id`). Automatically inherits all fiscal periods in the Set of Books' fiscal year (e.g. JUL-26 through ADJ-27). Set `require_budget_journals: true` to require formal double-entry budget journals, or `require_budget_journals: false` (default) to allow direct top-level balance injection into `gl_balances`. Optionally copy balances from an existing budget version via `copy_from_budget_name`.
- `list_budgets` (`POST /v1/gpt/list_budgets`): List all Oracle GL Budgets and Forecast versions defined for a Set of Books (`sob_id`) or across all Sets of Books, including inherited period ranges (`first_valid_period_name` to `last_valid_period_name`), `require_budget_journals` flag, status (`OPEN`, `CURRENT`, `FROZEN`), posted budget journal count, and total budgeted amounts.
- `update_budget` (`POST /v1/gpt/update_budget`): Update an existing Budget or Forecast version's `status` (`OPEN`, `CURRENT`, `FROZEN`), `require_budget_journals` flag (`true` or `false`), `budget_type` (`BUDGET` or `FORECAST`), `description`, or valid period range.
- `inject_budget_balances` (`POST /v1/gpt/inject_budget_balances`): Directly inject or update budget/forecast amounts in the top-level `gl_balances` table (`actual_flag = "B"`, linked to `budget_name`) WITHOUT creating journal entries, when `require_budget_journals = false` on the target budget. Supports single-period amounts (`period_name` + `amount` or `debit`/`credit`), multi-period maps (`periods: { "JUL-26": 10000, "AUG-26": 12000 }`), or 12-month annual spreading (`annual_amount` + `spread_rule: "EVEN" | "4_4_5"`), and automatically rolls forward YTD balances across all fiscal periods.
- `generate_excel_report` (`POST /v1/gpt/generate_excel_report`): Generates a formatted Microsoft Excel (.xlsx) workbook populated with live =Get_Balance($C$4, $C$5, $C$6, $C$7, "E", "A", "", $F$4, $A11, $B11) formulas, pre-calculated numeric values, and an interactive Yellow Parameter Block ($C$4 = SOB_ID, $C$5 = Period, $C$6 = Balance_Type, $C$7 = Currency, $C$8 = Budget_Name, $F$4 = Company Seg1, $F$5 = Cost Center Seg3). Supports report_type = "FINANCIAL_PACK" (3 tabs: P&L, Balance Sheet, Trial Balance), "PNL", "BALANCE_SHEET", "TRIAL_BALANCE", "MULTI_PERIOD_TREND" (side-by-side period columns), "MULTI_BOOK_CONSOLIDATION" (side-by-side Set of Books columns), or "CUSTOM". Returns a direct clickable download_url.
- `list_bank_accounts` (`POST /v1/gpt/list_bank_accounts`): List all Oracle Cash Management (CE) Bank Accounts (`ce_bank_accounts`), designated Bank/Credit Card/Clearing GL accounts (`account_sub_type`), Set of Books bank reconciliation posting mode (`bank_recon_posting_mode`: `AUTO_POST_HIGH_CONFIDENCE` | `REVIEW_ALL` | `AUTO_POST_ALL`), and deterministic bank reconciliation rules (`ce_reconciliation_rules`) for a Set of Books (`sob_id`).
- `upsert_bank_account` (`POST /v1/gpt/upsert_bank_account`): Create or update an Oracle Cash Management (CE) Bank Account (`ce_bank_accounts`) and automatically designate its linked GL natural account with `account_sub_type` (`BANK_CASH` or `CREDIT_CARD`). Links the bank account to its primary GL Cash CCID (`gl_account_code`), optional Bank Clearing (`1015`), Bank Charges (`6100`), Interest Income (`4020`), and Suspense (`1200`) accounts.
- `update_sob_bank_recon_settings` (`POST /v1/gpt/update_sob_bank_recon_settings`): Update the Set of Books (`sob_id`) Bank Reconciliation Posting Mode (`bank_recon_posting_mode`: `AUTO_POST_HIGH_CONFIDENCE` | `REVIEW_ALL` | `AUTO_POST_ALL`) and date matching tolerance (`bank_recon_match_days_tolerance` in days).
- `upsert_bank_reconciliation_rule` (`POST /v1/gpt/upsert_bank_reconciliation_rule`): Create or update a deterministic Bank Reconciliation Rule (`ce_reconciliation_rules`) that matches bank statement narratives or counterparties and allocates them to a target GL account and cost center (with optional tax split).
- `preview_bank_statement_import` (`POST /v1/gpt/preview_bank_statement_import`): Parses raw CSV, TSV, OFX/QFX, CAMT.053 XML, or JSON bank exports, auto-detects the format, date convention (DD/MM/YYYY vs MM/DD/YYYY), and column mapping (Date, Description, Amount or Debit/Credit, Counterparty, Reference, Running Balance), normalizes sign polarity, and checks for duplicate lines.
- `import_bank_statement` (`POST /v1/gpt/import_bank_statement`): Imports bank statement lines into `ce_statement_headers` and `ce_statement_lines` (from `raw_content` CSV/OFX/CAMT.053/JSON or structured `lines`), deduplicates overlapping imports via `line_fingerprint`, and by default (`auto_process: true`) runs the 3-Tier Bank Reconciliation Engine respecting the Set of Books `bank_recon_posting_mode`.
- `process_bank_statement` (`POST /v1/gpt/process_bank_statement`): Run the 3-Tier Bank Statement Reconciliation Engine on imported statement lines: Tier 1 matches existing unreconciled GL journal lines on the Bank CCID (`MATCHED_EXISTING_JOURNAL`), Tier 2 evaluates deterministic Bank Rules + AI Accountant Brain (`AUTO_POSTED` or `AI_SUGGESTED` depending on the SOB `bank_recon_posting_mode`), and Tier 3 flags ambiguous lines as `NEEDS_USER_INPUT` with a specific question and candidate accounts.
- `resolve_bank_statement_lines` (`POST /v1/gpt/resolve_bank_statement_lines`): Resolve one or more Bank Statement lines that are in `NEEDS_USER_INPUT`, `AI_SUGGESTED`, or `UNPROCESSED` status: approve AI/Rule suggestions (`APPROVE_SUGGESTION`), post to a user-specified GL account or multi-line split (`POST_NEW_JOURNAL`), link to an existing GL journal (`MATCH_EXISTING_JOURNAL`), or exclude (`IGNORE`). Optionally saves the allocation as a reusable Bank Rule (`save_as_rule: true`).
- `get_bank_reconciliation_report` (`POST /v1/gpt/get_bank_reconciliation_report`): Generate a comprehensive Bank Reconciliation Report for a Set of Books (`sob_id`) and Bank Account: compares Statement Closing Balance vs. GL Cash Account YTD Balance (`gl_balances`), lists all imported statements (`ce_statement_headers`), breaks down statement lines by status (`MATCHED_EXISTING_JOURNAL`, `AUTO_POSTED`, `USER_POSTED`, `AI_SUGGESTED`, `NEEDS_USER_INPUT`, `UNPROCESSED`), highlights the Action Queue requiring user review/input, and lists Unreconciled GL Cash Journal Lines.
- `get_ar_setup` (`POST /v1/gpt/get_ar_setup`): Get the Accounts Receivable subledger onboarding status and General Ledger Control Account mappings (`ar_control_account_code`, `default_tax_account_code`, `default_sales_account_code`, `default_cost_center_code`) for a Set of Books (`sob_id`).
- `configure_ar_setup` (`POST /v1/gpt/configure_ar_setup`): Onboard or update the Accounts Receivable subledger for a Set of Books (`sob_id`) by mapping it to existing postable GL accounts (`ar_control_account_code`, `default_tax_account_code`, `default_sales_account_code`) or creating missing GL control accounts inline (`create_ar_control_account`, `create_tax_control_account`, `create_sales_account`).
- `list_tax_rates` (`POST /v1/gpt/list_tax_rates`): List all Tax Rates (`ar_tax_rates`) configured for a Set of Books (`sob_id`), including `tax_code`, display `name` (e.g. "GST on Income", "BAS Excluded", "GST Free Income", "GST on Expenses"), effective `rate_percent`, multi-component breakdown, `tax_account_code`, `tax_account_name`, and the count of GL accounts and products using each tax rate.
- `upsert_tax_rate` (`POST /v1/gpt/upsert_tax_rate`): Create or update a Tax Rate (`ar_tax_rates`) for a Set of Books (`sob_id`), with optional `tax_rate_id`, multi-component tax breakdown, `tax_account_code` mapping, and optional GL account assignments (`assign_to_account_codes`).
- `delete_tax_rate` (`POST /v1/gpt/delete_tax_rate`): Delete a non-system Tax Rate (`ar_tax_rates`) that is not referenced by any invoice lines.
- `list_ar_contacts` (`POST /v1/gpt/list_ar_contacts`): List Contacts (`ar_contacts` — Customers, Suppliers, or Both) for a Set of Books (`sob_id`), including contact details, primary contact person, address, and real-time "Invoices owed to you" / "Overdue" balance summaries and invoice lists.
- `upsert_ar_contact` (`POST /v1/gpt/upsert_ar_contact`): Create or update a Contact (`ar_contacts`) in Accounts Receivable / Payable. Defaults `contact_type` to `CUSTOMER` (also supports `SUPPLIER` or `BOTH`), with primary contact person, email, street address, city, state/region, postal code, payment terms (`payment_terms_days`), and default revenue account / tax rate.
- `list_ar_products` (`POST /v1/gpt/list_ar_products`): List non-inventory Products & Services (`ar_products`) for a Set of Books (`sob_id`), including item `code` (e.g. "AppDev", "BS", "PM"), `name`, `sale_price`, preferred GL `sales_account_code` ("4010", "4020"), `sales_tax_rate_code`, `default_cost_center_code`, and `description`.
- `upsert_ar_product` (`POST /v1/gpt/upsert_ar_product`): Create or update a non-inventory Product or Service (`ar_products`, `track_inventory = false` in Products & Services): defines `code`, `name`, `sale_price`, preferred GL `sales_account_code`, `sales_tax_rate_code`, `default_cost_center_code`, and `description`.
- `delete_ar_product` (`POST /v1/gpt/delete_ar_product`): Delete, archive (`mode: "ARCHIVE"`), or restore (`mode: "RESTORE"`) a Product or Service (`ar_products`).
- `list_ar_invoices` (`POST /v1/gpt/list_ar_invoices`): List Accounts Receivable Invoices (`ar_invoices`) with their line items, payments, invoice status (`DRAFT`, `AWAITING_APPROVAL`, `AWAITING_PAYMENT`, `PARTIALLY_PAID`, `PAID`, `VOIDED`), and GL Posting & Closed-Period flags (`gl_posted_flag`, `gl_posting_status`, `issue_date_period_name`, `issue_date_period_status`, `gl_period_name`, `gl_je_header_id`, `gl_posting_error`).
- `get_ar_invoice` (`POST /v1/gpt/get_ar_invoice`): Retrieve a single Accounts Receivable Invoice (`ar_invoices`) by `invoice_id` or `invoice_number` (e.g. "INV-0168"), including its line items, recorded payments, customer contact details, and linked GL journal status.
- `create_ar_invoice` (`POST /v1/gpt/create_ar_invoice`): Create or update a multi-line AR Sales Invoice (`ar_invoices` & `ar_invoice_lines`). Lines can either reference a defined Product (`item_code` / `product_id`, inheriting its preferred GL account, price, tax rate, and description) OR be completely freeform (`description`, `quantity`, `unit_price`, `account_code`, `tax_rate_code`, `division_code`). Follows Henda GL rules: `DRAFT` / `AWAITING_APPROVAL` invoices do not hit the GL (`gl_posted_flag = false`); when `status = "AWAITING_PAYMENT"` or `approve_immediately = true`, it automatically posts a balanced journal to the GL if the issue date period is OPEN, or flags `BLOCKED_PERIOD_NOT_OPEN` if the period is closed/unopened.
- `approve_ar_invoice` (`POST /v1/gpt/approve_ar_invoice`): Approve a `DRAFT` or `AWAITING_APPROVAL` AR Invoice (transitions status to `AWAITING_PAYMENT` and posts the balanced AR journal to the General Ledger or flags `BLOCKED_PERIOD_NOT_OPEN` according to `closed_period_policy`).
- `post_ar_invoices_to_gl` (`POST /v1/gpt/post_ar_invoices_to_gl`): Run the Accounts Receivable -> General Ledger Posting Process (`post_ar_invoices_to_gl`). Sweeps all approved (`AWAITING_PAYMENT`, `PARTIALLY_PAID`, `PAID`) unposted AR invoices (`gl_posted_flag = false`), validates GL period status (`OPEN` vs `CLOSED` / `NEVER_OPENED`), posts balanced double-entry journals (Debit `1200 Accounts Receivable Control`, Credit Line Revenue accounts, Credit `2100 GST/Tax Payable Control`), updates `gl_balances`, and sets `gl_posted_flag = true` & `gl_posting_status = "POSTED"`.
- `record_ar_payment` (`POST /v1/gpt/record_ar_payment`): Record a customer payment against an approved AR Invoice (`ar_payments`): posts a balanced Cash Receipt journal to the General Ledger (Debit `1010 Operating Cash at Bank`, Credit `1200 Accounts Receivable Control`) and updates `amount_paid_minor`, `amount_due_minor`, and `status` (`PARTIALLY_PAID` or `PAID`).
- `void_ar_invoice` (`POST /v1/gpt/void_ar_invoice`): Void an unpaid AR Invoice (`status = "VOIDED"`). If the invoice was already posted to the General Ledger (`gl_posted_flag = true`), automatically reverses its GL journal entry.
- `list_ar_invoice_layouts` (`POST /v1/gpt/list_ar_invoice_layouts`): List all AI-customizable AR Invoice Layouts & Branding Themes (`ar_invoice_layouts`) for a Set of Books (`sob_id`), including their color palette, typography, header style, embedded logo (`logo_data_uri`), custom HTML/CSS template (`template_mode`), and counts of assigned customers & invoices.
- `get_ar_invoice_layout` (`POST /v1/gpt/get_ar_invoice_layout`): Retrieve a single AR Invoice Layout (`ar_invoice_layouts`) by `layout_id` or `layout_code` along with a portable `.henda-layout.json` export bundle.
- `upsert_ar_invoice_layout` (`POST /v1/gpt/upsert_ar_invoice_layout`): Create or update an AI-Customizable AR Invoice Layout / Branding Theme (`ar_invoice_layouts`) for a Set of Books (`sob_id`). Allows ChatGPT, Claude, or a remote AR developer to create or modify invoice styles by speaking to the AI or uploading a logo (`logo_data_uri`), customizing colors (`primary_color`, `accent_color`, `table_header_bg`, `table_header_text`), `header_style` (`CLASSIC_SPLIT` | `MODERN_BANNER` | `MINIMAL_CLEAN` | `BOLD_ACCENT_BAR`), column visibility, EFT bank remittance details, or full Mustache/Handlebars `custom_html_template` + `custom_css`.
- `delete_ar_invoice_layout` (`POST /v1/gpt/delete_ar_invoice_layout`): Delete a non-system AR Invoice Layout (`ar_invoice_layouts`) by `layout_id` or `layout_code`.
- `render_ar_invoice_html` (`POST /v1/gpt/render_ar_invoice_html`): Render an AR Invoice (or sample preview) into a complete standalone HTML/CSS printable document (`html_document`) using the cascading Invoice Layout resolution: Per-Invoice override (`ar_invoices.invoice_layout_id`) -> Per-Customer default (`ar_contacts.default_invoice_layout_id`) -> Set of Books default (`ar_subledger_settings.default_invoice_layout_id`).
- `execute_graphql` (`POST /v1/gpt/execute_graphql`): Execute TwentyCRM-style GraphQL compound queries and plural batch mutations in a single fast call (`POST /graphql`). Supports introspection (`__schema`), compound queries (`glLedgers`, `glCoaSegments`, `coaStructure`, `glAccounts`, `glSegmentValues`, `glPeriods`, `glBudgets`, `trialBalance`, `pnl`, `balanceSheet`, `accountantBrain`, `arSetup`, `arTaxRates`, `arContacts`, `arProducts`, `arInvoices`, `arInvoiceLayouts`, `bankAccounts`, `bankReconciliation`, `glWandBatchBalances`, `glWandBatchDescriptions`), and plural batch mutations (`createGlLedgers`, `createGlAccounts`, `updateGlAccounts`, `createGlSegmentValues`, `updateGlSegmentValues`, `deleteGlAccounts`, `manageGlPeriods`, `createGlJournals`, `createGlBudgets`, `injectGlBudgetBalances`, `configureArSetup`, `upsertArTaxRates`, `upsertArContacts`, `upsertArProducts`, `createArInvoices`, `approveArInvoices`, `postArInvoicesToGl`, `recordArPayments`, `upsertArInvoiceLayouts`, `upsertBankAccounts`, `importBankStatement`, `processBankStatement`, `resolveBankStatementLines`, `executeGraphBatch`).
- `execute_rest_batch` (`POST /v1/gpt/execute_rest_batch`): Execute a TwentyCRM-compatible REST Batch mutation (`POST /rest/batch/:objectName`) to bulk-create or upsert records in a single call. Supported `object_name` values: `glAccounts`, `glSegmentValues`, `glLedgers`, `glJournals`, `glBudgets`, `glBudgetBalances`, `glBudgetJournals`, `arContacts`, `arProducts`, `arTaxRates`, `arInvoices`, `arInvoiceLayouts`, `ceBankAccounts`.
- `evaluate_gl_wand_batch` (`POST /v1/gpt/evaluate_gl_wand_batch`): Vectorized Henda Excel Add-in Formula Batch Evaluator: evaluates dozens or hundreds of `=Get_Balance(...)` (`balance_queries`) and `=Segment_Description(...)` (`description_queries`) formulas in a single in-memory snapshot pass (`<2ms`). Ideal when building financial models, multi-period matrices, or multi-book consolidations.
- `expand_segment_hierarchy` (`POST /v1/gpt/expand_segment_hierarchy`): Expand a Parent Summary Account (e.g. "1000", "4000", "5000", "6000"), Range ("4000-4999"), List ("1010,1200"), or Wildcard ("%") into its postable child segment values (mirrors the Henda Excel Add-in Expand function and Web Console hierarchy view).
- `resolve_code_combination` (`POST /v1/gpt/resolve_code_combination`): Validate and resolve (or dynamically create) a Chart of Accounts Code Combination (`gl_code_combinations.ccid`) for a Set of Books (`sob_id`), verifying that every segment value exists, is active, and is postable (`allow_posting = true`, `is_summary = false`).
- `manage_tenants_and_api_keys` (`POST /v1/gpt/manage_tenants_and_api_keys`): Manage Multi-Tenant Workspaces & User-Level Personal Access Tokens (`henda_live_...`): list registered tenants (`list_tenants`), register & onboard a new tenant workspace with founding ORG_ADMIN user, optional initial Set of Books, and Resend welcome email (`register_tenant`), list access tokens (`list_api_keys`), generate a new user-scoped Personal Access Token (`create_api_key`), verify a raw token (`verify_token`), or revoke a token (`revoke_api_key`).
- `get_api_and_graph_discovery` (`POST /v1/gpt/get_api_and_graph_discovery`): Retrieve the machine-readable Henda API, GraphQL, Batch & Strict ERP Invariants Discovery Catalog (`GET /v1/discovery`), including all Graph tools, GraphQL queries & plural mutations, REST batch object names, and active Sets of Books.