openapi: 3.0.0 info: title: 'Ledga Financial Ledger API' description: "Double-entry accounting ledger system with multi-tenancy support.\n *\n * ## Features\n * - Double-entry accounting with immutable transactions\n * - Multi-tenant isolation with tenant-scoped data\n * - Multi-currency support (fiat and cryptocurrencies)\n * - Configurable precision and rounding modes\n * - Transaction codes for standardized entry templates\n * - Account sets for grouped reporting\n * - Real-time balance calculations\n *\n * ## Authentication\n * All API endpoints require authentication via Laravel Sanctum bearer tokens.\n *\n * ## Monetary Values\n * - All monetary amounts are stored as integer minor units (pence/cents/satoshis)\n * - API accepts and returns decimal strings for user-facing values\n * - Precision is configurable per ledger (storage_decimals and display_decimals)\n *\n * ## Pagination\n * List endpoints use cursor-based pagination for consistency.\n * See docs/api/PAGINATION.md for details." contact: email: support@ledga.com version: 1.0.0 servers: - url: 'http://my-default-host.com' description: 'Local Development Server' paths: /api/v1/accounts: get: tags: - Accounts summary: 'List all accounts in a ledger' description: "Display a listing of accounts\n\nUses cursor-based pagination for consistency. See docs/api/PAGINATION.md\nFor hierarchical view, use tree=true parameter." operationId: getAccounts parameters: - name: type in: query description: 'Filter by account type' required: false schema: type: string enum: - asset - liability - equity - revenue - expense - name: active in: query description: 'Filter by active status' required: false schema: type: boolean - name: parent_id in: query description: 'Filter by parent account UUID' required: false schema: type: string format: uuid - name: search in: query description: 'Search in code or name' required: false schema: type: string - name: tree in: query description: 'Return hierarchical tree structure (non-paginated)' required: false schema: type: boolean default: false - name: limit in: query description: 'Number of items per page (max 100)' required: false schema: type: integer default: 25 maximum: 100 - name: cursor in: query description: 'Cursor for pagination' required: false schema: type: string responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/Account' meta: $ref: '#/components/schemas/PaginationMeta' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Ledger not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] post: tags: - Accounts summary: 'Create a new account' description: 'Store a newly created account' operationId: createAccount requestBody: required: true content: application/json: schema: required: - code - name - type - category properties: code: description: 'Account code (must be unique within ledger)' type: string maxLength: 36 example: '1000' name: description: 'Account name' type: string maxLength: 255 example: Cash type: type: string enum: - asset - liability - equity - revenue - expense example: asset category: description: 'Account category — system (internal/GL) or customer (end-user balance)' type: string enum: - system - customer example: system normal_balance: description: 'Normal balance side (defaults based on type)' type: string enum: - debit - credit example: debit nullable: true parent_code: description: 'Parent account code for hierarchical structure (must exist in same ledger)' type: string maxLength: 36 nullable: true description: type: string maxLength: 1000 nullable: true is_active: type: boolean default: true is_system: description: 'System accounts cannot be deleted' type: boolean default: false metadata: description: 'Arbitrary structured metadata for the account' type: object nullable: true enforce_balance_limits: description: 'When true, balance must stay between min_balance and max_balance' type: boolean default: false min_balance: description: 'Lower balance limit as a major-unit decimal string. Required when enforce_balance_limits is true. Negative values are permitted for liability accounts.' type: string pattern: '^-?\d+(?:\.\d+)?$' example: '0.00' nullable: true max_balance: description: 'Upper balance limit as a major-unit decimal string. Must be >= min_balance.' type: string pattern: '^-?\d+(?:\.\d+)?$' example: '10000.00' nullable: true type: object responses: 201: description: 'Account created successfully' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/Account' type: object 400: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/accounts/{accountId}': get: tags: - Accounts summary: 'Get a specific account' description: 'Display the specified account' operationId: getAccount parameters: - name: accountId in: path description: 'Account UUID' required: true schema: type: string format: uuid responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/Account' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] put: tags: - Accounts summary: 'Update an account' description: 'Update the specified account' operationId: updateAccount parameters: - name: accountId in: path description: 'Account UUID' required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: properties: parent_id: description: 'Parent account UUID for hierarchical structure' type: string format: uuid nullable: true code: description: '4-digit account code' type: string maxLength: 4 minLength: 4 pattern: '^\d{4}$' name: type: string maxLength: 255 example: 'Cash - Updated' type: type: string enum: - asset - liability - equity - revenue - expense normal_balance: type: string enum: - debit - credit description: type: string maxLength: 1000 nullable: true is_active: type: boolean metadata: type: object nullable: true enforce_balance_limits: description: 'Enable trigger-enforced min/max balance limits' type: boolean min_balance: description: 'Lower balance limit as a major-unit decimal string. Negative values are permitted for liability accounts.' type: string pattern: '^-?\d+(?:\.\d+)?$' example: '0.00' nullable: true max_balance: description: 'Upper balance limit as a major-unit decimal string. Must be >= min_balance.' type: string pattern: '^-?\d+(?:\.\d+)?$' example: '10000.00' nullable: true type: object responses: 200: description: 'Account updated successfully' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/Account' type: object 400: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] delete: tags: - Accounts summary: 'Delete an account' description: 'Remove the specified account' operationId: deleteAccount parameters: - name: accountId in: path description: 'Account UUID' required: true schema: type: string format: uuid responses: 200: description: 'Account deleted successfully' content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/accounts/{accountId}/balance-history': get: tags: - Accounts summary: 'Get account balance history' description: 'Get account balance history' operationId: getAccountBalanceHistory parameters: - name: accountId in: path description: 'Account UUID' required: true schema: type: string format: uuid - name: start_date in: query description: 'Start date for history' required: false schema: type: string format: date - name: end_date in: query description: 'End date for history' required: false schema: type: string format: date responses: 200: description: 'Balance history retrieved successfully' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: account: type: object period: type: object history: type: array items: type: object ending_balance: type: number type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/accounts/initialize-defaults: post: tags: - Accounts summary: 'Initialize default chart of accounts for a ledger' description: 'Initialize default chart of accounts' operationId: initializeDefaultAccounts responses: 200: description: 'Default accounts created successfully' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: accounts_count: type: integer example: 15 type: object type: object 400: description: 'Ledger already has accounts' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/accounts/{accountId}/entries': get: tags: - Accounts summary: 'Get all entries for an account with rolling balance' description: "Get all entries for an account with rolling balance calculation\n\nReturns entries in chronological order by effective_date with a calculated\nbalance_after field showing the running balance after each entry." operationId: getAccountEntries parameters: - name: accountId in: path description: 'Account UUID' required: true schema: type: string format: uuid - name: start_date in: query description: 'Filter entries from this date (inclusive)' required: false schema: type: string format: date example: '2025-01-01' - name: end_date in: query description: 'Filter entries up to this date (inclusive)' required: false schema: type: string format: date example: '2025-12-31' - name: layer in: query description: 'Filter by transaction layer' required: false schema: type: string enum: - settled - pending - encumbrance - name: limit in: query description: 'Number of items per page (max 100)' required: false schema: type: integer default: 25 maximum: 100 - name: cursor in: query description: 'Cursor for pagination' required: false schema: type: string responses: 200: description: 'Entries retrieved successfully' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: properties: id: type: string format: uuid transaction_id: type: string format: uuid account_id: type: string format: uuid account_code: type: string example: '1000' type: type: string enum: - debit - credit amount: type: string example: '100.00' description: type: string nullable: true layer: type: string enum: - settled - pending - encumbrance effective_date: type: string format: date balance_after: description: 'Running balance after this entry' type: string example: '1000.00' transaction: properties: reference: type: string description: type: string type: object type: object meta: properties: account: properties: id: type: string format: uuid code: type: string name: type: string normal_balance: type: string enum: - debit - credit type: object pagination: $ref: '#/components/schemas/PaginationMeta' type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/accounts/code/{code}': get: tags: - Accounts summary: 'Get a specific account by its code' description: 'Display the specified account by code' operationId: getAccountByCode parameters: - name: code in: path description: 'Account code (customer-defined identifier)' required: true schema: type: string example: '1000' responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/Account' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/accounts/code/{code}/balance': get: tags: - Accounts summary: 'Get account balance by code with layer details' description: 'Get account balance by code with layer details' operationId: getAccountBalanceByCode parameters: - name: code in: path description: 'Account code (customer-defined identifier)' required: true schema: type: string example: '1000' - name: as_of_date in: query description: 'Calculate balance as of this date' required: false schema: type: string format: date - name: layer in: query description: 'Filter by specific layer' required: false schema: type: string enum: - settled - pending - encumbrance responses: 200: description: 'Balance retrieved successfully' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: account_id: type: string format: uuid account_code: type: string example: '1000' account_name: type: string example: Cash account_type: type: string example: asset normal_balance: type: string example: debit balances: properties: settled: description: 'Confirmed cleared funds - what you can spend' type: string example: '1000.00' pending: description: 'Unconfirmed transactions (not yet spendable)' type: string example: '50.00' overdue: description: 'Encumbrances past their due date' type: string example: '20.00' future: description: 'Encumbrances due today or later' type: string example: '80.00' type: object layer_details: description: 'Detailed breakdown per layer' type: object currency: type: string example: GBP as_of_date: type: string format: date example: '2025-01-15' calculated_at: type: string format: date-time type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/accounts/{accountId}/balance': get: tags: - Accounts summary: 'Get account balance with layer details' description: "Get account balance with layer details\n\nReturns balances for each accounting layer (settled, pending) plus\nencumbrance breakdown (overdue, future). Per issue #86, the \"available\"\nbalance concept was removed - only settled funds are spendable." operationId: getAccountBalance parameters: - name: accountId in: path description: 'Account UUID' required: true schema: type: string format: uuid - name: as_of_date in: query description: 'Calculate balance as of this date (Y-m-d format)' required: false schema: type: string format: date - name: layer in: query description: 'Filter by specific layer (informational only, all layers are always returned)' required: false schema: type: string enum: - settled - pending - encumbrance responses: 200: description: 'Balance retrieved successfully' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: account_id: type: string format: uuid example: 01234567-89ab-cdef-0123-456789abcdef account_code: type: string example: '1000' account_name: type: string example: Cash account_type: type: string example: asset normal_balance: type: string example: debit balances: properties: settled: description: 'Confirmed cleared funds - what you can spend' type: string example: '1000.00' pending: description: 'Unconfirmed transactions (not yet spendable)' type: string example: '50.00' overdue: description: 'Encumbrances past their due date' type: string example: '20.00' future: description: 'Encumbrances due today or later' type: string example: '80.00' type: object layer_details: description: 'Detailed breakdown per layer' type: object currency: type: string example: GBP as_of_date: type: string format: date example: '2025-01-15' calculated_at: type: string format: date-time type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/accounts/{accountId}/balance/point-in-time': get: tags: - Accounts summary: 'Get an account point-in-time balance for a single layer' description: "Get an account's point-in-time balance for a single layer (issue #118).\n\nRecomputes the balance at an exact instant from the immutable `entries`\ntable via {@see AccountBalanceQueryService::asOf()}. This is a distinct\nsurface from getBalance(): it returns ONE layer reconstructed at `as_of`,\nnever the layered snapshot." operationId: getAccountPointInTimeBalance parameters: - name: accountId in: path description: 'Account UUID' required: true schema: type: string format: uuid - name: as_of in: query description: 'Point-in-time instant: ISO 8601 with an explicit timezone (Z or ±HH:MM) at SECOND precision, e.g. 2026-04-15T14:07:32Z. The balance is recomputed from the immutable entries as of this instant; ledger timestamps are second-granular.' required: true schema: type: string format: date-time pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})$' example: '2026-04-15T14:07:32Z' - name: layer in: query description: 'The single layer to reconstruct (defaults to settled).' required: false schema: type: string default: settled enum: - settled - pending - encumbrance responses: 200: description: 'Point-in-time balance retrieved successfully' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: account_id: type: string format: uuid example: 01234567-89ab-cdef-0123-456789abcdef account_code: type: string example: '1000' layer: type: string enum: - settled - pending - encumbrance example: settled balance: description: 'Single-layer balance reconstructed at `as_of`, as a major-unit decimal string.' type: string example: '150.00' currency: type: string example: GBP as_of: description: 'The requested instant, normalised to UTC.' type: string format: date-time example: '2026-04-15T14:07:32+00:00' type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/accounts/code/{code}/balance/point-in-time': get: tags: - Accounts summary: 'Get an account point-in-time balance for a single layer, by code' description: "Get an account's point-in-time balance for a single layer, by code.\n\nBy-code sibling of {@see getPointInTimeBalance()} (mirrors the\ngetBalanceByCode → getBalance delegation)." operationId: getAccountPointInTimeBalanceByCode parameters: - name: code in: path description: 'Account code (customer-defined identifier)' required: true schema: type: string example: '1000' - name: as_of in: query description: 'Point-in-time instant: ISO 8601 with an explicit timezone (Z or ±HH:MM) at SECOND precision, e.g. 2026-04-15T14:07:32Z. The balance is recomputed from the immutable entries as of this instant; ledger timestamps are second-granular.' required: true schema: type: string format: date-time pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})$' example: '2026-04-15T14:07:32Z' - name: layer in: query description: 'The single layer to reconstruct (defaults to settled).' required: false schema: type: string default: settled enum: - settled - pending - encumbrance responses: 200: description: 'Point-in-time balance retrieved successfully' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: account_id: type: string format: uuid example: 01234567-89ab-cdef-0123-456789abcdef account_code: type: string example: '1000' layer: type: string enum: - settled - pending - encumbrance example: settled balance: description: 'Single-layer balance reconstructed at `as_of`, as a major-unit decimal string.' type: string example: '150.00' currency: type: string example: GBP as_of: description: 'The requested instant, normalised to UTC.' type: string format: date-time example: '2026-04-15T14:07:32+00:00' type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/account-sets: get: tags: - 'Account Sets' summary: 'List all account sets' description: "Display a listing of account sets\n\nUses cursor-based pagination for consistency. See docs/api/PAGINATION.md" operationId: getAccountSets parameters: - name: search in: query description: 'Search in code or name' required: false schema: type: string - name: limit in: query description: 'Number of items per page (max 100)' required: false schema: type: integer default: 25 maximum: 100 - name: cursor in: query description: 'Cursor for pagination' required: false schema: type: string responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/AccountSet' meta: $ref: '#/components/schemas/PaginationMeta' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] post: tags: - 'Account Sets' summary: 'Create a new account set' description: 'Store a newly created account set' operationId: createAccountSet requestBody: required: true content: application/json: schema: required: - code - name properties: code: description: 'Unique code for this set' type: string example: OPERATING_EXPENSES name: description: 'Display name' type: string example: 'Operating Expenses' description: type: string nullable: true metadata: type: object nullable: true type: object responses: 201: description: 'Account set created' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/AccountSet' type: object 400: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/account-sets/{accountSetId}': get: tags: - 'Account Sets' summary: 'Get a specific account set' description: 'Display the specified account set' operationId: getAccountSet parameters: - name: accountSetId in: path description: 'Account Set UUID' required: true schema: type: string format: uuid responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/AccountSet' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account set not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] put: tags: - 'Account Sets' summary: 'Update an account set' description: 'Update the specified account set' operationId: updateAccountSet parameters: - name: accountSetId in: path description: 'Account Set UUID' required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: required: - code - name properties: code: type: string name: type: string description: type: string nullable: true metadata: type: object nullable: true type: object responses: 200: description: 'Account set updated' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/AccountSet' type: object 400: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account set not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] delete: tags: - 'Account Sets' summary: 'Delete an account set' description: 'Remove the specified account set' operationId: deleteAccountSet parameters: - name: accountSetId in: path description: 'Account Set UUID' required: true schema: type: string format: uuid responses: 200: description: 'Account set deleted' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: id: type: string format: uuid type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account set not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/account-sets/{accountSetId}/members': post: tags: - 'Account Sets' summary: 'Add an account or nested set to this account set' description: 'Add a member to the account set' operationId: addAccountSetMember parameters: - name: accountSetId in: path description: 'Account Set UUID' required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: required: - member_type - member_id properties: member_type: type: string enum: - account - account_set example: account member_id: description: 'UUID of account or account set' type: string format: uuid type: object responses: 200: description: 'Member added' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: member_type: type: string enum: - account - account_set member_id: type: string format: uuid type: object type: object 400: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account set not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] delete: tags: - 'Account Sets' summary: 'Remove an account or nested set from this account set' description: 'Remove a member from the account set' operationId: removeAccountSetMember parameters: - name: accountSetId in: path description: 'Account Set UUID' required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: required: - member_type - member_id properties: member_type: type: string enum: - account - account_set member_id: type: string format: uuid type: object responses: 200: description: 'Member removed' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: member_type: type: string enum: - account - account_set member_id: type: string format: uuid type: object type: object 400: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account set or member not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/account-sets/{accountSetId}/balance': get: tags: - 'Account Sets' summary: 'Get aggregated balance for all accounts in this set' description: 'Get aggregated balance for the account set' operationId: getAccountSetBalance parameters: - name: accountSetId in: path description: 'Account Set UUID' required: true schema: type: string format: uuid responses: 200: description: 'Balance retrieved' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: account_set_id: type: string format: uuid account_set_code: type: string account_set_name: type: string total_balance: type: string example: '1000.00' currency: type: string example: USD account_count: type: integer type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account set not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/account-sets/{accountSetId}/accounts': get: tags: - 'Account Sets' summary: 'Get all accounts in this set (recursively includes nested sets)' description: 'Get all accounts in the account set (recursively)' operationId: getAccountSetAccounts parameters: - name: accountSetId in: path description: 'Account Set UUID' required: true schema: type: string format: uuid responses: 200: description: 'Accounts retrieved' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/Account' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Account set not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/attribute-definitions: get: tags: - 'Attribute Catalog' summary: "List the tenant's searchable attribute definitions (catalog)" description: "List the tenant's catalog." operationId: listAttributeDefinitions parameters: - name: limit in: query required: false schema: type: integer default: 25 maximum: 100 - name: cursor in: query description: 'Opaque keyset cursor returned by this endpoint. A malformed or foreign cursor is rejected as 422.' required: false schema: type: string responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/AttributeDefinition' meta: $ref: '#/components/schemas/PaginationMeta' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] post: tags: - 'Attribute Catalog' summary: 'Declare a searchable attribute key' description: 'Declare a key (required to opt a tenant into strict mode). Applies the same key guard rails as the write path (charset, reserved-name, distinct-key cap). Requires the `attributes:admin` capability on the API key (this endpoint mutates tenant-wide governance state); a key without it receives 403 ATTRIBUTE_ADMIN_CAPABILITY_REQUIRED.' operationId: declareAttributeDefinition requestBody: required: true content: application/json: schema: required: - key properties: key: description: 'Lowercase snake_case. Must not be reserved or exceed the tenant distinct-key cap.' type: string maxLength: 64 example: customer_id label: type: string example: 'Customer ID' nullable: true indexed: type: boolean default: true type: object responses: 201: description: 'Attribute definition declared' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/AttributeDefinition' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: "Forbidden — missing the required 'attributes:admin' capability (ATTRIBUTE_ADMIN_CAPABILITY_REQUIRED)" content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 409: description: 'Key already declared' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Guard-rail violation (INVALID_ATTRIBUTE_KEY / RESERVED_ATTRIBUTE_KEY / ATTRIBUTE_KEY_CAP_EXCEEDED)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/attribute-definitions/{key}': patch: tags: - 'Attribute Catalog' summary: "Update an attribute definition's label / indexed flag" description: "Update a declared key's mutable metadata (label / indexed); the key itself is immutable. Requires the `attributes:admin` capability on the API key; a key without it receives 403 ATTRIBUTE_ADMIN_CAPABILITY_REQUIRED." operationId: updateAttributeDefinition parameters: - name: key in: path required: true schema: type: string example: customer_id requestBody: required: false content: application/json: schema: properties: label: type: string example: 'Customer ID' nullable: true indexed: type: boolean example: false type: object responses: 200: description: 'Attribute definition updated' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/AttributeDefinition' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: "Forbidden — missing the required 'attributes:admin' capability (ATTRIBUTE_ADMIN_CAPABILITY_REQUIRED)" content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Attribute definition not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/attribute-settings: get: tags: - 'Attribute Catalog' summary: "Read the tenant's attribute settings (strict mode)" description: "Read the tenant's attribute settings." operationId: getAttributeSettings responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: strict_mode: type: boolean example: false type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] put: tags: - 'Attribute Catalog' summary: "Toggle the tenant's attribute strict mode" description: "Toggle the tenant's strict mode. Requires the `attributes:admin` capability on the API key (strict mode is tenant-wide governance state); a key without it receives 403 ATTRIBUTE_ADMIN_CAPABILITY_REQUIRED." operationId: updateAttributeSettings requestBody: required: true content: application/json: schema: required: - strict_mode properties: strict_mode: description: 'When true, only declared keys are accepted on the write path.' type: boolean example: true type: object responses: 200: description: 'Settings updated' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: strict_mode: type: boolean example: true type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: "Forbidden — missing the required 'attributes:admin' capability (ATTRIBUTE_ADMIN_CAPABILITY_REQUIRED)" content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/fx/rates: get: tags: - FX summary: 'List stored exchange rates for the tenant' description: "List the tenant's stored rates (newest first), optionally filtered by pair/source." operationId: listExchangeRates parameters: - name: base in: query description: 'Filter by base currency.' required: false schema: type: string example: EUR - name: quote in: query description: 'Filter by quote currency.' required: false schema: type: string example: USD - name: source in: query description: 'Filter by provenance (manual, ecb, …).' required: false schema: type: string example: manual - name: limit in: query description: 'Items per page (max 100).' required: false schema: type: integer default: 25 maximum: 100 - name: cursor in: query description: 'Cursor for pagination.' required: false schema: type: string responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/ExchangeRate' meta: $ref: '#/components/schemas/PaginationMeta' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] post: tags: - FX summary: 'Store a manual exchange-rate override' description: 'Store a MANUAL rate override for the tenant.' operationId: storeExchangeRate requestBody: required: true content: application/json: schema: required: - base_currency - quote_currency - rate properties: base_currency: type: string example: EUR quote_currency: type: string example: USD rate: description: '1 base = rate quote (positive decimal). The inverse is derived.' type: string example: '1.081' effective_at: description: 'Defaults to now.' type: string format: date-time nullable: true expires_at: type: string format: date-time nullable: true type: object responses: 201: description: 'Rate stored' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/ExchangeRate' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 409: description: 'A rate already exists for this pair at that effective time' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/fx/rates/{from}/{to}': get: tags: - FX summary: 'Get the current resolved rate for a pair' description: "The current resolved rate for a pair (manual override → live provider → DB\nfallback, per the stale-rate policy)." operationId: getCurrentExchangeRate parameters: - name: from in: path description: 'Base currency.' required: true schema: type: string example: EUR - name: to in: path description: 'Quote currency.' required: true schema: type: string example: USD responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/ExchangeRateQuote' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Invalid currency, or no rate available / rate stale' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/fx/rates/{from}/{to}/history': get: tags: - FX summary: 'List stored rate history for a pair' description: "The tenant's stored rate history for a pair (newest first)." operationId: getExchangeRateHistory parameters: - name: from in: path description: 'Base currency.' required: true schema: type: string example: EUR - name: to in: path description: 'Quote currency.' required: true schema: type: string example: USD - name: limit in: query description: 'Items per page (max 100).' required: false schema: type: integer default: 25 maximum: 100 - name: cursor in: query description: 'Cursor for pagination.' required: false schema: type: string responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/ExchangeRate' meta: $ref: '#/components/schemas/PaginationMeta' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Invalid currency' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/fx/convert: get: tags: - FX summary: 'Convert an amount between two currencies (calculator, posts nothing)' description: "Convert an amount between two currencies at the current resolved rate. Posts\nnothing." operationId: convertCurrency parameters: - name: from in: query description: 'Source currency.' required: true schema: type: string example: USD - name: to in: query description: 'Target currency.' required: true schema: type: string example: EUR - name: amount in: query description: 'Amount in the source currency (major units).' required: true schema: type: string example: '100.00' responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/FxConversion' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error, or no rate available / rate stale' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/journals: get: tags: - Journals summary: 'List all journals' description: 'Display a listing of journals for a ledger.' operationId: getJournals parameters: - name: status in: query description: 'Filter by status' required: false schema: type: string enum: - active - closed - name: search in: query description: 'Search in code or name' required: false schema: type: string - name: limit in: query description: 'Number of items per page (max 100)' required: false schema: type: integer default: 25 maximum: 100 - name: cursor in: query description: 'Cursor for pagination' required: false schema: type: string responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/Journal' meta: $ref: '#/components/schemas/PaginationMeta' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] post: tags: - Journals summary: 'Create a new journal' description: 'Store a newly created journal.' operationId: createJournal requestBody: required: true content: application/json: schema: required: - code - name properties: code: description: 'Unique code within ledger' type: string example: SALES name: type: string example: 'Sales Journal' description: type: string nullable: true status: type: string default: active enum: - active - closed metadata: type: object nullable: true type: object responses: 201: description: 'Journal created' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/Journal' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 409: description: 'Journal code already exists' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/journals/{journalId}': get: tags: - Journals summary: 'Get a specific journal' description: 'Display the specified journal.' operationId: getJournal parameters: - name: journalId in: path description: 'Journal UUID' required: true schema: type: string format: uuid responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/Journal' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Journal not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] put: tags: - Journals summary: 'Update a journal' description: 'Update the specified journal.' operationId: updateJournal parameters: - name: journalId in: path description: 'Journal UUID' required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: properties: code: type: string name: type: string description: type: string nullable: true status: type: string enum: - active - closed metadata: type: object nullable: true type: object responses: 200: description: 'Journal updated' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/Journal' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: 'Forbidden (cannot rename DEFAULT journal)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Journal not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 409: description: 'Journal code already exists' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] delete: tags: - Journals summary: 'Delete a journal' description: 'Remove the specified journal.' operationId: deleteJournal parameters: - name: journalId in: path description: 'Journal UUID' required: true schema: type: string format: uuid responses: 204: description: 'Journal deleted' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: 'Forbidden (cannot delete DEFAULT journal)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Journal not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 409: description: 'Cannot delete journal with existing transactions' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/journals/{journalId}/statistics': get: tags: - Journals summary: 'Get journal statistics' description: 'Get journal statistics.' operationId: getJournalStatistics parameters: - name: journalId in: path description: 'Journal UUID' required: true schema: type: string format: uuid responses: 200: description: 'Statistics retrieved' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: total_transactions: type: integer posted_transactions: type: integer pending_transactions: type: integer reversed_transactions: type: integer last_transaction_date: type: string format: date-time nullable: true total_accounts_affected: type: integer type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Journal not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/strings: get: tags: - Strings summary: 'List ledger strings for the tenant' description: "List the tenant's strings." operationId: listStrings parameters: - name: limit in: query description: 'Number of items per page (max 100)' required: false schema: type: integer default: 25 maximum: 100 - name: cursor in: query description: 'Cursor for pagination' required: false schema: type: string responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/LedgerString' meta: $ref: '#/components/schemas/PaginationMeta' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] post: tags: - Strings summary: 'Create a ledger string' description: 'Create a string for the tenant.' operationId: createString requestBody: required: true content: application/json: schema: required: - code - name properties: code: description: 'Unique within the tenant. Letters, numbers, dashes and underscores.' type: string maxLength: 50 example: treasury-fx name: type: string maxLength: 255 example: 'Treasury FX group' description: type: string maxLength: 1000 nullable: true is_active: type: boolean default: true type: object responses: 201: description: 'String created successfully' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/LedgerString' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/strings/{code}': get: tags: - Strings summary: 'Get a ledger string with its member ledgers' description: 'Show a single string and its member ledgers.' operationId: getString parameters: - name: code in: path description: 'String code (unique within the tenant)' required: true schema: type: string example: treasury-fx responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/LedgerString' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'String not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/reports/trial-balance: get: tags: - Reports summary: 'Get trial balance report' description: 'Returns all system accounts with their debit/credit balances, plus a rollup of all user accounts. Ensures debits equal credits.' operationId: getTrialBalance parameters: - name: layer in: query description: 'Transaction layer to report on' required: false schema: type: string default: settled enum: - settled - pending - encumbrance - name: as_of_date in: query description: 'Report balances as of this date' required: false schema: type: string format: date responses: 200: description: 'Trial balance report' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: as_of_date: type: string format: date layer: type: string accounts: type: array items: type: object totals: properties: total_debits: type: string example: '10000.00' total_credits: type: string example: '10000.00' is_balanced: type: boolean type: object type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/reports/income-statement: get: tags: - Reports summary: 'Get income statement report' description: 'Returns revenue and expense accounts for a date range, grouped by system accounts and customer accounts. Calculates net income.' operationId: getIncomeStatement parameters: - name: from_date in: query description: 'Start date for the report period' required: true schema: type: string format: date - name: to_date in: query description: 'End date for the report period' required: true schema: type: string format: date - name: layer in: query description: 'Transaction layer to report on' required: false schema: type: string default: settled enum: - settled - pending - encumbrance responses: 200: description: 'Income statement report' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: period: properties: from_date: type: string format: date to_date: type: string format: date type: object layer: type: string revenue: type: object expenses: type: object net_income: type: string example: '5000.00' type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/strings/{code}/accounts': get: tags: - Strings summary: 'List accounts across all member ledgers of a string' description: 'List every account across all member ledgers of the string (cursor-paginated).' operationId: listStringAccounts parameters: - name: code in: path description: 'String code (unique within the tenant)' required: true schema: type: string example: treasury-fx - name: limit in: query description: 'Number of items per page (max 100)' required: false schema: type: integer default: 25 maximum: 100 - name: cursor in: query description: 'Cursor for pagination' required: false schema: type: string responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/StringAccountRow' meta: $ref: '#/components/schemas/PaginationMeta' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: "String not found or the key's ledger is not a member" content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/strings/{code}/accounts/{accountCode}/balance': get: tags: - Strings summary: 'Unified per-ledger balance for an account code across a string' description: 'Returns one balance line PER MEMBER LEDGER (never collapsed by currency). Member ledgers that have not materialized the account get a synthesized zero line flagged `materialized: false`. Pass `?include=total_in_base_currency` (#103) to also receive an indicative sum of every member line converted to the base currency at the current FX rate; the base defaults to the configured reporting currency and can be overridden with `?base_currency=`.' operationId: getStringAccountBalance parameters: - name: code in: path description: 'String code (unique within the tenant)' required: true schema: type: string example: treasury-fx - name: accountCode in: path description: 'Account code (logically present across the whole string)' required: true schema: type: string maxLength: 36 example: '1000' - name: include in: query description: 'Comma-separated opt-in extras. Currently: `total_in_base_currency`.' required: false schema: type: string example: total_in_base_currency - name: base_currency in: query description: 'Base currency for `total_in_base_currency` (defaults to the configured reporting currency).' required: false schema: type: string example: USD responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/StringUnifiedBalance' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: "String/account not found or the key's ledger is not a member" content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Invalid account code' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/strings/{stringCode}/transfer': post: tags: - Strings summary: 'Post an atomic same-currency transfer between two member ledgers of a string' description: 'Moves an equal amount of a customer account from the source member ledger to the target member ledger (same currency, no rate). BOTH legs post atomically in one database transaction. Requires an api key whose ledger is a member of the string and which carries the `strings:participate:{stringCode}` capability. Supply a first-class idempotency key via the `Idempotency-Key` header (or an `idempotency_key` body field); replaying it returns the original result without double-posting.' operationId: postStringTransfer parameters: - name: stringCode in: path description: 'String code (unique within the tenant).' required: true schema: type: string example: treasury-fx - name: Idempotency-Key in: header description: 'First-class idempotency key (canonical). Falls back to the body `idempotency_key` when absent.' required: false schema: type: string maxLength: 255 example: transfer-2026-0001 requestBody: required: true content: application/json: schema: required: - source_ledger_code - target_ledger_code - account_code - amount - reference properties: source_ledger_code: description: 'Code of the member ledger value leaves.' type: string example: usd-main target_ledger_code: description: 'Code of the member ledger value arrives in (must differ from the source).' type: string example: usd-ops account_code: description: 'The logical customer account, present across the string.' type: string maxLength: 36 example: '1000' amount: description: 'Amount to move, in the shared currency (major units).' type: string example: '100.00' reference: description: 'The per-ledger transaction reference stamped on both legs.' type: string maxLength: 100 example: XFER-2026-0001 effective_date: description: 'Posting effective date (Y-m-d). Defaults to today when omitted.' type: string format: date example: '2026-06-30' nullable: true description: description: 'Optional human description recorded on both legs.' type: string maxLength: 255 example: 'Treasury sweep' nullable: true attributes: description: 'Optional searchable business dimensions — a flat map of `key` => `value` string pairs (e.g. `{"customer_id": "C-123", "loan_id": "L-42"}`) stamped on BOTH legs (each leg is independently searchable). Keys must be lowercase snake_case (max 64 chars) and not shadow a reserved field; values are strings (max 128 chars). Subject to per-transaction (default 20) and per-tenant distinct-key caps, and, when the tenant runs strict mode, must be declared in the attribute catalog first — a violation returns 422 with an `ATTRIBUTE_*` code synchronously at the gate. Written atomically with both legs and immutable thereafter.' type: object example: customer_id: C-123 loan_id: L-42 nullable: true additionalProperties: type: string maxLength: 128 idempotency_key: description: 'Body fallback for the idempotency key when the Idempotency-Key header is not sent.' type: string maxLength: 255 example: transfer-2026-0001 nullable: true type: object responses: 201: description: 'Transfer posted (both legs committed)' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/StringOperationResult' type: object 200: description: 'Idempotent replay: the original result is returned' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/StringOperationResult' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: 'Forbidden (STRING_KEY_NOT_IN_STRING / STRING_KEY_MISSING_CAPABILITY / STRING_FOREIGN_LEDGER / STRING_OP_NOT_ALLOWED)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 409: description: 'Conflict (STRING_PERIOD_LOCKED / STRING_INACTIVE / STRING_NOT_FOUND)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error (STRING_CURRENCY_MISMATCH / STRING_OPERATION_INVALID)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/strings/{stringCode}/convert': post: tags: - Strings summary: 'Post an atomic different-currency conversion between two member ledgers of a string' description: 'Moves value from a customer account in the source member ledger to the target member ledger in a DIFFERENT currency. Both `source_amount` and `target_amount` are authoritative; `rate` is recorded for audit only. BOTH legs post atomically. Requires an api key whose ledger is a member of the string and which carries the `strings:participate:{stringCode}` capability. Supply a first-class idempotency key via the `Idempotency-Key` header (or an `idempotency_key` body field); replaying it returns the original result without double-posting.' operationId: postStringConvert parameters: - name: stringCode in: path description: 'String code (unique within the tenant).' required: true schema: type: string example: treasury-fx - name: Idempotency-Key in: header description: 'First-class idempotency key (canonical). Falls back to the body `idempotency_key` when absent.' required: false schema: type: string maxLength: 255 example: convert-2026-0001 requestBody: required: true content: application/json: schema: required: - source_ledger_code - target_ledger_code - account_code - source_amount - target_amount - reference properties: source_ledger_code: description: 'Code of the member ledger value leaves.' type: string example: usd-main target_ledger_code: description: 'Code of the member ledger value arrives in (must differ from the source and use a different currency).' type: string example: eur-main account_code: description: 'The logical customer account, present across the string.' type: string maxLength: 36 example: '1000' source_amount: description: 'Authoritative amount leaving the source account, in the source currency (major units).' type: string example: '100.00' target_amount: description: 'Authoritative amount arriving in the target account, in the target currency (major units).' type: string example: '92.00' rate: description: 'The conversion rate, recorded for audit only (never used to recompute either amount). OPTIONAL: when omitted, a live rate is resolved from the FX rate service and snapshotted before posting; an explicit rate stays authoritative.' type: string example: '0.92' nullable: true reference: description: 'The per-ledger transaction reference stamped on both legs.' type: string maxLength: 100 example: FX-2026-0001 effective_date: description: 'Posting effective date (Y-m-d). Defaults to today when omitted.' type: string format: date example: '2026-06-30' nullable: true description: description: 'Optional human description recorded on both legs.' type: string maxLength: 255 example: 'USD→EUR conversion' nullable: true attributes: description: 'Optional searchable business dimensions — a flat map of `key` => `value` string pairs (e.g. `{"customer_id": "C-123", "loan_id": "L-42"}`) stamped on BOTH legs (each leg is independently searchable). Keys must be lowercase snake_case (max 64 chars) and not shadow a reserved field; values are strings (max 128 chars). Subject to per-transaction (default 20) and per-tenant distinct-key caps, and, when the tenant runs strict mode, must be declared in the attribute catalog first — a violation returns 422 with an `ATTRIBUTE_*` code synchronously at the gate. Written atomically with both legs and immutable thereafter.' type: object example: customer_id: C-123 loan_id: L-42 nullable: true additionalProperties: type: string maxLength: 128 idempotency_key: description: 'Body fallback for the idempotency key when the Idempotency-Key header is not sent.' type: string maxLength: 255 example: convert-2026-0001 nullable: true type: object responses: 201: description: 'Conversion posted (both legs committed)' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/StringOperationResult' type: object 200: description: 'Idempotent replay: the original result is returned' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/StringOperationResult' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: 'Forbidden (STRING_KEY_NOT_IN_STRING / STRING_KEY_MISSING_CAPABILITY / STRING_FOREIGN_LEDGER / STRING_OP_NOT_ALLOWED)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 409: description: 'Conflict (STRING_PERIOD_LOCKED / STRING_INACTIVE / STRING_NOT_FOUND)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error (STRING_CURRENCY_MISMATCH / STRING_OPERATION_INVALID)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/trancodes: get: tags: - 'Transaction Codes' summary: 'List transaction code templates' description: 'Display a listing of tranCodes for the specified ledger.' operationId: getTransactionCodes parameters: - name: status in: query description: 'Filter by status' required: false schema: type: string enum: - active - deprecated - name: search in: query description: 'Search in code, name, or description' required: false schema: type: string - name: limit in: query description: 'Number of items per page (max 100)' required: false schema: type: integer default: 25 maximum: 100 - name: cursor in: query description: 'Cursor for pagination' required: false schema: type: string responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/TransactionCode' meta: $ref: '#/components/schemas/PaginationMeta' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] post: tags: - 'Transaction Codes' summary: 'Create a transaction code template' description: 'Store a newly created tranCode.' operationId: createTransactionCode requestBody: required: true content: application/json: schema: required: - code - name - entries_template properties: code: description: 'Unique code for this template (immutable after creation; uppercase letters, numbers, hyphen, underscore)' type: string example: PAYMENT name: type: string example: 'Customer Payment' description: type: string nullable: true status: type: string default: active enum: - active - deprecated params_schema: oneOf: - $ref: '#/components/schemas/ParamsSchema' nullable: true entries_template: $ref: '#/components/schemas/EntriesTemplate' attributes_template: oneOf: - $ref: '#/components/schemas/AttributesTemplate' nullable: true validation_rules: type: object nullable: true metadata: type: object nullable: true type: object responses: 201: description: 'Transaction code created' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/TransactionCode' type: object 400: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/trancodes/{id}': get: tags: - 'Transaction Codes' summary: 'Get a specific transaction code template' description: 'Display the specified tranCode.' operationId: getTransactionCode parameters: - name: id in: path description: 'Transaction Code UUID' required: true schema: type: string format: uuid responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/TransactionCode' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Transaction code not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] put: tags: - 'Transaction Codes' summary: 'Update a transaction code template (increments version)' description: "Update the specified tranCode.\nNote: Updates increment the version number for audit trail." operationId: updateTransactionCode parameters: - name: id in: path description: 'Transaction Code UUID' required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: description: '`code` is immutable after creation and is silently ignored if supplied here.' required: - name - entries_template properties: name: type: string description: type: string nullable: true params_schema: oneOf: - $ref: '#/components/schemas/ParamsSchema' nullable: true entries_template: $ref: '#/components/schemas/EntriesTemplate' attributes_template: oneOf: - $ref: '#/components/schemas/AttributesTemplate' nullable: true validation_rules: type: object nullable: true metadata: type: object nullable: true type: object responses: 200: description: 'Transaction code updated' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/TransactionCode' type: object 400: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Transaction code not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/trancodes/{id}/deprecate': post: tags: - 'Transaction Codes' summary: 'Mark a transaction code as deprecated (one-way state transition)' description: 'Sets `status` to `deprecated`. There is no API path back to `active` — once deprecated, the transaction code remains in the system for historical reference but is no longer suitable for new transactions. The record itself is never deleted; existing transactions that referenced it stay valid.' operationId: deprecateTransactionCode parameters: - name: id in: path description: 'Transaction Code UUID' required: true schema: type: string format: uuid responses: 200: description: 'Transaction code deprecated' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/TransactionCode' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Transaction code not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/trancodes/{id}/validate-params': post: tags: - 'Transaction Codes' summary: "Validate a parameter payload against a transaction code's params_schema" description: "Dry-run check of a `params` payload against the transaction code's `params_schema`. Returns 200 with `valid: true` when all required parameters are supplied and types match, or 422 with a per-field `errors` map otherwise. Useful before invoking the trancode to surface validation errors without creating a transaction." operationId: validateTransactionCodeParams parameters: - name: id in: path description: 'Transaction Code UUID' required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: properties: params: description: "Parameter payload to validate against the trancode's `params_schema`. Map of parameter name → value." type: object example: amount: '100.00' from_account: '1000' to_account: '4000' type: object responses: 200: description: 'Parameters are valid' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: valid: type: boolean example: true message: type: string example: 'Parameters are valid' type: object type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Transaction code not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Parameter validation failed' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/transactions: get: tags: - Transactions summary: 'List all transactions in a ledger' description: "Display a listing of the resource.\n\nUses cursor-based pagination for consistency. See docs/api/PAGINATION.md" operationId: getTransactions parameters: - name: layer in: query description: 'Filter by transaction layer' required: false schema: type: string enum: - settled - pending - encumbrance - name: status in: query description: 'Filter by transaction status' required: false schema: type: string enum: - pending - posted - void - failed - reversed - name: from_date in: query description: 'Filter transactions from this date' required: false schema: type: string format: date - name: to_date in: query description: 'Filter transactions to this date' required: false schema: type: string format: date - name: correlation_id in: query description: 'Filter by correlation ID' required: false schema: type: string - name: limit in: query description: 'Number of items per page (max 100)' required: false schema: type: integer default: 25 maximum: 100 - name: cursor in: query description: 'Cursor for pagination' required: false schema: type: string responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/Transaction' meta: $ref: '#/components/schemas/PaginationMeta' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] post: tags: - Transactions summary: 'Create a new transaction (direct entries or trancode invocation)' description: "Two posting modes are accepted on this endpoint and are mutually exclusive — exactly one must be used per request:\n\n**Mode 1 — Direct entries.** Caller supplies `entries[]` and the server stores them after balance + account-existence checks. Use this when each transaction is bespoke or when the caller already knows the exact debit/credit pairs to write.\n\n**Mode 2 — Transaction-code invocation.** Caller supplies `transaction_code` + `transaction_code_params`. The server looks up the named, active trancode in the current ledger, validates the params against its `params_schema`, runs the entries template through the expression engine (substitution + CEL-based Money grammar — `+ - * /` and the `round()` helper), and writes the resulting entries. Use this when the same transaction shape is replayed many times — define the template once via `POST /trancodes`, invoke by code thereafter. Aligns with the convention used by ledger systems where standardised transaction shapes are encoded as templates.\n\nSending both `entries` and `transaction_code` on the same request returns 422 — the server will not guess which mode the caller intended.\n\nTop-level fields (`effective_date`, `description`, `layer`, `journal_id`, `correlation_id`, `correlation_type`, `metadata`, `idempotency_key`) apply to both modes." operationId: createTransaction requestBody: required: true content: application/json: schema: description: 'Either `entries` (Mode 1) or `transaction_code` + `transaction_code_params` (Mode 2) must be supplied — never both.' required: - effective_date - description - idempotency_key properties: effective_date: description: 'Transaction effective date' type: string format: date example: '2025-01-15' description: type: string example: 'Payment received from customer' reference: description: 'External reference number' type: string example: INV-001 layer: description: 'Case-insensitive on the request side; values like `Settled` or `SETTLED` are normalised to canonical lowercase before validation. Responses always render the canonical lowercase form.' type: string default: settled enum: - settled - pending - encumbrance journal_id: type: string format: uuid nullable: true correlation_id: description: "Group related transactions. If omitted but correlation_source_id is given, defaults to the source transaction's group handle (its correlation_id, else its id)." type: string nullable: true correlation_type: description: 'Correlation classifier (e.g. invoice, refund, reschedule). Paired with correlation_source_id — supply both or neither.' type: string maxLength: 50 nullable: true correlation_source_id: description: 'Optional predecessor transaction (same ledger) to link to. Creates a Correlation pair row (source = this id, target = the new transaction) classified by correlation_type — e.g. a reschedule replacement pointing at its voided original.' type: string format: uuid nullable: true idempotency_key: description: 'Unique key to prevent duplicate transactions' type: string example: unique-key-123 metadata: type: object nullable: true attributes: description: 'Optional searchable business dimensions — a flat map of `key` => `value` string pairs (e.g. `{"customer_id": "C-123", "loan_id": "L-42"}`). Applies to both posting modes. Keys must be lowercase snake_case (max 64 chars) and not shadow a reserved field; values are strings (max 128 chars). Subject to per-transaction (default 20) and per-tenant distinct-key caps, and, when the tenant runs strict mode, must be declared in the attribute catalog first — a violation returns 422 with an `ATTRIBUTE_*` code. Written atomically with the transaction and immutable thereafter.' type: object example: customer_id: C-123 loan_id: L-42 nullable: true additionalProperties: type: string maxLength: 128 entries: description: 'Mode 1 only. Double-entry transaction entries (must balance after server-side resolution). Mutually exclusive with `transaction_code`.' type: array items: required: - type - amount properties: account_code: description: 'Account code (alternative to account_id)' type: string example: '1000' account_id: description: 'Account UUID (alternative to account_code)' type: string format: uuid type: type: string enum: - debit - credit example: debit amount: description: 'Amount in major units (e.g., dollars)' type: string example: '100.00' description: type: string nullable: true metadata: type: object nullable: true type: object example: - account_code: '1000' type: debit amount: '100.00' - account_code: '4000' type: credit amount: '100.00' transaction_code: description: 'Mode 2 only. Code of an active trancode in this ledger. Must be paired with `transaction_code_params`. Mutually exclusive with `entries`.' type: string maxLength: 50 example: BOOK_TRANSFER transaction_code_params: description: "Mode 2 only. Parameter map keyed by parameter name as declared in the trancode's `params_schema`. Values are substituted into the template (account selectors and amount expressions) at materialisation time." type: object example: amount: '100.00' from_account: '1000' to_account: '4000' type: object responses: 202: description: 'Transaction accepted and processing' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: id: type: string format: uuid status: type: string example: pending idempotency_key: type: string correlation_id: type: string message: type: string type: object type: object 400: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 409: description: 'Idempotency key conflict' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 503: description: 'Idempotency service unavailable (code SERVICE_UNAVAILABLE) — fail-closed with a Retry-After header; nothing is written' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/transactions/correlation: get: tags: - Transactions summary: 'List transactions sharing a correlation ID (chronological)' description: "List transactions sharing a correlation ID, in posting order.\n\nThe correlation id is taken as a **query parameter** (`?correlation_id=`),\nnot a path segment, so it can round-trip any value the write API accepts\n(`string|max:50`) — including ids containing '/', '%', etc. that a path\nsegment cannot carry.\n\nReturns the full correlation trail for that id within the authenticated\nledger. Deliberately ordered chronologically by posting time (created_at\nasc, id asc) — a correlation trail answers \"what happened, and in what\norder\" — which is distinct from the transaction list endpoint's\nfinancial-chronology ordering (effective_date desc). The UUIDv7 `id` is\na stable, time-ordered tiebreaker.\n\nLedger-scoped via $ledger->transactions(): a key issued for ledger A\nnever surfaces ledger B's rows even if both used the same correlation\nid. An unknown or foreign correlation id yields an empty paginator\n(200 with empty data) rather than a 404 — the endpoint is not an\nexistence oracle.\n\nUses cursor-based pagination for consistency. See docs/api/PAGINATION.md" operationId: getTransactionsByCorrelation parameters: - name: correlation_id in: query description: 'Correlation ID to group transactions by' required: true schema: type: string maxLength: 50 - name: limit in: query description: 'Number of items per page (1-100)' required: false schema: type: integer default: 25 maximum: 100 minimum: 1 - name: cursor in: query description: 'Cursor for pagination' required: false schema: type: string responses: 200: description: 'Successful operation (empty data when no transactions share the id)' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/Transaction' meta: $ref: '#/components/schemas/PaginationMeta' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error (missing or too-long correlation_id)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/transactions/by-attribute: get: tags: - Transactions summary: 'Search transactions by a searchable business dimension (tenant-scoped, cross-ledger)' description: 'Return the transactions carrying a given `key`=`value` dimension (e.g. `customer_id`=`C-123`), newest first. Tenant-scoped and cross-ledger by default; the tenant is derived server-side from the API key and is never taken from the query string. A value that exists only in another tenant returns an empty paginator (never a 404). Optional `ledger_id` narrows to one ledger; optional `from`/`to` bound the `transaction_created_at` window.' operationId: searchTransactionsByAttribute parameters: - name: key in: query description: 'Attribute key (dimension) to search on, e.g. customer_id' required: true schema: type: string maxLength: 64 - name: value in: query description: 'Exact attribute value to match, e.g. C-123' required: true schema: type: string maxLength: 128 - name: ledger_id in: query description: 'Optional — narrow the search to a single ledger within the tenant' required: false schema: type: string format: uuid - name: from in: query description: 'Optional inclusive lower bound on transaction_created_at (enables partition pruning). Format `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` — NO timezone (the column is timestamp without time zone).' required: false schema: type: string pattern: '^\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?$' example: '2026-07-01 00:00:00' - name: to in: query description: 'Optional inclusive upper bound on transaction_created_at (enables partition pruning). Format `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` — NO timezone (the column is timestamp without time zone).' required: false schema: type: string pattern: '^\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?$' example: '2026-07-31 23:59:59' - name: limit in: query description: 'Number of items per page (1-100)' required: false schema: type: integer default: 25 maximum: 100 minimum: 1 - name: cursor in: query description: 'Opaque keyset cursor returned by this endpoint. A malformed or foreign cursor is rejected as 422.' required: false schema: type: string responses: 200: description: 'Successful operation (empty data when no transaction in this tenant carries the dimension)' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: array items: $ref: '#/components/schemas/Transaction' meta: $ref: '#/components/schemas/PaginationMeta' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: 'Forbidden (no tenant context)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Validation error (missing/too-long key or value, bad ledger_id/date)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] /api/v1/transactions/batch: post: tags: - Transactions summary: 'Create multiple transactions in a batch' description: 'Create multiple transactions in a single API request. Each transaction is processed independently, supporting partial success. Maximum 100 transactions per batch (configurable). Searchable attributes are NOT supported on this endpoint: a batch item carrying `attributes` is rejected with 422 (attributes are immutable and write-once, so silently dropping them would be unrecoverable). Create attributed transactions via POST /api/v1/transactions.' operationId: createTransactionBatch requestBody: required: true content: application/json: schema: required: - transactions properties: transactions: description: 'Array of transactions to create (max 100)' type: array items: required: - idempotency_key - effective_date - description - entries properties: idempotency_key: description: 'Unique key for idempotency (required per transaction)' type: string example: tx-001 reference: description: 'External reference number' type: string example: INV-001 description: type: string example: 'Invoice payment' effective_date: type: string format: date example: '2026-01-15' layer: description: 'Case-insensitive on the request side; values like `Settled` or `SETTLED` are normalised to canonical lowercase before validation. Responses always render the canonical lowercase form.' type: string default: settled enum: - settled - pending - encumbrance journal_id: type: string format: uuid nullable: true correlation_id: type: string nullable: true metadata: type: object nullable: true entries: type: array items: required: - type - amount properties: account_code: type: string example: '1000' account_id: type: string format: uuid type: type: string enum: - debit - credit amount: type: string example: '100.00' description: type: string nullable: true metadata: type: object nullable: true type: object type: object type: object example: transactions: - idempotency_key: tx-001 reference: INV-001 description: 'Invoice payment' effective_date: '2026-01-15' entries: - account_code: '1000' type: debit amount: '100.00' - account_code: '4000' type: credit amount: '100.00' - idempotency_key: tx-002 reference: INV-002 description: 'Second invoice payment' effective_date: '2026-01-15' entries: - account_code: '1000' type: debit amount: '200.00' - account_code: '4000' type: credit amount: '200.00' responses: 202: description: 'Batch processed (may include partial success)' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: properties: results: type: array items: properties: idempotency_key: type: string status: type: string enum: - accepted - rejected id: type: string format: uuid nullable: true correlation_id: type: string nullable: true error: type: string nullable: true error_code: type: string nullable: true type: object summary: properties: total: type: integer accepted: type: integer rejected: type: integer type: object type: object type: object 400: description: 'Validation error (batch format invalid)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 503: description: 'Idempotency service unavailable (code SERVICE_UNAVAILABLE) — the whole batch is rejected fail-closed with a Retry-After header; nothing is written' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/transactions/{transactionId}': get: tags: - Transactions summary: 'Get a specific transaction' description: 'Display the specified resource.' operationId: getTransaction parameters: - name: transactionId in: path description: 'Transaction UUID' required: true schema: type: string format: uuid responses: 200: description: 'Successful operation' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/Transaction' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Transaction not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/transactions/{transactionId}/reverse': post: tags: - Transactions summary: 'Reverse a posted transaction' description: 'Reverse a transaction' operationId: reverseTransaction parameters: - name: transactionId in: path description: 'Transaction UUID to reverse' required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: required: - reason - date properties: reason: description: 'Reason for reversal' type: string example: 'Customer refund' date: description: 'Effective date of reversal' type: string format: date example: '2025-01-15' reference: type: string example: REF-001 nullable: true metadata: type: object nullable: true idempotency_key: type: string nullable: true type: object responses: 201: description: 'Reversal transaction created' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/Transaction' type: object 400: description: 'Validation error' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Transaction not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 409: description: 'Idempotency conflict — request with this key in progress (idempotency_key_in_use) or key already used for a different operation (idempotency_key_reused)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 422: description: 'Transaction cannot be reversed' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 503: description: 'Idempotency service unavailable (code SERVICE_UNAVAILABLE) — fail-closed with a Retry-After header; nothing is written' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] '/api/v1/transactions/{transactionId}/void': post: tags: - Transactions summary: 'Void a posted transaction' description: "Void a posted transaction.\n\nFlips status to VOID and recalculates balances so the transaction's\neffect disappears, without deleting rows or touching entries (Article\n1.1: lifecycle metadata is mutable, financial content is not). This is\nthe sanctioned \"remove from schedule\" mechanism for encumbrance-layer\nschedules (e.g. reschedules) — see docs/api/rest/transactions.md." operationId: voidTransaction parameters: - name: transactionId in: path description: 'Transaction UUID to void' required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: properties: reason: description: 'Optional reason recorded on the transaction and in the activity log.' type: string maxLength: 255 example: rescheduled nullable: true type: object responses: 200: description: 'Transaction voided' content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: $ref: '#/components/schemas/Transaction' type: object 401: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 404: description: 'Transaction not found' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 409: description: 'Not voidable (code TRANSACTION_NOT_VOIDABLE) or effective date in a locked period (code PERIOD_LOCKED)' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - apiKey: [] components: schemas: StringAccountRow: title: 'String Account Row' description: 'One account in one member ledger of a string, identifying its owning ledger and account identity.' required: - id - ledger_id - code - name - type - normal_balance properties: id: description: 'Account id.' type: string format: uuid ledger_id: description: 'Id of the owning member ledger.' type: string format: uuid ledger_code: description: 'Code of the owning member ledger' type: string example: gbp-main currency: description: 'Currency of the owning member ledger' type: string example: GBP code: type: string example: '1000' name: type: string example: Cash type: type: string enum: - asset - liability - equity - revenue - expense example: asset category: type: string enum: - system - customer example: customer normal_balance: type: string enum: - debit - credit example: debit is_active: type: boolean example: true materialized: description: 'True when this row is a materialized copy sourced from a sibling member (its string_source_id is set).' type: boolean example: false type: object Account: title: Account description: 'A chart of accounts entry for tracking financial transactions' required: - id - code - name - type - category - normal_balance properties: id: type: string format: uuid ledger_id: type: string format: uuid parent_id: description: 'Parent account for hierarchical structure' type: string format: uuid nullable: true code: description: 'Account code (unique within ledger)' type: string example: '1000' name: type: string example: Cash type: type: string enum: - asset - liability - equity - revenue - expense example: asset category: description: 'Account category — system (internal/GL accounts) or customer (end-user balance accounts)' type: string enum: - system - customer example: system normal_balance: description: 'Normal balance side' type: string enum: - debit - credit example: debit balance: description: 'Current balance in major units' type: string example: '1000.00' description: type: string nullable: true is_active: type: boolean example: true is_system: description: 'System accounts cannot be deleted' type: boolean example: false metadata: type: object nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time type: object AccountSet: title: 'Account Set' description: 'A logical grouping of accounts for reporting purposes' required: - id - code - name properties: id: type: string format: uuid ledger_id: type: string format: uuid code: description: 'Unique code within ledger' type: string example: OPERATING_EXPENSES name: type: string example: 'Operating Expenses' description: type: string nullable: true metadata: type: object nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time type: object AttributeDefinition: title: 'Attribute Definition' description: 'A catalogued searchable transaction dimension ("key") for a tenant. Auto-populated on first use or declared explicitly for strict mode.' required: - id - key - indexed - usage_count properties: id: type: string format: uuid key: description: 'The governed dimension name (lowercase snake_case, unique within the tenant).' type: string maxLength: 64 example: customer_id label: description: 'Optional human-friendly display name.' type: string example: 'Customer ID' nullable: true indexed: description: 'Reserved forward-compatibility metadata; has NO behavioural effect in v1 — a single composite index serves every key, so search works identically for indexed=false dimensions.' type: boolean example: true usage_count: description: 'Number of times the key has been stamped on a transaction.' type: integer format: int64 example: 1200 first_seen_at: description: 'When the key was first used (null for a declared-but-unused key).' type: string format: date-time nullable: true last_seen_at: description: 'When the key was most recently used.' type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time type: object Entry: title: Entry description: 'A single entry in a double-entry transaction' required: - id - transaction_id - account_id - type - amount properties: id: type: string format: uuid account_id: type: string format: uuid account_code: type: string example: '1000' account_name: type: string example: Cash nullable: true amount: description: 'Amount in major units' type: string example: '100.00' type: type: string enum: - debit - credit example: debit description: type: string nullable: true layer: type: string enum: - settled - pending - encumbrance example: settled type: object ExchangeRate: title: 'Exchange Rate' description: 'A stored FX exchange-rate snapshot for a currency pair. `rate` and `inverse_rate` are decimal ratios (strings), never minor-unit money.' required: - id - base_currency - quote_currency - rate - inverse_rate - source - effective_at properties: id: description: "A stored FX exchange-rate snapshot for a currency pair within a tenant (#103).\n\nRows are either caller-supplied `manual` overrides or provider-fetched live rates\n(e.g. `ecb`); both are stored per-tenant. `rate` / `inverse_rate` are DECIMAL\nRATIOS (NUMERIC(40,18)), never minor-unit money — they are cast to `string` so a\nhigh-precision rate is NEVER coerced through a lossy float.\n\nIt carries the {@see HasTenancy} global scope like every other tenant model, but\nthe FX read/write paths ({@see \\App\\Services\\Fx\\ManualRateProvider},\n{@see \\App\\Services\\Fx\\ExchangeRateService}) additionally pin an explicit\n`tenant_id` predicate so they are correct regardless of ambient isolation state\n(charter #166 security rule)." type: string format: uuid base_currency: description: 'Base currency (1 unit of this).' type: string example: EUR quote_currency: description: 'Quote currency (how much 1 base is worth).' type: string example: USD rate: description: '1 base_currency = rate quote_currency (decimal ratio).' type: string example: '1.081000000000000000' inverse_rate: description: 'Reciprocal of rate (1 quote_currency in base_currency).' type: string example: '0.925069380203515263' source: description: 'Provenance: manual | ecb | openexchangerates | …' type: string example: manual effective_at: type: string format: date-time expires_at: type: string format: date-time nullable: true created_at: type: string format: date-time type: object Journal: title: Journal description: 'A journal for organizing related transactions' required: - id - code - name - status properties: id: type: string format: uuid ledger_id: type: string format: uuid code: description: 'Unique code within ledger' type: string example: SALES name: type: string example: 'Sales Journal' description: type: string nullable: true status: type: string enum: - active - closed example: active metadata: type: object nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time type: object Ledger: title: Ledger description: 'A financial ledger containing chart of accounts and transactions' required: - id - code - name - currency - status properties: id: type: string format: uuid example: 0191234-5678-90ab-cdef-1234567890ab code: description: 'Unique ledger code' type: string example: main-ledger name: type: string example: 'Main Ledger' description: type: string example: 'Primary accounting ledger' nullable: true currency: description: 'ISO currency code' type: string example: USD storage_decimals: description: 'Storage precision (decimals)' type: integer example: 2 display_decimals: description: 'Display precision' type: integer example: 2 rounding_mode: type: string enum: - half_up - half_down - half_even - half_ceiling - half_floor example: half_up timezone: type: string example: America/New_York fiscal_year_start_month: description: 'Fiscal year start month (1-12)' type: integer example: 4 fiscal_year_start_day: description: 'Fiscal year start day (1-31)' type: integer example: 6 is_active: type: boolean example: true status: type: string enum: - active - inactive example: active settings: type: object nullable: true metadata: type: object nullable: true created_at: type: string format: date-time example: '2025-10-16T12:00:00Z' updated_at: type: string format: date-time example: '2025-10-16T12:00:00Z' type: object PaginationMeta: title: 'Pagination Metadata' description: 'Cursor-based pagination metadata as emitted by PaginatedResponse. Wraps the actual cursor fields under a `pagination` key inside the envelope `meta`.' properties: pagination: properties: limit: description: 'Page size requested.' type: integer example: 25 has_more: description: 'True if another page is available.' type: boolean example: true next_cursor: type: string example: eyJpZCI6IjAxOWRjZjg3LTUwN2ItNzE5OS05ZTE1LWZhY2YxNjVlNzRjMSJ9 nullable: true previous_cursor: type: string nullable: true type: object type: object LedgerString: title: 'Ledger String' description: 'A string links multiple single-currency ledgers into one logical, cross-currency group.' required: - id - code - name - is_active properties: id: type: string format: uuid code: description: 'String code (unique within the tenant)' type: string maxLength: 50 example: treasury-fx name: type: string example: 'Treasury FX group' description: type: string example: 'Cross-currency treasury ledgers' nullable: true is_active: type: boolean example: true ledgers: description: 'Member ledgers (only present on the show endpoint).' type: array items: properties: id: type: string format: uuid code: type: string example: gbp-main name: type: string example: 'GBP Main' currency: type: string example: GBP type: object created_at: type: string format: date-time updated_at: type: string format: date-time type: object Transaction: title: Transaction description: 'A double-entry accounting transaction' required: - id - ledger_id - description - effective_date - status properties: id: type: string format: uuid ledger_id: type: string format: uuid journal_id: type: string format: uuid nullable: true reference: type: string example: INV-001 nullable: true description: type: string example: 'Payment received' effective_date: type: string format: date-time date: description: 'Alias for effective_date' type: string format: date-time layer: type: string enum: - settled - pending - encumbrance example: settled status: type: string enum: - pending - posted - void - failed - reversed example: posted total_amount: description: 'Total transaction amount in major units' type: string example: '100.00' entry_count: type: integer example: 2 hash: description: 'Transaction hash for integrity' type: string nullable: true previous_hash: type: string nullable: true correlation_id: description: 'Group related transactions' type: string nullable: true metadata: type: object nullable: true original_transaction_id: type: string format: uuid nullable: true reversal_reason: type: string nullable: true entries: type: array items: $ref: '#/components/schemas/Entry' created_at: type: string format: date-time updated_at: type: string format: date-time type: object EntryTemplate: title: 'Entry Template' description: 'A single entry in an entries_template. The `account` and `amount` fields each accept either a literal value or a parameter reference / expression that resolves at runtime when the trancode is materialised into a transaction.' required: - account - type - amount properties: account: description: 'Account **code** selector (not a UUID). May be a fixed account code (e.g. "1000") or a parameter reference (e.g. "{params.from_account}") whose resolved value must itself be an account code. Parameter references must use the `{params.NAME}` form — bare `{NAME}` is reserved for system-injected variables and is rejected by the expression engine. Resolved at trancode-execution time against the supplied params and used as the `account_code` of the generated transaction entry.' type: string example: '{params.from_account}' type: type: string enum: - debit - credit amount: description: 'Amount expression. May be a decimal string ("100.00"), a parameter reference ("{params.amount}"), or a CEL expression wrapped in braces ("{params.amount * 1.05}", "{round(params.amount * 0.025)}"). The expression dialect is [Google CEL](https://github.com/google/cel-spec) — Money values support `+ - * /` and the `round()` helper.' type: string example: '{params.amount * 1.05}' description: description: 'Optional per-entry description.' type: string nullable: true type: object EntriesTemplate: title: 'Entries Template' description: 'Double-entry template stored on a transaction code. At least 2 entries are required; once parameters are substituted, debits and credits must balance.' required: - entries properties: entries: type: array items: $ref: '#/components/schemas/EntryTemplate' minItems: 2 type: object example: entries: - account: '{params.from_account}' type: credit amount: '{params.amount}' - account: '{params.to_account}' type: debit amount: '{params.amount}' AttributesTemplate: title: 'Attributes Template' description: 'Optional map of searchable business dimensions to auto-stamp on every transaction this code produces (epic #212). A flat `{ "": "" }` object: each **key** is a lowercase snake_case dimension name (subject to the tenant''s attribute guard rails and strict mode, validated at create/update time), and each **value** is a literal (`"web"`), a parameter reference (`"{params.customer_id}"`), or a `{}` resolved on a DEDICATED attribute runtime — it shares the `entries_template` engine''s complexity/length guards and Money grammar, but additionally allows string results and string `+` concatenation (e.g. `{params.region + "_gold"}`) while deliberately withholding CEL''s regex/string-function surface. Expressions must resolve to a string, integer, or Money value (raw floats and non-scalars are rejected). Resolved values are stamped atomically with the transaction; an explicit invoke-time `attributes` value for the same key overrides the template-derived one.' type: object example: channel: web customer_id: '{params.customer_id}' additionalProperties: type: string ParamsSchema: title: 'TranCode Parameter Schema' description: 'JSON-Schema-style declaration of the parameters this trancode accepts when generating a transaction.' properties: type: type: string enum: - object example: object required: description: 'Names of parameters that the caller must provide when invoking this trancode.' type: array items: type: string example: - amount properties: description: 'Map of parameter name → JSON-Schema fragment describing the parameter shape. Parameters that feed an `account` slot must resolve to an account **code** string (not a UUID), to match the trancode-generated transaction entry shape.' type: object example: amount: type: string description: 'Payment amount in major units' from_account: type: string description: 'Source account code' to_account: type: string description: 'Destination account code' type: object TransactionCode: title: 'Transaction Code' description: 'A reusable template for creating transactions with parameters' required: - id - code - name - entries_template properties: id: type: string format: uuid ledger_id: type: string format: uuid code: description: 'Unique code for this template (immutable after creation)' type: string example: PAYMENT name: type: string example: 'Customer Payment' description: description: 'Human-readable description' type: string nullable: true status: type: string enum: - active - deprecated example: active version: description: 'Version number (increments on update)' type: integer example: 1 params_schema: oneOf: - $ref: '#/components/schemas/ParamsSchema' nullable: true entries_template: $ref: '#/components/schemas/EntriesTemplate' attributes_template: oneOf: - $ref: '#/components/schemas/AttributesTemplate' nullable: true validation_rules: type: object nullable: true metadata: type: object nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time type: object AccountBalanceResponse: title: 'Account Balance Response' description: 'Layered balance snapshot for a single account. Per issue #86, "available" was removed — only settled funds are spendable. Encumbrances are split into overdue (past due date) and future (due today or later).' required: - success - data type: object allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: success: description: 'Structured response for account balance endpoint' type: boolean example: true data: required: - account_id - account_code - account_name - account_type - normal_balance - balances - layer_details - currency - as_of_date - calculated_at properties: account_id: type: string format: uuid example: 01234567-89ab-cdef-0123-456789abcdef account_code: type: string example: '1000' account_name: type: string example: Cash account_type: type: string enum: - asset - liability - equity - revenue - expense example: asset normal_balance: type: string enum: - debit - credit example: debit balances: required: - settled - pending - overdue - future properties: settled: description: 'Confirmed cleared funds — what you can spend' type: string example: '1000.00' pending: description: 'Unconfirmed transactions (not yet spendable)' type: string example: '50.00' overdue: description: 'Encumbrances past their due date' type: string example: '20.00' future: description: 'Encumbrances due today or later' type: string example: '80.00' type: object layer_details: description: 'Detailed breakdown per accounting layer' type: object currency: type: string example: GBP as_of_date: type: string format: date example: '2025-01-15' calculated_at: type: string format: date-time type: object type: object ErrorEnvelope: title: 'Error Envelope' description: 'Uniform error response envelope returned for all 4xx and 5xx responses.' required: - success - message properties: success: description: 'Standard error response for API endpoints' type: boolean example: false message: description: 'Human-readable error summary.' type: string example: 'Validation failed' code: description: 'Canonical machine-readable error code.' type: string example: VALIDATION_ERROR nullable: true errors: description: 'Optional per-field validation errors keyed by field name.' type: object nullable: true additionalProperties: type: array items: type: string meta: description: 'Optional metadata (e.g. retry_after for rate limits).' type: object nullable: true type: object ExchangeRateQuote: title: 'Resolved Exchange Rate' description: 'A resolved rate for a pair: the decimal ratio, its inverse, provenance, effective time, and a stale flag.' required: - base_currency - quote_currency - rate - inverse_rate - source - effective_at - stale properties: base_currency: description: "Schema + envelope factory for a RESOLVED current/historical rate (#103) — the\noutput of {@see \\App\\Services\\Fx\\ExchangeRateService::getCurrentRate()}.\n\nDistinct from {@see ExchangeRateResource}, which renders a stored DB row: a resolved\nquote may be a synthetic 1:1 (same currency) or a just-fetched live rate that also\ncarries the `stale` flag. Kept a plain holder (does NOT extend {@see SuccessResponse})\nso the `#[OA\\Schema]` resolves with its explicit properties intact." type: string example: EUR quote_currency: type: string example: USD rate: description: '1 base_currency = rate quote_currency.' type: string example: '1.081000000000000000' inverse_rate: type: string example: '0.925069380203515263' source: description: 'manual | ecb | identity (same currency) | …' type: string example: ecb effective_at: type: string format: date-time expires_at: type: string format: date-time nullable: true stale: description: 'True when the rate is older than the configured staleness threshold.' type: boolean example: false type: object FxConversion: title: 'FX Conversion Result' description: 'The result of converting an amount between two currencies at a resolved rate. Nothing is posted.' required: - from - to - amount - converted - rate - inverse_rate - source - effective_at - stale properties: from: description: "Schema + envelope factory for the conversion calculator\n(`GET /api/v1/fx/convert`), #103.\n\nDescribes an amount converted from one currency to another at a resolved rate.\nIt is a pure calculation — nothing is posted. Amounts are major-unit STRINGS.\nKept a plain holder (does NOT extend {@see SuccessResponse}) so the `#[OA\\Schema]`\nresolves with its explicit properties intact." type: string example: USD to: type: string example: EUR amount: description: 'The input amount in `from` (major units).' type: string example: '100.00' converted: description: 'The converted amount in `to` (major units).' type: string example: '92.00' rate: description: '1 from = rate to.' type: string example: '0.920000000000000000' inverse_rate: type: string example: '1.086956521739130435' source: type: string example: ecb effective_at: type: string format: date-time stale: type: boolean example: false type: object StringOperationResult: title: 'String Operation Result' description: 'The committed pair produced by a cross-ledger string transfer/convert: the shared correlation id and both legs.' required: - operation - string_code - correlation_id - replayed - source - target properties: operation: description: 'The cross-ledger operation that was posted.' type: string enum: - transfer - convert string_code: description: 'The string the operation was posted against.' type: string example: treasury-fx correlation_id: description: 'Shared handle stamped on BOTH leg transactions; groups the pair across ledgers.' type: string format: uuid replayed: description: 'True when this idempotency key had already posted: the original result is returned and nothing was posted again.' type: boolean example: false source: description: 'The leg on the source ledger (value leaves the customer account here).' required: - ledger_code - ledger_id - transaction_id - reference - amount properties: ledger_code: description: 'Code of the source member ledger.' type: string example: usd-main ledger_id: description: 'Id of the source member ledger.' type: string format: uuid transaction_id: description: 'Id of the posted source-leg transaction.' type: string format: uuid reference: description: 'The per-ledger transaction reference of the source leg.' type: string example: FX-2026-0001 amount: description: 'Source-leg amount in the source currency (major units).' type: string example: '100.00' type: object target: description: 'The leg on the target ledger (value arrives in the customer account here).' required: - ledger_code - ledger_id - transaction_id - reference - amount properties: ledger_code: description: 'Code of the target member ledger.' type: string example: eur-main ledger_id: description: 'Id of the target member ledger.' type: string format: uuid transaction_id: description: 'Id of the posted target-leg transaction.' type: string format: uuid reference: description: 'The per-ledger transaction reference of the target leg.' type: string example: FX-2026-0001 amount: description: 'Target-leg amount in the target currency (major units).' type: string example: '92.00' type: object rate: description: 'The authoritative conversion rate for a convert (audit only); null for a transfer.' type: string example: '0.92' nullable: true type: object StringBalanceLine: title: 'String Balance Line' description: 'The balance of an account code within a SINGLE member ledger. There is one line per member ledger — never collapsed by currency.' required: - ledger_id - ledger_code - currency - storage_decimals - display_decimals - balances properties: ledger_id: description: 'Id of the member ledger this balance line belongs to.' type: string format: uuid ledger_code: type: string example: gbp-main currency: type: string example: GBP storage_decimals: description: 'Storage precision of this member ledger' type: integer example: 2 display_decimals: description: 'Display precision of this member ledger' type: integer example: 2 balances: required: - settled - pending properties: settled: description: 'Confirmed cleared funds (major units)' type: string example: '1000.00' pending: description: 'Unconfirmed transactions (major units)' type: string example: '50.00' type: object materialized: description: 'Present and false ONLY on a synthesized zero line for a member that has not materialized the account. Omitted (implicit true) on real rows, including a soft-deleted account reported with a zero balance.' type: boolean example: false type: object StringUnifiedBalance: title: 'String Unified Balance' description: "An account code's balance across every member ledger of a string, one line per member ledger." required: - string_code - account_code - ledgers properties: string_code: type: string example: treasury-fx account_code: type: string example: '1000' ledgers: description: 'One balance line per member ledger, ordered by ledger_code.' type: array items: $ref: '#/components/schemas/StringBalanceLine' total_in_base_currency: description: 'Present ONLY when requested via `?include=total_in_base_currency` (#103): the sum of every member line converted to the base currency at the current FX rate. Indicative — computed from displayed member balances, so it moves with the rate.' required: - base_currency - settled - pending properties: base_currency: type: string example: USD settled: description: 'Total settled balance in the base currency (major units).' type: string example: '1234.56' pending: description: 'Total pending balance in the base currency (major units).' type: string example: '78.90' type: object nullable: true type: object SuccessEnvelope: title: 'Success Envelope' description: 'Uniform success response envelope. Endpoints supply a typed `data` property via `allOf` composition; this base schema only defines the shared fields.' required: - success properties: success: description: 'Standard success response for API endpoints' type: boolean example: true message: description: 'Optional human-readable confirmation message.' type: string nullable: true meta: description: 'Optional metadata (pagination, etc.).' type: object nullable: true type: object securitySchemes: sanctum: type: http description: 'Laravel Sanctum Bearer Token' bearerFormat: Sanctum scheme: bearer tags: - name: 'Account Sets' description: 'Logical groupings of accounts for reporting' - name: Journals description: 'Transaction journals for organizing transactions' - name: Reports description: 'Financial reports and statements' - name: Accounts description: Accounts - name: 'Attribute Catalog' description: 'Attribute Catalog' - name: FX description: FX - name: Strings description: Strings - name: 'Transaction Codes' description: 'Transaction Codes' - name: Transactions description: Transactions