jaz-cli 2.0.0

package/assets/skills/api/references/feature-glossary.md

@@ -0,0 +1,216 @@
+# Feature Glossary
+
+Business context for Jaz platform features — what they are, when to use them, and which API endpoints correspond. This supplements the API-focused reference files with product knowledge that helps AI agents understand the *purpose* behind API calls.
+
+For full help center content split by section, see [help-center-mirror/](../help-center-mirror/) or [help.jaz.ai](https://help.jaz.ai). For the complete endpoint catalog (80+), see [full-api-surface.md](./full-api-surface.md).
+
+---
+
+## Invoices
+
+Sales documents sent to customers for goods/services rendered. Track Accounts Receivable, support multi-currency with FX gain/loss, and integrate with payments, customer credits, delivery slips, and recurring schedules. Statuses: draft, payment due, overdue, partially paid, fully paid.
+
+Key capabilities: draft/approval workflows, multi-currency (auto-fetch ECB rates or custom org rates), scheduled/recurring invoices with dynamic scheduler strings, delivery slips, sales subscriptions with proration, bulk import (up to 1,000), Quick Fix for bulk field edits, GST/VAT adjustments.
+
+If payment date equals invoice date, it's recorded as a cash transaction (not AR). Transaction fees are deducted from cash received. RGL = `(Invoice payment / Transaction Rate) - (Cash received / Payment Rate)`.
+
+**API**: CRUD `GET/POST/PUT/DELETE /invoices`, `POST /invoices/search`, `POST /invoices/:id/payments`, `GET /invoices/:id/payments`, `POST /invoices/:id/credits`, `GET /invoices/:id/download`, `POST/GET/DELETE /invoices/:id/attachments`, `PUT /invoices/:id/approve`, `POST /scheduled/invoices` (CRUD), `POST /scheduled/subscriptions` (recurring). Generic payment ops: `GET/PUT/DELETE /payments/:id`
+
+---
+
+## Bills
+
+Purchase documents from suppliers for goods/services received. Track Accounts Payable with multi-currency FX. Bills follow the same lifecycle as invoices but with reversed RGL logic and admin-only approval workflows. Supports withholding tax (WHT) on line items.
+
+Key capabilities: bill receipts (short-form template creating bill + payment together), purchase order PDFs from drafts, scheduled/recurring bills, WHT certificate payments (always credited to WHT Payable account), bulk import.
+
+Transaction fees are added to cash spent (not deducted like invoices). RGL = `(Cash spent / Payment rate) - (Bill payment / Transaction rate)`.
+
+**API**: CRUD `GET/POST/PUT/DELETE /bills`, `POST /bills/search`, `POST /bills/:id/payments`, `GET /bills/:id/payments`, `POST /bills/:id/credits`, `POST/GET/DELETE /bills/:id/attachments`, `PUT /bills/:id/approve`, `POST /scheduled/bills` (CRUD). Generic payment ops: `GET/PUT/DELETE /payments/:id`
+
+---
+
+## Customer Credits
+
+Credit notes that reduce amounts owed by customers — issued for returns, discounts, or corrections. Can be applied to invoices (same currency only) or refunded to customers. Statuses: draft, credit available, fully applied.
+
+Active credits only can be applied to invoices. Application has no additional ledger impact (already accounted at creation). Refunds use `refundAmount` + `refundMethod` (NOT `paymentAmount`/`paymentMethod`). Voiding a credit deletes associated refunds and unapplies from invoices.
+
+**API**: CRUD `GET/POST/PUT/DELETE /customer-credit-notes`, `POST /customer-credit-notes/search`, `POST /customer-credit-notes/:id/refunds`, `GET /customer-credit-notes/:id/refunds`, `POST /customer-credit-notes/:id/credits` (apply to invoice), `GET /customer-credit-notes/:id/download`
+
+---
+
+## Supplier Credits
+
+Credit notes that reduce amounts owed to suppliers — issued by suppliers for returns, discounts, or corrections. Can be applied to bills (same currency only) or refunded from suppliers. Same lifecycle as customer credits.
+
+Supports withholding tax on credit line items. Supplier credit note PDFs are NOT available for download (internal records only). Import supports credit notes but NOT refunds.
+
+**API**: CRUD `GET/POST/PUT/DELETE /supplier-credit-notes`, `POST /supplier-credit-notes/search`, `POST /supplier-credit-notes/:id/refunds`, `GET /supplier-credit-notes/:id/refunds`, `POST /supplier-credit-notes/:id/credits` (apply to bill)
+
+---
+
+## Deposits
+
+Track advance payments and prepaid balances. Customer deposits are liabilities (money received before goods/services delivered). Supplier deposits are assets (money paid before goods/services received). Support multi-currency, top-ups, drawdowns, and integration with invoice/bill payment workflows.
+
+Can block payments if deposit balance is insufficient. View all contacts with deposits and filter by balance status. Managed via dedicated deposit accounts in the Chart of Accounts.
+
+There is no dedicated `/deposits` endpoint (returns 404). Deposits are managed through deposit-designated CoA accounts, with transactions recorded as journal entries and payments on invoices/bills drawing from those deposit accounts.
+
+**API**: `POST /journals` (record deposit top-ups/drawdowns via deposit CoA accounts), `POST /chart-of-accounts` (create deposit accounts), `POST /invoices/:id/payments` / `POST /bills/:id/payments` (draw from deposit account via `accountResourceId`)
+
+---
+
+## Journal Entries
+
+Manual accounting entries for non-payment transactions. Three types: Manual Journals (multi-line debit/credit entries), Cash Journals (2-line cash transfers between bank accounts with cross-currency support), and Transfer Journals (year-end trial balance transfers, non-editable).
+
+Minimum 2 balanced entries required. Cash journals are restricted to exactly 2 lines. Bank/cash/current asset/equity/liability accounts cannot have tax profiles applied. Supports scheduled/recurring journals with dynamic scheduler strings (`{{YEAR}}`, `{{MONTH}}`).
+
+Cash transfer FX logic: if either side is base currency, keep as-is; if both non-base, fetch rate for cash-out and derive cash-in. Transfer rate = `Cash-in amount / Cash-out amount`.
+
+**API**: CRUD `GET/POST/PUT/DELETE /journals`, `POST /journals/search`, `POST/GET/DELETE /journals/:id/attachments`, `POST /cash-in-journals`, `POST /cash-out-journals`, `POST /cash-transfer-journals`, `POST /cashflow-transactions/search`, `DELETE /cashflow-journals/:id`, `POST /scheduled/journals` (CRUD)
+
+---
+
+## Capsules
+
+Containers that group related transactions for complex accounting scenarios. Use cases: prepaid expenses (annual insurance amortization), deferred revenue, accrued expenses, fixed asset acquisitions (CIP), intercompany transactions, renovation projects.
+
+A capsule links invoices, bills, journals, and schedulers into a single logical unit. The ledger can be filtered and grouped by capsule. Capsule Types are customizable labels. A capsule must be empty before deletion. Clio (AI assistant) can auto-detect complex transactions and suggest capsule creation with linked schedulers.
+
+**API**: CRUD `GET/POST/PUT/DELETE /capsules`, `POST /capsules/search`, `POST /move-transaction-capsules`, CRUD `GET/POST/PUT/DELETE /capsuleTypes`, `POST /capsuleTypes/search` (also available as `/capsule-types/*` kebab-case aliases)
+
+---
+
+## Reports
+
+Financial statements and accounting reports for compliance, analysis, and audit. All reports support multi-currency display, exchange rate transparency, and Excel/PDF export.
+
+| Report | What it shows |
+|--------|--------------|
+| **Trial Balance** | Debit/credit verification worksheet — if unbalanced, arithmetic error exists |
+| **Balance Sheet** | Assets/liabilities/equity snapshot at a point in time |
+| **Profit & Loss** | Revenue/costs/expenses over a period; supports tracking tag filters |
+| **Cashflow Statement** | Cash inflows/outflows categorized as operating/investing/financing |
+| **General Ledger** | Complete record of all transactions; group by accounts/contacts/transactions/relationships/tax profiles/capsules |
+| **Aged Receivables** | Outstanding invoices by overdue periods; summary and detail views |
+| **Aged Payables** | Outstanding bills by overdue periods; summary and detail views |
+| **Cash Balance** | Bank/cash account balances at a specific date |
+| **Equity Movement** | Changes in equity accounts over a period |
+| **Bank Balance Summary** | Consolidated bank account balances with lock dates and currencies |
+
+FX-related accounts auto-created: FX Bank Revaluation, FX Realized, FX Unrealized, FX Rounding (each with Gains and Loss variants). Retained Earnings auto-updates at financial year-end via CYE rollover.
+
+**API**: `POST /generate-reports/trial-balance`, `POST /generate-reports/balance-sheet`, `POST /generate-reports/profit-and-loss`, `POST /generate-reports/general-ledger`, `POST /generate-reports/cashflow`, `POST /generate-reports/cash-balance`, `POST /generate-reports/ar-report`, `POST /generate-reports/ap-report`, `POST /generate-reports/bank-balance-summary`, `POST /generate-reports/equity-movement`, and more. Data exports: `POST /data-exports/trial-balance`, `POST /data-exports/profit-and-loss`, `POST /data-exports/general-ledger`, etc. Also: `POST /generate-report-packs-pdf`, `POST /statement-of-account-export`
+
+---
+
+## Contacts
+
+Customer and supplier records. A single contact can be both customer AND supplier simultaneously. Each contact has transaction settings (default payment terms, currency, GST profile, WHT codes, PDF/email templates) that auto-fill when creating transactions.
+
+Contact Groups organize contacts for report filtering (Aged Receivables/Payables, Ledger). Contact Relationships use pre-defined types (Associate Company, Director/Shareholder, Parent Company, etc.) for related-party reporting. Sales Activity PDFs show statement of balances and accounts per currency.
+
+**API**: CRUD `GET/POST/PUT/DELETE /contacts`, `POST /contacts/search`, CRUD `GET/POST/PUT/DELETE /contact-groups`, `POST /contact-groups/search`
+
+---
+
+## Products & Items
+
+Items for sales (revenue accounts) and purchases (expense accounts). Each item has Internal Name (org use), Sale Name (invoice PDF), and Purchase Name (bill PDF). Items support default tax profiles, COGS tracking, and unique item codes.
+
+Inventory items use Fixed Cost (non-GAAP, for fully-landed costs) or Weighted Average Cost (recalculates on each stock addition). Costing method cannot be changed after selection. "Block insufficient deductions" prevents sales reducing stock below zero.
+
+Catalogs group items for bulk application to invoices/credits/scheduled invoices/subscriptions. Catalogs can be assigned to contact groups.
+
+**API**: CRUD `GET/POST/PUT/DELETE /items`, `POST /items/search`, `DELETE /items/:id` (also deletes inventory items), `POST /inventory-items`, `GET /inventory-items`, `GET /inventory-item-balance/:id`, CRUD `GET/POST/PUT/DELETE /catalogs`, `POST /catalogs/search`, `POST /purchase-items/search`
+
+---
+
+## Bank Reconciliations
+
+Match bank statement lines to Jaz transactions to verify cash balances. This is where most day-to-day bookkeeping happens — reconciling what the bank shows vs what Jaz has recorded.
+
+**Auto-Reconciliation**: Runs daily at midnight with configurable rules — Match (existing transactions), Quick Reconcile (create journals), Apply Rule (bank rules), Cash Transfer. Three magic thresholds: Strict, Balanced, Lenient. Can exclude specific records via Saved Search.
+
+**Magic Match**: Auto-suggests transaction matches within 30 days (with contact) or 3 days (payments only), matching by amount + contact name.
+
+**Bank Feeds**: Connect Airwallex, Aspire, Stripe, Wise, or Xendit for automated statement sync (up to 12 months history, daily auto-sync).
+
+**Bank Rules**: Auto-allocate amounts using percentage-only or fixed+percentage splits (max 10 fixed + 10 percentage lines). Support dynamic strings like `#{{bankReference}}`, `#{{payeeName}}`.
+
+Statement amounts are recorded in the bank account's currency — no auto-conversion. Cross-currency transactions prompt for cash received/spent in statement currency. Reconciled transactions become uneditable (must reset to edit).
+
+**API**: `POST /bank-records/:accountResourceId` (JSON import), `POST /bank-records/:accountResourceId/search`, `POST /magic/importBankStatementFromAttachment` (multipart CSV/OFX), CRUD `GET/POST/PUT/DELETE /bank-rules`, `POST /bank-rules/search`, `GET /bank-accounts`, `POST /view-auto-reconciliation`
+
+---
+
+## Approvals
+
+Workflow for draft invoices and bills requiring admin sign-off before activation. Three user roles: Admins (approve + create active), Preparers (submit drafts for approval), Members (submit own drafts only). Status progression: Draft → For Approval → Approved (active). Approval PDFs capture Submitted By / Approved By audit trail.
+
+**API**: `PUT /invoices/:id/approve`, `PUT /bills/:id/approve`
+
+---
+
+## Fixed Assets
+
+Fixed asset register with straight-line depreciation. Register assets from invoice/bill line items or standalone. Auto-posts monthly depreciation journal entries. Formula: `(Cost - Salvage Value) / Useful Life`.
+
+Fixed assets lock their linked line items — cannot edit account, amounts, or exchange rates on a line item with an active fixed asset. Must delete the asset before modifying the line item. Fixed asset journals can be grouped in capsules for CIP, renovations, and disposals.
+
+**API**: CRUD `GET/POST/PUT/DELETE /fixed-assets`, `POST /fixed-assets/search`, `POST /mark-as-sold/fixed-assets`, `POST /undo-disposal/fixed-assets/:id`, `POST /discard-fixed-assets/:id`, `POST /transfer-fixed-assets`, `POST /fixed-assets-types/search`
+
+---
+
+## AI Agents
+
+**Clio**: AI assistant for accounting tasks. Auto-extracts invoice/bill data from PDF/image attachments (OCR), detects multi-step transactions (prepaid expenses, deferred revenue, accruals), and suggests capsule creation with linked schedulers. Creates draft transactions for user review. Session-based (no persistent chat history). Available on web and Android (iOS coming).
+
+**Agent Builder**: Configure custom AI agents in Settings > Agent Builder with name, email (a-z, 0-9, + symbol), and workflow preferences.
+
+**Jaz Magic**: Contact-level setting controlling auto-extraction behavior — line items (detailed extraction), summary totals (single amount), or none. Up to 10 images can be merged into a single PDF.
+
+**API**: `POST /magic/createBusinessTransactionFromAttachment` (OCR PDF → draft transaction), `POST /magic/importBankStatementFromAttachment`, `PUT /invoices/magic-update`, `PUT /bills/magic-update`, `PUT /journals/magic-update`, `GET /invoices/magic-search`, `GET /bills/magic-search` (all magic endpoints use `x-magic-api-key`)
+
+---
+
+## Settings & Configuration
+
+**Chart of Accounts**: Account codes, names, types (Revenue, Expense, Asset, Liability, Equity), subtypes, lock dates per account. System accounts (AR, AP, FX) are auto-created and cannot be deleted.
+
+**Tax Profiles**: GST/VAT codes with rates, scoped to sales-only, purchases-only, or both. Pre-provisioned per org — discover via GET, never create.
+
+**Currencies & FX Rates**: Enable currencies before use. Rate priority: transaction-level custom rate > org-level custom rate > ECB/Frankfurter auto-fetch. Rate direction: `rate` = functionalToSource (1 base = X foreign).
+
+**Tracking Tags**: Custom labels for reporting. Apply to line items or transaction headers. Filter reports by tags but cannot group by them (except capsules in ledger).
+
+**Custom Fields**: Text/number/date/dropdown fields. Apply to invoices/bills/journals/contacts. Can show on PDFs and be made mandatory.
+
+**Lock Dates**: Prevent edits to transactions before a date (org-wide or per-account). Prevents backdated entries.
+
+**User Roles**: Admin (full access), Preparer (create drafts, submit for approval), Member (own drafts only). Granular permissions by module (AR, AP, Treasury, Journals).
+
+**API**: CRUD `GET/POST/PUT/DELETE /chart-of-accounts`, `POST /chart-of-accounts/bulk-upsert`, `POST /chart-of-accounts/search`, `GET /tax-profiles`, `POST /tax-profiles/search`, CRUD `GET/POST/PUT/DELETE /tags`, `POST /tags/search`, CRUD `GET/POST/PUT/DELETE /custom-fields`, `POST /custom-fields/search`, `POST /organization/currencies` (enable), `DELETE /organization/currencies/:code` (disable), `POST /organization-currencies/:code/rates` (set FX rate, CRUD), `GET /organization` (org details), CRUD `GET/POST/PUT/DELETE /organization/bookmarks`, CRUD `GET/POST/PUT/DELETE /nano-classifiers`, `POST /nano-classifiers/search`, `GET /organization-users`, `POST /organization-users/search`. Reference data: `GET /account-classifications`, `GET /withholding-tax-codes`, `GET /tax-types`, `GET /modules`, `GET /search` (Typesense full-text)
+
+---
+
+## Collaboration
+
+Threaded comments on transactions for team communication and audit trails. Add comments to invoices, bills, journals, and credit notes. Tag team members with @mentions to trigger notifications.
+
+---
+
+## Data Import
+
+Bulk import for all entity types. All imports use .xlsx templates with error review before finalizing. Limits: 1,000 rows (invoices/bills/journals/credits/items), 2MB (items), 12 files (bank statements). Imports create active transactions (not drafts) for invoices/bills. Items can update existing records based on item code.
+
+Bank statement import supports CSV and PDF with configurable column mapping. Statement amounts recorded in bank account currency (no auto-conversion). Auto-detects date format.
+
+**API**: `POST /magic/importBankStatementFromAttachment` (multipart: `sourceFile`, `accountResourceId`, `businessTransactionType: "BANK_STATEMENT"`, `sourceType: "FILE"`)
+
+---
+
+*Maintained alongside [help.jaz.ai](https://help.jaz.ai).*

package/assets/skills/api/references/field-map.md

@@ -0,0 +1,428 @@
+# Jaz API Field Name Map
+
+> Complete mapping of intuitive/guessed field names to actual Jaz API field names.
+> Organized by resource type. Every field verified against production API.
+
+---
+
+## Universal Fields
+
+| What You'd Guess | Actual API Field | Context |
+|------------------|-------------------|---------|
+| `id` | `resourceId` | Every resource, every response |
+| `contactId` | `contactResourceId` | POST body reference |
+| `accountId` | `accountResourceId` | POST body reference |
+| `bankAccountId` | `accountResourceId` | Payments, cash entries. **Alias `bankAccountResourceId` now accepted on POST.** |
+| `taxProfileId` | `taxProfileResourceId` | POST body reference |
+| `itemId` | `itemResourceId` | POST body reference |
+| `creditNoteId` | `creditNoteResourceId` | POST body reference |
+
+**Pattern**: References always use `<resource>ResourceId` suffix.
+**Exception**: Bank account references in payments and cash entries use `accountResourceId` (NOT `bankAccountResourceId`).
+
+---
+
+## Date Fields
+
+| What You'd Guess | Actual API Field | Used In |
+|------------------|-------------------|---------|
+| `issueDate` | `valueDate` | Invoices, bills, credit notes, journals, cash entries. **Alias `issueDate` now accepted on POST.** |
+| `invoiceDate` | `valueDate` | Invoices. **Alias accepted on POST.** |
+| `billDate` | `valueDate` | Bills |
+| `journalDate` | `valueDate` | Journals |
+| `paymentDate` | `valueDate` | Invoice/bill payments (NOT `paymentDate`!) |
+| `date` (payment) | `valueDate` | Invoice/bill payments |
+| `date` (bank) | `transactionDate` | Bank records |
+| `asAtDate` | `endDate` | Reports (trial balance) |
+
+**Pattern**: Transaction documents AND payments use `valueDate`. Bank records use `transactionDate`. Reports use `startDate`/`endDate`.
+**CORRECTION**: Payments use `valueDate` (NOT `paymentDate` as previously documented).
+**FORMAT**: All dates MUST be `YYYY-MM-DD` strings (e.g., `"2026-02-08"`). ISO datetime and epoch ms are rejected. OAS may declare `integer/int64` but strings work.
+
+### Date Format Matrix (Request vs Response)
+
+| Context | Direction | Format | Example |
+|---------|-----------|--------|---------|
+| Create/update requests | Inbound | `YYYY-MM-DD` string | `"valueDate": "2026-02-14"` |
+| Search filter dates (`DateExpression`) | Inbound | `YYYY-MM-DD` string | `{ "valueDate": { "gte": "2026-01-01" } }` |
+| Search filter datetimes (`DateTimeExpression`) | Inbound | RFC3339 string | `{ "createdAt": { "gte": "2026-01-01T00:00:00Z" } }` |
+| **ALL response dates** | **Outbound** | **`int64` epoch milliseconds** | `"valueDate": 1707868800000` |
+
+**CRITICAL**: ALL dates in API responses are `int64` epoch milliseconds — including `valueDate`, `createdAt`, `updatedAt`, `approvedAt`, `submittedAt`, `matchDate`, `startDate`, `endDate`, `lastScheduleDate`, `nextScheduleDate`. To convert: `new Date(epochMs).toISOString().slice(0, 10)` → `"2026-02-14"`.
+
+**Which fields use DateExpression (YYYY-MM-DD) vs DateTimeExpression (RFC3339)**:
+- `DateExpression`: `valueDate`, `dueDate`, `startDate`, `endDate`, `purchaseDate`, `matchDate`, `approvedAt`, `submittedAt`, `depreciationStartDate`, `depreciationEndDate`, `disposalValueDate`, `proratedStartDate`, `lastScheduleDate`, `nextScheduleDate`
+- `DateTimeExpression`: `createdAt`, `updatedAt` (on invoices, bills, journals, custom fields)
+
+---
+
+### Middleware Alias Table (Complete)
+
+These aliases are applied by middleware on POST/PUT endpoints. The alias is only used if the canonical field is absent from the request body.
+
+| Alias | Canonical | Middleware | Applied To |
+|-------|-----------|------------|-----------|
+| `issueDate` | `valueDate` | `txnDateAliases` | POST/PUT: invoices, bills, customer-credit-notes, supplier-credit-notes, journals, cash-in-journals, cash-out-journals, cash-transfer-journals, scheduled/invoices, scheduled/bills, scheduled/journals, scheduled/subscriptions |
+| `date` | `valueDate` | `txnDateAliases` | Same as above (all transaction and scheduled create/update endpoints) |
+| `paymentDate` | `valueDate` | `paymentAliases` | POST: invoice payments, bill payments. PUT: payments |
+| `bankAccountResourceId` | `accountResourceId` | `paymentAliases` | Same as above |
+| `paymentAmount` | `refundAmount` | `refundAliases` | POST: customer-credit-notes refunds, supplier-credit-notes refunds |
+| `paymentMethod` | `refundMethod` | `refundAliases` | Same as above |
+| `name` | `tagName` | `tagAliases` | POST/PUT: tags |
+| `name` | `internalName` | `itemAliases` | POST: items, inventory-items |
+| `accountType` | `classificationType` | Code-level alias | POST/PUT: chart-of-accounts, bulk-upsert |
+| `currencyCode` | `currency` | Code-level alias | POST: chart-of-accounts bulk-upsert |
+
+---
+
+## Organization & Auth
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `apiKey` header | `x-jk-api-key` | Custom header (not Authorization: Bearer) |
+| `org.id` | `data[0].resourceId` | Org endpoint returns a LIST |
+| `org.baseCurrency` | `data[0].currency` | Not `baseCurrency` |
+| `org.country` | `data[0].countryCode` | ISO 2-letter code |
+
+---
+
+## Chart of Accounts
+
+| What You'd Guess | Actual API Field | Context |
+|------------------|-------------------|---------|
+| `chartOfAccounts` (upsert body) | `accounts` | POST bulk-upsert wrapper |
+| `currencyCode` (in POST) | `currency` | POST body (GET returns `currencyCode`!) |
+| `accountClass` or `accountType` | `classificationType` | POST body — uses `accountType` values |
+| `type` | `accountType` | GET response field |
+| `class` | `accountClass` | GET response field |
+| `accountNumber` | `code` | String, can be null. **Codes differ between orgs — match by name, not code** |
+
+### classificationType → accountType Mapping
+
+When POSTing, `classificationType` must be one of these exact strings (same as `accountType` from GET):
+
+| classificationType Value | accountClass (GET) |
+|-------------------------|-------------------|
+| `"Bank Accounts"` | Asset |
+| `"Cash"` | Asset |
+| `"Current Asset"` | Asset |
+| `"Fixed Asset"` | Asset |
+| `"Inventory"` | Asset |
+| `"Current Liability"` | Liability |
+| `"Non-current Liability"` | Liability |
+| `"Shareholders Equity"` | Equity |
+| `"Operating Revenue"` | Revenue |
+| `"Other Revenue"` | Revenue |
+| `"Operating Expense"` | Expense |
+| `"Direct Costs"` | Expense |
+
+---
+
+## Contacts
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `contactType: "customer"` | `customer: true` | Boolean, not enum |
+| `contactType: "supplier"` | `supplier: true` | Boolean, not enum |
+| `defaultCurrencyCode` | `currency` | ISO code string |
+| `taxRegistrationNumber` | `taxNumber` | UEN (SG), TIN (PH) |
+| `address.line1` | `addressLine1` | Top-level, NOT nested |
+| `address.line2` | `addressLine2` | Top-level |
+| `address.city` | `city` | Top-level |
+| `address.postalCode` | `postalCode` | Top-level |
+| `address.country` | `countryCode` | ISO 2-letter code, top-level |
+| `displayName` | `billingName` | Required, set = name |
+
+---
+
+## Items
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `name` | `internalName` | Display name. **Alias `name` now accepted on POST; GET returns both `internalName` and `name`.** |
+| `sku` | `itemCode` | Unique code |
+| `type` | `type` | `"PRODUCT"` or `"SERVICE"` |
+| `sellPrice` | `salePrice` | Decimal |
+| `buyPrice` | `purchasePrice` | Decimal |
+| `sellAccountId` | `saleAccountResourceId` | CoA UUID |
+| `buyAccountId` | `purchaseAccountResourceId` | CoA UUID |
+| `sellTaxId` | `saleTaxProfileResourceId` | Tax profile UUID |
+| `buyTaxId` | `purchaseTaxProfileResourceId` | Tax profile UUID |
+| `sellable` | `appliesToSale` | Boolean |
+| `purchasable` | `appliesToPurchase` | Boolean |
+| `sellName` | `saleItemName` | REQUIRED when `appliesToSale: true` |
+| `buyName` | `purchaseItemName` | REQUIRED when `appliesToPurchase: true` |
+
+---
+
+## Invoices / Bills
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `invoiceNumber` | `reference` | User-visible number |
+| `referenceNumber` | `reference` | Same field |
+| `issueDate` | `valueDate` | THE invoice date |
+| `description` (line item) | `name` | Line item description |
+| `price` (line item) | `unitPrice` | Per-unit price |
+| `qty` (line item) | `quantity` | Count |
+| `taxId` (line item) | `taxProfileResourceId` | Tax profile UUID |
+| `accountId` (line item) | `accountResourceId` | CoA UUID (required if !saveAsDraft) |
+| `isDraft` | `saveAsDraft` | Boolean — defaults to `false`. Omitting creates a finalized transaction. |
+| `currencyCode: "USD"` (string for FX) | SILENTLY IGNORED | Creates invoice in base currency! No error returned |
+| `currency: "USD"` (string for FX) | CAUSES 400 ERROR | "Invalid request body" — string form rejected |
+| `currency` (object form) | `currency: { sourceCurrency, exchangeRate }` | **ONLY working form** for FX transactions |
+
+---
+
+## Withholding Tax (Bills & Supplier Credit Notes Only)
+
+| What You'd Guess | Actual API Field | Notes |
+|---|---|---|
+| `tax` | `withholdingTax` | Nested object on each line item |
+| `withholdingTaxCode` | `withholdingTax.code` | String code (e.g., "WC010") |
+| `withholdingTaxRate` | `withholdingTax.rate` | Numeric percentage (e.g., 10) |
+| `withholdingTaxDescription` | `withholdingTax.description` | Optional description |
+
+**Not supported on**: Invoices, customer credit notes, journals, cash entries. Only bills and supplier credit notes.
+
+---
+
+## Journals
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `lineItems` | `journalEntries` | Array of entries |
+| `lines` | `journalEntries` | Same |
+| `entries` | `journalEntries` | Same |
+| `debit` / `credit` (entry) | `amount` + `type` | `amount`: number, `type`: `"DEBIT"` or `"CREDIT"` (UPPERCASE) |
+| `currency` (top level) | DO NOT SEND | Causes "Invalid request body" |
+
+---
+
+## Cash Entries
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `bankAccountResourceId` | `accountResourceId` (top level) | The BANK account UUID — NOT `bankAccountResourceId` |
+| `amount` (flat) | `journalEntries[].amount` | Cash entries use `journalEntries` array, same as journals |
+| `description` | NOT USED | Cash entries do not have a flat `description` field |
+| `bankAccount` | `accountResourceId` (top level) | Same as above |
+| offset account | `journalEntries[].accountResourceId` | The offsetting account goes in `journalEntries` |
+| (omit saveAsDraft) | `saveAsDraft` | **REQUIRED** — must be included on cash-in and cash-out journals |
+
+---
+
+## Payments
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `amount` | `paymentAmount` | **Bank account currency** — actual cash moved. NOT `amount`. |
+| (none) | `transactionAmount` | **Transaction document currency (invoice/bill/credit note)** — amount applied to balance. Equal to `paymentAmount` for same-currency. For FX: differs (e.g., USD invoice paid from SGD bank at 1.35 → `paymentAmount: 1350`, `transactionAmount: 1000`). |
+| `bankAccountResourceId` | `accountResourceId` | Canonical is `accountResourceId`. **Alias `bankAccountResourceId` now accepted on POST.** |
+| (none) | `paymentMethod` | Required: `"BANK_TRANSFER"` |
+| (none) | `reference` | Required: payment reference string |
+| `date` / `paymentDate` | `valueDate` | NOT `paymentDate`, NOT `date`. Must be `YYYY-MM-DD` |
+| (flat object) | `{ payments: [...] }` | Must be wrapped in array |
+
+**Cross-currency payments**: `paymentAmount` is the bank account currency amount (actual cash moved), `transactionAmount` is the invoice/bill currency amount (applied to balance). Verified via live FX testing: USD invoice ($1000) paid from SGD bank at 1.35 rate → `paymentAmount: 1350` (SGD), `transactionAmount: 1000` (USD).
+**Bill payments**: Standalone `POST /bills/{id}/payments` was broken (nil pointer dereference) — fixed in backend PR #112. Embed-in-creation pattern is still a valid alternative.
+**Invoice payments**: Standalone `POST /invoices/{id}/payments` works fine.
+**TransactionFeeCollected**: NOT supported on bill payments (model field missing). Only invoice payments support collected fees.
+
+---
+
+## Tags
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `name` | `tagName` | **Alias `name` now accepted on POST; GET returns both `tagName` and `name`.** |
+
+---
+
+## Credit Note Applications
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `{ creditNoteResourceId, amount }` | `{ credits: [{ creditNoteResourceId, amountApplied }] }` | Must wrap in `credits` array |
+| `amount` | `amountApplied` | NOT `amount` |
+
+---
+
+## Custom Fields
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `name` (in GET response) | `customFieldName` | GET returns both `customFieldName` and `name` alias. |
+| `name` (in POST body) | `name` | POST accepts `name`. |
+| `showOnPdf` | `printOnDocuments` | Required boolean |
+| `appliesTo` | DO NOT SEND | Causes "Invalid request body" |
+| `type` values | `"TEXT"`, `"DATE"`, `"DROPDOWN"` | UPPERCASE strings |
+
+---
+
+## Bank Records
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `date` | `transactionDate` | ISO date string |
+| `direction` | `type` | `"CREDIT"` or `"DEBIT"` (uppercase) |
+| `memo` | `description` | Free text |
+| (negative amount) | `amount` (positive) + `type` | Always positive, direction via type |
+
+**Creating bank records**: Use multipart `POST /api/v1/magic/importBankStatementFromAttachment` — the only endpoint for creating bank records. No JSON POST endpoint exists.
+
+---
+
+## Schedulers
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `frequency` | `repeat` | Creation field. `"WEEKLY"`, `"MONTHLY"`, `"QUARTERLY"`, `"YEARLY"`. NOT `frequency` or `interval` |
+| `interval` (response) | `interval` | Response field. Shows the recurrence after creation. Different name from creation! |
+| (flat payload) | `{ invoice: {...} }` or `{ bill: {...} }` | Document wrapped in type key |
+| `saveAsDraft: true` | `saveAsDraft: false` | MUST be false — true causes INVALID_SALE_STATUS / INVALID_PURCHASE_STATUS |
+
+---
+
+## Currencies
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `{ currencyCode: "USD" }` | `{ currencies: ["USD"] }` | Enable endpoint — array of ISO codes |
+| `/organization/currencies/:code/rates` | `/organization-currencies/:code/rates` | **Hyphenated** path for rates (NOT nested) |
+| `exchangeRate` (rate POST body) | `rate` | Just `rate`, not `exchangeRate` |
+| `effectiveDate` / `valueDate` / `date` | `rateApplicableFrom` | Rate start date, `YYYY-MM-DD` only |
+| `expiryDate` | `rateApplicableTo` | Optional rate end date |
+| `rate` (GET response) | `rateFunctionalToSource` | Base→source rate in GET response |
+| `inverseRate` | `rateSourceToFunctional` | Source→base rate in GET response |
+
+> **Rate direction cheat-sheet**: POST `rate` = GET `rateFunctionalToSource` = "1 base → X foreign". If your data is "1 foreign → X base", **invert before POSTing**.
+
+---
+
+## Inventory Items
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `itemUnit` / `unitName` | `unit` | String, e.g., `"pcs"`, `"box"`. REQUIRED |
+| `costingMethod: "FIXED_COST"` | `costingMethod: "FIXED"` | Only `"FIXED"` or `"WAC"` |
+| `purchaseAccountResourceId` (any type) | `purchaseAccountResourceId` (Inventory type!) | MUST be Inventory-type CoA account |
+| `DELETE /inventory-items/:id` | `DELETE /items/:id` | Delete via items endpoint, not inventory-items |
+
+---
+
+## Cash Transfer Journals
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `fromAccountResourceId` | `cashOut.accountResourceId` | Sub-object, NOT flat |
+| `toAccountResourceId` | `cashIn.accountResourceId` | Sub-object, NOT flat |
+| `amount` (flat) | `cashOut.amount` / `cashIn.amount` | Amount in each sub-object |
+
+---
+
+## Credit Note Refunds
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `payments` wrapper | `refunds` wrapper | NOT `payments` |
+| `paymentAmount` | `refundAmount` | NOT `paymentAmount` |
+| `paymentMethod` | `refundMethod` | NOT `paymentMethod` |
+
+---
+
+## Bookmarks
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `{ name, url }` | `{ items: [{ name, value, categoryCode, datatypeCode }] }` | Array wrapper with 4 fields per item |
+| `url` | `value` | General-purpose value field |
+| `category` | `categoryCode` | Enum: `GENERAL_INFORMATION`, etc. |
+| `type` | `datatypeCode` | Enum: `LINK`, `TEXT`, `NUMBER`, `BOOLEAN`, `DATE` |
+
+---
+
+## Scheduled Journals
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `journal: { journalEntries: [...] }` | `schedulerEntries: [...]` (flat) | NOT nested like invoices/bills |
+| `journalEntries` | `schedulerEntries` | Different name than regular journals |
+| (nested) `reference` / `valueDate` | (top-level) `reference` / `valueDate` | Flat alongside `repeat`/`startDate`/`endDate` |
+
+---
+
+## Reports (All Types)
+
+| Report | Required Fields | Notes |
+|--------|----------------|-------|
+| Trial balance | `startDate`, `endDate` | |
+| Balance sheet | `primarySnapshotDate` | Single date |
+| P&L | `primarySnapshotDate`, `secondarySnapshotDate` | |
+| General ledger | `startDate`, `endDate`, `groupBy: "ACCOUNT"` | |
+| Cashflow | `primaryStartDate`, `primaryEndDate` | Different from other date pairs |
+| Cash balance | `reportDate` | Single date, unique field name |
+| AR/AP report | `endDate` | Single date |
+| AR/AP summary | `startDate`, `endDate` | |
+| Bank balance summary | `primarySnapshotDate` | Same as balance sheet |
+| Equity movement | `primarySnapshotStartDate`, `primarySnapshotEndDate` | Yet another pair |
+
+## Data Exports
+
+| Export | Required Fields | Notes |
+|--------|----------------|-------|
+| Trial balance | `startDate`, `endDate` | Same as generate-reports |
+| P&L | `startDate`, `endDate` | DIFFERENT from generate-reports (no snapshot dates) |
+| General ledger | `startDate`, `endDate`, `groupBy: "ACCOUNT"` | Same as generate-reports |
+| AR/AP report | `endDate` | Same as generate-reports |
+
+---
+
+## Pagination
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `page` | NOT SUPPORTED | Silently ignored — use `limit`/`offset` |
+| `size` | NOT SUPPORTED | Silently ignored — use `limit`/`offset` |
+| `pageSize` | NOT SUPPORTED | Use `limit` |
+| `per_page` | NOT SUPPORTED | Use `limit` |
+| `page_number` | NOT SUPPORTED | Use `offset` (item-based, not page-based) |
+| (default page size) | `limit` (default: 100) | Query param for GET, JSON body for POST /search |
+| (skip N items) | `offset` (default: 0) | Query param for GET, JSON body for POST /search |
+
+**GET list endpoints**: `?limit=100&offset=0` (query params)
+**POST /search endpoints**: `{ "limit": 100, "offset": 0 }` (JSON body)
+**Min/max**: limit 1–1000, offset 0–65536
+**Response**: `{ totalPages, totalElements, data: [...] }` — consistent across all endpoints
+
+---
+
+## Response Shape Quirks
+
+| Endpoint | Response Shape | What You'd Expect |
+|----------|---------------|-------------------|
+| `GET /organization` | `{ data: [...] }` (list!) | `{ data: {...} }` (single) |
+| `GET /organization/currencies` | `{ data: { data: [...] } }` | `{ data: [...] }` |
+| `POST /chart-of-accounts/bulk-upsert` | `{ data: { resourceIds: [...] } }` | Individual results |
+| `POST /organization/currencies` | `{ data: { resourceIds: [...] } }` | Confirmation object |
+| `GET /invoices/{id}` line items | `organizationAccountResourceId` | `accountResourceId` (POST uses `accountResourceId`) |
+
+---
+
+## Recommended Serialization Patterns
+
+Battle-tested patterns from production Jaz API clients:
+
+| Pattern | Detail |
+|---------|--------|
+| Serialization | `model_dump(mode="json", by_alias=True, exclude_unset=True, exclude_none=True)` |
+| Alias generator | `alias_generator=to_camel` (snake_case to camelCase) |
+| Date type | Python `date` type serializes to `YYYY-MM-DD` strings |
+| Bill payments | Always embedded in bill creation body, never standalone |
+| Bank records | Multipart import via `importBankStatementFromAttachment` — the only endpoint |
+| Scheduled bills | Wrapped as `{ repeat, startDate, endDate, bill: {...} }`. Field is `repeat` (NOT `frequency`/`interval`) |
+| FX currency | MUST use `currency` OBJECT: `{ sourceCurrency: "USD", exchangeRate: 1.35 }`. String `currencyCode` is silently ignored. |
+
+---
+
+*Last updated: 2026-02-14 — Date format matrix: Added request vs response date format asymmetry (YYYY-MM-DD in, epoch ms out). Complete middleware alias table from Go source code. DateExpression vs DateTimeExpression field classification.*